cloudflare / workers-docs Goto Github PK

Get slack bot actually working and port it to use our shared domain

We have existing content that includes examples for event.waitUntil() and event.passThroughOnException(). Add these to the FetchEvent runtime api reference document. Not a hard requirement for launch, but certainly low-hanging fruit.

(Placeholder issue: I'd like to have someone run through the tutorial and make sure it works as expected. Feedback and any changes from that will be tracked here)

Need to link to the appropriate docs for the six global methods implemented on our Service Worker Global scope. Part of #11

Part of #11.

Document the objects, methods, properties. Indicate the non-standard behavior (we only encode to and decode from UTF-8; this conforms to the standard for Encoding, but not for Decoding).

Per my notes at https://wiki.cfops.it/display/EW/Runtime+API+Doc+Questions:

• TextEncoder is missing TextEncoder.encodeInto(), but otherwise fully implemented. only encodes into UTF-8 (follows standard)
• TextDecoder only supports decoding from UTF-8, (standard requires more) but otherwise fully implemented.
• TextEncoderStream and TextDecoderStream are both unimplemented.

Help wanted in terms of feedback for how this new proposal is structured. it's a little work for me to redeploy all the demos, git repos, markdown etc.. for each template so I want to get it right this time around. Do you think this OK and worth the time? Should we combine/split things? rename suggestions?

https://github.com/cloudflare/workers-docs/blob/master/reference/templates/index.md
Sending and Receiving Data and Redirects are really confusing on the way it's organized with fetches and reading in requests.

Remy and I came up with organizing it as something like:

Subrequests

subrequest.js
Examples of making fetch requests from within your Worker script including generating JSON post requests then reading in the resulting response body, aggregating multiple requests into one response, and following/catching redirects.

Incoming requests

request.js
Examples of reading in a POST request body of type JSON and form-data and manipulating request headers before it reaches the origin server.

Redirects

redirect.js
Examples of sending single and bulk redirects from a Worker script.

The existing api documentation is out of sync; it says that on a successful DELETE of a script, it does not return a response body, however the code seems to indicate that it does. This may not be the only inconsistency; we should assess the whole API to confirm parity. Stretch goal: test suite for maintaining documentation parity.

(Placeholder issue: I'd like to have someone run through the tutorial and make sure it works as expected. Feedback and any changes from that will be tracked here)

Some endpoints that are public are not documented. We should take careful stock of which of these we want to add documentation for, understanding that it's possible we may want to take the opportunity to change them before making them public.

https://gist.github.com/victoriabernard92/4e73ed016998acace1db8c780104ba71

We have naming conventions for scripts. We should add this to the Script Object reference.

Part of #11

Document our implementation of the WebCrypto API. At minimum we should document the surface of the API, but an article would also be helpful, as this api is full of 🐉s.

From my notes at https://wiki.cfops.it/display/EW/Runtime+API+Doc+Questions:
"this has a big red warning on the MDN doc site saying "if you don't know what this is, don't mess w/ it", which is appropriately scary, but we support it.
The WebCrypto API is a key feature, so it does feel weird that MDN is so discouraging of its use. However, I think some warning is appropriate, since you really do have to know what you're doing to use the SubtleCrypto API safely. We have some recipes which use the WebCrypto API. Perhaps we could list what algorithms we support and link to well-reviewed and commented examples of their use?"

This could potentially be split out into multiple issues:

• Document the shape of an error message (the API sends in the form of a list of objects with code and message)
• Per endpoint, document the possible error responses (HTTP status and error object(s)) that can be expected and what they mean. (Possible to break up by doc, i.e. routes/scripts/bindings).
• The API Gateway can also return errors, as it processes the account/zone id URL parameters. Document or link to errors relevant to workers endpoints.

Fixed by #41

Let's list out the current recipes and choose which to salvage. We'll keep the list here and prioritize 3 to turn into templates and tutorials.

Because of some odd idiosyncrasies within the Fetch API that become more apparent with our Service Worker applications, (see this issue in the fetch standard: whatwg/fetch#671), many of our users are surprised by unexpected loss of data when modifying requests and responses inside of their workers. Include a short article outlining best practices for modifying request and response objects from inside of a worker.

currently the PR associated with this has a good coverage of requests, not so much responses.

In addition to the pages about FetchEvent and CacheAPI, include a short blurb about our implementation of the Service Worker API; previous versions of our documentation simply said we implemented "as much as makes sense", which is only intuitive if you are already familiar with the product. This piece should indicate something about the lifecycle (or lack thereof) of our Service Worker implementation -- scripts are pushed to the edge, rather than downloaded like they are in the browser, so installation and activation steps are unnecessary; additionally, all implementation tied to the attempt to sync up the versions of all instances of service workers, as is done in the browser, is impractical for our 6000+ machine network, and therefore we don't attempt, meaning that more than one version of your script may be active at a time across our network.

Stuff blows up when code like this runs inside of a Worker:

ReferenceError: Worker is not defined

We should document what exists in the global scope and (via @ashleygwilliams in-person) provide library authors with a checklist to help check if their project will work inside of Workers

Minimum topics to cover:

• Finding your Zone ID / Account ID in the Cloudflare Dashboard
• Finding your Cloudflare API key

Link these from all tutorials, as well as the Config API index.

Comb through the docs and figure out where reference links will be helpful and start adding relative links. This may need to wait until we have decided on our technical architecture.

Config API includes endpoints to handle "routes" for workers, also known as "filters". Provide a brief overview of the concept on the Routes reference page, as well as an overview of how routes are arranged and how to think about precedence. Include the concept of a no-op, "placeholder" route.

Flesh out the Fetch API reference page.

Part of #11

We compress bundles (workers with wasm bindings atm), and soon will compress all scripts. This makes the concept of script size a bit opaque. Let's call out this compression explicitly and provide users with a way to assess their bundle size without deploying a worker. This may include a little collaboration with the Config API to include size in more responses.

This should be addressed in the Plans and Limitations section of the reference documentation.

• Move Cloudflare API keys/configuration section into re-usable part in Reference
• Link to reference section of docs
• Update generate project screenshot when JS support lands in wrangler
• Update “Preview your Worker” image when JS support lands in Wrangler
• Update “Publish your Project” section with Zoneless + Wrangler setup
• Update “Install Wrangler” link

Document how to use the editor and it's constraints

document serverless for multiscript and single

This is already started in #42 . Necessary additions:

Document the API surface (objects, methods, properties implemented). Use https://wiki.cfops.it/display/EW/Runtime+API+Doc+Questions for reference, link to mdn where appropriate.

Important to note:

• put will throw an error if the request method is not GET
• match will simply return undefined if the request method is not GET
• put will also throw an error on a response with status code 206.

This issue is part of #11 and related to #44

This really has to do with clarifying when a fetch event is considered "done" and how that impacts async actions. Specifically deals with .respondWith and .waitUntil.

• Move Cloudflare API keys/configuration section into re-usable part in Reference
• Link to final version of codebase on GitHub
• Explain that users need to know the script-name.subdomain.workers.dev URL they’re deploying to, before creating Slack config
• Router NPM package?
• Wrangler screenshot for build/publish
• Link to GitHub source for Slack bot code
• Link to second tutorial (“Building and deploying a serverless function on Cloudflare Workers”)
• Link to Template Gallery

This issue isn't unique to workers, but it is something that trips up our users a lot. It's a well documented problem out there on the internet, but it is worth covering.

provide snippet that uses these and provides sane api
there are shims for this ("atou" and "utoa" for example) like this one: https://gist.github.com/zackdouglas/d9e36168dadbba0762469290cae07c99

Part of #11 . Document objects, methods, properties implemented within the workers runtime. include short overview and example (provided in existing recipe here: https://developers.cloudflare.com/workers/recipes/streaming-responses/)

Refer to https://wiki.cfops.it/display/EW/Runtime+API+Doc+Questions for the specifics.