@statewalker/webrun-http-streams 0.1.1 → 0.2.2

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

package/src/http1/encode.ts

@@ -0,0 +1,181 @@
+import { discard } from "../bytes.js";
+import type { ByteSource, RequestEnvelope, ResponseEnvelope } from "../message.js";
+import { encodeChunked } from "./chunked.js";
+import { HttpParseError } from "./errors.js";
+import {
+  assertValidHost,
+  assertValidStatusText,
+  assertValidTarget,
+  encodeHeaderLines,
+  encodeLatin1,
+  getAll,
+  isBodylessStatus,
+  isToken,
+  parseContentLength,
+  withoutHeaders,
+} from "./headers.js";
+
+export type ResolvedHttpCodecOptions = {
+  scheme: "http" | "https";
+  host: string;
+  maxHeaderBytes: number;
+};
+
+/** Headers the codec owns: a caller-supplied copy is dropped and re-derived. */
+const REQUEST_OWNED = ["host", "connection", "transfer-encoding"];
+const RESPONSE_OWNED = ["connection", "transfer-encoding"];
+
+/**
+ * Split a URL into an origin-form request target and an authority *without*
+ * going through `new URL()`. `URL` normalises percent-encoding and would
+ * re-serialise the target — which is the exact class of defect note 15 found
+ * in @libp2p/http, where rebuilding the request line silently dropped
+ * `url.search`. Here the target is a verbatim slice of the caller's string.
+ */
+export function splitTarget(
+  url: string,
+  opts: ResolvedHttpCodecOptions,
+): { target: string; authority: string } {
+  if (url.startsWith("/")) {
+    // Neither field is trusted just because it came from a caller's own url:
+    // an unvalidated CRLF here would splice a second request line (or an
+    // extra header) onto the wire — see C1.
+    assertValidTarget(url);
+    return { target: url, authority: opts.host };
+  }
+  const match = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/([^/?#]*)([^#]*)/.exec(url);
+  if (!match) {
+    throw new HttpParseError(`cannot derive a request target from url: ${JSON.stringify(url)}`);
+  }
+  // Both capture groups are mandatory in the regex above (neither is
+  // `?`-quantified), so a successful match always populates them — an empty
+  // string is possible, `undefined` is not.
+  const rawAuthority = match[1]!;
+  if (rawAuthority === "") {
+    throw new HttpParseError(`url has no authority: ${JSON.stringify(url)}`);
+  }
+  // Host is `uri-host [ ":" port ]` — no userinfo (RFC 9110 §7.2). Strip any
+  // `user:pass@` prefix so credentials never end up in a header proxies log.
+  const at = rawAuthority.lastIndexOf("@");
+  const authority = at === -1 ? rawAuthority : rawAuthority.slice(at + 1);
+  assertValidHost(authority);
+
+  const rawTarget = match[2]!;
+  const target = rawTarget === "" ? "/" : rawTarget.startsWith("/") ? rawTarget : `/${rawTarget}`;
+  assertValidTarget(target);
+  return { target, authority };
+}
+
+async function* emitBody(
+  body: ByteSource,
+  declared: number | undefined,
+): AsyncGenerator<Uint8Array> {
+  if (declared === undefined) {
+    yield* encodeChunked(body);
+    return;
+  }
+  let sent = 0;
+  for await (const chunk of body) {
+    if (chunk.byteLength === 0) continue;
+    sent += chunk.byteLength;
+    if (sent > declared) {
+      throw new HttpParseError(
+        `body exceeds declared Content-Length ${declared} (${sent} bytes so far)`,
+      );
+    }
+    yield chunk;
+  }
+  if (sent !== declared) {
+    throw new HttpParseError(`body is ${sent} bytes but Content-Length declares ${declared}`);
+  }
+}
+
+export async function* encodeRequest(
+  env: RequestEnvelope,
+  body: ByteSource | undefined,
+  opts: ResolvedHttpCodecOptions,
+): AsyncGenerator<Uint8Array> {
+  if (!isToken(env.method)) {
+    throw new HttpParseError(`invalid method: ${JSON.stringify(env.method)}`);
+  }
+  const { target, authority } = splitTarget(env.url, opts);
+  if (authority === "") {
+    throw new HttpParseError("no Host available: url has no authority and no host is configured");
+  }
+
+  const carried = withoutHeaders(env.headers, REQUEST_OWNED);
+  const declared = parseContentLength(getAll(carried, "content-length"));
+
+  let head = `${env.method} ${target} HTTP/1.1\r\n`;
+  head += `Host: ${authority}\r\n`;
+  head += encodeHeaderLines(carried);
+  head += "Connection: close\r\n";
+  if (body !== undefined && declared === undefined) head += "Transfer-Encoding: chunked\r\n";
+  head += "\r\n";
+  yield encodeLatin1(head);
+
+  if (body === undefined) {
+    // A head promising `declared` bytes with no body at all is a knowingly
+    // truncated message — the failure must land here, not on the peer that
+    // trusted the header. Content-Length: 0 is the one declared length an
+    // absent body actually satisfies. See I1.
+    if (declared !== undefined && declared !== 0) {
+      throw new HttpParseError(`body is 0 bytes but Content-Length declares ${declared}`);
+    }
+    return;
+  }
+  yield* emitBody(body, declared);
+}
+
+export async function* encodeResponse(
+  env: ResponseEnvelope,
+  body: ByteSource | undefined,
+  // Unused: response encoding needs no scheme/host/maxHeaderBytes. Kept
+  // positionally so this signature mirrors `encodeRequest`'s, which the
+  // `newHttpCodec` wrapper in ./index.ts relies on when partially applying
+  // `opts` to both.
+  _opts: ResolvedHttpCodecOptions,
+  requestMethod?: string,
+): AsyncGenerator<Uint8Array> {
+  if (!Number.isInteger(env.status) || env.status < 100 || env.status > 599) {
+    throw new HttpParseError(`invalid status: ${env.status}`);
+  }
+  const reason = env.statusText ?? "";
+  assertValidStatusText(reason);
+
+  // RFC 9110 §8.6: a 1xx or 204 MUST NOT carry Content-Length — there is no
+  // body to measure, ever, regardless of what the caller supplied. A
+  // response to HEAD is different: no body is sent on *this* response, but
+  // the Content-Length describes the body a GET would have sent, so it stays
+  // (M4).
+  const bodylessStatus = isBodylessStatus(env.status);
+  const bodyless = bodylessStatus || requestMethod?.toUpperCase() === "HEAD";
+
+  const owned = bodylessStatus ? [...RESPONSE_OWNED, "content-length"] : RESPONSE_OWNED;
+  const carried = withoutHeaders(env.headers, owned);
+  const declared = parseContentLength(getAll(carried, "content-length"));
+
+  let head = `HTTP/1.1 ${env.status} ${reason}\r\n`;
+  head += encodeHeaderLines(carried);
+  head += "Connection: close\r\n";
+  if (!bodyless && body !== undefined && declared === undefined) {
+    head += "Transfer-Encoding: chunked\r\n";
+  }
+  head += "\r\n";
+  yield encodeLatin1(head);
+
+  if (bodyless) {
+    await discard(body);
+    return;
+  }
+  if (body === undefined) {
+    // Same truncation guard as encodeRequest — see I1. Not reached when
+    // bodyless: a response to HEAD legitimately keeps a declared
+    // Content-Length with no body (M4), and that is not a truncation.
+    if (declared !== undefined && declared !== 0) {
+      throw new HttpParseError(`body is 0 bytes but Content-Length declares ${declared}`);
+    }
+    return;
+  }
+  yield* emitBody(body, declared);
+}

package/src/http1/errors.ts

@@ -0,0 +1,8 @@
+/**
+ * Raised for any byte sequence this codec refuses to interpret. Every case is
+ * a refusal to guess: HTTP/1.1 parsers that guess are how request smuggling
+ * works.
+ */
+export class HttpParseError extends Error {
+  override readonly name = "HttpParseError";
+}

package/src/http1/headers.ts

@@ -0,0 +1,263 @@
+import type { ByteReader } from "../bytes.js";
+import { HttpParseError } from "./errors.js";
+
+export type HeaderList = [string, string][];
+
+const TCHAR = new Set(
+  "!#$%&'*+-.^_`|~0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
+);
+
+const SP = 0x20;
+const HTAB = 0x09;
+
+export function isTokenChar(byte: number): boolean {
+  return byte > SP && byte < 0x7f && TCHAR.has(String.fromCharCode(byte));
+}
+
+export function isToken(value: string): boolean {
+  if (value.length === 0) return false;
+  for (const ch of value) {
+    if (!TCHAR.has(ch)) return false;
+  }
+  return true;
+}
+
+/**
+ * Header bytes are latin-1: byte-preserving, matching Node, and lossless
+ * across a decode/encode round-trip. Control characters are rejected
+ * separately by `assertValidHeaderValue`.
+ */
+export function decodeLatin1(bytes: Uint8Array): string {
+  let out = "";
+  for (const byte of bytes) out += String.fromCharCode(byte);
+  return out;
+}
+
+export function encodeLatin1(text: string): Uint8Array {
+  const out = new Uint8Array(text.length);
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code > 0xff) {
+      throw new HttpParseError(`not latin-1 encodable: ${JSON.stringify(text)}`);
+    }
+    out[i] = code;
+  }
+  return out;
+}
+
+// RFC 3986 `authority` grammar, restricted to `host [ ":" port ]` (no
+// userinfo — RFC 9110 §7.2 excludes it from Host). Two shapes: an IP-literal
+// in brackets, or a reg-name. Shared by the decoder (validating a Host header
+// taken off the wire) and the encoder (validating the authority `splitTarget`
+// derives from a caller-supplied url) so the grammar is defined exactly once.
+const HOST_IP_LITERAL = /^\[[0-9A-Fa-f:.]+\](:\d{1,5})?$/;
+const HOST_REG_NAME = /^[A-Za-z0-9._~-]+(:\d{1,5})?$/;
+
+/**
+ * Validates a value that is about to become (or was read as) a `Host`
+ * header: untrusted input either way, so an unrecognised shape is a refusal,
+ * not a guess. Rejects a present-but-empty value, one carrying userinfo
+ * (`evil.com@good.com`), and — the reason this also runs on encode — one
+ * smuggling a CRLF-terminated line into the authority of a caller-supplied
+ * url. Never applied to trusted configuration (a codec's `opts.host`).
+ */
+export function assertValidHost(host: string): void {
+  if (!HOST_IP_LITERAL.test(host) && !HOST_REG_NAME.test(host)) {
+    throw new HttpParseError(`invalid Host header: ${JSON.stringify(host)}`);
+  }
+}
+
+/**
+ * A request-target must be entirely visible ASCII (RFC 9110 VCHAR) — nothing
+ * `<= 0x20` (space and every control character, CR/LF included) and nothing
+ * `>= 0x7F` (DEL and beyond). Applied on encode (`splitTarget`, so a
+ * caller-supplied url can never inject a second request line) and on decode
+ * (so a relay that decodes then re-encodes can never put an embedded control
+ * character back on the wire).
+ */
+export function assertValidTarget(target: string): void {
+  for (let i = 0; i < target.length; i++) {
+    const code = target.charCodeAt(i);
+    if (code <= SP || code >= 0x7f) {
+      throw new HttpParseError(`invalid request-target: ${JSON.stringify(target)}`);
+    }
+  }
+}
+
+/**
+ * Shared control-character check behind both `assertValidHeaderValue` and
+ * `assertValidStatusText` — the two were previously checked by different,
+ * looser rules (statusText only rejected CR/LF), which is exactly the
+ * asymmetry class C1 and M5 are both instances of. `label` is prepended
+ * verbatim to each message, so callers keep their own wording.
+ */
+function assertNoControlChars(label: string, value: string): void {
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code === 0x0d || code === 0x0a) {
+      throw new HttpParseError(`${label} contains CR or LF`);
+    }
+    if ((code < SP && code !== HTAB) || code === 0x7f) {
+      throw new HttpParseError(`${label} contains a control character`);
+    }
+    if (code > 0xff) {
+      throw new HttpParseError(`${label} is not latin-1 encodable`);
+    }
+  }
+}
+
+export function assertValidHeaderValue(name: string, value: string): void {
+  assertNoControlChars(`header "${name}" value`, value);
+}
+
+/** Same character class as a header value (M5) — CR/LF, every C0 control, and DEL. */
+export function assertValidStatusText(value: string): void {
+  assertNoControlChars("statusText", value);
+}
+
+export function encodeHeaderLines(headers: HeaderList): string {
+  let out = "";
+  for (const [name, value] of headers) {
+    if (!isToken(name)) throw new HttpParseError(`invalid header name: ${JSON.stringify(name)}`);
+    assertValidHeaderValue(name, value);
+    out += `${name}: ${value}\r\n`;
+  }
+  return out;
+}
+
+/**
+ * Read to the blank line. `alreadyUsed` is the byte count of the start line,
+ * so the bound covers the whole head section rather than the headers alone.
+ */
+export async function readHeaderSection(
+  reader: ByteReader,
+  maxHeaderBytes: number,
+  alreadyUsed: number,
+): Promise<HeaderList> {
+  const headers: HeaderList = [];
+  let used = alreadyUsed;
+  while (true) {
+    const remaining = maxHeaderBytes - used;
+    if (remaining <= 0) {
+      throw new HttpParseError(`head section exceeds ${maxHeaderBytes} bytes`);
+    }
+    const lineBytes = await reader.readLine(remaining);
+    used += lineBytes.byteLength + 2;
+    if (used > maxHeaderBytes) {
+      throw new HttpParseError(`head section exceeds ${maxHeaderBytes} bytes`);
+    }
+    if (lineBytes.byteLength === 0) return headers;
+    if (lineBytes[0] === SP || lineBytes[0] === HTAB) {
+      throw new HttpParseError("obs-fold header continuation is not accepted");
+    }
+    const line = decodeLatin1(lineBytes);
+    const colon = line.indexOf(":");
+    if (colon <= 0) throw new HttpParseError(`malformed header line: ${JSON.stringify(line)}`);
+    const name = line.slice(0, colon);
+    if (!isToken(name)) throw new HttpParseError(`invalid header name: ${JSON.stringify(name)}`);
+    const value = line
+      .slice(colon + 1)
+      .replace(/^[ \t]+/, "")
+      .replace(/[ \t]+$/, "");
+    assertValidHeaderValue(name, value);
+    headers.push([name, value]);
+  }
+}
+
+export function getAll(headers: HeaderList, name: string): string[] {
+  const lower = name.toLowerCase();
+  return headers.filter(([k]) => k.toLowerCase() === lower).map(([, v]) => v);
+}
+
+export function withoutHeaders(headers: HeaderList, names: string[]): HeaderList {
+  const drop = new Set(names.map((n) => n.toLowerCase()));
+  return headers.filter(([k]) => !drop.has(k.toLowerCase()));
+}
+
+/**
+ * Parse a `Content-Length` field into a single validated value.
+ *
+ * RFC 9110 §8.6 permits the value to be a comma-separated list of identical
+ * numbers (a relay may have appended one), so the list is folded; differing
+ * values are a refusal, not a choice. Shared by `resolveFraming` on decode and
+ * by the encoder's declared-length check, which previously carried its own
+ * copy that did NOT split on commas — so decode accepted `5, 5` while encode
+ * rejected it, and a relay that decoded then re-encoded threw.
+ *
+ * Returns undefined when the field is absent.
+ */
+export function parseContentLength(values: string[]): number | undefined {
+  if (values.length === 0) return undefined;
+  const unique = new Set(values.flatMap((v) => v.split(",").map((s) => s.trim())));
+  if (unique.size !== 1) {
+    throw new HttpParseError(`conflicting Content-Length values: ${[...unique].join(", ")}`);
+  }
+  // `unique.size === 1` is checked directly above, so this spread has exactly
+  // one element. The `!` is what lets a consumer compiling with
+  // `noUncheckedIndexedAccess` build against this source: without it `raw` is
+  // `string | undefined` and the `.test(raw)` below is a type error in THEIR
+  // build, not in this package's own (which does not enable the flag, so it
+  // cannot catch the regression). It was lost once already, in a rebase that
+  // resolved toward a refactor of this function.
+  const raw = [...unique][0]!;
+  if (!/^\d{1,15}$/.test(raw)) {
+    throw new HttpParseError(`invalid Content-Length: ${JSON.stringify(raw)}`);
+  }
+  return Number(raw);
+}
+
+/**
+ * Statuses that carry no body whatever the headers say (RFC 9110 §8.6): 1xx,
+ * 204 and 304. Defined once because the encoder must not frame a body for
+ * them and the decoder must not try to read one — two lists that agreed today
+ * and were free to drift tomorrow.
+ *
+ * A response to HEAD is also bodyless, but that depends on the request rather
+ * than the status, so callers test it separately.
+ */
+export function isBodylessStatus(status: number): boolean {
+  return status < 200 || status === 204 || status === 304;
+}
+
+export type BodyFraming =
+  | { kind: "chunked" }
+  | { kind: "length"; length: number }
+  | { kind: "none" };
+
+/**
+ * RFC 9112 §6.3, with every ambiguity turned into a refusal. In particular a
+ * message declaring both Content-Length and Transfer-Encoding is rejected
+ * rather than resolved — disagreeing on which one wins is request smuggling.
+ */
+export function resolveFraming(headers: HeaderList, version: string): BodyFraming {
+  const te = getAll(headers, "transfer-encoding");
+  const cl = getAll(headers, "content-length");
+
+  if (te.length > 0 && cl.length > 0) {
+    throw new HttpParseError(
+      "message declares both Content-Length and Transfer-Encoding; refusing (request smuggling)",
+    );
+  }
+
+  if (te.length > 0) {
+    const encodings = te
+      .join(",")
+      .split(",")
+      .map((s) => s.trim().toLowerCase())
+      .filter((s) => s !== "");
+    if (encodings.length !== 1 || encodings[0] !== "chunked") {
+      throw new HttpParseError(`unsupported Transfer-Encoding: ${JSON.stringify(te.join(", "))}`);
+    }
+    if (version === "HTTP/1.0") {
+      throw new HttpParseError("Transfer-Encoding is not valid in HTTP/1.0");
+    }
+    return { kind: "chunked" };
+  }
+
+  const length = parseContentLength(cl);
+  if (length !== undefined) {
+    return { kind: "length", length };
+  }
+
+  return { kind: "none" };
+}