@statewalker/webrun-http-streams 0.3.2 → 0.4.0

package/README.md

@@ -112,7 +112,8 @@ const { envelope, body } = await httpFetch(call, {
 ```
 
 Signatures: `httpFetch(call, env, body?, { codec? })` and
-`httpServe(handler, { codec? })`. Over a real transport, `call` comes from an
+`httpServe(handler, { codec? })`; the handler is `(env, body, exchange) => result`, where
+`exchange.signal` aborts when the caller abandons the exchange (see below). Over a real transport, `call` comes from an
 adapter's `connect` and `httpServe(...)` goes to its `serve`.
 
 A relative `url` works but does not survive the round trip verbatim. HTTP/1.1
@@ -137,6 +138,40 @@ Both take an optional last argument `{ codec }`. `fetchOverDuplex` plumbs
 `request.signal` into body iteration, so aborting the signal ends the call. An
 already-aborted signal rejects before anything is sent.
 
+On the serving side, the handler's `request.signal` aborts when the exchange is abandoned before
+it is over — the caller aborted its fetch, stopped reading, or its transport went away, or the
+serving side tore the stream down (its timeout, a shutdown) — with `webrun-http-streams: the
+exchange was abandoned before it was over` (`EXCHANGE_ABANDONED_MESSAGE`). A handler that waits
+before it answers can stop then instead of holding on for nothing:
+
+```ts
+import { serveFetchOverDuplex } from "@statewalker/webrun-http-streams";
+
+// A long poll: answer in 30 s, or stop at once when the caller leaves.
+const handler = serveFetchOverDuplex(async (request) => {
+  if (!request.signal.aborted) {
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, 30_000);
+      request.signal.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer);
+          resolve();
+        },
+        { once: true },
+      );
+    });
+  }
+  return new Response(request.signal.aborted ? null : "news");
+});
+```
+
+Check `signal.aborted` before waiting: the exchange may already be abandoned when the handler
+runs. The exchange is over once the response went out in full and the handler is done with the
+request body; until then it can still be abandoned, so a handler that answers `202` first and
+reads the upload afterwards sees an abort if the upload is cut. A completed exchange never aborts.
+`newHttpServerStub` builds its requests without this signal.
+
 ### Site host: `DuplexSiteBuilder`
 
 ```ts
@@ -246,7 +281,7 @@ Check `err.name`, not `instanceof`; see
 
 | Export | What it is |
 | --- | --- |
-| `httpFetch`, `httpServe` | Data layer. Types: `HttpDataHandler`, `HttpDataHandlerResult`, `HttpDataOptions`, `HttpFetchResult`. |
+| `httpFetch`, `httpServe` | Data layer. Types: `HttpDataHandler`, `HttpDataHandlerResult`, `HttpDataOptions`, `HttpExchange`, `HttpFetchResult`; `EXCHANGE_ABANDONED_MESSAGE`. |
 | `fetchOverDuplex`, `serveFetchOverDuplex` | Fetch layer. |
 | `DuplexSiteBuilder`, `SiteHandler` | Site host over an adapter's `Serve<P>`. |
 | `newHttpClientStub`, `newHttpServerStub` | Transport-agnostic stubs. Types: `HttpHandler`, `SerializedHttpEnvelope`, `SerializedHttpRequest`, `SerializedHttpResponse`. |
@@ -332,6 +367,18 @@ producer's `finally` does not run. On a transport that multiplexes calls with a
 bounded stream table this holds one slot per such call. Closing it needs
 `httpFetch` to expose the call for cancellation.
 
+### How a handler that has not answered learns its caller left
+
+A transport tells the serving side a caller is gone by calling `return()` on the handler's
+output. On an async generator that call is queued behind the `next()` still pending inside it —
+the `await handler(request)` — so it would arrive only once the handler answered, which a long
+poll may never do. `httpServe` therefore hands the transport a generator whose `return()` and
+`throw()` abort the exchange's signal at once, then forward as usual; one that already finished
+aborts nothing. It relies on the transport calling `return()` without waiting for the pending
+`next()`: `@statewalker/webrun-rpc`'s `serve` and `@statewalker/webrun-streams-libp2p`'s `serve` do.
+A transport that only awaits `return()` after `next()` settles delivers the abandonment no
+earlier than the answer.
+
 ### Hop-by-hop headers are dropped at the fetch layer
 
 The codec surfaces every header verbatim. The fetch layer strips `connection`,

package/dist/fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAG1D,OAAO,EAAe,KAAK,eAAe,EAAwB,MAAM,gBAAgB,CAAC;AAsFzF;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,QAAQ,CAAC,CA4DnB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAChD,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAwER;AAED,wFAAwF;AACxF,eAAO,MAAM,uBAAuB,QAAS,CAAC"}
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAG1D,OAAO,EAAe,KAAK,eAAe,EAAwB,MAAM,gBAAgB,CAAC;AAsFzF;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,QAAQ,CAAC,CA4DnB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAChD,OAAO,GAAE,eAAoB,GAC5B,MAAM,CA0ER;AAED,wFAAwF;AACxF,eAAO,MAAM,uBAAuB,QAAS,CAAC"}

package/dist/http-data.d.ts

@@ -73,7 +73,26 @@ export interface HttpDataHandlerResult {
  * conventional `HttpHandler` used by `webrun-http-browser` and `SiteBuilder`
  * — see `http-stubs.ts` and `fetch.ts`.
  */
-export type HttpDataHandler = (env: RequestEnvelope, body: AsyncIterable<Uint8Array>) => Promise<HttpDataHandlerResult>;
+export type HttpDataHandler = (env: RequestEnvelope, body: AsyncIterable<Uint8Array>, exchange: HttpExchange) => Promise<HttpDataHandlerResult>;
+/** What a handler is told about the exchange it serves. */
+export interface HttpExchange {
+    /**
+     * Aborts when the exchange is abandoned before it is over: the caller gave
+     * up or its transport went away, or the serving side tore the stream down
+     * (its own timeout, a shutdown). A handler that waits before it answers (a
+     * long poll) can stop then. The exchange is over once the response went out
+     * in full and the handler is done with the request body: a handler that
+     * answers first and reads the upload afterwards still sees an abort if the
+     * upload is cut. A completed exchange never aborts.
+     */
+    signal: AbortSignal;
+}
+/**
+ * The reason of `HttpExchange.signal` when the exchange is abandoned with no
+ * error of its own (`return()`); one abandoned by `throw(error)` aborts with
+ * that error.
+ */
+export declare const EXCHANGE_ABANDONED_MESSAGE = "webrun-http-streams: the exchange was abandoned before it was over";
 /**
  * Initiate an HTTP call over a `Duplex`. The caller's `call: Duplex` is
  * obtained from any `webrun-streams-*` adapter's `connect`. Returns the

package/dist/http-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-data.d.ts","sourceRoot":"","sources":["../src/http-data.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAK1D,OAAO,KAAK,EACV,UAAU,EAEV,YAAY,EACZ,eAAe,EACf,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAEtB,gEAAgE;AAChE,eAAO,MAAM,iBAAiB,mBAAmB,CAAC;AAElD,MAAM,MAAM,eAAe,GAAG;IAC5B,gFAAgF;IAChF,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;IACxB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,KAC5B,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAgGpC;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,eAAe,EACpB,IAAI,CAAC,EAAE,UAAU,EACjB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CA0D1B;AAsBD,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAMtD;AA4CD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAqDzF"}
+{"version":3,"file":"http-data.d.ts","sourceRoot":"","sources":["../src/http-data.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAM1D,OAAO,KAAK,EACV,UAAU,EAEV,YAAY,EACZ,eAAe,EACf,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAEtB,gEAAgE;AAChE,eAAO,MAAM,iBAAiB,mBAAmB,CAAC;AAElD,MAAM,MAAM,eAAe,GAAG;IAC5B,gFAAgF;IAChF,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;IACxB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,EAC/B,QAAQ,EAAE,YAAY,KACnB,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAEpC,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,uEAC+B,CAAC;AAgGvE;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,eAAe,EACpB,IAAI,CAAC,EAAE,UAAU,EACjB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CA0D1B;AAsBD,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAMtD;AA4CD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CA8DzF"}

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { defaultCodec } from "./codec-default.js";
 export { DuplexSiteBuilder, type SiteHandler } from "./duplex-site-builder.js";
 export { decodeMessage, encodeMessage, jsonEnvelopeCodec, type RequestEnvelope, type ResponseEnvelope, } from "./envelope.js";
 export { fetchOverDuplex, serveFetchOverDuplex } from "./fetch.js";
-export { type HttpDataHandler, type HttpDataHandlerResult, type HttpDataOptions, type HttpFetchResult, httpFetch, httpServe, PEER_ERROR_HEADER, } from "./http-data.js";
+export { EXCHANGE_ABANDONED_MESSAGE, type HttpDataHandler, type HttpDataHandlerResult, type HttpDataOptions, type HttpExchange, type HttpFetchResult, httpFetch, httpServe, PEER_ERROR_HEADER, } from "./http-data.js";
 export { HttpError, type HttpErrorOptions } from "./http-error.js";
 export { type HttpHandler, newHttpClientStub, newHttpServerStub, type SerializedHttpEnvelope, type SerializedHttpRequest, type SerializedHttpResponse, } from "./http-stubs.js";
 export { type HttpCodecOptions, HttpParseError, httpCodec, newHttpCodec, } from "./http1/index.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EACL,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,SAAS,EACT,SAAS,EACT,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EACL,KAAK,WAAW,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,gBAAgB,EACrB,cAAc,EACd,SAAS,EACT,YAAY,GACb,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,UAAU,EACV,cAAc,EACd,eAAe,EACf,YAAY,EACZ,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EACL,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EACL,0BAA0B,EAC1B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,SAAS,EACT,SAAS,EACT,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EACL,KAAK,WAAW,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,gBAAgB,EACrB,cAAc,EACd,SAAS,EACT,YAAY,GACb,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,UAAU,EACV,cAAc,EACd,eAAe,EACf,YAAY,EACZ,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -800,6 +800,12 @@ function asyncDisposable(target, dispose) {
 //#region src/http-data.ts
 /** Carries the serialized JS error between two webrun peers. */
 const PEER_ERROR_HEADER = "x-webrun-error";
+/**
+* The reason of `HttpExchange.signal` when the exchange is abandoned with no
+* error of its own (`return()`); one abandoned by `throw(error)` aborts with
+* that error.
+*/
+const EXCHANGE_ABANDONED_MESSAGE = "webrun-http-streams: the exchange was abandoned before it was over";
 /** Hard cap on the peer-error header (M3): see `encodeErrorResponse`. */
 const MAX_DETAIL_CHARS = 4096;
 /**
@@ -980,7 +986,11 @@ async function drain(output) {
 */
 function httpServe(handler, options = {}) {
 	const codec = options.codec ?? defaultCodec;
-	return async function* httpHandlerDuplex(input) {
+	return (input) => {
+		const abandoned = new AbortController();
+		return abortingOnReturn(exchange(input, { signal: abandoned.signal }), (reason) => abandoned.abort(reason ?? /* @__PURE__ */ new Error("webrun-http-streams: the exchange was abandoned before it was over")));
+	};
+	async function* exchange(input, context) {
 		let decoded;
 		try {
 			decoded = await codec.decodeRequest(input);
@@ -992,7 +1002,7 @@ function httpServe(handler, options = {}) {
 		const replyCodec = decoded.codec ?? codec;
 		let result;
 		try {
-			result = await handler(decoded.envelope, decoded.body);
+			result = await handler(decoded.envelope, decoded.body, context);
 		} catch (error) {
 			yield* encodeErrorResponse(replyCodec, error, decoded.envelope.method);
 			return;
@@ -1007,7 +1017,36 @@ function httpServe(handler, options = {}) {
 				await result.release?.();
 			} catch {}
 		}
+	}
+}
+/**
+* `gen`, except that `return()` and `throw()` from its consumer call `abandon`
+* at once — before they are queued behind a `next()` still parked inside the
+* generator (the handler's `await`) — unless the generator already finished.
+*/
+function abortingOnReturn(gen, abandon) {
+	let finished = false;
+	const settle = (r) => {
+		if (r.done) finished = true;
+		return r;
+	};
+	const wrapped = {
+		next: (...args) => gen.next(...args).then(settle),
+		return(value) {
+			if (!finished) abandon();
+			finished = true;
+			return gen.return(value);
+		},
+		throw(error) {
+			if (!finished) abandon(error);
+			finished = true;
+			return gen.throw(error);
+		},
+		[Symbol.asyncIterator]() {
+			return wrapped;
+		}
 	};
+	return asyncDisposable(wrapped, () => wrapped.return(void 0));
 }
 //#endregion
 //#region src/request-streams.ts
@@ -1285,10 +1324,11 @@ async function fetchOverDuplex(call, request, options = {}) {
 * registered with any `webrun-streams-*` adapter's `serve`.
 */
 function serveFetchOverDuplex(handler, options = {}) {
-	return httpServe(async (env, body) => {
+	return httpServe(async (env, body, exchange) => {
 		const reqInit = {
 			method: env.method,
-			headers: forwardableHeaders(env.headers)
+			headers: forwardableHeaders(env.headers),
+			signal: exchange?.signal
 		};
 		let upload;
 		if (env.method !== "GET" && env.method !== "HEAD") {
@@ -1584,4 +1624,4 @@ var HttpError = class HttpError extends Error {
 	}
 };
 //#endregion
-export { DuplexSiteBuilder, HttpError, HttpParseError, PEER_ERROR_HEADER, decodeMessage, defaultCodec, encodeMessage, fetchOverDuplex, httpCodec, httpFetch, httpServe, jsonEnvelopeCodec, newHttpClientStub, newHttpCodec, newHttpServerStub, newSniffingCodec, serveFetchOverDuplex };
+export { DuplexSiteBuilder, EXCHANGE_ABANDONED_MESSAGE, HttpError, HttpParseError, PEER_ERROR_HEADER, decodeMessage, defaultCodec, encodeMessage, fetchOverDuplex, httpCodec, httpFetch, httpServe, jsonEnvelopeCodec, newHttpClientStub, newHttpCodec, newHttpServerStub, newSniffingCodec, serveFetchOverDuplex };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-http-streams",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "description": "HTTP request/response over a webrun-streams Duplex, encoded as HTTP/1.1, plus transport-agnostic fetch stubs",

package/src/fetch.ts

@@ -166,10 +166,12 @@ export function serveFetchOverDuplex(
   handler: (request: Request) => Promise<Response>,
   options: HttpDataOptions = {},
 ): Duplex {
-  return httpServe(async (env, body) => {
+  return httpServe(async (env, body, exchange) => {
     const reqInit: RequestInit = {
       method: env.method,
       headers: forwardableHeaders(env.headers),
+      // Aborts when the caller abandons the exchange (see `HttpExchange`).
+      signal: exchange?.signal,
     };
     let upload: ReturnType<typeof trackingEnd> | undefined;
     if (env.method !== "GET" && env.method !== "HEAD") {

package/src/http-data.ts

@@ -1,5 +1,6 @@
 import type { Duplex } from "@statewalker/webrun-streams";
 import { deserializeError, serializeError } from "@statewalker/webrun-streams";
+import { asyncDisposable } from "./async-dispose.js";
 import { discard } from "./bytes.js";
 import { defaultCodec } from "./codec-default.js";
 import { HttpParseError } from "./http1/errors.js";
@@ -91,8 +92,31 @@ export interface HttpDataHandlerResult {
 export type HttpDataHandler = (
   env: RequestEnvelope,
   body: AsyncIterable<Uint8Array>,
+  exchange: HttpExchange,
 ) => Promise<HttpDataHandlerResult>;
 
+/** What a handler is told about the exchange it serves. */
+export interface HttpExchange {
+  /**
+   * Aborts when the exchange is abandoned before it is over: the caller gave
+   * up or its transport went away, or the serving side tore the stream down
+   * (its own timeout, a shutdown). A handler that waits before it answers (a
+   * long poll) can stop then. The exchange is over once the response went out
+   * in full and the handler is done with the request body: a handler that
+   * answers first and reads the upload afterwards still sees an abort if the
+   * upload is cut. A completed exchange never aborts.
+   */
+  signal: AbortSignal;
+}
+
+/**
+ * The reason of `HttpExchange.signal` when the exchange is abandoned with no
+ * error of its own (`return()`); one abandoned by `throw(error)` aborts with
+ * that error.
+ */
+export const EXCHANGE_ABANDONED_MESSAGE =
+  "webrun-http-streams: the exchange was abandoned before it was over";
+
 /** Hard cap on the peer-error header (M3): see `encodeErrorResponse`. */
 const MAX_DETAIL_CHARS = 4096;
 
@@ -337,7 +361,16 @@ async function drain(output: AsyncGenerator<Uint8Array>): Promise<void> {
  */
 export function httpServe(handler: HttpDataHandler, options: HttpDataOptions = {}): Duplex {
   const codec = options.codec ?? defaultCodec;
-  return async function* httpHandlerDuplex(input) {
+  return (input) => {
+    const abandoned = new AbortController();
+    return abortingOnReturn(exchange(input, { signal: abandoned.signal }), (reason) =>
+      abandoned.abort(reason ?? new Error(EXCHANGE_ABANDONED_MESSAGE)),
+    );
+  };
+  async function* exchange(
+    input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
+    context: HttpExchange,
+  ): AsyncGenerator<Uint8Array> {
     // A refusal to parse the request must still produce a response. Left
     // uncaught, the exception propagates out of this generator and NOTHING is
     // written — a real peer waits, then sees the connection end with no status
@@ -366,7 +399,7 @@ export function httpServe(handler: HttpDataHandler, options: HttpDataOptions = {
     const replyCodec = decoded.codec ?? codec;
     let result: HttpDataHandlerResult;
     try {
-      result = await handler(decoded.envelope, decoded.body);
+      result = await handler(decoded.envelope, decoded.body, context);
     } catch (error) {
       yield* encodeErrorResponse(replyCodec, error, decoded.envelope.method);
       return;
@@ -387,5 +420,39 @@ export function httpServe(handler: HttpDataHandler, options: HttpDataOptions = {
         }
       }
     }
+  }
+}
+
+/**
+ * `gen`, except that `return()` and `throw()` from its consumer call `abandon`
+ * at once — before they are queued behind a `next()` still parked inside the
+ * generator (the handler's `await`) — unless the generator already finished.
+ */
+function abortingOnReturn<T>(
+  gen: AsyncGenerator<T>,
+  abandon: (reason?: unknown) => void,
+): AsyncGenerator<T> {
+  let finished = false;
+  const settle = (r: IteratorResult<T>) => {
+    if (r.done) finished = true;
+    return r;
+  };
+  const wrapped: AsyncGenerator<T> = {
+    next: (...args: [] | [unknown]) => gen.next(...args).then(settle),
+    return(value) {
+      if (!finished) abandon();
+      finished = true;
+      return gen.return(value);
+    },
+    throw(error) {
+      if (!finished) abandon(error);
+      finished = true;
+      return gen.throw(error);
+    },
+    [Symbol.asyncIterator]() {
+      return wrapped;
+    },
   };
+  // `await using` ends it as leaving a `for await` early does.
+  return asyncDisposable(wrapped, () => wrapped.return(undefined));
 }

package/src/index.ts

@@ -9,9 +9,11 @@ export {
 } from "./envelope.js";
 export { fetchOverDuplex, serveFetchOverDuplex } from "./fetch.js";
 export {
+  EXCHANGE_ABANDONED_MESSAGE,
   type HttpDataHandler,
   type HttpDataHandlerResult,
   type HttpDataOptions,
+  type HttpExchange,
   type HttpFetchResult,
   httpFetch,
   httpServe,