When I arrived at Cloudflare for an internship in the summer of 2018, I was taken on a tour, introduced to my mentor who took me out for coffee (shoutout to Preston), and given a quick whiteboard overview of how Cloudflare works. Each of the interns would work on a small project of their own and they’d try to finish them by the end of the summer. The description of the project I was given on my very first day read something along the lines of “implementing signed exchanges in a Cloudflare Worker to fix the AMP URL attribution problem,” which was a lot to take in at once. I asked so many questions those first couple of weeks. What are signed exchanges? Can I put these stickers on my laptop? What’s a Cloudflare Worker? Is there a limit to how much Topo Chico I can take from the fridge? What’s the AMP URL attribution problem? Where’s the bathroom?
I got the answers to all of those questions (and more!) and eventually landed a full-time job at Cloudflare. Here’s the story of my internship and working on the Workers Developer Experience team at Cloudflare.
Getting Started with Workers in 2018
After doing a lot of reading, and asking a lot more questions, it was time to start coding. I set up a Cloudflare account with a Workers subscription, and was greeted with a page that looked something like this:
I was able to change the code in the text area on the left, click “Update”, and the changes would be reflected on the right — fairly self-explanatory. There was also a testing tab which allowed me to handcraft HTTP requests with different methods and custom headers. So far so good.
As my project evolved, it became clear that I needed to leave the Workers editor behind. Anything more than a one-off script tends to require JavaScript modules and multiple files. I spent some time setting up a local development environment for myself with npm and webpack (see, purgatory: a place or state of temporary suffering. merriam-webster.com).
After I finally got everything working, my iteration cycle looked a bit like this:
Make a change to my code
Run
npm run build
(which ran webpack and bundled my code in a single script)Open
./dist/worker.min.js
(the output from my build step)Copy the entire contents of the built Worker to my clipboard
Switch to the Cloudflare Workers Dashboard
Paste my script into the Workers editor
Click update
Investigate the behavior of my recently modified script
Rinse and repeat
There were two main things here that were decidedly not a fantastic developer experience:
Inspecting the value of a variable by adding a console.log statement would take me ~2-3 minutes and involved lots of manual steps to perform a full rebuild.
I was unable to use familiar HTTP clients such as cURL and Postman without deploying to production. This was because the Workers Preview UI was an iframe nested in the dashboard.
Luckily for me, Cloudflare Workers deploy globally incredibly quickly, so I could push the latest iteration of my Worker, wait just a few seconds for it to go live, and cURL away.
A Better Workers Developer Experience in 2019
Shortly after we shipped AMP Real URL, Cloudflare released Wrangler, the official CLI tool for developing Workers, and I was hired full time to work on it. Wrangler came with a feature that automated steps 2-7 of my workflow by running the command wrangler preview
, which was a significant improvement. Running the command would build my Worker and open the browser automatically for me so I could see log messages and test out HTTP requests. That summer, our intern Matt Alonso created wrangler preview --watch
. This command automatically updates the Workers preview window when changes are made to your code. You can read more about that here. This was, yet again, another improvement over my old friend Build and Open and Copy and Switch Windows and Paste Forever and Ever, Amen. But there was still no way that I could test my Worker with any HTTP client I wanted without deploying to production — I was still locked in to using the nested iframe.
A few months ago we decided it was time to do something about it. To the whiteboard!
Enter wrangler dev
Most web developers are familiar with developing their applications on localhost
, and since Wrangler is written in Rust, it means we could start up a server on localhost that would handle requests to a Worker. The idea was to somehow start a server on localhost
and then transform incoming requests and send them off to a preview session running on a Cloudflare server.
Proof of Concept
What we came up with ended up looking a little something like this — when a developer runs wrangler dev
, do the following:
Build the Worker
Upload the Worker via the Cloudflare API as a previewable Worker
The Cloudflare API takes the uploaded script and creates a preview session, and returns an access token
Start listening for incoming HTTP requests at
localhost:8787
Top secret fact: 8787 spells out Rust on a phone numpad — Happy Easter!
All incoming requests to
localhost:8787
are modified:
All headers are prepended with
cf-ew-raw-
(for instance,X-Auth-Header
would becomecf-ew-raw-X-Auth-Header
)The URL is changed to
https://rawhttp.cloudflareworkers.com/${path}
The Host header is changed to
rawhttp.cloudflareworkers.com
The
cf-ew-preview
header is added with the access token returned from the API in step 3
After sending this request, the response is modified
All headers not prefixed with
cf-ew-raw-
are discarded and headers with the prefix have it removed (for instance,cf-ew-raw-X-Auth-Success
would becomeX-Auth-Success
)
The hard part here was already done — the Workers Core team had already implemented the API to support the Preview UI. We just needed to gently nudge Wrangler and the API to be the best of friends. After some investigation into Rust’s HTTP ecosystem, we settled on using the HTTP library hyper, which I highly recommend if you’re in need of a low level HTTP library — it’s fast, correct, and the ergonomics are constantly improving. After a bit of work, we got a prototype working and carved Wrangler ❤️ Cloudflare API into the old oak tree down by Lady Bird Lake.
Usage
Let’s say I have a Workers script that looks like this:
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
async function handleRequest(request) {
let message = "Hello, World!"
return new Response(message)
}
If I created a Wrangler project with this code and ran wrangler dev
, this is what it looked like:
$ wrangler dev
? Listening on http://127.0.0.1:8787
In another terminal session, I could run the following:
$ curl localhost:8787
Hello, World!
It worked! Hooray!
Just the Right Amount of Scope Creep
At this point, our initial goal was complete: any HTTP client could test out a Worker before it was deployed. However, wrangler dev
was still missing crucial functionality. When running wrangler preview
, it’s possible to view console.log
output in the browser editor. This is incredibly useful for debugging Workers applications, and something with a name like wrangler dev
should include a way to view those logs as well. “This will be easy,” I said, not yet knowing what I was signing up for. Buckle up!
console.log, V8, and the Chrome Devtools Protocol, Oh My!
My first goal was to get a Hello, World!
message streamed to my terminal session so that developers can debug their applications using wrangler dev
. Let’s take the script from earlier and add a console.log
statement to it:
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
async function handleRequest(request) {
let message = "Hello, World!"
console.log(message) // this line is new
return new Response(message)
}
If you’d like to follow along, you can paste that script into the editor at cloudflareworkers.com using Google Chrome.
This is what the Preview editor looks like when that script is run:
You can see that Hello, World!
has been printed to the console. This may not be the most useful example, but in more complex applications logging different variables is helpful for debugging. If you’re following along, try changing console.log(message)
to something more interesting, like console.log(request.url)
.
The console may look familiar to you if you’re a web developer because it’s the same interface you see when you open the Developer Tools in Google Chrome. Since Cloudflare Workers is built on top of V8 (more info about that here and here), the Workers runtime is able to create a WebSocket that speaks the Chrome Devtools Protocol. This protocol allows the client (your browser, Wrangler, or anything else that supports WebSockets) to send and receive messages that contain information about the script that is running.
In order to see the messages that are being sent back and forth between our browser and the Workers runtime:
Click the Network tab at the top of the inspector
Click the filter icon underneath the Network tab (it looks like a funnel and is nested between the cancel icon and the search icon)
Click WS to filter out all requests but WebSocket connections
Your inspector should look like this:
Then, reload the page, and select the /inspect
item to view its messages. It should look like this:
Hey look at that! We can see messages that our browser sent to the Workers runtime to enable different portions of the developer tools for this Worker, and we can see that the runtime sent back our Hello, World!
Pretty cool!
On the Wrangler side of things, all we had to do to get started was initialize a WebSocket connection for the current Worker, and send a message with the method Runtime.enable
so the Workers runtime would enable the Runtime domain and start sending console.log
messages from our script.
After those initial steps, it quickly became clear that a lot more work was needed to get to a useful developer tool. There’s a lot that goes into the Chrome Devtools Inspector and most of the libraries for interacting with it are written in languages other than Rust (which we use for Wrangler). We spent a lot of time switching WebSocket libraries due to incompatibilities across operating systems (turns out TLS is hard) and implementing the part of the Chrome Devtools Protocol in Rust that we needed to. There’s a lot of work that still needs to be done in order to make wrangler dev
a top notch developer tool, but we wanted to get it into the hands of developers as quickly as possible.
Try it Out!
wrangler dev
is currently in alpha, and we’d love it if you could try it out! You should first check out the Quick Start and then move on to wrangler dev. If you run into issues or have any feedback, please let us know!
Signing Off
I’ve come a long way from where I started in 2018 and so has the Workers ecosystem. It’s been awesome helping to improve the developer experience of Workers for future interns, internal Cloudflare teams, and of course our customers. I can’t wait to see what we do next. I have some ideas for what’s next with Wrangler, so stay posted!
P.S. Wrangler is also open source, and we are more than happy to field bug reports, feedback, and community PRs. Check out our Contribution Guide if you want to help out!