New and improved Workers Docs | Hacker News Reader

New and improved Workers Docs

blog.cloudflare.com

53 pointsadamschwartz21 comments

Big fans of Workers here. It has made our developmental, operational, and deploymental nightmares go away.

...but we've consistently seen users complain about latency and we have observed Cloudflare does not run Workers in the nearest location to the user. This can been semi-confirmed via https://cloudflare-test.judge.sh Our endpoints are always routed to a destination which is not the nearest whilst other enterprise and business domains get served from a nearer location.

This can also be confirmed using Coudflare's own https://www.cloudflare.com/cdn-cgi/trace endpoint (substitute www.cloudflare.com with any of your Workers endpoint to see how differently it is routed. I've been told it might be fickleness of anycast routing and it could be). Disappointing since it is hard to get customer service reps to look at your support tickets when you're on a "free account" (despite paying for Workers).

We have no use for Cloudflare's other products and so it doesn't make sense to purchase pro/business subscriptions.

That said, I'd still recommend using it since it so darn fast.

Edit: Apologies to everyone for an unrelated rant. It was impulsive. I'm unable to delete this comment.

This isn't terribly surprising to me, they might not have the compute deployed in all their sites to serve the more expensive worker requests.

To clarify:

- Workers run in the colo that received the request. We currently literally have no capability to forward Workers requests to other colos. (It's possible we'll introduce that in the future, but it's not the case today.)

- Enabling Workers does not affect how your traffic is routed to colos. So if you're seeing Workers requests not going to the closest colo today, then regular non-Workers requests wouldn't either.

It sounds like the issue here is that your base Cloudflare plan is the "free" plan (confusingly-named because you're separately paying $5/month for workers on top of that).

When we have a colo that doesn't have enough capacity to handle all the local traffic, we often route free-plan traffic away from it, and they end up landing at the next-closest colo. This is completely unrelated to Workers -- it applies to any kind of Cloudflare traffic. If you upgrade to a higher plan level (e.g. pro at $20/month), you should see this happen much less often, if ever.

Sorry that this is confusing! We should probably document this better.

(I'm the lead engineer on Workers.)

Hey Kenton. I recently migrated a few of my static sites to Workers and was hoping you could clarify what the teams plan is around security headers. The only documentation I could find was some random blog post from 2 years ago that didn't help as the way workers function has changed since then and it's no longer as simple as just dropping in a few lines of code.

I'd love to easily configure security headers so my sites are getting good ratings again, but I couldn't find it in the documentation and it doesn't seem like there's been any update to support this. Is your team working on making security headers easier to enable for workers or is there something I missed for setting this up?

Hi! Hmm, not sure I understand. In a Worker, you can set whatever headers you want on the response, in code. What problem are you running into exactly? What do you mean when you say "the way workers function has changed"?

Sorry if I wasn't clear. Yes I understand I can set whatever headers I want in a response via the edit options for my workers. The problem I'm running in to is that I created a worker for a static site and it has a massive 1 line JS blob for the script section that I have to go through to set this. I never created this, it's just what was set up when I used Wrangler to deploy my static site.

This is fine except it's a huge hassle to modify and I'm actually a bit surprised that by default workers don't use secure headers. I figured they would since they're pretty standard now and I'd rather have to disable them if I needed then to manually configure them. If someone isn't familiar with security headers there's also a good chance they would deploy their site and never enable them which makes sites running on workers less secure by default.

I'm going off this several year old blog post: https://scotthelme.co.uk/security-headers-cloudflare-worker/ that talks about how to set this up and it seems like functionality has changed a bit since then, or maybe I am misunderstanding their screenshots. Outside of this I can't find any documentation from Cloudflare about setting these headers that is more recent, or what I would need to set for a new worker that has recently been created to get this functionality.

So I guess my question is two fold, are there plans to make it easier to enable secure headers than to manually modify the worker itself? My plan is to do that currently once I stop slacking and decide to just parse this giant JS blob.

My second question is are there any plans to add documentation around functionality such as this? I was really shocked to see that secure headers weren't something that's simply enabled by default and even more so when I looked through the docs and didn't see any examples on how to set them up. Maybe my use case is niche, but I thought secure headers were pretty standard at this point.

Hmm, it sounds like you originally deployed your site using Wrangler, but then you tried to edit it in the online editor. The code you saw was minified -- not intended to be edited directly.

The right way to edit the worker code is on your local machine before using wrangler to publish it. There should be a file in your project directory like `workers-site/index.js` which is your worker code in easily-editable format.

BTW, this file was copied from a template when you first generated the project. Earlier this year we updated the template to set several security headers:

https://github.com/cloudflare/worker-sites-template/commit/8...

But if you generated your project before that, you probably still have the old code. If you haven't made any changes yourself, you might want to regenerate your project so that it uses the latest template.

Okay that makes more sense and is just my bad then. I hadn't even looked at the index thoroughly as the minified JS correlated to the `workers-site/worker/script.js` and I didn't realize the index.js was responsible for generating that based on content mismatch.

I generated my worker the second week of May so it's totally possible that this wasn't in the release I generated with. Thanks for pointing out that the template had been updated.

Kenton, what a great response.

I worked in tech for the past ~20 years and I've seen my fair share of exchanges like this one; your answer contains essentially everything I would have recommended:

- you clarified the issue

- you didn't take anything personally, but used a humble and warm approach to "defuse" the "rant"

- you admit the limitations of your company's current approach and immediately provide suggestions on how they can be improved (e.g. free plan being "confusingly-named", "We should probably document this better").

Only thing you might be missing is:

- Contact me at $email if I can be of further help

In any case, well done. Cloudflare has a great reputation and you are making it look even better.

This is so much better than the old docs. I'm super bullish on workers as a next-gen computing platform.

How is it better? (I read the blog post [1], as a technical writer I'm curious to hear people's first impression about which changes are most impactful)

[1] https://blog.cloudflare.com/new-and-improved-workers-docs/

Yep, also interested in this. I'm writing and managing (among other things) the team at https://dvc.org/doc and had a lot of discussions like "How do we name and structure the high level navigation items"? From what I read in the blog post (and even considering how much the need to explain the change) this split `Tutorials, How-to guides, Learning` is still confusing to me, to be honest. So, would be great to get more opinions.

(@kaycebasques cool stuff with Lighthouse and other docs, btw!)

(Designer of the docs)

We also published as part of this release some documentation for the so-called “Docs engine” which powers these new docs, which may somewhat answer this question.

https://developers.cloudflare.com/workers/docs-engine

(Note: They currently live within the Workers docs site for now but will get a proper home soon.)

With respect to the information architecture and content design, much of that is discussed in the Contributor’s Guide [1] and Docs-flavored Markdown [2] pages.

The very short version is that we borrowed many ideas from Divio’s documentation system [3], which recommend dividing your content into four distinct buckets: Tutorials, How-to Guides, Explanation, and Reference.

The layout and visual design were inspired by dozens of other docs sites we tested and studied, stealing the best ideas we could from everywhere we looked.

It’s also worth noting that the Cloudflare Workers docs have been open-sourced for over a year now [4], and these new docs (as well as the new engine which powers them) will continue to carry the same license. Contributions are welcome and we’re hopeful and excited to see further uses of the docs engine over time.

[1] https://developers.cloudflare.com/workers/docs-engine/contri...

[2] https://developers.cloudflare.com/workers/docs-engine/docs-f...

[3] https://documentation.divio.com/

[4] https://git.io/JJAWP

(edit: formatting)

Fellow docs person here. Really like the new design—both in terms of information architecture and actually browsing the site! It looks like your docs engine is based on Gatsby. I'm looking into replacing our current static site generator, and Gatsby's near the top of the potential list.

I haven't dug into the repo yet, but building your own docs engine atop Gatsby seems like it would require a lot of additional config. Any major things you needed to address that Gatsby couldn't do out of the box? And when you say further use of the docs engine, are you open to other organizations using/tweaking it?

Gatsby is pretty powerful but also quite complicated and has a fair amount of issues to deal with.

For example it was pretty unergonomic to set up support for deploying to a `pathPrefix` [1] while retaining the ability to develop locally [2].

Nevertheless, we were able to make it work and have been relatively happy with Gatsby overall.

Absolutely! The docs are dual MIT and Apache licensed [3] so have at it. One note: we have not yet completely teased apart the so-called “engine” from our particularly implementation itself. This is something we’re planning to do, in part because we need to to support our other docs sites. You may find it easier to work with once we’ve done that. That being said, you can also just fork the repo, change the content and branding, and things should mostly “just work”. Of course if you run into issues along the way, we’d be glad to have contributions back to the project itself. Good luck!

[1]: https://git.io/JUJsy

[2]: https://github.com/gatsbyjs/gatsby/issues/16040

[3]: https://github.com/cloudflare/workers-docs-engine

Here’s a blog post on the process and rationale: https://blog.cloudflare.com/new-and-improved-workers-docs/

It sure would be nice if there were an off-GitHub way to help you guys with your docs. Before this new revamp, I spotted a link whose redirect had disappeared. I resorted to emailing someone on staff, and they filed an issue about it, but it was an experience that's pretty far removed from the efficiency of a wiki.

The docs are on GitHub:

https://github.com/cloudflare/workers-docs-engine

By "off-GitHub" do you mean you'd prefer there were some other way to edit the docs directly? Mind if I ask why?

The repo is linked all over the docs. It what I used to track down the problem.

> By "off-GitHub" do you mean you'd prefer there were some other way to edit the docs directly?

Yup.

OK, but, what's the problem with GitHub? I want to understand. Like, is this a political thing, or is this a usability thing?

Not sure why your reply was deleted, but FWIW...

> https://www.colbyrussell.com/2020/05/13/psa-wikis.html

Forking a github repository to edit one file and submit it back as a PR is super-duper easy these days. You can do it entirely from the UI by just clicking the pencil icon when viewing the file you want to edit.

I'd argue the only real difference from a classic Wiki is that you need to submit the change for review. There's really no practical way we could eliminate the need for review.

Reply on news.ycombinator.com