@statewalker/webrun-http-streams 0.2.4 → 0.3.0

package/README.md

@@ -1,80 +1,98 @@
 # @statewalker/webrun-http-streams
 
-HTTP request / response over a `Duplex` from any `webrun-streams-*` adapter.
-Replaces the retired `webrun-http` + `webrun-http-port` packages.
+## What it is
 
-## Install
+HTTP request/response over a `Duplex` from `@statewalker/webrun-streams`. A
+caller sends a standard `Request` (or a plain envelope plus body bytes) into a
+`Duplex` call and gets a `Response` back. A server wraps a
+`(Request) => Promise<Response>` handler as a `Duplex` that any transport
+adapter can serve. The bytes on the `Duplex` are conforming HTTP/1.1 by
+default. The package also ships a pair of transport-agnostic stubs that move a
+structured-clonable envelope instead of bytes.
+
+## Why it exists
+
+A `Duplex` is one call that streams bytes in and bytes out, and every transport
+adapter in this repository produces one: `@statewalker/webrun-rpc` over a
+`MessagePort` or worker, `@statewalker/webrun-streams-ws`,
+`@statewalker/webrun-streams-webrtc`, `@statewalker/webrun-streams-libp2p`,
+`@statewalker/webrun-streams-livekit`, `@statewalker/webrun-streams-peerjs`.
+This package puts HTTP on top of that seam, so an HTTP handler or a fetch-style
+caller works over any of those transports without change.
+
+The default wire format is real HTTP/1.1, not a private encoding. A peer that
+is not webrun at all, such as `node:http`, can read what this package writes
+and write what it reads.
+
+## How to use
 
 ```sh
-npm install @statewalker/webrun-http-streams
+pnpm add @statewalker/webrun-http-streams
 ```
 
-One runtime dependency, [`@statewalker/webrun-streams`](../webrun-streams); no
-peer dependencies. ESM only (`"type": "module"`). Needs standard `Request`,
-`Response`, `ReadableStream`, `TextEncoder` and `TextDecoder` — present in
-browsers, Node 18+, Deno, Bun and Cloudflare Workers.
+- **Peer dependencies:** none.
+- **Runtime dependency:** `@statewalker/webrun-streams` (the `Duplex` type,
+  stream helpers, error serialisation).
+- **Entry point:** one, `.`. ESM only: `dist/index.js` with `dist/index.d.ts`.
+  The `source` export condition points at `src/index.ts`.
+- **Environment:** anything with `Request`, `Response`, `ReadableStream`,
+  `TextEncoder` and `TextDecoder`: browsers, workers, service workers, Node,
+  Deno, Bun. Firefox loses request-body streaming; see
+  [Firefox buffers request bodies](#firefox-buffers-request-bodies).
 
-Pair it with a transport adapter to get a `Duplex`:
-[`-ws`](../webrun-streams-ws), [`webrun-rpc`](../webrun-rpc),
-[`-webrtc`](../webrun-streams-webrtc), [`-libp2p`](../webrun-streams-libp2p),
-[`-livekit`](../webrun-streams-livekit), [`-peerjs`](../webrun-streams-peerjs).
+The API comes in three layers on the `Duplex` seam, plus the stubs:
 
-## Getting started
+| Layer | Exports | Shape |
+| --- | --- | --- |
+| Data | `httpFetch`, `httpServe` | Envelope + `AsyncIterable<Uint8Array>` body. No `Request`/`Response`. |
+| Fetch | `fetchOverDuplex`, `serveFetchOverDuplex` | Standard `Request` / `Response`. |
+| Site host | `DuplexSiteBuilder` | Hands a `(Request) => Promise<Response>` handler to an adapter's `serve`. |
+| Stubs (no `Duplex`) | `newHttpClientStub`, `newHttpServerStub` | `SerializedHttpEnvelope` over any `send` function. |
 
-Pick a transport, then move standard `Request` / `Response` objects across it.
-Here the transport is an in-process `MessageChannel`, so the whole exchange runs
-in one process with no network:
+Happy path, with `@statewalker/webrun-rpc` as the transport over an in-process
+`MessageChannel`:
 
 ```ts
-import { connect, serve } from "@statewalker/webrun-rpc";
+import { connect, overPipe, serve, structuredCodec } from "@statewalker/webrun-rpc";
 import { fetchOverDuplex, serveFetchOverDuplex } from "@statewalker/webrun-http-streams";
 
-// --- server side ---
 const channel = new MessageChannel();
+
+// server side
 const stop = await serve(
-  { port: channel.port2 },
+  { mux: overPipe(channel.port2, { codec: structuredCodec, side: "responder" }) },
   serveFetchOverDuplex(async (request) => {
     const url = new URL(request.url);
     return Response.json({ path: url.pathname, method: request.method });
   }),
 );
 
-// --- client side ---
-const { call, close } = await connect({ port: channel.port1 });
+// client side
+const { call, close } = await connect({
+  mux: overPipe(channel.port1, { codec: structuredCodec, side: "initiator" }),
+});
 const response = await fetchOverDuplex(call, new Request("http://local/api/todo/7"));
 
-console.log(response.status);        // 200
-console.log(await response.json());  // { path: "/api/todo/7", method: "GET" }
+console.log(response.status); // 200
+console.log(await response.json()); // { path: "/api/todo/7", method: "GET" }
 
 await close();
 await stop();
 ```
 
-Swap `@statewalker/webrun-rpc` for
-[`-ws`](../webrun-streams-ws), [`-webrtc`](../webrun-streams-webrtc),
-[`-libp2p`](../webrun-streams-libp2p), [`-livekit`](../webrun-streams-livekit)
-or [`-peerjs`](../webrun-streams-peerjs) and nothing else changes — that is the
-whole point of the `Duplex` seam.
-
-Streaming bodies work as you would expect: a `Response` whose body is a
-`ReadableStream` streams across the transport chunk by chunk, which is what
-makes server-sent events work over a `MessagePort` or a WebRTC link.
+Swap the transport adapter and nothing else changes. A `Response` whose body is
+a `ReadableStream` streams across chunk by chunk, so server-sent events work
+over a `MessagePort` or a WebRTC link.
 
-## Layers
+## Examples
 
-Three of them sit on the `Duplex` seam, plus one older transport-agnostic pair
-that predates it and is kept for `webrun-http-browser`.
-
-### Data layer — `httpFetch` / `httpServe`
-
-Envelopes and body iterators, no `Request`/`Response` involved.
+### Data layer: `httpFetch` / `httpServe`
 
 ```ts
 import { httpFetch, httpServe } from "@statewalker/webrun-http-streams";
 
-// `call` is a Duplex. In-process it can be the handler itself; over a
-// transport it comes from an adapter's `connect`:
-//   const { call } = await connect({ url });   // webrun-streams-ws
+// A Duplex is `(input) => AsyncGenerator<Uint8Array>`, so the server side is a
+// usable `call` with no transport at all: the cheapest way to test a handler.
 const call = httpServe(async (env, body) => {
   for await (const _chunk of body) {
     /* drain the request body */
@@ -93,20 +111,17 @@ const { envelope, body } = await httpFetch(call, {
 // envelope.status === 200; `body` is an AsyncIterable<Uint8Array>
 ```
 
-`httpServe(handler)` returns a `Duplex` you can hand to any adapter's
-`serve(...)`. Because a `Duplex` is just `(input) => AsyncGenerator<Uint8Array>`,
-the handler side *is* a usable `call` with no transport at all — that is what
-the snippet above does, and it is the cheapest way to test a handler.
+Signatures: `httpFetch(call, env, body?, { codec? })` and
+`httpServe(handler, { codec? })`. Over a real transport, `call` comes from an
+adapter's `connect` and `httpServe(...)` goes to its `serve`.
 
-A relative `url` in the envelope works, but note it does not survive the round
-trip verbatim: HTTP/1.1 origin-form carries no scheme or authority, so the
-decoder rebuilds an absolute url from the codec's `scheme`/`host` options.
-`url: "/api/time"` arrives at the handler as `http://localhost/api/time` unless
-you configure the codec (see below).
+A relative `url` works but does not survive the round trip verbatim. HTTP/1.1
+origin-form carries no scheme or authority, so the decoder rebuilds an
+absolute url from the codec's `scheme` and `host` options: `url: "/api/time"`
+reaches the handler as `http://localhost/api/time` unless you configure the
+codec.
 
-### Fetch layer — `fetchOverDuplex` / `serveFetchOverDuplex`
-
-The same thing in terms of standard `Request` / `Response`.
+### Fetch layer: `fetchOverDuplex` / `serveFetchOverDuplex`
 
 ```ts
 import { fetchOverDuplex, serveFetchOverDuplex } from "@statewalker/webrun-http-streams";
@@ -118,44 +133,42 @@ const response = await fetchOverDuplex(call, new Request("http://peer.test/api/t
 await response.text(); // "hello /api/time"
 ```
 
-Hop-by-hop headers (`connection`, `transfer-encoding`, `host`, …) are stripped
-in both directions: the codec surfaces them verbatim, but they are meaningless
-to a `Request`/`Response` and re-emitting them from a relay would corrupt its
-framing.
-
-`fetchOverDuplex` plumbs `request.signal` into body iteration, so aborting the
-signal terminates the call.
+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.
 
-### Site host — `DuplexSiteBuilder`
+### Site host: `DuplexSiteBuilder`
 
 ```ts
 import { DuplexSiteBuilder } from "@statewalker/webrun-http-streams";
-import { serve } from "@statewalker/webrun-rpc";
+import { overPipe, serve, structuredCodec } from "@statewalker/webrun-rpc";
+
+const siteHandler = async (request: Request) =>
+  new Response(`site ${new URL(request.url).pathname}`);
+const { port2 } = new MessageChannel();
 
 const stop = await new DuplexSiteBuilder()
-  .setHandler(siteHandler) // (Request) => Promise<Response>
-  .start(serve, { port });
+  .setHandler(siteHandler)
+  .start(serve, { mux: overPipe(port2, { codec: structuredCodec, side: "responder" }) });
 // later: await stop();
 ```
 
-`.setCodec(codec)` pins the wire format. `DuplexSiteBuilder` is the
-cross-platform sibling of `HostedSiteBuilder` (browser + ServiceWorker) — same
-`SiteHandler` seam, different transport. It holds no site configuration of its
-own; endpoints, files and auth belong to the `SiteHandler` producer (typically
-`SiteBuilder`).
-
-> Not runnable as written above: it needs a live `MessagePort` and
-> `@statewalker/webrun-rpc`, which this package does not depend on.
-> `start` accepts any `Serve<P>`, so an in-process one is enough to exercise
-> it. Calling `start()` before `setHandler()` throws.
+`start(serve, params)` accepts any adapter's `Serve<P>` together with its
+params. `.setCodec(codec)` pins the wire format. The builder holds no site
+configuration: endpoints, files and auth belong to whatever produced the
+handler. `SiteHandler` is exported as the structural type
+`(request: Request) => Promise<Response>`, so this package does not depend on
+any site-builder package. Calling `start()` before `setHandler()` rejects with
+`DuplexSiteBuilder.start: setHandler(handler) must be called before start()`.
 
-### Transport-agnostic stubs — `newHttpClientStub` / `newHttpServerStub`
+### Transport-agnostic stubs: `newHttpClientStub` / `newHttpServerStub`
 
-Predates the `Duplex` seam and does **not** use it. Instead of bytes on a wire,
-these move a `SerializedHttpEnvelope` — a plain options object plus a body
-iterable — over whatever `send` function you give them. `webrun-http-browser`
-is built on this pair, because a MessagePort can structured-clone the envelope
-directly and never needs a byte encoding.
+These do not use the `Duplex` seam. They move a `SerializedHttpEnvelope`
+(`{ options, content }`: plain request or response options plus a body
+iterable) over whatever `send` function you give them. A `MessagePort` can
+structured-clone that envelope directly, so it never needs a byte encoding.
+`@statewalker/webrun-http-browser` builds its ServiceWorker transport on this
+pair.
 
 ```ts
 import { newHttpClientStub, newHttpServerStub } from "@statewalker/webrun-http-streams";
@@ -167,56 +180,8 @@ const res = await client(new Request("http://peer.test/x", { method: "POST", bod
 await res.text(); // "echo hi"
 ```
 
-A `send` that resolves `undefined` — no service registered for this call —
-becomes a `404` on the client side. `SerializedHttpEnvelope.content` must be
-*productive*: it has to yield or finish on its own, because a body neither stub
-is allowed to read is released by draining it, not by a bare `.return()`.
-
-Use the `Duplex` layers for anything new. These stay because the browser
-package's MessagePort transport is built around them.
-
-## Wire format
-
-Conforming **HTTP/1.1** by default — a `Duplex` carries bytes a real HTTP
-implementation can parse, and accepts bytes a real HTTP implementation
-produces. Verified against `node:http` in both directions.
-
-```
-POST /api?a=1 HTTP/1.1
-Host: peer.test
-Connection: close
-Transfer-Encoding: chunked
-
-5
-hello
-0
-
-```
-
-One message per `Duplex` call: `Connection: close` is always emitted, and bytes
-after a complete message are an error. Bodies use `Content-Length` when the
-caller declares one and chunked transfer coding otherwise; a message declaring
-both is refused.
-
-The codec is deliberately strict: every ambiguity is a refusal rather than a
-guess. One consequence worth calling out explicitly — RFC 9112 §2.2 permits a
-recipient to *tolerate* a single leading CRLF sent before the request-line
-("SHOULD ignore"). This codec declines that leniency and refuses it as a
-malformed request line; see ADR-0006.
-
-### Bodyless messages
-
-Responses with a null-body status — **204, 205, 304** — and responses to `HEAD`
-or `OPTIONS` put no bytes on the wire, in both directions, even if the
-handler's `Response` carries a body stream. The handler's stream is cancelled
-rather than sent. On the reading side you get `new Response(null, init)`, whose
-`.body` is `null`.
-
-The internal null-body set also lists 101 and 103, but neither is reachable
-through the fetch layer: `ResponseInit.status` must be 200–599, so
-`fetchOverDuplex` throws a `TypeError` from the `Response` constructor if a
-peer answers with one. Use the data layer (`httpFetch`) if you need to see an
-informational status.
+A `send` that resolves `undefined` (no service for this call) becomes a `404`
+on the client side.
 
 ### Choosing a codec
 
@@ -224,104 +189,41 @@ informational status.
 import {
   defaultCodec,
   httpCodec,
+  httpFetch,
   jsonEnvelopeCodec,
   newHttpCodec,
   newSniffingCodec,
 } from "@statewalker/webrun-http-streams";
 
-// default: writes HTTP/1.1, accepts HTTP/1.1 or the legacy JSON envelope
+// default: writes HTTP/1.1, accepts HTTP/1.1 or the JSON envelope
 await httpFetch(call, env);
 
 // pinned
-await httpFetch(call, env, body, { codec: httpCodec });
+await httpFetch(call, env, undefined, { codec: httpCodec });
 
 // the scheme and authority are not on the HTTP/1.1 wire; supply them here
 const codec = newHttpCodec({ scheme: "https", host: "peer.test" });
+
+// your own write/accept combination
+const strict = newSniffingCodec({ write: httpCodec, accept: [httpCodec] });
 ```
 
 | `newHttpCodec` option | Default | Meaning |
 | --- | --- | --- |
-| `scheme` | `"http"` | Scheme used to rebuild an absolute url on decode. Configuration, not wire data — a peer configured `http` rebuilds an `https` url as `http`. |
+| `scheme` | `"http"` | Scheme used to rebuild an absolute url on decode. Configuration, not wire data: a peer configured `http` rebuilds an `https` url as `http`. |
 | `host` | `"localhost"` | Authority used when a url carries none. Also fills the mandatory `Host` header. |
 | `maxHeaderBytes` | `65536` | Bound on the whole head section, start line included. |
 
-`httpCodec` is `newHttpCodec()` with those defaults. `defaultCodec` — used
-whenever no `codec` option is supplied — is
+`httpCodec` is `newHttpCodec()` with those defaults. `defaultCodec`, used
+whenever no `codec` option is given, is
 `newSniffingCodec({ write: httpCodec, accept: [httpCodec, jsonEnvelopeCodec] })`.
 
-The previous format — `<JSON.stringify(envelope)>` + newline + body bytes —
-remains available as `jsonEnvelopeCodec` (and as the raw `encodeMessage` /
-`decodeMessage` pair), and readers accept it automatically, so the two ends of
-a peer pair can be upgraded in either order. A server answers in whichever
-format read the request. Sniffing needs no handshake because the formats are
-self-identifying: a JSON envelope always begins `{`, which is not a token
-character and so can never begin an HTTP start-line. See ADR-0006.
-
-## Browser support
-
-Everything here is built on `Request`, `Response`, `ReadableStream`,
-`TextEncoder` and `TextDecoder`. Browsers do **not** behave uniformly, and one
-difference is large enough to change what this package can do.
-
-**Firefox does not implement `Request.prototype.body`** (checked against
-Firefox 146). `Object.getOwnPropertyDescriptor(Request.prototype, "body")` is
-`null` — the accessor is genuinely absent — and because a `ReadableStream` is
-then not a recognised `BodyInit`, `new Request(url, { body: stream })` falls
-through to the string branch and stores the literal text
-`[object ReadableStream]`.
-
-Both directions have a fallback, and both cost the same thing:
-
-- **Sending** (`fetchOverDuplex`, `newHttpClientStub`) — with no
-  `request.body` to stream from, the whole payload is buffered with
-  `request.arrayBuffer()` before it goes on the wire.
-- **Receiving** (`serveFetchOverDuplex`, `newHttpServerStub`) — the request
-  body is drained into one contiguous buffer before the `Request` handed to
-  your handler is constructed. Without this the handler would silently read the
-  string `[object ReadableStream]` and answer `200` with corrupt data.
-
-So on Firefox: **request streaming does not happen**. A 1 GiB upload from a
-Firefox page is a 1 GiB allocation, where Chromium and Node stream it chunk by
-chunk. Response streaming is unaffected — `Response.body` exists everywhere.
-
-The check is a capability probe, not a user-agent test, so it flips on its own
-the day Firefox ships request streams. Safari is untested and is the case to
-look at first if a report arrives: it has had `Request.body` since 11.1 but
-only accepts a stream as `init.body` from Technology Preview 250, so a shipping
-Safari has the reader half without the upload half and takes the streaming
-branch here.
-
-One further divergence, on the sending side only: buffering cannot distinguish
-an absent body from an empty one. Chromium's
-`new Request(url, { method: "POST", body: "" })` yields a non-null empty
-stream, so an empty body is framed on the wire; on the Firefox path a
-zero-length `arrayBuffer()` is indistinguishable from no body and none is sent.
-Both decode to the same empty body at the far end, so only the framing differs.
-This does not arise for the stubs, whose envelope always carries a `content`
-iterable.
-
-## Errors
-
-The codec answers on the wire wherever it can, because a real HTTP peer cannot
-receive a JavaScript exception — only a response, or a connection that ends
-with no status.
-
-| Situation | On the wire | On a webrun caller |
-| --- | --- | --- |
-| Handler throws | `500 Internal Server Error`, message in the body | `httpFetch` rejects with the peer's error, stack and custom fields preserved |
-| Request cannot be parsed | `400 Bad Request`, reason in the body | `httpFetch` rejects with the parse error |
-| Transport fails | nothing — the failure is not ours to answer | the error propagates unchanged |
-
-Both error responses carry the serialized error in an `x-webrun-error` header
-(exported as `PEER_ERROR_HEADER`), which is what lets a webrun peer re-throw a
-real `Error` rather than a status code. A third party just reads a conforming
-response and ignores the header. The header value is bounded at 4096
-characters, so a very large error message is truncated rather than blowing past
-`maxHeaderBytes` at the reader.
+`jsonEnvelopeCodec` is a second format: `JSON.stringify(envelope)`, a newline,
+then the body bytes. `encodeMessage` / `decodeMessage` expose that framing for
+any envelope type. A server answers in whichever format read the request, so a
+peer that speaks only the JSON envelope is answered as a JSON envelope.
 
-Refusals are always `HttpParseError`, whichever codec read the message, so a
-consumer can tell "the peer sent something malformed" from "the transport
-broke". **Check `err.name`, not `instanceof`** — the two cases differ:
+### Telling a malformed message from a broken transport
 
 ```ts
 import { httpFetch } from "@statewalker/webrun-http-streams";
@@ -330,69 +232,201 @@ try {
   await httpFetch(call, env);
 } catch (err) {
   if ((err as Error).name === "HttpParseError") {
-    // malformed bytes — one side or an intermediary is at fault
+    // malformed bytes: one side or an intermediary is at fault
   } else {
     throw err; // transport failure, or the peer handler's own error
   }
 }
 ```
 
-`instanceof HttpParseError` holds only when *this* side's decoder refused what
-the peer sent. When the peer refuses **your** request, its 400 travels back
-through the `x-webrun-error` header and is rehydrated by `deserializeError`,
-which builds a plain `Error` carrying the original `name`, `message`, `stack`
-and custom fields — not the original class. So `err.name` is
-`"HttpParseError"` in both directions, and `instanceof` is true in only one.
-The same applies to every error class crossing this boundary, including your
-own handler's `Error` subclasses.
-
-A refusal is answered in whatever format the peer was speaking, so a caller
-pinned to the legacy envelope receives its 400 as an envelope rather than as
-HTTP/1.1.
-
-`HttpError` is a separate, unrelated helper for handlers that want to raise a
-status deliberately (`HttpError.errorResourceNotFound()` and friends). It is
-not wired into the wire format: throwing one produces a 500 like any other
-exception.
+Check `err.name`, not `instanceof`; see
+[Errors cross the wire as responses](#errors-cross-the-wire-as-responses).
 
-## Exports
+### Exports
 
 | Export | What it is |
 | --- | --- |
 | `httpFetch`, `httpServe` | Data layer. Types: `HttpDataHandler`, `HttpDataHandlerResult`, `HttpDataOptions`, `HttpFetchResult`. |
 | `fetchOverDuplex`, `serveFetchOverDuplex` | Fetch layer. |
-| `DuplexSiteBuilder`, `SiteHandler` | Site host over a `Connect`/`Serve` pair. |
+| `DuplexSiteBuilder`, `SiteHandler` | Site host over an adapter's `Serve<P>`. |
 | `newHttpClientStub`, `newHttpServerStub` | Transport-agnostic stubs. Types: `HttpHandler`, `SerializedHttpEnvelope`, `SerializedHttpRequest`, `SerializedHttpResponse`. |
 | `defaultCodec`, `httpCodec`, `newHttpCodec`, `HttpCodecOptions` | HTTP/1.1 codec and the default sniffing codec. |
-| `jsonEnvelopeCodec`, `encodeMessage`, `decodeMessage` | Legacy JSON-envelope format. |
-| `newSniffingCodec`, `SniffingCodecOptions` | Build your own write/accept combination. |
+| `jsonEnvelopeCodec`, `encodeMessage`, `decodeMessage` | JSON-envelope format. |
+| `newSniffingCodec`, `SniffingCodecOptions` | Build a write/accept combination. |
 | `HttpParseError` | Every codec refusal. |
-| `HttpError`, `HttpErrorOptions` | Status-raising helper for handlers; not wired into the wire format. |
+| `HttpError`, `HttpErrorOptions` | Status-carrying error for handlers; not wired into the wire format. |
 | `PEER_ERROR_HEADER` | `"x-webrun-error"`. |
 | `MessageCodec`, `ByteSource`, `RequestEnvelope`, `ResponseEnvelope`, `DecodedRequest`, `DecodedResponse`, `ResponseCodecOptions` | The codec seam's types. |
 
-## Dependencies
+## Internals
 
-| Dependency | Kind | Why |
-| --- | --- | --- |
-| [`@statewalker/webrun-streams`](../webrun-streams) | runtime | The `Duplex` seam, chunk collectors and error serialisation. |
+### One HTTP/1.1 message per `Duplex` call
+
+```
+caller                                     Duplex                                server
+Request -> envelope+body -> encodeRequest  ==bytes==>  decodeRequest -> envelope+body -> handler
+Response <- envelope+body <- decodeResponse <==bytes==  encodeResponse <- envelope+body <-'
+```
+
+```
+POST /api?a=1 HTTP/1.1
+Host: peer.test
+Connection: close
+Transfer-Encoding: chunked
 
-No peer dependencies and no runtime dependencies outside the workspace. Relies
-on the platform for `Request`, `Response`, `ReadableStream`, `TextEncoder` and
-`TextDecoder`.
+5
+hello
+0
 
-Downstream consumers in this workspace:
-[`webrun-http-browser`](../webrun-http-browser) and
-[`webrun-rpc-http`](../webrun-rpc-http).
+```
 
-## Scripts
+`Connection: close` is always emitted, and bytes after a complete message are
+an error (`N trailing bytes after a complete message`). Running several calls
+at once is the transport adapter's job, not the codec's. Bodies use
+`Content-Length` when the caller declares one and chunked transfer coding
+otherwise. The codec is tested against `node:http` in both directions
+(`tests/http1-node-interop.test.ts`).
+
+### The codec refuses instead of guessing
+
+Every ambiguity is an `HttpParseError`. Some that a reader meets in practice:
+
+- a message with both `Content-Length` and `Transfer-Encoding`:
+  `message declares both Content-Length and Transfer-Encoding; refusing (request smuggling)`;
+- a head larger than `maxHeaderBytes`: `head section exceeds 65536 bytes`;
+- obsolete line folding: `obs-fold header continuation is not accepted`;
+- an HTTP/1.1 request without `Host`: `HTTP/1.1 request has no Host header`;
+- a header value that is not latin-1, or that contains CR, LF or a control
+  character.
+
+RFC 9112 §2.2 lets a recipient ignore a single CRLF before the request line.
+This codec does not: it answers `400 Bad Request` with
+`malformed request line`.
+
+### Format sniffing needs no handshake
+
+The formats identify themselves by their first byte. A JSON envelope always
+begins with `{`, which is not an HTTP token character, and every HTTP start
+line (a method, or `HTTP/1.1`) begins with one. The sniffing codec peeks one
+byte and picks the first accepted codec that claims it. An empty stream fails
+with `sniff: stream ended before any bytes arrived`; an unknown first byte
+fails with `sniff: no accepted codec recognises a message starting with byte 0x..`.
+
+### Bodyless responses carry no bytes
+
+Responses with a null-body status (204, 205, 304) and responses to `HEAD` or
+`OPTIONS` put no body bytes on the wire, even if the handler's `Response` has a
+body stream; the handler's stream is cancelled. The reader gets
+`new Response(null, init)`, whose `.body` is `null`.
+
+The null-body set also contains 101 and 103, but `fetchOverDuplex` cannot
+return them: `ResponseInit.status` must be 200–599, so the `Response`
+constructor throws a `RangeError` (`init["status"] must be in the range of 200
+to 599, inclusive.` in Node) if a peer answers with one. Use `httpFetch` to see
+an informational status.
+
+Known gap: for these bodyless responses `fetchOverDuplex` does not release the
+underlying `Duplex` call. `httpFetch` returns only `{ envelope, body }`, and
+`.return()` on a body generator nobody has pulled from is a no-op, so the
+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.
+
+### Hop-by-hop headers are dropped at the fetch layer
+
+The codec surfaces every header verbatim. The fetch layer strips `connection`,
+`host`, `keep-alive`, `proxy-authenticate`, `proxy-authorization`, `te`,
+`trailer`, `transfer-encoding` and `upgrade` in both directions. They mean
+nothing to a `Request`/`Response`, and a relay that re-emitted them would
+corrupt its own framing.
+
+### Errors cross the wire as responses
+
+A real HTTP peer cannot receive a JavaScript exception, only a response or a
+connection that ends with no status. So the server answers on the wire wherever
+it can:
+
+| Situation | On the wire | What a webrun caller sees |
+| --- | --- | --- |
+| Handler throws | `500 Internal Server Error`, message in the body | `httpFetch` rejects with the peer's error; `name`, `message`, `stack` and custom fields preserved |
+| Request cannot be parsed | `400 Bad Request`, reason in the body | `httpFetch` rejects with the parse error |
+| Transport fails | nothing | the transport error propagates unchanged |
+
+Both error responses carry the serialised error in the `x-webrun-error` header
+(`PEER_ERROR_HEADER`). A webrun peer re-throws it; any other client reads a
+normal response. The header value is escaped to printable ASCII and capped at
+4096 characters. Without the cap a huge message would push the head past the
+reader's `maxHeaderBytes`, and the caller would see
+`head section exceeds 65536 bytes` instead of the real error. On this path the
+caller also cancels the `Duplex` output, which frees the call's slot on a
+multiplexing transport.
+
+`instanceof HttpParseError` holds only when this side's decoder refused the
+peer's bytes. When the peer refuses your request, its 400 comes back through
+the header, and `deserializeError` builds a plain `Error` with the original
+`name`, `message`, `stack` and fields, not the original class. The same is true
+of every error class crossing this boundary, including your handler's own
+`Error` subclasses. A refusal is answered in the format the peer was speaking.
+
+`HttpError` is a separate helper for handlers that want to carry a status
+(`HttpError.errorResourceNotFound()`, `errorForbidden()`, `errorResourceGone()`,
+`errorInternalError()`, `fromError()`). The wire format does not read it:
+throwing one produces a 500 like any other exception.
+
+### Firefox buffers request bodies
+
+Firefox does not implement `Request.prototype.body` (checked against Firefox
+146). Without it, `new Request(url, { body: stream })` does not reject a
+`ReadableStream`; it stores the literal text `[object ReadableStream]`. The
+package detects this with a capability probe
+(`Object.getOwnPropertyDescriptor(Request.prototype, "body")`), evaluated per
+call, not a user-agent test.
+
+- **Sending** (`fetchOverDuplex`, `newHttpClientStub`): the whole payload is
+  read with `request.arrayBuffer()` before it goes on the wire.
+- **Receiving** (`serveFetchOverDuplex`, `newHttpServerStub`): the request body
+  is drained into one buffer before the handler's `Request` is built. Without
+  this the handler would read `[object ReadableStream]` and answer 200 with
+  corrupt data.
+
+So on Firefox a 1 GiB upload is a 1 GiB allocation, where Chromium and Node
+stream it. Response streaming is unaffected. Safari is untested: it has
+`Request.body`, but only accepts a stream as `init.body` from Technology
+Preview 250, so a shipping Safari takes the streaming branch here.
+
+Buffering cannot tell an absent body from an empty one. Chromium frames an
+empty POST body on the wire; the Firefox path sends none. Both decode to the
+same empty body at the far end.
+
+### Stub bodies must be productive
+
+`SerializedHttpEnvelope.content` must yield or finish on its own. A body neither
+stub may read (a GET/HEAD/OPTIONS request, a null-body-status response) is
+released by pulling once and then calling `.return()`, because `.return()` on a
+generator that has not started is a no-op and would leak the producer. A
+`content` that blocks forever without yielding makes the stub block with it.
+A `content` that waits on a peer that may never send should carry its own
+timeout.
+
+### Dependencies
+
+One runtime dependency, `@statewalker/webrun-streams`, for the `Duplex` and
+`Serve` types, `fromReadableStream` / `toReadableStream`, and
+`serializeError` / `deserializeError`. No peer dependencies. Everything else is
+platform API.
+
+### Scripts
 
 ```sh
-pnpm test        # vitest run
-pnpm run build   # rolldown + tsc --emitDeclarationOnly
-pnpm lint        # biome check src tests
+pnpm test             # vitest run
+pnpm run build        # rolldown + tsc --emitDeclarationOnly
+pnpm run typecheck    # tsc --noEmit
+pnpm run lint         # biome check src tests
 ```
 
+`tests/readme-examples.test.ts` runs the snippets in this file against the
+source.
+
 ## License
 
-MIT © statewalker — see [LICENSE](../../LICENSE).
+MIT

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;AAE1D,OAAO,EAAE,KAAK,eAAe,EAAwB,MAAM,gBAAgB,CAAC;AAsF5E;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,QAAQ,CAAC,CA0EnB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAChD,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAiDR"}
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAE1D,OAAO,EAAE,KAAK,eAAe,EAAwB,MAAM,gBAAgB,CAAC;AAsF5E;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAiDnB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAChD,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAqDR"}

package/dist/http-data.d.ts

@@ -9,10 +9,25 @@ export type HttpDataOptions = {
 export interface HttpFetchResult {
     envelope: ResponseEnvelope;
     body: AsyncIterable<Uint8Array>;
+    /**
+     * Abandons the call: the peer's producer is released (its `finally` runs).
+     * Leaving `body` early — `break`, `.return()`, a cancelled stream — does
+     * the same; this is for a caller that never starts reading it, such as a
+     * bodyless response. Optional, so that results built elsewhere (mocks,
+     * custom transports) still type-check; `httpFetch` always sets it.
+     */
+    release?(): Promise<void>;
 }
 export interface HttpDataHandlerResult {
     envelope: ResponseEnvelope;
     body?: ByteSource;
+    /**
+     * Called when the caller abandons the response before its end. A body the
+     * codec never started pulling cannot be released through the iterator
+     * protocol (`.return()` on a generator in suspended start does nothing), so
+     * a producer that holds resources says here how to let them go.
+     */
+    release?: () => unknown;
 }
 /**
  * Low-level HTTP-over-Duplex handler. Takes the request envelope plus body

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;CACtB,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;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,CAM1B;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAwCzF"}
+{"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;CACtB,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;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;CACzB;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,CAkB1B;AA0BD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAoDzF"}

package/dist/index.js

@@ -855,11 +855,41 @@ async function throwIfPeerError(result, output) {
 async function httpFetch(call, env, body, options = {}) {
 	const codec = options.codec ?? defaultCodec;
 	const output = call(codec.encodeRequest(env, body));
-	const result = await codec.decodeResponse(output, { method: env.method });
+	const decoded = await codec.decodeResponse(output, { method: env.method });
+	const release = async () => {
+		try {
+			await output.return?.(void 0);
+		} catch {}
+	};
+	const result = {
+		envelope: decoded.envelope,
+		body: releasingOnExit(decoded.body, release),
+		release
+	};
 	await throwIfPeerError(result, output);
 	return result;
 }
 /**
+* `body`, but leaving it before its end releases the call.
+*
+* The body the codec hands back is a generator of its own over a `ByteReader`,
+* and `.return()` on it never reaches the call's `output` (see
+* `throwIfPeerError` for why the codec must not do that itself). So a caller
+* that stopped reading — an aborted `fetch`, a cancelled response stream —
+* left the peer's producer parked forever, holding its handler open. Safe here
+* for the same reason it is safe in `throwIfPeerError`: `output` is this
+* call's own response-only generator, and the request was fully sent.
+*/
+async function* releasingOnExit(body, release) {
+	let completed = false;
+	try {
+		yield* body;
+		completed = true;
+	} finally {
+		if (!completed) await release();
+	}
+}
+/**
 * Wrap an HTTP handler as a `Duplex` so it can be registered with any
 * `webrun-streams-*` adapter's `serve`.
 */
@@ -882,7 +912,15 @@ function httpServe(handler, options = {}) {
 			yield* encodeErrorResponse(replyCodec, error, decoded.envelope.method);
 			return;
 		}
-		yield* replyCodec.encodeResponse(result.envelope, result.body, { method: decoded.envelope.method });
+		let completed = false;
+		try {
+			yield* replyCodec.encodeResponse(result.envelope, result.body, { method: decoded.envelope.method });
+			completed = true;
+		} finally {
+			if (!completed) try {
+				await result.release?.();
+			} catch {}
+		}
 	};
 }
 //#endregion
@@ -1140,14 +1178,14 @@ async function fetchOverDuplex(call, request, options = {}) {
 		const buffered = new Uint8Array(await request.arrayBuffer());
 		if (buffered.byteLength > 0) body = [buffered];
 	}
-	const { envelope, body: respBody } = await httpFetch(call, env, body, options);
+	const { envelope, body: respBody, release } = await httpFetch(call, env, body, options);
 	const responseInit = {
 		status: envelope.status,
 		statusText: envelope.statusText,
 		headers: forwardableHeaders(envelope.headers)
 	};
 	if (request.method === "HEAD" || request.method === "OPTIONS" || NULL_BODY_STATUSES.has(envelope.status)) {
-		await respBody.return?.();
+		await release?.();
 		return new Response(null, responseInit);
 	}
 	return new Response(asyncIterableToReadable(withAbort(respBody, request.signal)), responseInit);
@@ -1183,7 +1221,8 @@ function serveFetchOverDuplex(handler, options = {}) {
 		}
 		return {
 			envelope: respEnv,
-			body: response.body ? readableToAsyncIterable(response.body) : void 0
+			body: response.body ? readableToAsyncIterable(response.body) : void 0,
+			release: () => response.body?.cancel()
 		};
 	}, options);
 }

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@statewalker/webrun-http-streams",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
-  "description": "HTTP request/response over Duplex — merge of webrun-http + webrun-http-port",
-  "homepage": "https://github.com/statewalker/webrun-wire",
+  "description": "HTTP request/response over a webrun-streams Duplex, encoded as HTTP/1.1, plus transport-agnostic fetch stubs",
+  "bugs": {
+    "url": "https://github.com/statewalker/webrun-wire/issues"
+  },
+  "homepage": "https://github.com/statewalker/webrun-wire/tree/main/packages/webrun-http-streams#readme",
   "author": {
     "name": "Mikhail Kotelnikov",
     "email": "mikhail.kotelnikov@gmail.com"
@@ -12,7 +15,8 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git@github.com:statewalker/webrun-wire.git"
+    "url": "git+https://github.com/statewalker/webrun-wire.git",
+    "directory": "packages/webrun-http-streams"
   },
   "exports": {
     ".": {
@@ -26,7 +30,7 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-streams": "^0.2.1"
+    "@statewalker/webrun-streams": "^0.2.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",

package/src/fetch.ts

@@ -126,46 +126,21 @@ export async function fetchOverDuplex(
     const buffered = new Uint8Array(await request.arrayBuffer());
     if (buffered.byteLength > 0) body = [buffered];
   }
-  const { envelope, body: respBody } = await httpFetch(call, env, body, options);
+  const { envelope, body: respBody, release } = await httpFetch(call, env, body, options);
   const responseInit: ResponseInit = {
     status: envelope.status,
     statusText: envelope.statusText,
     headers: forwardableHeaders(envelope.headers),
   };
   // `new Response(body, { status })` throws for the null-body-status set, and
-  // HEAD/OPTIONS carry no body either, so return a bodyless Response and try to
-  // let go of the body we were handed.
-  //
-  // KNOWN GAP — this `.return()` does not actually release the producer, and
-  // `discard` would not fix it either. Do not read it as a working drain.
-  //
-  // `respBody` is *not* the generator the codec pulled from. `decodeResponse`
-  // pulls from its `input` (the `output` generator returned by `call(...)`) to
-  // read the head, and hands back a freshly constructed one —
-  // `convertBodyErrors(readBody(...))` in `http1/decode.ts`. Nobody has pulled
-  // from that, so it is in suspended start and `.return()` on it is a no-op,
-  // exactly as in the two sites `http-stubs.ts` fixed. Measured: the producer's
-  // `finally` does not run for 204, 205, 304, HEAD+200 or OPTIONS+200.
-  //
-  // `discard` does not help because the release has to reach further down.
-  // `ByteReader` never propagates `.return()` to its own `#iter`, so only
-  // `await output.return()` frees the underlying call — and `fetchOverDuplex`
-  // has no handle on `output`, since `httpFetch` returns only `{envelope,
-  // body}`. Closing this needs `httpFetch` to expose the call for cancellation;
-  // that is a design change, not a patch here.
-  //
-  // Worth knowing which shapes leak a *populated* body rather than an empty
-  // one: `decodeResponse`'s own bodyless test covers status < 200, 204, 304 and
-  // HEAD, so for 205 and for OPTIONS the decoder frames a real body that is
-  // then abandoned. `http-data.ts` (see `throwIfPeerError`) spells out the cost
-  // on a mux transport — one stream-table slot per call, until `maxStreams`.
+  // HEAD/OPTIONS carry no body either, so return a bodyless Response and
+  // release the call: nobody will read the body, so leaving it cannot.
   if (
     request.method === "HEAD" ||
     request.method === "OPTIONS" ||
     NULL_BODY_STATUSES.has(envelope.status)
   ) {
-    const returnable = respBody as AsyncIterable<Uint8Array> & { return?: () => unknown };
-    await returnable.return?.();
+    await release?.();
     return new Response(null, responseInit);
   }
   return new Response(asyncIterableToReadable(withAbort(respBody, request.signal)), responseInit);
@@ -225,6 +200,10 @@ export function serveFetchOverDuplex(
     return {
       envelope: respEnv,
       body: response.body ? readableToAsyncIterable(response.body) : undefined,
+      // A body the codec never started reading has no reader to cancel
+      // through; cancel the stream itself. Once read, it is locked and this
+      // rejects, harmlessly: the reader's own cancellation has run.
+      release: () => response.body?.cancel(),
     };
   }, options);
 }

package/src/http-data.ts

@@ -22,11 +22,26 @@ export type HttpDataOptions = {
 export interface HttpFetchResult {
   envelope: ResponseEnvelope;
   body: AsyncIterable<Uint8Array>;
+  /**
+   * Abandons the call: the peer's producer is released (its `finally` runs).
+   * Leaving `body` early — `break`, `.return()`, a cancelled stream — does
+   * the same; this is for a caller that never starts reading it, such as a
+   * bodyless response. Optional, so that results built elsewhere (mocks,
+   * custom transports) still type-check; `httpFetch` always sets it.
+   */
+  release?(): Promise<void>;
 }
 
 export interface HttpDataHandlerResult {
   envelope: ResponseEnvelope;
   body?: ByteSource;
+  /**
+   * Called when the caller abandons the response before its end. A body the
+   * codec never started pulling cannot be released through the iterator
+   * protocol (`.return()` on a generator in suspended start does nothing), so
+   * a producer that holds resources says here how to let them go.
+   */
+  release?: () => unknown;
 }
 
 /**
@@ -152,11 +167,47 @@ export async function httpFetch(
 ): Promise<HttpFetchResult> {
   const codec = options.codec ?? defaultCodec;
   const output = call(codec.encodeRequest(env, body));
-  const result = await codec.decodeResponse(output, { method: env.method });
+  const decoded = await codec.decodeResponse(output, { method: env.method });
+  const release = async () => {
+    try {
+      await output.return?.(undefined);
+    } catch {
+      /* the call is being abandoned; nothing to report */
+    }
+  };
+  const result: HttpFetchResult = {
+    envelope: decoded.envelope,
+    body: releasingOnExit(decoded.body, release),
+    release,
+  };
   await throwIfPeerError(result, output);
   return result;
 }
 
+/**
+ * `body`, but leaving it before its end releases the call.
+ *
+ * The body the codec hands back is a generator of its own over a `ByteReader`,
+ * and `.return()` on it never reaches the call's `output` (see
+ * `throwIfPeerError` for why the codec must not do that itself). So a caller
+ * that stopped reading — an aborted `fetch`, a cancelled response stream —
+ * left the peer's producer parked forever, holding its handler open. Safe here
+ * for the same reason it is safe in `throwIfPeerError`: `output` is this
+ * call's own response-only generator, and the request was fully sent.
+ */
+async function* releasingOnExit(
+  body: AsyncIterable<Uint8Array>,
+  release: () => Promise<void>,
+): AsyncGenerator<Uint8Array> {
+  let completed = false;
+  try {
+    yield* body;
+    completed = true;
+  } finally {
+    if (!completed) await release();
+  }
+}
+
 /**
  * Wrap an HTTP handler as a `Duplex` so it can be registered with any
  * `webrun-streams-*` adapter's `serve`.
@@ -197,8 +248,20 @@ export function httpServe(handler: HttpDataHandler, options: HttpDataOptions = {
       yield* encodeErrorResponse(replyCodec, error, decoded.envelope.method);
       return;
     }
-    yield* replyCodec.encodeResponse(result.envelope, result.body, {
-      method: decoded.envelope.method,
-    });
+    let completed = false;
+    try {
+      yield* replyCodec.encodeResponse(result.envelope, result.body, {
+        method: decoded.envelope.method,
+      });
+      completed = true;
+    } finally {
+      if (!completed) {
+        try {
+          await result.release?.();
+        } catch {
+          /* already released through the body, or nothing to release */
+        }
+      }
+    }
   };
 }