Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท Workers

Workers Subrequests, fetch() and the Cache API

Call origins and APIs with fetch() from a Worker, control edge caching with cf options and the Cache API, use waitUntil for background work and avoid subrequest limits.

A Worker rarely answers everything itself. It often calls another service: your origin server, a third-party API, another Worker. Each fetch() call from inside a Worker is a subrequest. This lesson covers how to make them, how to cache their results at the edge, and how to keep slow work off the critical path.

Proxying to an origin

The simplest useful Worker forwards a request and tweaks something on the way:

JavaScript
export default {
  async fetch(request) {
    const url = new URL(request.url);
    url.hostname = "origin.example.com";        // send it somewhere else

    const upstream = new Request(url, request); // copy method, headers, body
    upstream.headers.set("x-forwarded-by", "worker");

    const response = await fetch(upstream);
    const out = new Response(response.body, response);   // make headers mutable
    out.headers.set("x-served-by", "edge");
    return out;
  },
};

Two details matter. new Request(url, request) clones the incoming request with a new URL, and new Response(body, response) makes a copy whose headers you may edit, because responses returned by fetch() are immutable.

Caching with the cf options

The cheapest way to cache a subrequest is the Cloudflare-specific second argument to fetch():

JavaScript
const res = await fetch("https://api.example.com/products", {
  cf: {
    cacheEverything: true,     // cache even types Cloudflare normally skips (JSON, HTML)
    cacheTtl: 300,             // keep it 5 minutes at the edge
    cacheTtlByStatus: { "200-299": 300, "404": 30, "500-599": 0 },
    cacheKey: "products-v1",   // custom cache key (optional)
  },
});

This uses the same edge cache you configured in the CDN chapter, in the data center that handled the request. Each data center has its own copy, so a popular URL is fetched from your origin at most once per location per TTL, not once per visitor.

The Cache API

When you want to decide yourself what is stored and when, use the Cache API (caches.default or a named cache). The pattern is "look up, otherwise fetch and store":

JavaScript
export default {
  async fetch(request, env, ctx) {
    const cache = caches.default;
    const key = new Request(new URL(request.url).toString(), { method: "GET" });

    let response = await cache.match(key);
    if (response) return response;                       // HIT

    response = await fetch("https://api.example.com/data");
    response = new Response(response.body, response);    // mutable copy
    response.headers.set("cache-control", "public, max-age=60");

    ctx.waitUntil(cache.put(key, response.clone()));     // store without delaying the reply
    return response;                                     // MISS
  },
};

Three rules: the cache key must be a GET request, the response needs a usable Cache-Control (the TTL comes from it), and cache.put stores only in the current data center (it is not global). The Cache API does not work on workers.dev domains: it needs your own zone on a custom domain.

waitUntil: work after the response

ctx.waitUntil(promise) tells the runtime "keep this alive after you send the response". It is how you write to a cache, send analytics or call a webhook without making the visitor wait. A promise you do not await and do not pass to waitUntil may be cancelled as soon as the response is delivered.

JS A cache with waitUntil (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The output shows the point of caching: four requests, only two origin calls, and only visitors who arrive after the TTL pay for a refresh.

Subrequest limits and good manners

A single invocation may make a limited number of subrequests (a lower number on the free plan than on paid plans; check the current Limits page). Design for fewer calls:

  • Cache what you can instead of calling every time.
  • Fetch independent resources in parallel with Promise.all.
  • Avoid loops that call an API once per item; use a batch endpoint.
  • Remember that calls to your own KV, R2 and D1 bindings have their own, separate limits.

Also set a timeout. A hanging origin keeps your request open, so use an AbortSignal:

JavaScript
const res = await fetch(url, { signal: AbortSignal.timeout(3000) });

Fetching in parallel

JS Sequential vs parallel subrequests

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why do you write new Response(upstream.body, upstream) before editing headers?

    The Response returned by fetch() is immutable. Constructing a new one from its body and init gives you editable headers.
  2. 2. What is ctx.waitUntil() for?

    waitUntil keeps the invocation alive for work such as cache writes or analytics so the visitor does not wait for it.
  3. 3. Where does cache.put() store a response?

    The Cache API is per data center. A different location has its own cache and may miss until it is filled.
  4. 4. Which option best reduces origin load for a JSON API response that changes every few minutes?

    cacheEverything with a TTL lets the edge answer repeats without touching the origin until the TTL expires.

Summary

  • Each fetch() in a Worker is a subrequest; proxying means copying the request with a new URL and the response into a mutable one.
  • cf options (cacheEverything, cacheTtl, cacheTtlByStatus, cacheKey) give simple edge caching for subrequests.
  • The Cache API (caches.default) gives full control, is per data center, needs a custom domain and Cache-Control TTLs.
  • ctx.waitUntil runs work after the response; use Promise.all and timeouts to stay under subrequest limits.

Next: Wrangler, Deploying and Environments