Document Request.signal

Author: npaun

src/content/changelog/workers/2025-03-14-handle-request-cancellation.mdx

@@ -0,0 +1,43 @@
+---
+title: Handle request cancellation with Request.signal
+description: Workers can now add event listeners on Request.signal and perform tasks when the request is cancelled
+products:
+  - workers
+date: 2025-03-14T01:00:00Z
+---
+
+import { Render, TypeScriptExample } from "~/components";
+
+`Request` objects now have a `signal` property. You can now attach an event listener to the `signal` and perform tasks when the request to your Worker is canceled by the client.
+
+This lets you do things like clean up after the request or write to logs before your Worker is aborted.
+
+<TypeScriptExample filename="index.ts">
+```ts
+import { WorkerEntrypoint } from 'cloudflare:workers'; 
+
+class Example extends WorkerEntrypoint {
+  async fetch(req: Request): Response {
+    req.signal.onabort = () => {
+      console.log('The request was aborted!');
+    };
+
+    const { readable, writable } = new IdentityTransformStream();
+    this.ctx.waitUntil(this.sendPing(writable));
+    return new Response(readable);
+  }
+
+  async sendPing(writable: WritableStream): void {
+     const writer = writable.getWriter();
+     const enc = new TextEncoder();
+
+     for (;;) {
+       // Send 'ping' every second to keep the connection alive
+       await writer.write(enc.encode('ping')); 
+       scheduler.wait(1000);
+     }
+  }
+}
+</TypeScriptExample>
+
+For more information see the [`Request` documentation](/workers/runtime-apis/request).

src/content/compatibility-flags/request-signal-passthrough.md

@@ -0,0 +1,15 @@
+---
+_build: 
+  publishResources: false
+  render: never
+  list: never
+
+name: "Request.signal is passed through to subrequests"
+sort_date: "2025-03-14"
+enable_date: "request_signal_passthrough"
+disable_date: "no_request_signal_passthrough"
+---
+
+When this flag is enabled, the `signal` property of the incoming request to a Worker follows Web-standard behaviour, and will be passed through when the request is cloned, or a new request is created from it. As a result, if the incoming request is canceled by the client, all outgoing subrequests will also be canceled, unless the `signal` property is explicitly modified or cleared.
+
+Because support for Request.signal was recently added to Cloudflare Workers, this behaviour will not apply to existing Workers, and can also be disabled by setting `no_request_signal_passthrough`.

src/content/docs/workers/runtime-apis/request.mdx

@@ -88,6 +88,8 @@ An object containing properties that you want to apply to the request.
 
   * The redirect mode to use: `follow`, `error`, or `manual`. The default  for a new `Request` object is `follow`. Note, however, that the incoming `Request` property of a `FetchEvent` will have redirect mode `manual`.
 
+* `signal` AbortSignal optional
+  * If provided, the request can be canceled by triggering an abort on the corresponding `AbortController`.
 
 
 #### The `cf` property (`RequestInitCfProperties`)
@@ -194,6 +196,9 @@ All properties of an incoming `Request` object (the request you receive from the
 
   * The redirect mode to use: `follow`, `error`, or `manual`. The `fetch` method will automatically follow redirects if the redirect mode is set to `follow`. If set to `manual`, the `3xx` redirect response will be returned to the caller as-is. The default for a new `Request` object is `follow`. Note, however, that the incoming `Request` property of a `FetchEvent` will have redirect mode `manual`.
 
+* `signal` AbortSignal read-only
+  * The `AbortSignal` corresponding to this request. By attaching an event listener to the signal, a Worker can take action when the request made to it is canceled by the client. For example, the Worker may write log entries or perform cleanup tasks before being aborted.
+
 * `url` string read-only
 
   * Contains the URL of the request.