Cloudflare Worker

Code powers foobar.rustymagnet.xyz.

• Cloudflare Worker
• Learnings
  • Time
  • Testing
  • Secrets
  • Environment
  • Deploy
  • Debug
  • Workflows
• Architecture
  • End-2-End deployment workflow
  • Design choices

Learnings

Time

Careful using Date outside a route. Your dev machine will work as expected but the Cloudflare Worker won't.

let epochDatee = Date.now();  // always zero / `1970-01-01` 

addEventListener("fetch", event => {
    let localDate = Date.now(); // expected time and date
})

Testing

Vitest Version

Still, Cloudflare tests only worked with "vitest": "^2.0.5" as written here. If you upgraded, all the tests failed.

The lock file will get out of sync if you don't use the --save-exact:

npm install vitest@2.0.5 --save-dev --save-exact

Proxy

Caution

Expect hard to debug errors if there are tools on your machine proxying client connections or intercepting DNS queries.

Environment Variables

Testing required "cloudflare:test" to access environment variables in tests:

import { env } from "cloudflare:test";

it("/carpark ok", async () => {
    const res = await app.request("/carpark", {}, env);
    expect(res.status).toBe(200);
});

Secrets

Local code uses a .dev.vars to read secret environment variables. The normal .env file is used by Cloudflare code.

Environment

Where

Environment specific values can be set in the wrangler.toml file as below; these can be source controlled safely as these are overridden locally by the .devs.vars ( local tests ) and production secrets.

[env.testing.vars]
  SECURITY_HEADER_NAME = "X-Header"
  SECRET_KEY = "dummy"
  ENVIRONMENT = "TESTING"

Pass environment to tests

The environment setting can be fed to vitest: wrangler: { configPath: "./wrangler.toml", environment: "testing" }

Deploy

Caution

Always set the correct deploy flag when uploading the Cloudflare npx wrangler deploy -e prod. Get this wrong and you can override real production secrets.

[!INFO] Cloudflare suggest here treating your wrangler.toml file as the source of truth for your Worker configuration.

Debug

tail

console.log() output is available. Use the tail command in the cli tool. This also outputs Cloudflare added headers like cf-ipcountry, asn, ray-id, True IP.

wrangler tail foo

logs

When errors happened inside a Worker, the output to the console was limited:

[ERROR] Uncaught (async) Error: internal error

But the logs helped:

Logs were written to "/<home>/.wrangler/logs/wrangler-2024-11-16.log"
DNS lookup failed.

Workflows

You could start a backend workflow using a workflow; this was written using QStash from Upstash.

To test it locally, ngrok was used to route all of the Worker requests via ngrok. So you no longer went to localhost:8787/carpark. Instead you used: https://abcd.ngrok-free.app/carpark

Caution

This wouldn't work when other software were proxying client connections.

# start ngrok
ngrok http localhost:3001 --log=stdout

# set local environment .dev.vars
QSTASH_TOKEN="xxxx"
UPSTASH_WORKFLOW_URL="https://abcd.ngrok-free.app"

# inspect state of requests or local tunnelling
http://localhost:4040/inspect/http
http://localhost:4040/status

Architecture

End-2-End deployment workflow

sequenceDiagram

   participant Engineer
   participant GitHub
   participant CircleCI
   participant Cloudflare
   Engineer->>GitHub: code change
   GitHub->>CircleCI: assess change before deploying
   CircleCI->>CircleCI: set up Cloudflare's Wranger cli tool
   CircleCI->>CircleCI: Lint code
   CircleCI->>CircleCI: Test code 
   CircleCI->>Cloudflare: Wrangler cli uploads code change to Cloudflare with the deploy flag

Loading

Design choices

• Started on itty-router. But docs and testing were clearer with Hono.
• The app used Grouping of routers to slim down code into discrete files. Link here.
• Local dev connects to ngrox tunnelling.
• Setting the ENVIRONMENT variable needs to be handled; a great article here
• A Boilerplate on structuring project.
• The JWT work was based these helpers.