Cloudflare Docs
Workers
Visit Workers on GitHub
Set theme to dark (⇧+D)

Fetch Handler

​​ Background

Incoming HTTP requests to a Worker are passed to the fetch() handler as a request object. To respond to the request with a response, return a Response object:


export default {
async fetch(request, env, ctx) {
return new Response('Hello World!');
},
};

​​ Parameters

  • request Request

    • The incoming HTTP request.
  • env object

    • The bindings assigned to the Worker. As long as the environment has not changed, the same object (equal by identity) is passed to all requests.
  • context.waitUntil(promisePromise) : void

  • context.passThroughOnException() : void


​​ Lifecycle methods

When responding to a HTTP request, the fetch handler may use any of the following methods to augment or control how the request is handled.

​​ context.waitUntil()

The waitUntil() method extends the lifetime of the fetch event. It accepts a Promise-based task which the Workers runtime will execute before the handler terminates but without blocking the response. For example, this is ideal for caching responses or handling logging.


export default {
async fetch(request, env, context) {
// Forward / Proxy original request
let res = await fetch(request);
// Add custom header(s)
res = new Response(res.body, res);
res.headers.set('x-foo', 'bar');
// Cache the response
// NOTE: Does NOT block / wait
context.waitUntil(caches.default.put(request, res.clone()));
// Done
return res;
},
};

​​ context.passThroughOnException()

The passThroughOnException method allows a a Worker to fail open, and pass a request through to an origin server when a Worker throws an unhandled exception. This can be useful when using Workers as a layer in front of an existing service, allowing the service behind the Worker to handle any unexpected error cases that arise in your Worker.


export default {
async fetch(request, env, context) {
// Proxy to origin on unhandled/uncaught exceptions
context.passThroughOnException();
throw new Error('Oops');
},
};