Using workers

Writing a worker

Add a <script type=worker> element and export a fetch() handler. The handler receives a Request and returns a Response, as in a service worker or a Cloudflare Worker.

<iframe src=:hello></iframe>
<script type=worker edge>
  export default {
    fetch: request => new Response(`Hello from ${new URL(request.url).pathname}`)
  }
</script>

Three forms of the handler work: fetch(request, env, ctx) { … }, async fetch(request, env, ctx) { … } and fetch: (request, env, ctx) => …. Keep fetch as the only property of export default. Handler forms lists what else the transform accepts and what it rejects.

Calling the worker

Prefix a path with : to reach the worker. Everything after the first : becomes the pathname that the worker sees, and the query string is kept:

On RTEdge.net, the text before the first : also selects the route, so /app/: calls the worker of the route name/app.

In HTML and JavaScript, write the colon first: <iframe src=:>, fetch(':api') or new EventSource(':sse'). A reference such as api:x is read as a URL scheme. ./a:b works, and the worker sees /b. Fragments never reach the worker.

<output id=out></output>
<script type=module>
  const { greeting } = await fetch(':api/greet?name=Ada').then(r => r.json())
  out.value = greeting
</script>
<script type=worker edge>
  export default {
    fetch: request => {
      const { pathname, searchParams } = new URL(request.url)
      if (pathname !== '/api/greet') return new Response('Not found', { status: 404 })
      return Response.json({ greeting: `Hello, ${searchParams.get('name') ?? 'world'}!` })
    }
  }
</script>

What a worker receives

The handler is called with three arguments:

• request is a standard Request with the platform's rt property: the signed-in user, the client IP address, the domain and route, and where the code runs.
• env is exactly { KV, FS }: key–value storage and the assets that you declare with worker:fs.
• ctx is the execution context. ctx.waitUntil(promise) keeps the worker alive for background work in both runtimes.

Several worker scripts

A page may have more than one worker script. The playground joins the text of all of them, in document order, into one program, and runs it. Only the first script's edge, fetch, io:host and io:fail attributes count, so put them there. The scripts must stay one valid program: two export default statements across scripts make every request fail.

On RTEdge.net, only the edge scripts are merged, in document order, into the worker of the route. A deploy of a page with no edge script deletes the route's existing worker.

Data and assets

Use env.KV for data that must outlive a request, and env.FS for files that only the worker should read:

export default {
  fetch: async (request, { KV, FS }) => {
    const { user } = request.rt
    if (!user) return new Response('Sign in first', { status: 401 })
    const kv = KV.open({ user })                       // call it, never await it
    await kv.put('last-seen', new Date().toISOString())
    return new Response(FS['greeting.txt'].body)       // a worker:fs asset
  }
}

Always check request.rt.user before you open per-user storage: a null user opens the scope that all visitors share. See Storing data in KV.

Making outbound requests

A worker calls other servers with fetch(). Use absolute URLs, such as https://api.example.com/v1/x, or protocol-relative ones such as //api.example.com/v1/x, so that the code works in both places.

• In the playground, the fetch() of a worker is a browser fetch. CORS applies to cross-origin reads, headers such as Cookie, Host and User-Agent cannot be set, and credentials default to same-origin. Relative URLs resolve against the output origin: ::su and the files you export are answered live, and everything else goes to the network. A request from the worker never re-enters the worker, so fetch(':other') inside a worker reaches out.rtcode.io and gets a 404.
• On RTEdge.net, the wrapper patches fetch(): //host/x becomes https://host/x, and relative URLs fail. To reach files of your page, use env.FS. To call another deployment, use https://in.rt.ht/<route>/<path>. Every outbound request passes through a platform outbound worker, and TCP sockets with connect() are not available. See Outbound requests.

The playground and RTEdge.net

The same worker code behaves differently in these areas:

Treat these differences as features: the playground gives you a fast loop and fakes what it can, and RTEdge.net runs the real thing. Test the behaviours you depend on after you deploy.

Deploying a worker

Give the script edge and deploy with Ctrl+S / ⌘+S. The playground bundles static imports first, and RTEdge.net uploads one worker for the route. After a successful upload, a second toast links to name.rt.ht/:, the root of the worker. Errors from the upload appear as separate toasts. Call the worker with a : URL, such as https://name.rt.ht/:api/greet?name=Ada.

• A deployment with an edge worker has a private source: only the owner, the editors and io:user permits can open it with ?. Add io:guest to every edge script to keep it public.
• Every <script type=worker> is blanked out of the served page. edge:redact and edge:remove change only the served HTML, so keep secrets inside a private worker; see Keeping secrets out of deployments.
• The worker keeps the wrapper version of the day it was deployed. Redeploy to pick up platform changes; see The edge worker runtime.
• By default, an account can have edge workers on up to 5 routes; see Limits and quotas.

Logging and errors

In the playground, calls to console in worker code appear in the playground console with the 🛎️⚙️ prefix, and the network panel lists every request that the worker handled. A failed worker either gives an HTTP 500 with a stack or a network error, and io:fail=open forwards the request to the network instead; see Failing open or closed.

On RTEdge.net, an uncaught exception shows a 500 page, an undefined response a 501 page, and a : call to a route without a worker a 404 page. See Error pages. The console output of a deployed worker is not part of the response. Tail logs Experimental collect it; see Usage and tail logs.

Mistakes to avoid

• Writing export default { fetch } or fetch: async function () {}, adding other properties, or adding other export statements.
• Putting await in front of env.KV.open(), or opening per-user storage for a visitor who is not signed in.
• Calling fetch() at the top level of the module, and keeping important state in module variables.
• Fetching a relative URL from a worker that you deploy.
• Leaving a worker script empty, or ending it with a // comment right before </script>.
• Relying on edge:user to protect a : URL.

Module scope and state explains why each of these fails.

See also

• <script type=worker>
• The fetch() handler
• Request.rt
• env
• KVNamespace
• Storing data in KV
• Mocking third-party APIs
• Importing modules and WebAssembly
• The edge worker runtime
• Building a full-stack app