Skip to main content
Version: 4.3.0

FetchEvent.handoffRequest()

handoffRequest() forwards the eventual result of an upstream fetch() to the downstream client. When the request is eligible, the host takes over delivery without waiting for JavaScript to receive and forward the response.

When To Use Handoff​

Use handoff for proxy-style handlers that make routing, authentication, or request header decisions before contacting an origin, then forward its response without inspecting its status or body. It is particularly useful for slow origins and long downloads: an eligible pending request can continue after the runtime has finished its work, allowing sandbox resources to be released or reused earlier. Handoff does not make the origin respond sooner.

Use respondWith() instead when JavaScript must inspect the upstream status, transform the response body, retry a failed request, or choose a custom error response. Handoff transfers responsibility for the response; it does not provide a second opportunity to handle the result in JavaScript.

addEventListener('fetch', (event) => {
const response = fetch(event.request, { backend: 'origin' });
setResponseHeader(response, 'x-proxy', 'compute');
removeResponseHeader(response, 'x-internal-origin', 'response');
event.handoffRequest(response);
});

Note the lack of an await or .then() before calling handoffRequest(). You pass the promise returned by fetch() directly to handoffRequest().

Syntax And Lifetime​

event.handoffRequest(responsePromise);

Pass the original promise returned directly by fetch(). An async wrapper or .then() produces another promise without the pending-request metadata, so it cannot use direct handoff or the fetch-promise header helpers.

Call handoffRequest() synchronously within the fetch event handler, before returning or awaiting anything. It returns undefined. Choose either handoffRequest() or respondWith() for an event, not both.

Do not rely on the fetch promise settling after a direct handoff: the host owns the pending response and the runtime no longer resolves that promise. In particular, do not pass it to waitUntil(). Independent work registered with waitUntil() can still keep the runtime alive, so handoff does not guarantee immediate sandbox completion.

When Direct Handoff Is Unavailable​

Not every fetch has a transferable host pending request. For example, guest-side cache fills must complete cache processing in the runtime, cached responses may already be available, and JavaScript-streamed request bodies need the runtime to finish their upload.

In those cases, handoffRequest() uses the same promise reactions as respondWith(): it keeps the event alive until the promise settles, applies queued header operations, and sends the resulting response. This fallback does not release the runtime early. A rejected promise produces the runtime's normal 500 error response. For direct handoff, the host sends the eventual origin response or its synthetic error response.

An error while attempting the transfer itself is reported to JavaScript rather than silently retrying delivery through the promise path.

Adjusting Response Headers​

Queue header operations on the original fetch promise before handing it off:

setResponseHeader(responsePromise, name, value, target);
appendResponseHeader(responsePromise, name, value, target);
removeResponseHeader(responsePromise, name, target);

setResponseHeader() replaces existing values, appendResponseHeader() preserves existing values and adds another, and removeResponseHeader() deletes the header. The optional target selects which outcome receives the operation:

TargetApplies To
'response'An upstream response, including HTTP statuses such as 404 and 500.
'error'A synthetic response caused by a fetch failure, such as a connection failure.
'any' (default)Either outcome.

An HTTP 500 received from the origin is a fulfilled fetch response, not a rejected promise, so it uses the 'response' operations. For example:

setResponseHeader(response, 'x-upstream-result', 'received', 'response');
setResponseHeader(response, 'x-upstream-result', 'failed', 'error');
setResponseHeader(response, 'access-control-allow-origin', '*');
event.handoffRequest(response);