really the docs just need to be better.
really the docs just need to be better. there are so many details here that matter that are undocumented
2 Replies
Hey @Avi and @1984 Ford Laser , just saw this now - thanks for the discussion/feedback!
Would you be able to identify specific topics / pages you would like to improve, and create an issue for it? At least that way, your feedback won't be buried.
Also, given that you're both well-versed with the mechanics of DO, you could even create a PR on an existing page - that would really expedite the turnaround to creating / updating pages
https://github.com/cloudflare/cloudflare-docs/issues
GitHub
cloudflare/cloudflare-docs
Cloudflare’s documentation. Contribute to cloudflare/cloudflare-docs development by creating an account on GitHub.
I think the problem is a bit more fundamental than just docs. Outgoing external connections are allowed but my reading of the tea leaves ("... choose three...", input/output gates unless...,
blockConcurrancyWhile, etc.) leads me to believe that's not the primary way DO's designers (Kenton) intended for them to be used. It would really help if Cloudflare just said that... short of a "use at your own risk" statement, but more than just "it's supported".
AND...
Offered truly best practices guidance when using DOs. Agent is a really bad example put out by Cloudflare because it has its own still unfixed security-relevant race condition because it calls setTimeout() which opens the input gate. See: [https://github.com/cloudflare/agents/issues/321]. If Cloudflare can't even get this right, how are other folks supposed to?
I have my own personal "rules" that I've learned by being burned like the issue above. No setTimeout(). No instance variables except under specific circumstances. No external fetch() outside of blockConcurrencyWhile unless they are at the end of processing a request/message and have fire and forget expectations. Etc. I also push external fetches off to a Worker to allow faster hibernation. I don't know enough details like Avi is saying to know if my "rules" are too restrictive, but they are my attempt to stay this side of safe. It would be nice if Cloudflare said something like, "in order to take advantage of the ideal concurrency model, here are the best practices..."