@statewalker/webrun-http-streams 0.3.1 → 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
@@ -1278,17 +1317,18 @@ async function fetchOverDuplex(call, request, options = {}) {
 		else await release?.();
 		return new Response(null, responseInit);
 	}
-	return new Response(asyncIterableToReadable(withAbort(respBody, request.signal)), responseInit);
+	return new Response(responseBody(respBody, request.signal, release), responseInit);
 }
 /**
 * Wrap a `(Request) => Promise<Response>` handler as a `Duplex` so it can be
 * 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") {
@@ -1409,15 +1449,78 @@ function trackingEnd(source) {
 		settle
 	};
 }
-async function* withAbort(iter, signal) {
-	if (!signal) {
-		yield* iter;
-		return;
-	}
-	for await (const chunk of iter) {
-		if (signal.aborted) throw abortReason(signal);
-		yield chunk;
-	}
+/**
+* How long a cancelled body waits for the read in flight before it abandons the call anyway.
+* The read's answer tells a body that has ended (the call is finished: an upload the handler
+* reads after answering goes on) from one that has not; a peer that sends nothing more never
+* answers it. A body whose end comes later than this after the cancel is abandoned too, so a
+* handler still streaming its response and still reading the upload then loses the upload.
+*/
+const CANCEL_GRACE_MS = 1e3;
+/**
+* The response body as a stream that the request's signal can end at any time.
+*
+* An abort errors the stream with the abort's reason at once — a read waiting
+* for a peer that sends nothing more rejects then, not when a next chunk
+* arrives, which may be never — and abandons the call (`release`), so on a
+* multiplexed transport its port is given back whether or not anyone still
+* reads the body. The listener is removed once the body ends, however it ends:
+* read to its end, cancelled, failed or aborted. A body nobody reads or cancels
+* keeps it until the signal aborts (and keeps the call open until then anyway).
+* A cancel abandons the call too — unless the read in flight comes back with the
+* body's end, which finishes it instead (see `cancel`).
+*/
+function responseBody(body, signal, release) {
+	const it = body[Symbol.asyncIterator]();
+	let controller;
+	let ended = false;
+	let reading = false;
+	const end = () => {
+		ended = true;
+		signal?.removeEventListener("abort", onAbort);
+	};
+	const onAbort = () => {
+		if (ended) return;
+		end();
+		try {
+			controller.error(abortReason(signal));
+		} catch {}
+		release?.();
+	};
+	return new ReadableStream({
+		start(c) {
+			controller = c;
+			if (signal?.aborted) onAbort();
+			else signal?.addEventListener("abort", onAbort, { once: true });
+		},
+		async pull(c) {
+			try {
+				reading = true;
+				const { done, value } = await it.next().finally(() => {
+					reading = false;
+				});
+				if (ended) return;
+				if (done) {
+					end();
+					c.close();
+					return;
+				}
+				c.enqueue(value);
+			} catch (err) {
+				if (ended) return;
+				end();
+				c.error(err);
+			}
+		},
+		cancel() {
+			end();
+			const returned = Promise.resolve(it.return?.()).catch(() => {});
+			if (!reading) return;
+			const grace = setTimeout(() => void release?.(), CANCEL_GRACE_MS);
+			grace.unref?.();
+			returned.finally(() => clearTimeout(grace));
+		}
+	});
 }
 //#endregion
 //#region src/duplex-site-builder.ts
@@ -1521,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.1",
+  "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

@@ -155,7 +155,7 @@ export async function fetchOverDuplex(
     else await release?.();
     return new Response(null, responseInit);
   }
-  return new Response(asyncIterableToReadable(withAbort(respBody, request.signal)), responseInit);
+  return new Response(responseBody(respBody, request.signal, release), responseInit);
 }
 
 /**
@@ -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") {
@@ -329,16 +331,88 @@ function trackingEnd(source: AsyncIterable<Uint8Array>): {
   return { source: tracked, settle };
 }
 
-async function* withAbort(
-  iter: AsyncIterable<Uint8Array>,
+/**
+ * How long a cancelled body waits for the read in flight before it abandons the call anyway.
+ * The read's answer tells a body that has ended (the call is finished: an upload the handler
+ * reads after answering goes on) from one that has not; a peer that sends nothing more never
+ * answers it. A body whose end comes later than this after the cancel is abandoned too, so a
+ * handler still streaming its response and still reading the upload then loses the upload.
+ */
+const CANCEL_GRACE_MS = 1_000;
+
+/**
+ * The response body as a stream that the request's signal can end at any time.
+ *
+ * An abort errors the stream with the abort's reason at once — a read waiting
+ * for a peer that sends nothing more rejects then, not when a next chunk
+ * arrives, which may be never — and abandons the call (`release`), so on a
+ * multiplexed transport its port is given back whether or not anyone still
+ * reads the body. The listener is removed once the body ends, however it ends:
+ * read to its end, cancelled, failed or aborted. A body nobody reads or cancels
+ * keeps it until the signal aborts (and keeps the call open until then anyway).
+ * A cancel abandons the call too — unless the read in flight comes back with the
+ * body's end, which finishes it instead (see `cancel`).
+ */
+function responseBody(
+  body: AsyncIterable<Uint8Array>,
   signal: AbortSignal | undefined,
-): AsyncGenerator<Uint8Array> {
-  if (!signal) {
-    yield* iter;
-    return;
-  }
-  for await (const chunk of iter) {
-    if (signal.aborted) throw abortReason(signal);
-    yield chunk;
-  }
+  release: (() => Promise<void>) | undefined,
+): ReadableStream<Uint8Array> {
+  const it = body[Symbol.asyncIterator]();
+  let controller!: ReadableStreamDefaultController<Uint8Array>;
+  let ended = false;
+  let reading = false;
+  const end = () => {
+    ended = true;
+    signal?.removeEventListener("abort", onAbort);
+  };
+  const onAbort = () => {
+    if (ended) return;
+    end();
+    try {
+      controller.error(abortReason(signal as AbortSignal));
+    } catch {
+      /* already closed or errored */
+    }
+    void release?.();
+  };
+  return new ReadableStream<Uint8Array>({
+    start(c) {
+      controller = c;
+      if (signal?.aborted) onAbort();
+      else signal?.addEventListener("abort", onAbort, { once: true });
+    },
+    async pull(c) {
+      try {
+        reading = true;
+        const { done, value } = await it.next().finally(() => {
+          reading = false;
+        });
+        if (ended) return; // aborted or cancelled while this read waited
+        if (done) {
+          end();
+          c.close();
+          return;
+        }
+        c.enqueue(value);
+      } catch (err) {
+        if (ended) return;
+        end();
+        c.error(err);
+      }
+    },
+    cancel() {
+      end();
+      const returned = Promise.resolve(it.return?.()).catch(() => {});
+      if (!reading) return; // `it` is at rest: its return abandons the call (releasingOnExit)
+      // A read is in flight, and `it.return()` is queued behind it: that read's answer decides.
+      // The body's end → the call is finished, not abandoned, so an upload the handler reads
+      // after answering goes on; a chunk → the return then abandons the call. A peer that never
+      // answers (sends nothing more, for good) would hold the call forever: abandon it after a
+      // grace, without waiting in `cancel()` either way.
+      const grace = setTimeout(() => void release?.(), CANCEL_GRACE_MS);
+      (grace as { unref?: () => void }).unref?.();
+      void returned.finally(() => clearTimeout(grace));
+    },
+  });
 }

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,