Learning

8.1 Workers and fetch(keepalive): the superset transport

The keepalive flag's specification, the fetch-groups exemption that lets requests outlive their context, and the exact capability trade against sendBeacon.

Levels: Advanced ~15 min read

Advanced

Workers cannot call sendBeacon — that fact is now old news in this series. What replaces it is not a compromise but a different tool with a wider handle and a weaker promise: fetch() with keepalive: true. This page reads the flag's actual specification, traces the mechanism that lets requests outlive their context, and inventories exactly what the superset gains and gives up.

The flag, in the spec's own words

"A request has an associated boolean keepalive. Unless stated otherwise it is false. This can be used to allow the request to outlive the environment settings object, e.g., navigator.sendBeacon() and the HTML img element use this." — Fetch, Requests

The mechanism behind those fourteen words sits in the fetch groups algorithm: when a group is terminated — the document discarded, the worker stopped — every in-flight request's controller is terminated unless its request's keepalive is true. That exemption is the entire survival trick, and it is the same one beacons rely on: a sendBeacon request and a hand-rolled fetch(keepalive) request are exempt from teardown by the same clause, draw from the same 64 KiB in-flight pool, and are indistinguishable to a service worker (as the detection page showed). The series' test suite verifies the worker side directly: inside a real dedicated worker, navigator.sendBeacon is undefined, fetch is present, and a fetch(keepalive) POST reaches a route-intercepted collector intact.

The superset advantages

The two keepalive transports compared; the last three rows are where decisions actually live.
Capability	sendBeacon	fetch(keepalive)
HTTP method	POST only, fixed	any method
Headers	none — Content-Type is derived	any headers via `RequestInit`
Response	never seen	full `Response` object
Credentials	forced `include`	omit / same-origin / include
Return signal	synchronous boolean	Promise
Flush on hidden	MUST, per the Beacon spec	not required by any spec
Shared 64 KiB pool	yes	yes — the same pool

Read the last three rows together and the shape of every later decision appears: the two transports differ in signal, guarantee, and synchrony — not in capacity. A hybrid that falls back from one to the other is choosing a different contract, not a different quota.

The sender recipe, with response handling

The runnable example is the reference sender for the superset side: one async function with the three RequestInit fields that matter, a result object mirroring the beacon's boolean shape (with status and body when available), and honest error routing — the stream-plus-keepalive TypeError surfaces synchronously from Request construction, while the quota refusal arrives later as a rejected promise. The injectable fetch lets the success path run under this page's network-blocking sandbox:

Interactive Runnable example

Edit

// fetch(keepalive) with response handling: the superset transport.
//
// What fetch(keepalive) offers that sendBeacon cannot:
//   - any HTTP method (sendBeacon is POST-only, by spec)
//   - any headers via RequestInit
//   - a Response you can read (sendBeacon never sees one)
//   - credentials of your choosing (sendBeacon forces 'include')
// What it gives up (spec facts):
//   - the MUST-flush-on-hidden guarantee (Beacon spec, sendBeacon only)
//   - the synchronous boolean (you get a Promise instead)
//
// Error modes, straight from the specs — note BOTH are async
// rejections from fetch(), not synchronous throws:
//   - ReadableStream body + keepalive  -> TypeError at Request
//     construction (synchronous, at call time)
//   - body over the 64 KiB in-flight pool -> "network error"
//     inside Fetch -> the promise REJECTS with a TypeError
//
// fetch is injectable for testing; the default is the real one.

async function sendKeepalive(url, data, opts = {}, deps = {}) {
  const f = deps.fetch || fetch;
  try {
    const response = await f(url, {
      method: opts.method || 'POST',
      body: data === null || data === undefined ? undefined : data,
      keepalive: true,
      headers: opts.headers,
      credentials: opts.credentials || 'include',
    });
    const body = await response.text().catch(() => '');
    return { queued: true, status: response.status, body };
  } catch (e) {
    // Rejection path: quota overflow becomes a network error;
    // this preview's CSP also rejects any real send — same path.
    return { queued: false, error: e && e.name };
  }
}

function sendJsonKeepalive(url, json, opts = {}, deps = {}) {
  return sendKeepalive(url, JSON.stringify(json), {
    ...opts,
    headers: { 'Content-Type': 'application/json', ...opts.headers },
  }, deps);
}

(async () => {
  // 1. Success path with a mocked fetch (the preview's CSP would
  //    block a real request — mocked transport shows the shape):
  const ok = await sendKeepalive('https://collect.example.com/x', 'hello', {}, {
    fetch: async () => new Response('stored', { status: 200 }),
  });
  console.log('mocked success   =>', JSON.stringify(ok));

// 2. The credentials default mirrors sendBeacon's forced
  //    'include' — observe what init actually carries:
  const seen = [];
  await sendKeepalive('https://collect.example.com/x', 'a', {}, {
    fetch: async (url, init) => {
      seen.push(init);
      return new Response(null, { status: 204 });
    },
  });
  console.log('default init     => method=' + seen[0].method,
    'keepalive=' + seen[0].keepalive,
    'credentials=' + seen[0].credentials);

// 3. JSON with a real Content-Type header — the thing sendBeacon
  //    cannot do without leaving no-cors territory:
  const json = await sendJsonKeepalive('https://collect.example.com/x',
    { a: 1 }, {}, {
      fetch: async (url, init) => {
        seen.push(init);
        return new Response(null, { status: 204 });
      },
    });
  console.log('json send        => queued=' + json.queued,
    '| content-type=' + seen[1].headers['Content-Type']);

// 4. The real fetch under this preview's CSP (connect-src 'none')
  //    -> the promise REJECTS. Same path quota overflow takes:
  const rejected = await sendKeepalive('https://collect.example.com/x', 'hi');
  console.log('CSP-blocked send =>', JSON.stringify(rejected));
})();

Ready to run.

Quick check

Inside a dedicated worker, which call can send telemetry that survives the worker's termination?

// inside a worker
?

Key takeaways

keepalive exempts a request from fetch-group termination — the survival mechanism beacons and keepalive fetches share.
Verified in the series' suite: a real worker has no sendBeacon, has fetch, and its keepalive POST arrives intact.
The superset: any method, any headers, a real Response, chosen credentials — at the cost of the MUST-flush guarantee and the sync boolean.
Error modes: stream bodies throw at Request construction; quota refusals reject the fetch promise with a TypeError.
Capacity is never the difference: both transports draw from the same 64 KiB in-flight pool.

Was this page helpful?

Yes No

Mark this learning resource complete to track your learning progress.

Suggest an edit