@statewalker/webrun-http-streams 0.1.1 → 0.2.1

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;
+    }
+  }
+}

package/src/http1/decode.ts

@@ -0,0 +1,208 @@
+import { ByteReader, ByteStreamError } from "../bytes.js";
+import type { ByteSource, DecodedRequest, DecodedResponse } from "../message.js";
+import { decodeChunked } from "./chunked.js";
+import type { ResolvedHttpCodecOptions } from "./encode.js";
+import { HttpParseError } from "./errors.js";
+import {
+  assertValidHost,
+  assertValidTarget,
+  type BodyFraming,
+  decodeLatin1,
+  getAll,
+  isBodylessStatus,
+  isToken,
+  readHeaderSection,
+  resolveFraming,
+} from "./headers.js";
+
+const VERSIONS = new Set(["HTTP/1.1", "HTTP/1.0"]);
+const ABSOLUTE_FORM = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
+
+/**
+ * One message per Duplex call (ADR-0006), so bytes after a complete message
+ * are an error. Checked against what is ALREADY BUFFERED rather than by
+ * awaiting end-of-stream: a live socket from a keep-alive peer never reaches
+ * EOF, so awaiting one would hang instead of failing.
+ */
+function assertNoBufferedBytes(reader: ByteReader): void {
+  const extra = reader.bufferedLength();
+  if (extra > 0) {
+    throw new HttpParseError(`${extra} trailing bytes after a complete message`);
+  }
+}
+
+/**
+ * The public error contract (I2): everything leaving `decodeRequest` /
+ * `decodeResponse` is an `HttpParseError`, whether the refusal happened
+ * synchronously (a malformed start line or header) or lazily while the body
+ * is later drained. `ByteStreamError` — the `ByteReader`'s own class, never
+ * exported — is the one thing converted here, message and all preserved via
+ * `cause`. Anything else is a genuine failure of the underlying source (a
+ * dropped socket, say) and must reach the caller unchanged: blanket-catching
+ * would hide that distinction.
+ */
+function toHttpParseError(err: unknown): never {
+  if (err instanceof ByteStreamError) {
+    throw new HttpParseError(err.message, { cause: err });
+  }
+  throw err;
+}
+
+/** Applies `toHttpParseError` across the whole lifetime of a body generator. */
+async function* convertBodyErrors(source: AsyncGenerator<Uint8Array>): AsyncGenerator<Uint8Array> {
+  try {
+    yield* source;
+  } catch (err) {
+    toHttpParseError(err);
+  }
+}
+
+async function* readBody(
+  reader: ByteReader,
+  framing: BodyFraming,
+  opts: ResolvedHttpCodecOptions,
+  noneMeansEof: boolean,
+): AsyncGenerator<Uint8Array> {
+  if (framing.kind === "chunked") {
+    yield* decodeChunked(reader, opts.maxHeaderBytes);
+    assertNoBufferedBytes(reader);
+    return;
+  }
+  if (framing.kind === "length") {
+    let remaining = framing.length;
+    while (remaining > 0) {
+      const part = await reader.readSome(remaining);
+      if (part === undefined) {
+        throw new HttpParseError(`body truncated: ${remaining} of ${framing.length} bytes missing`);
+      }
+      remaining -= part.byteLength;
+      yield part;
+    }
+    assertNoBufferedBytes(reader);
+    return;
+  }
+  if (noneMeansEof) {
+    yield* reader.rest();
+    return;
+  }
+  assertNoBufferedBytes(reader);
+}
+
+/**
+ * `readLine`'s bound is best-effort — it is skipped when the line is already
+ * buffered — so a very long start line can reach these messages intact. Since
+ * a refusal is now echoed back to the sender in a 400 body, quote only enough
+ * to diagnose rather than reflecting the whole thing.
+ */
+function quoteLine(line: string): string {
+  const MAX = 120;
+  return line.length <= MAX
+    ? JSON.stringify(line)
+    : `${JSON.stringify(line.slice(0, MAX))} (truncated from ${line.length} chars)`;
+}
+
+export async function decodeRequest(
+  input: ByteSource,
+  opts: ResolvedHttpCodecOptions,
+): Promise<DecodedRequest> {
+  const reader = new ByteReader(input);
+  try {
+    const startBytes = await reader.readLine(opts.maxHeaderBytes);
+    const startLine = decodeLatin1(startBytes);
+    const parts = startLine.split(" ");
+    if (parts.length !== 3) {
+      throw new HttpParseError(`malformed request line: ${quoteLine(startLine)}`);
+    }
+    // `parts.length === 3` is checked above, so all three elements are present.
+    const [method, target, version] = parts as [string, string, string];
+    if (!isToken(method)) throw new HttpParseError(`invalid method: ${JSON.stringify(method)}`);
+    if (!VERSIONS.has(version)) {
+      throw new HttpParseError(`unsupported HTTP version: ${JSON.stringify(version)}`);
+    }
+    if (target === "*") {
+      throw new HttpParseError("asterisk-form request target is not supported");
+    }
+    // A relay that decodes then re-encodes must never be able to put a
+    // control character (a raw CR chief among them) back onto a request
+    // line — see C1.
+    assertValidTarget(target);
+
+    const headers = await readHeaderSection(reader, opts.maxHeaderBytes, startBytes.byteLength + 2);
+
+    const hosts = getAll(headers, "host");
+    if (hosts.length > 1) throw new HttpParseError("multiple Host headers");
+    const host = hosts[0];
+
+    let url: string;
+    if (target.startsWith("/")) {
+      if (version === "HTTP/1.1" && host === undefined) {
+        throw new HttpParseError("HTTP/1.1 request has no Host header");
+      }
+      if (host !== undefined) assertValidHost(host);
+      // The scheme is not on the wire in origin-form; it comes from config.
+      url = `${opts.scheme}://${host ?? opts.host}${target}`;
+    } else if (ABSOLUTE_FORM.test(target)) {
+      url = target;
+    } else {
+      throw new HttpParseError(`unsupported request target: ${JSON.stringify(target)}`);
+    }
+
+    // `Host` grammar alone is not sufficient proof that the assembled url is
+    // sane — this is a fail-safe belt-and-braces check, not a
+    // re-serialisation: the parsed `URL` is discarded, and `url` itself is
+    // what reaches the envelope untouched.
+    try {
+      new URL(url);
+    } catch {
+      throw new HttpParseError(`decoded url is not a valid URL: ${JSON.stringify(url)}`);
+    }
+
+    return {
+      envelope: { url, method, headers },
+      body: convertBodyErrors(readBody(reader, resolveFraming(headers, version), opts, false)),
+    };
+  } catch (err) {
+    toHttpParseError(err);
+  }
+}
+
+export async function decodeResponse(
+  input: ByteSource,
+  opts: ResolvedHttpCodecOptions,
+  method: string,
+): Promise<DecodedResponse> {
+  const reader = new ByteReader(input);
+  try {
+    const startBytes = await reader.readLine(opts.maxHeaderBytes);
+    const startLine = decodeLatin1(startBytes);
+
+    const firstSp = startLine.indexOf(" ");
+    if (firstSp === -1) {
+      throw new HttpParseError(`malformed status line: ${quoteLine(startLine)}`);
+    }
+    const version = startLine.slice(0, firstSp);
+    if (!VERSIONS.has(version)) {
+      throw new HttpParseError(`unsupported HTTP version: ${JSON.stringify(version)}`);
+    }
+    const afterVersion = startLine.slice(firstSp + 1);
+    const secondSp = afterVersion.indexOf(" ");
+    const codeText = secondSp === -1 ? afterVersion : afterVersion.slice(0, secondSp);
+    if (!/^\d{3}$/.test(codeText)) {
+      throw new HttpParseError(`invalid status code: ${JSON.stringify(codeText)}`);
+    }
+    const status = Number(codeText);
+    const statusText = secondSp === -1 ? "" : afterVersion.slice(secondSp + 1);
+
+    const headers = await readHeaderSection(reader, opts.maxHeaderBytes, startBytes.byteLength + 2);
+
+    const bodyless = isBodylessStatus(status) || method.toUpperCase() === "HEAD";
+    const framing: BodyFraming = bodyless ? { kind: "none" } : resolveFraming(headers, version);
+
+    return {
+      envelope: { status, statusText, headers },
+      body: convertBodyErrors(readBody(reader, framing, opts, !bodyless)),
+    };
+  } catch (err) {
+    toHttpParseError(err);
+  }
+}