@statewalker/webrun-http-streams 0.1.1 → 0.2.1

package/dist/message.d.ts

@@ -0,0 +1,50 @@
+/** Anything the codecs will read bytes from. */
+export type ByteSource = AsyncIterable<Uint8Array> | Iterable<Uint8Array>;
+export type RequestEnvelope = {
+    url: string;
+    method: string;
+    headers: [string, string][];
+};
+export type ResponseEnvelope = {
+    status: number;
+    statusText: string;
+    headers: [string, string][];
+};
+export type DecodedRequest = {
+    envelope: RequestEnvelope;
+    body: AsyncIterable<Uint8Array>;
+    /** The codec that actually read this message; set by the sniffing codec. */
+    codec?: MessageCodec;
+};
+export type DecodedResponse = {
+    envelope: ResponseEnvelope;
+    body: AsyncIterable<Uint8Array>;
+};
+/** Extra context a codec may need that the envelope does not carry. */
+export type ResponseCodecOptions = {
+    /**
+     * Method of the request this response answers. Required by HTTP/1.1: a
+     * response to HEAD carries framing headers but no body, and no parser can
+     * know that from the response bytes alone.
+     */
+    method: string;
+};
+/**
+ * One wire format. Requests and responses are separate operations because
+ * HTTP/1.1 serialises them differently — a codec cannot be generic over the
+ * envelope the way the JSON format was.
+ */
+export interface MessageCodec {
+    readonly name: string;
+    /**
+     * True if a message in this format may begin with `byte`. Used by the
+     * sniffing codec to dispatch without a negotiation handshake. Implementations
+     * must be mutually exclusive with every other codec they are paired with.
+     */
+    sniff(byte: number): boolean;
+    encodeRequest(env: RequestEnvelope, body?: ByteSource): AsyncGenerator<Uint8Array>;
+    encodeResponse(env: ResponseEnvelope, body?: ByteSource, options?: ResponseCodecOptions): AsyncGenerator<Uint8Array>;
+    decodeRequest(input: ByteSource): Promise<DecodedRequest>;
+    decodeResponse(input: ByteSource, options: ResponseCodecOptions): Promise<DecodedResponse>;
+}
+//# sourceMappingURL=message.d.ts.map

package/dist/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../src/message.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;AAE1E,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CACjC,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE7B,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IACnF,cAAc,CACZ,GAAG,EAAE,gBAAgB,EACrB,IAAI,CAAC,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,cAAc,CAAC,UAAU,CAAC,CAAC;IAE9B,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1D,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC5F"}

package/dist/request-streams.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The one place that knows a runtime may not implement request body streams,
+ * and the buffering both fallbacks need. `fetch.ts` and `http-stubs.ts` each
+ * carry a client and a server direction that must agree on the answer, so the
+ * predicate lives here rather than being written out four times.
+ */
+/**
+ * Whether `Request.prototype` exposes a `body` accessor. Two call sites read
+ * that property, and two more depend on the constructor accepting a
+ * `ReadableStream` as `init.body`; this predicate answers for all four.
+ *
+ * What was verified, and all that is claimed here: Firefox (146 at the time of
+ * writing) has *neither*, and Chromium and Node have *both*. On Firefox it is
+ * not that `body` is `undefined` on the instance —
+ * `Object.getOwnPropertyDescriptor(Request.prototype, "body")` is `null`, the
+ * accessor is genuinely absent — and because a `ReadableStream` is then not a
+ * recognised `BodyInit`, the constructor falls through to the string branch and
+ * stores the literal text `[object ReadableStream]`.
+ *
+ * The two halves are NOT guaranteed to ship together, so do not read this as a
+ * test for "request streams" in general. Safari is the counterexample: 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 this returns `true` there. That looks benign — WebKit appears
+ * to store the stream on the `Request` rather than stringify it, and its error
+ * comes from `fetch()`, which this package never calls on the objects it builds
+ * — but it is untested, and it is the case to look at first if a Safari report
+ * arrives. The sharper probe, if one is ever needed, is whether
+ * `new Request(url, {method:"POST", body:new ReadableStream(), duplex:"half"})`
+ * has a `content-type` of `text/plain;charset=UTF-8` (stringified) or `null`
+ * (stored); it is not used here because it costs a `Request` and a
+ * `ReadableStream` per call and agrees with the descriptor check on every
+ * runtime measured.
+ *
+ * A capability check, never a user-agent test: the question is what this
+ * runtime does, and the answer flips on its own the day Firefox ships request
+ * streams. Evaluated per call rather than cached at module load so that a test
+ * can install a `Request` without the capability and exercise the real branch
+ * under Node.
+ */
+export declare function supportsRequestStreams(): boolean;
+/**
+ * Drain a body iterable into one contiguous buffer. Only the fallbacks need it.
+ * Allocates its own buffer rather than reusing `bytes.ts`'s `concatChunks`,
+ * which passes a single chunk straight through: that chunk is a view onto the
+ * decoder's own read buffer, and the result here is handed to `new Request` and
+ * outlives the decode. The allocation is also what makes it a
+ * `Uint8Array<ArrayBuffer>`, which `BodyInit` accepts and the looser
+ * `Uint8Array<ArrayBufferLike>` does not.
+ */
+export declare function collectBytes(source: AsyncIterable<Uint8Array>): Promise<Uint8Array<ArrayBuffer>>;
+//# sourceMappingURL=request-streams.d.ts.map

package/dist/request-streams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-streams.d.ts","sourceRoot":"","sources":["../src/request-streams.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAKhD;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,GAChC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAelC"}

package/dist/sniff.d.ts

@@ -0,0 +1,18 @@
+import type { MessageCodec } from "./message.js";
+export type SniffingCodecOptions = {
+    /** Codec used for everything this peer writes. */
+    write: MessageCodec;
+    /** Codecs this peer accepts on read, tried in order. */
+    accept: MessageCodec[];
+};
+/**
+ * Dispatches on byte 0. 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 — so no negotiation handshake, magic prefix, or version byte
+ * is needed.
+ *
+ * This is what makes a mixed-version peer pair safe: readers accept either
+ * format, so the two ends can be upgraded in any order.
+ */
+export declare function newSniffingCodec(options: SniffingCodecOptions): MessageCodec;
+//# sourceMappingURL=sniff.d.ts.map

package/dist/sniff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sniff.d.ts","sourceRoot":"","sources":["../src/sniff.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,cAAc,CAAC;AAE7D,MAAM,MAAM,oBAAoB,GAAG;IACjC,kDAAkD;IAClD,KAAK,EAAE,YAAY,CAAC;IACpB,wDAAwD;IACxD,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,YAAY,CA+C5E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-http-streams",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "description": "HTTP request/response over Duplex — merge of webrun-http + webrun-http-port",
@@ -22,14 +22,14 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-streams": "0.1.0"
+    "@statewalker/webrun-streams": "0.1.1"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
+    "@types/node": "^26.2.0",
     "rimraf": "^6.1.3",
-    "rolldown": "^1.0.0-rc.16",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.4"
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "sideEffects": false,
   "publishConfig": {
@@ -38,6 +38,8 @@
   "scripts": {
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
     "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
     "lint": "biome check src tests"
   }
 }

package/src/bytes.ts

@@ -0,0 +1,157 @@
+import type { ByteSource } from "./message.js";
+
+const CR = 0x0d;
+const LF = 0x0a;
+const EMPTY = new Uint8Array(0);
+
+export class ByteStreamError extends Error {
+  override readonly name = "ByteStreamError";
+}
+
+export function toAsyncIterator(input: ByteSource): AsyncIterator<Uint8Array> {
+  const asyncIter = (input as AsyncIterable<Uint8Array>)[Symbol.asyncIterator];
+  if (asyncIter) return asyncIter.call(input as AsyncIterable<Uint8Array>);
+  const syncIter = (input as Iterable<Uint8Array>)[Symbol.iterator]();
+  return {
+    next(): Promise<IteratorResult<Uint8Array>> {
+      return Promise.resolve(syncIter.next());
+    },
+  };
+}
+
+/**
+ * Discard an iterable we are contractually forbidden from consuming — a body
+ * skipped for HEAD/204, or one abandoned because the peer reported an error.
+ *
+ * The `.next()` is not optional: `.return()` on a generator still in suspended
+ * start is a no-op, so the body never runs and its `try/finally` never unwinds.
+ * Without it a wrapped ReadableStream or socket is never cancelled.
+ */
+export async function discard(source: ByteSource | undefined): Promise<void> {
+  if (source === undefined) return;
+  const it = toAsyncIterator(source);
+  try {
+    await it.next();
+    await it.return?.();
+  } catch {
+    /* the source is being discarded; its failures are not ours to surface */
+  }
+}
+
+export function concatChunks(parts: Uint8Array[], totalLen: number): Uint8Array {
+  if (parts.length === 1) {
+    const only = parts[0];
+    // `parts.length === 1` guarantees index 0 exists; falls through to the
+    // general path below in the unreachable case where it somehow doesn't.
+    if (only !== undefined) return only;
+  }
+  const out = new Uint8Array(totalLen);
+  let off = 0;
+  for (const p of parts) {
+    out.set(p, off);
+    off += p.byteLength;
+  }
+  return out;
+}
+
+/**
+ * Pull-based reader over a byte source. Holds at most one pending buffer, and
+ * hands out `subarray` views rather than copies — a body never passes through
+ * an allocation here.
+ */
+export class ByteReader {
+  #iter: AsyncIterator<Uint8Array>;
+  #buf: Uint8Array = EMPTY;
+  #done = false;
+
+  constructor(input: ByteSource) {
+    this.#iter = toAsyncIterator(input);
+  }
+
+  /** Bytes already pulled from the source but not yet consumed. */
+  bufferedLength(): number {
+    return this.#buf.byteLength;
+  }
+
+  /** Pull one more non-empty chunk. Returns false at end of stream. */
+  async #pull(): Promise<boolean> {
+    if (this.#done) return false;
+    while (true) {
+      const next = await this.#iter.next();
+      if (next.done) {
+        this.#done = true;
+        return false;
+      }
+      const chunk = next.value;
+      if (chunk.byteLength === 0) continue;
+      this.#buf =
+        this.#buf.byteLength === 0
+          ? chunk
+          : concatChunks([this.#buf, chunk], this.#buf.byteLength + chunk.byteLength);
+      return true;
+    }
+  }
+
+  async peekByte(): Promise<number | undefined> {
+    while (this.#buf.byteLength === 0) {
+      if (!(await this.#pull())) return undefined;
+    }
+    return this.#buf[0];
+  }
+
+  /** Up to `max` bytes. `undefined` means end of stream. */
+  async readSome(max: number): Promise<Uint8Array | undefined> {
+    while (this.#buf.byteLength === 0) {
+      if (!(await this.#pull())) return undefined;
+    }
+    const take = Math.min(max, this.#buf.byteLength);
+    const out = this.#buf.subarray(0, take);
+    this.#buf = this.#buf.subarray(take);
+    return out;
+  }
+
+  /**
+   * One CRLF-terminated line, without the CRLF. A bare LF is rejected: real
+   * peers always send CRLF, and tolerating a bare LF is precisely the lenience
+   * that lets request smuggling through a proxy pair.
+   *
+   * The `maxBytes` bound is best-effort: it only rejects a line if the check
+   * happens to run before the line is fully buffered. A line already sitting in
+   * the buffer bypasses the check. Callers needing a hard per-line limit or
+   * aggregate bounds must keep their own running total.
+   */
+  async readLine(maxBytes: number): Promise<Uint8Array> {
+    let searched = 0;
+    while (true) {
+      const idx = this.#buf.indexOf(LF, searched);
+      if (idx !== -1) {
+        if (idx === 0 || this.#buf[idx - 1] !== CR) {
+          throw new ByteStreamError("bare LF line terminator; CRLF required");
+        }
+        const line = this.#buf.subarray(0, idx - 1);
+        this.#buf = this.#buf.subarray(idx + 1);
+        return line;
+      }
+      searched = this.#buf.byteLength;
+      if (searched > maxBytes) {
+        throw new ByteStreamError(`line exceeds ${maxBytes} bytes without CRLF`);
+      }
+      if (!(await this.#pull())) {
+        throw new ByteStreamError(`stream ended after ${searched} bytes without CRLF`);
+      }
+    }
+  }
+
+  /** Everything not yet consumed, lazily. */
+  async *rest(): AsyncGenerator<Uint8Array> {
+    while (true) {
+      if (this.#buf.byteLength > 0) {
+        const out = this.#buf;
+        this.#buf = EMPTY;
+        yield out;
+        continue;
+      }
+      if (!(await this.#pull())) return;
+    }
+  }
+}

package/src/codec-default.ts

@@ -0,0 +1,13 @@
+import { jsonEnvelopeCodec } from "./envelope.js";
+import { httpCodec } from "./http1/index.js";
+import type { MessageCodec } from "./message.js";
+import { newSniffingCodec } from "./sniff.js";
+
+/**
+ * Writes HTTP/1.1; accepts HTTP/1.1 or the legacy JSON envelope. Used whenever
+ * no `codec` option is supplied.
+ */
+export const defaultCodec: MessageCodec = newSniffingCodec({
+  write: httpCodec,
+  accept: [httpCodec, jsonEnvelopeCodec],
+});

package/src/duplex-site-builder.ts

@@ -1,5 +1,6 @@
 import type { Serve } from "@statewalker/webrun-streams";
 import { serveFetchOverDuplex } from "./fetch.js";
+import type { MessageCodec } from "./message.js";
 
 /**
  * Structural alias of `SiteHandler` from `@statewalker/webrun-site-builder`.
@@ -29,12 +30,19 @@ export type SiteHandler = (request: Request) => Promise<Response>;
  */
 export class DuplexSiteBuilder {
   #handler?: SiteHandler;
+  #codec?: MessageCodec;
 
   setHandler(handler: SiteHandler): this {
     this.#handler = handler;
     return this;
   }
 
+  /** Pin the wire format. Defaults to HTTP/1.1 with legacy acceptance. */
+  setCodec(codec: MessageCodec): this {
+    this.#codec = codec;
+    return this;
+  }
+
   async start<P>(serve: Serve<P>, params: P): Promise<() => Promise<void>> {
     if (!this.#handler) {
       throw new Error("DuplexSiteBuilder.start: setHandler(handler) must be called before start()");
@@ -42,7 +50,7 @@ export class DuplexSiteBuilder {
     const handler = this.#handler;
     return serve(
       params,
-      serveFetchOverDuplex(async (req) => handler(req)),
+      serveFetchOverDuplex(async (req) => handler(req), { codec: this.#codec }),
     );
   }
 }

package/src/envelope.ts

@@ -1,16 +1,20 @@
-export type RequestEnvelope = {
-  url: string;
-  method: string;
-  headers: [string, string][];
-};
+import { concatChunks, toAsyncIterator } from "./bytes.js";
+import { HttpParseError } from "./http1/errors.js";
+import type {
+  ByteSource,
+  DecodedRequest,
+  DecodedResponse,
+  MessageCodec,
+  RequestEnvelope,
+  ResponseEnvelope,
+} from "./message.js";
 
-export type ResponseEnvelope = {
-  status: number;
-  statusText: string;
-  headers: [string, string][];
-};
+export type { RequestEnvelope, ResponseEnvelope } from "./message.js";
 
 const NEWLINE = 0x0a;
+
+/** Mirrors the HTTP/1.1 codec's default `maxHeaderBytes`. */
+const MAX_ENVELOPE_BYTES = 65536;
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
@@ -51,7 +55,7 @@ export async function decodeMessage<E>(
   while (true) {
     const next = await iter.next();
     if (next.done) {
-      throw new Error(
+      throw new HttpParseError(
         `decodeMessage: stream ended after ${accumLen} bytes without delimiter (\\n)`,
       );
     }
@@ -61,6 +65,15 @@ export async function decodeMessage<E>(
     if (nl === -1) {
       accum.push(chunk);
       accumLen += chunk.byteLength;
+      // The envelope is one line, so a peer that never sends the delimiter is
+      // sending garbage — without a bound this loop buffers it all and then
+      // concatenates a second copy. The HTTP/1.1 path refuses the same flood
+      // via maxHeaderBytes; this is its counterpart.
+      if (accumLen > MAX_ENVELOPE_BYTES) {
+        throw new HttpParseError(
+          `decodeMessage: envelope exceeds ${MAX_ENVELOPE_BYTES} bytes without delimiter (\\n)`,
+        );
+      }
       continue;
     }
     accum.push(chunk.subarray(0, nl));
@@ -74,7 +87,7 @@ export async function decodeMessage<E>(
   try {
     envelope = JSON.parse(decoder.decode(before)) as E;
   } catch (err) {
-    throw new Error(
+    throw new HttpParseError(
       `decodeMessage: malformed envelope JSON at bytes 0..${before.byteLength}: ${(err as Error).message}`,
     );
   }
@@ -91,26 +104,22 @@ export async function decodeMessage<E>(
   return { envelope, body: body() };
 }
 
-function toAsyncIterator(
-  input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
-): AsyncIterator<Uint8Array> {
-  const asyncIter = (input as AsyncIterable<Uint8Array>)[Symbol.asyncIterator];
-  if (asyncIter) return asyncIter.call(input as AsyncIterable<Uint8Array>);
-  const syncIter = (input as Iterable<Uint8Array>)[Symbol.iterator]();
-  return {
-    next(): Promise<IteratorResult<Uint8Array>> {
-      return Promise.resolve(syncIter.next());
-    },
-  };
-}
+const OPEN_BRACE = 0x7b;
 
-function concatChunks(parts: Uint8Array[], totalLen: number): Uint8Array {
-  if (parts.length === 1) return parts[0];
-  const out = new Uint8Array(totalLen);
-  let off = 0;
-  for (const p of parts) {
-    out.set(p, off);
-    off += p.byteLength;
-  }
-  return out;
-}
+/**
+ * The original wire format — `<JSON.stringify(envelope)>\n<body bytes…>` —
+ * expressed as a `MessageCodec`. Direction-agnostic: requests and responses
+ * serialise identically.
+ *
+ * Retained so a peer pair can be upgraded in either order; see ADR-0006.
+ */
+export const jsonEnvelopeCodec: MessageCodec = {
+  name: "json-envelope",
+  sniff: (byte: number): boolean => byte === OPEN_BRACE,
+  encodeRequest: (env: RequestEnvelope, body?: ByteSource) => encodeMessage(env, body),
+  encodeResponse: (env: ResponseEnvelope, body?: ByteSource) => encodeMessage(env, body),
+  decodeRequest: (input: ByteSource): Promise<DecodedRequest> =>
+    decodeMessage<RequestEnvelope>(input),
+  decodeResponse: (input: ByteSource): Promise<DecodedResponse> =>
+    decodeMessage<ResponseEnvelope>(input),
+};

package/src/fetch.ts

@@ -1,6 +1,30 @@
 import type { Duplex } from "@statewalker/webrun-streams";
 import type { RequestEnvelope, ResponseEnvelope } from "./envelope.js";
-import { httpFetch, httpServe } from "./http-data.js";
+import { type HttpDataOptions, httpFetch, httpServe } from "./http-data.js";
+import { NULL_BODY_STATUSES } from "./http-stubs.js";
+import type { ByteSource } from "./message.js";
+import { collectBytes, supportsRequestStreams } from "./request-streams.js";
+
+/**
+ * Connection-scoped headers. The codec surfaces them verbatim (decision 12),
+ * but they are meaningless to a `Request`/`Response`, and re-emitting them
+ * from a relay would corrupt its framing.
+ */
+const HOP_BY_HOP = new Set([
+  "connection",
+  "host",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+]);
+
+function forwardableHeaders(headers: [string, string][]): [string, string][] {
+  return headers.filter(([name]) => !HOP_BY_HOP.has(name.toLowerCase()));
+}
 
 function headersToArray(headers: Headers): [string, string][] {
   const out: [string, string][] = [];
@@ -67,35 +91,117 @@ function asyncIterableToReadable(iter: AsyncIterable<Uint8Array>): ReadableStrea
  * the other side. The request's `signal` is plumbed into the body iteration —
  * abort terminates the underlying call.
  */
-export async function fetchOverDuplex(call: Duplex, request: Request): Promise<Response> {
+export async function fetchOverDuplex(
+  call: Duplex,
+  request: Request,
+  options: HttpDataOptions = {},
+): Promise<Response> {
   if (request.signal?.aborted) throw abortReason(request.signal);
   const env: RequestEnvelope = {
     url: request.url,
     method: request.method,
     headers: headersToArray(request.headers),
   };
-  const body = request.body ? readableToAsyncIterable(request.body) : undefined;
-  const { envelope, body: respBody } = await httpFetch(call, env, body);
-  return new Response(asyncIterableToReadable(withAbort(respBody, request.signal)), {
+  let body: ByteSource | undefined;
+  if (request.body != null) {
+    // The streaming path stays first and unconditional: a runtime that has
+    // request streams never reaches the fallback, and never buffers an upload.
+    body = readableToAsyncIterable(request.body);
+  } else if (!supportsRequestStreams()) {
+    // Firefox. Without `request.body` there is nothing to stream from, so the
+    // only way to see the payload at all is to buffer the whole of it. Two
+    // consequences, both real, neither worth rediscovering:
+    //
+    //  1. Request streaming is lost outright on this path. A 1 GiB upload from
+    //     a Firefox page is a 1 GiB allocation here, where Chromium would have
+    //     streamed it chunk by chunk.
+    //  2. 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 envelope goes on the wire
+    //     (with the HTTP/1.1 codec, a chunked body whose only chunk is the
+    //     terminator); here a zero-length `arrayBuffer()` is indistinguishable
+    //     from no body and we send none. Both decode to the same empty body at
+    //     the far end — `kind: "none"` framing on a request means zero bytes,
+    //     not read-to-EOF — so only the framing differs, but it does differ.
+    const buffered = new Uint8Array(await request.arrayBuffer());
+    if (buffered.byteLength > 0) body = [buffered];
+  }
+  const { envelope, body: respBody } = await httpFetch(call, env, body, options);
+  const responseInit: ResponseInit = {
     status: envelope.status,
     statusText: envelope.statusText,
-    headers: envelope.headers,
-  });
+    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`.
+  if (
+    request.method === "HEAD" ||
+    request.method === "OPTIONS" ||
+    NULL_BODY_STATUSES.has(envelope.status)
+  ) {
+    const returnable = respBody as AsyncIterable<Uint8Array> & { return?: () => unknown };
+    await returnable.return?.();
+    return new Response(null, responseInit);
+  }
+  return new Response(asyncIterableToReadable(withAbort(respBody, request.signal)), responseInit);
 }
 
 /**
  * Wrap a `(Request) => Promise<Response>` handler as a `Duplex` so it can be
  * registered with any `webrun-streams-*` adapter's `serve`.
  */
-export function serveFetchOverDuplex(handler: (request: Request) => Promise<Response>): Duplex {
+export function serveFetchOverDuplex(
+  handler: (request: Request) => Promise<Response>,
+  options: HttpDataOptions = {},
+): Duplex {
   return httpServe(async (env, body) => {
     const reqInit: RequestInit = {
       method: env.method,
-      headers: env.headers,
+      headers: forwardableHeaders(env.headers),
     };
     if (env.method !== "GET" && env.method !== "HEAD") {
-      reqInit.body = asyncIterableToReadable(body);
-      (reqInit as RequestInit & { duplex?: string }).duplex = "half";
+      if (supportsRequestStreams()) {
+        reqInit.body = asyncIterableToReadable(body);
+        (reqInit as RequestInit & { duplex?: string }).duplex = "half";
+      } else {
+        // Firefox again, and this is the half that fails *silently*. The
+        // constructor does not reject a `ReadableStream` here, it stringifies
+        // it: the handler would read the literal text `[object ReadableStream]`
+        // and answer 200 with corrupt data, where the outbound direction at
+        // least fails loudly with a 500. Bytes it does accept, so drain first.
+        //
+        // Same cost as the outbound fallback: the whole upload is held in
+        // memory, and a handler that wanted to stream its request body cannot.
+        // Unlike outbound, an empty body is still passed through — the
+        // streaming branch above always sets `body` for these methods, and
+        // passing a zero-length `Uint8Array` keeps that true.
+        reqInit.body = await collectBytes(body);
+      }
     }
     const request = new Request(env.url, reqInit);
     const response = await handler(request);
@@ -104,11 +210,23 @@ export function serveFetchOverDuplex(handler: (request: Request) => Promise<Resp
       statusText: response.statusText,
       headers: headersToArray(response.headers),
     };
+    // Mirror the client direction: put no bytes on the wire for a
+    // null-body-status response or a HEAD/OPTIONS request, even if the
+    // handler's Response carries a body stream. Cancel it so the producer
+    // isn't left hanging.
+    if (
+      env.method === "HEAD" ||
+      env.method === "OPTIONS" ||
+      NULL_BODY_STATUSES.has(response.status)
+    ) {
+      await response.body?.cancel();
+      return { envelope: respEnv, body: undefined };
+    }
     return {
       envelope: respEnv,
       body: response.body ? readableToAsyncIterable(response.body) : undefined,
     };
-  });
+  }, options);
 }
 
 async function* withAbort(