@statewalker/webrun-http-streams 0.2.4 → 0.2.5

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/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@statewalker/webrun-http-streams",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "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",