@statewalker/webrun-http-streams 0.1.1 → 0.2.2

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(

package/src/http-data.ts

@@ -1,10 +1,23 @@
 import type { Duplex } from "@statewalker/webrun-streams";
-import {
-  decodeMessage,
-  encodeMessage,
-  type RequestEnvelope,
-  type ResponseEnvelope,
-} from "./envelope.js";
+import { deserializeError, serializeError } from "@statewalker/webrun-streams";
+import { discard } from "./bytes.js";
+import { defaultCodec } from "./codec-default.js";
+import { HttpParseError } from "./http1/errors.js";
+import type {
+  ByteSource,
+  DecodedRequest,
+  MessageCodec,
+  RequestEnvelope,
+  ResponseEnvelope,
+} from "./message.js";
+
+/** Carries the serialized JS error between two webrun peers. */
+export const PEER_ERROR_HEADER = "x-webrun-error";
+
+export type HttpDataOptions = {
+  /** Wire format. Defaults to `defaultCodec`: writes HTTP/1.1, accepts either. */
+  codec?: MessageCodec;
+};
 
 export interface HttpFetchResult {
   envelope: ResponseEnvelope;
@@ -13,7 +26,7 @@ export interface HttpFetchResult {
 
 export interface HttpDataHandlerResult {
   envelope: ResponseEnvelope;
-  body?: AsyncIterable<Uint8Array> | Iterable<Uint8Array>;
+  body?: ByteSource;
 }
 
 /**
@@ -29,6 +42,100 @@ export type HttpDataHandler = (
   body: AsyncIterable<Uint8Array>,
 ) => Promise<HttpDataHandlerResult>;
 
+/** Hard cap on the peer-error header (M3): see `encodeErrorResponse`. */
+const MAX_DETAIL_CHARS = 4096;
+
+/**
+ * JSON with every non-printable-ASCII character escaped, so the result is a
+ * legal latin-1 header value whatever the error message contained.
+ */
+function asciiJson(value: unknown): string {
+  return JSON.stringify(value).replace(
+    /[^\x20-\x7E]/g,
+    (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}
+
+/**
+ * Decision 13: a real HTTP peer cannot receive a JavaScript exception, only a
+ * response. So an uncaught handler error becomes a conforming 500 whose body
+ * carries the message, with the serialized error in a namespaced header that
+ * another webrun peer re-throws from.
+ */
+function encodeErrorResponse(
+  codec: MessageCodec,
+  error: unknown,
+  method: string,
+  status = 500,
+  statusText = "Internal Server Error",
+): AsyncGenerator<Uint8Array> {
+  const serialized = serializeError(error);
+  let detail = asciiJson(serialized);
+  if (detail.length > MAX_DETAIL_CHARS) detail = asciiJson({ message: serialized.message });
+  // The fallback above is itself unbounded — a >64 KiB handler message would
+  // still blow the head past maxHeaderBytes, and the client would then
+  // report "head section exceeds 65536 bytes" instead of the peer's actual
+  // error (M3). Truncate unconditionally as the last resort.
+  if (detail.length > MAX_DETAIL_CHARS) detail = detail.slice(0, MAX_DETAIL_CHARS);
+  const message = serialized.message ?? statusText;
+  return codec.encodeResponse(
+    {
+      status,
+      statusText,
+      headers: [
+        ["Content-Type", "text/plain; charset=utf-8"],
+        [PEER_ERROR_HEADER, detail],
+      ],
+    },
+    [new TextEncoder().encode(message)],
+    { method },
+  );
+}
+
+/**
+ * `output` is the `Duplex` call's own generator — one logical call, per the
+ * `Duplex` contract in `@statewalker/webrun-streams`: "Consumer `.return()`
+ * on the output → producer's `finally` runs." On a mux transport
+ * (`emulateMux`), that `finally` is what frees the stream-table slot; skip it
+ * and every peer-error response leaks one slot, unboundedly, until the mux
+ * itself is exhausted (`maxStreams` reached, every further call rejected).
+ *
+ * Cancelling `output` here — not inside the codec's own decode logic — is
+ * deliberate. `codec.decodeResponse` already pulled from `output` to read the
+ * head before this function runs, so unlike the body case above there's no
+ * suspended-start no-op to worry about. And it's safe specifically *because*
+ * this is the client's own response-only generator: the request was already
+ * fully sent before we got here, so there is nothing left to write on it.
+ * The equivalent is NOT safe inside `src/http1/decode.ts`'s `ByteReader` —
+ * that code also runs when a caller wires `codec.decodeRequest`/
+ * `decodeResponse` directly onto a raw bidirectional socket (see
+ * `tests/http1-node-interop.test.ts`), where the *same* object is read from
+ * and then written back to (a server reads the request, then replies on the
+ * same socket); cancelling the read side there tears down the whole
+ * connection out from under the pending write. That was tried and reverted —
+ * see the Task 11 report for the "socket hang up" failure it caused.
+ */
+async function throwIfPeerError(
+  result: HttpFetchResult,
+  output: AsyncGenerator<Uint8Array>,
+): Promise<void> {
+  const found = result.envelope.headers.find(([k]) => k.toLowerCase() === PEER_ERROR_HEADER);
+  if (!found) return;
+  await discard(result.body);
+  try {
+    await output.return?.(undefined);
+  } catch {
+    /* the call is being abandoned; a failing cancel must not mask the peer's error */
+  }
+  let payload: { message: string };
+  try {
+    payload = JSON.parse(found[1]) as { message: string };
+  } catch {
+    payload = { message: found[1] };
+  }
+  throw deserializeError(payload);
+}
+
 /**
  * Initiate an HTTP call over a `Duplex`. The caller's `call: Duplex` is
  * obtained from any `webrun-streams-*` adapter's `connect`. Returns the
@@ -40,22 +147,58 @@ export type HttpDataHandler = (
 export async function httpFetch(
   call: Duplex,
   env: RequestEnvelope,
-  body?: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
+  body?: ByteSource,
+  options: HttpDataOptions = {},
 ): Promise<HttpFetchResult> {
-  const output = call(encodeMessage(env, body));
-  return decodeMessage<ResponseEnvelope>(output);
+  const codec = options.codec ?? defaultCodec;
+  const output = call(codec.encodeRequest(env, body));
+  const result = await codec.decodeResponse(output, { method: env.method });
+  await throwIfPeerError(result, output);
+  return result;
 }
 
 /**
  * Wrap an HTTP handler as a `Duplex` so it can be registered with any
- * `webrun-streams-*` adapter's `serve`. The duplex `split`s the input to
- * recover envelope + body, dispatches to the handler, and emits the response
- * via `encodeMessage`.
+ * `webrun-streams-*` adapter's `serve`.
  */
-export function httpServe(handler: HttpDataHandler): Duplex {
+export function httpServe(handler: HttpDataHandler, options: HttpDataOptions = {}): Duplex {
+  const codec = options.codec ?? defaultCodec;
   return async function* httpHandlerDuplex(input) {
-    const { envelope: reqEnv, body: reqBody } = await decodeMessage<RequestEnvelope>(input);
-    const result = await handler(reqEnv, reqBody);
-    yield* encodeMessage(result.envelope, result.body);
+    // A refusal to parse the request must still produce a response. Left
+    // uncaught, the exception propagates out of this generator and NOTHING is
+    // written — a real peer waits, then sees the connection end with no status
+    // at all, which is the one place the "a real peer cannot receive a
+    // JavaScript exception" rule was not applied.
+    //
+    // Only HttpParseError is converted: that is the codec's refusal type, so
+    // it means the bytes were malformed. A transport failure is not our 400 to
+    // send and must keep propagating.
+    let decoded: DecodedRequest;
+    try {
+      decoded = await codec.decodeRequest(input);
+    } catch (error) {
+      if (!(error instanceof HttpParseError)) throw error;
+      // Answer in the format the peer was speaking, when sniffing got far
+      // enough to know it; otherwise fall back to our write codec.
+      const refusalCodec = (error as { codec?: MessageCodec }).codec ?? codec;
+      // The method is unknowable — the request line may be what failed — so
+      // encode as if for GET, which permits a body and so lets the peer read
+      // why it was refused.
+      yield* encodeErrorResponse(refusalCodec, error, "GET", 400, "Bad Request");
+      return;
+    }
+    // Reply in kind: answer with the codec that actually read the request, so a
+    // peer pinned to one format is never answered in the other.
+    const replyCodec = decoded.codec ?? codec;
+    let result: HttpDataHandlerResult;
+    try {
+      result = await handler(decoded.envelope, decoded.body);
+    } catch (error) {
+      yield* encodeErrorResponse(replyCodec, error, decoded.envelope.method);
+      return;
+    }
+    yield* replyCodec.encodeResponse(result.envelope, result.body, {
+      method: decoded.envelope.method,
+    });
   };
 }

package/src/http-stubs.ts

@@ -1,4 +1,6 @@
 import { fromReadableStream, toReadableStream } from "@statewalker/webrun-streams";
+import { discard } from "./bytes.js";
+import { collectBytes, supportsRequestStreams } from "./request-streams.js";
 
 export interface SerializedHttpRequest {
   url: string;
@@ -23,14 +25,26 @@ export interface SerializedHttpResponse {
 
 export interface SerializedHttpEnvelope<Options> {
   options: Options;
+  /**
+   * The body bytes. Must be *productive*: it has to yield or finish on its own,
+   * because a body neither stub is allowed to read (a GET/HEAD/OPTIONS request,
+   * a null-body-status response) is released with `discard`, and `discard` must
+   * await one `.next()` before `.return()` — a bare `.return()` is a no-op on a
+   * generator in suspended start and would leak the producer. So a `content`
+   * that blocks forever without yielding makes the stub block with it, where an
+   * earlier version returned immediately and leaked instead. Every transport in
+   * this repo satisfies this; a `content` that waits on a peer that may never
+   * send should carry its own timeout.
+   */
   content: AsyncIterable<Uint8Array>;
 }
 
 export type HttpHandler = (request: Request) => Response | Promise<Response>;
 
 // Statuses that MUST NOT carry a body — `new Response(body, { status })` throws
-// for these (per the Fetch spec's "null body status" set).
-const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
+// for these (per the Fetch spec's "null body status" set). Exported so
+// `fetch.ts` mirrors this exact set rather than redefining it.
+export const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
 
 const REQUEST_FIELDS = [
   "url",
@@ -45,6 +59,13 @@ const REQUEST_FIELDS = [
   "keepalive",
 ] as const;
 
+/** `SerializedHttpEnvelope.content` is never absent, only empty. */
+async function* noBytes(): AsyncGenerator<Uint8Array> {}
+
+async function* oneChunk(chunk: Uint8Array): AsyncGenerator<Uint8Array> {
+  yield chunk;
+}
+
 /**
  * Returns an HTTP handler that serializes a Request, hands the envelope to
  * `send` for transport, and deserializes the reply into a Response. Used on
@@ -63,9 +84,25 @@ export function newHttpClientStub(
       const val = (request as unknown as Record<string, unknown>)[field];
       if (val !== undefined && field !== "url") (options as Record<string, unknown>)[field] = val;
     }
-    const content = request.body
-      ? fromReadableStream(request.body as ReadableStream<Uint8Array>)
-      : (async function* () {})();
+    let content: AsyncIterable<Uint8Array>;
+    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.
+      content = fromReadableStream(request.body as ReadableStream<Uint8Array>);
+    } 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, and
+      // request streaming is lost outright on this path — a 1 GiB upload from a
+      // Firefox page is a 1 GiB allocation here.
+      //
+      // The empty-versus-absent body divergence that `fetch.ts` has to live
+      // with does not arise on this transport: `SerializedHttpEnvelope` always
+      // carries a `content` iterable, so a zero-length body and no body are
+      // already the same thing here, whichever runtime produced it.
+      content = oneChunk(new Uint8Array(await request.arrayBuffer()));
+    } else {
+      content = noBytes();
+    }
 
     const result = await send({ options, content });
 
@@ -77,14 +114,14 @@ export function newHttpClientStub(
     const method = options.method;
     // `new Response(body, ...)` throws for null-body statuses (204/205/304), and
     // HEAD/OPTIONS carry no body either — drain the (empty) content stream and
-    // emit a bodyless response.
+    // emit a bodyless response. `discard` rather than a bare `.return()`: see
+    // the note at the matching site in `newHttpServerStub` below.
     if (
       method === "HEAD" ||
       method === "OPTIONS" ||
       NULL_BODY_STATUSES.has(responseOptions.status)
     ) {
-      const returnable = result.content as AsyncIterable<Uint8Array> & { return?: () => unknown };
-      await returnable.return?.();
+      await discard(result.content);
       return new Response(null, responseOptions);
     }
     return new Response(toReadableStream(result.content[Symbol.asyncIterator]()), responseOptions);
@@ -111,22 +148,39 @@ export function newHttpServerStub(
     for (const [key, value] of headers) requestHeaders.append(key, value);
 
     const hasBody = method !== "GET" && method !== "HEAD" && method !== "OPTIONS";
-    let body: ReadableStream<Uint8Array> | undefined;
-    if (hasBody) {
-      body = toReadableStream(content[Symbol.asyncIterator]());
-    } else {
-      const returnable = content as AsyncIterable<Uint8Array> & { return?: () => unknown };
-      await returnable.return?.();
-    }
-
     const requestInit: RequestInit & { duplex?: "half" } = {
       ...forwardable,
       method,
       headers: requestHeaders,
     };
-    if (hasBody) {
-      requestInit.body = body;
+    if (!hasBody) {
+      // `discard`, not a bare `.return()`. GET/HEAD/OPTIONS arrive with a
+      // `content` iterable the transport built but nobody has pulled from yet,
+      // and `.return()` on an async generator still in *suspended start* is a
+      // no-op: the body never runs, its `try/finally` never unwinds, and
+      // whatever the producer holds open — a socket, a port subscription — is
+      // never released. `discard` calls `.next()` first for exactly this
+      // reason; see its comment in `bytes.ts`.
+      //
+      // `fetch.ts` has the same shape at its null-body-status branch and still
+      // uses the bare form — not because it is safe there (it is not; its
+      // producer's `finally` does not run either) but because `discard` cannot
+      // fix it: the release has to reach the `output` generator that
+      // `fetchOverDuplex` has no handle on. See the KNOWN GAP note there. Here
+      // the producer is reachable, so here it gets released.
+      await discard(content);
+    } else if (supportsRequestStreams()) {
+      requestInit.body = toReadableStream(content[Symbol.asyncIterator]());
       requestInit.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 client direction above at least
+      // sends an empty body a JSON endpoint rejects loudly. Bytes it does
+      // accept, so drain first — at the same cost as above, the whole upload in
+      // memory and no streaming left for the handler.
+      requestInit.body = await collectBytes(content);
     }
 
     const request = new Request(url, requestInit);

package/src/http1/chunked.ts

@@ -0,0 +1,89 @@
+import type { ByteReader } from "../bytes.js";
+import { ByteStreamError } from "../bytes.js";
+import type { ByteSource } from "../message.js";
+import { HttpParseError } from "./errors.js";
+import { decodeLatin1 } from "./headers.js";
+
+const CRLF = new Uint8Array([0x0d, 0x0a]);
+const LAST_CHUNK = new Uint8Array([0x30, 0x0d, 0x0a, 0x0d, 0x0a]); // "0\r\n\r\n"
+const encoder = new TextEncoder();
+
+/**
+ * Chunk sizes are written in HEXADECIMAL — a 21-byte chunk is `15`. Writing
+ * them in decimal is the defect note 15 found in @libp2p/http, and it is the
+ * one that cannot be caught downstream: decimal digits are also valid hex, so
+ * a conforming parser silently reads the wrong length.
+ *
+ * Zero-length source chunks are skipped; a zero-sized chunk on the wire is the
+ * body terminator.
+ */
+export async function* encodeChunked(body: ByteSource): AsyncGenerator<Uint8Array> {
+  for await (const chunk of body) {
+    if (chunk.byteLength === 0) continue;
+    yield encoder.encode(`${chunk.byteLength.toString(16)}\r\n`);
+    yield chunk;
+    yield CRLF;
+  }
+  yield LAST_CHUNK;
+}
+
+/**
+ * Decode a chunked body, yielding data chunks as they arrive. Nothing is
+ * accumulated: a chunk larger than the transport's frame is yielded in pieces.
+ */
+export async function* decodeChunked(
+  reader: ByteReader,
+  maxLineBytes: number,
+): AsyncGenerator<Uint8Array> {
+  while (true) {
+    const sizeLine = decodeLatin1(await reader.readLine(maxLineBytes));
+    const semicolon = sizeLine.indexOf(";"); // chunk extensions: accepted, ignored
+    const sizeText = semicolon === -1 ? sizeLine : sizeLine.slice(0, semicolon);
+    if (!/^[0-9a-fA-F]{1,32}$/.test(sizeText)) {
+      throw new HttpParseError(`invalid chunk size: ${JSON.stringify(sizeLine)}`);
+    }
+    const size = Number.parseInt(sizeText, 16);
+    if (!Number.isSafeInteger(size)) {
+      throw new HttpParseError(`chunk size is too large: ${JSON.stringify(sizeLine)}`);
+    }
+
+    if (size === 0) {
+      // Trailer section: legal input, read and discarded, never re-emitted.
+      let used = 0;
+      while (true) {
+        const remaining = maxLineBytes - used;
+        if (remaining <= 0) {
+          throw new HttpParseError(`trailer section exceeds ${maxLineBytes} bytes`);
+        }
+        const lineBytes = await reader.readLine(remaining);
+        used += lineBytes.byteLength + 2;
+        if (used > maxLineBytes) {
+          throw new HttpParseError(`trailer section exceeds ${maxLineBytes} bytes`);
+        }
+        if (lineBytes.byteLength === 0) break;
+      }
+      return;
+    }
+
+    let remaining = size;
+    while (remaining > 0) {
+      const part = await reader.readSome(remaining);
+      if (part === undefined) {
+        throw new HttpParseError(`chunk truncated: ${remaining} of ${size} bytes missing`);
+      }
+      remaining -= part.byteLength;
+      yield part;
+    }
+
+    try {
+      if ((await reader.readLine(2)).byteLength !== 0) {
+        throw new HttpParseError("chunk data not terminated by CRLF");
+      }
+    } catch (err) {
+      if (err instanceof ByteStreamError) {
+        throw new HttpParseError("chunk data not terminated by CRLF");
+      }
+      throw err;
+    }
+  }
+}