tunnelfetch 1.0.0

package/src/util/deadline.js

@@ -0,0 +1,266 @@
+// Deadlines.
+//
+// The design constraint here is measured, not assumed: on the target runtime `Date.now()` and
+// `performance.now()` are frozen for the whole of a synchronous execution slice and only advance
+// across I/O. A timeout implemented by comparing clock readings in a loop therefore either never
+// fires or fires at an unrelated moment. Everything below is driven by timer callbacks and stream
+// events instead, and no code path decides "has it been long enough?" by reading a clock.
+//
+// The idle deadline is the important one. For a streaming response, "how long since the last byte"
+// is the signal that something is wrong; "how long in total" is not — a legitimate download or a
+// slow SSE feed can run for minutes. Total is a backstop, idle is the control.
+
+import { TimeoutError, codes } from '../errors.js';
+
+/**
+ * @typedef {object} DeadlineOptions
+ * @property {number} [connectMs]    TCP connect (and proxy handshake) must complete within this
+ * @property {number} [handshakeMs]  TLS handshake must complete within this
+ * @property {number} [headersMs]    response status line + headers must arrive within this
+ * @property {number} [idleMs]       maximum gap between body chunks
+ * @property {number} [totalMs]      hard ceiling on the whole request; a backstop, not the control
+ */
+
+// The idle default is deliberately generous, and the reasoning is asymmetry rather than taste.
+// Idle time is free on this runtime — it bills CPU, not wall clock — and once response headers
+// have arrived a connection no longer occupies one of the six per-invocation slots reserved for
+// requests still awaiting headers. So an over-long idle timeout costs a connection that is not
+// being paid for, while an over-short one aborts a request that was going to succeed. Nor can the
+// value be tuned to a peer's heartbeat: streaming APIs that send keep-alive events do not commit
+// to an interval, and a server generating a long response before its first token is legitimately
+// silent for exactly as long as it takes. Err long.
+export const DEFAULT_DEADLINES = Object.freeze({
+  connectMs: 10_000,
+  handshakeMs: 15_000,
+  // The one phase that does hold a header-wait slot, hence tighter than idle. A peer that buffers
+  // a whole slow response before sending its head needs this raised; streaming peers do not.
+  headersMs: 30_000,
+  idleMs: 60_000,
+  totalMs: 0, // 0 means no ceiling: streaming responses legitimately run long
+});
+
+/**
+ * Owns every timer for one request and exposes a single AbortSignal that fires when any of them
+ * elapses. Callers abort on the signal rather than each racing their own promise, so a timeout in
+ * one phase tears down the whole connection instead of leaking a socket into the background.
+ */
+export class DeadlineController {
+  /**
+   * @param {DeadlineOptions} options
+   * @param {{ signal?: AbortSignal, setTimer?: typeof setTimeout, clearTimer?: typeof clearTimeout }} [env]
+   */
+  constructor(options = {}, env = {}) {
+    this.options = { ...DEFAULT_DEADLINES, ...options };
+    // Wrapped rather than captured bare: on the target runtime the timer builtins are bound to
+    // the global object and a detached `setTimeout` reference throws "Illegal invocation".
+    // Node tolerates the detached form, so this only ever fails in production — which is where
+    // the live rig found it.
+    this._setTimer = env.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    this._clearTimer = env.clearTimer ?? ((id) => clearTimeout(id));
+    this._controller = new AbortController();
+    /** @type {any} */
+    this._phaseTimer = null;
+    this._phaseName = null;
+    /** @type {any} */
+    this._idleTimer = null;
+    this._totalTimer = null;
+    this._settled = false;
+    /** @type {TimeoutError|null} */
+    this.error = null;
+
+    if (this.options.totalMs > 0) {
+      this._totalTimer = this._setTimer(
+        () => this._fire(codes.TIMEOUT_TOTAL, 'total', this.options.totalMs),
+        this.options.totalMs,
+      );
+    }
+
+    // An externally supplied signal (the caller's AbortSignal) must tear us down too.
+    const outer = env.signal;
+    if (outer) {
+      if (outer.aborted) this._abortFromOuter(outer);
+      else {
+        this._onOuterAbort = () => this._abortFromOuter(outer);
+        outer.addEventListener('abort', this._onOuterAbort, { once: true });
+        this._outer = outer;
+      }
+    }
+  }
+
+  get signal() {
+    return this._controller.signal;
+  }
+
+  get aborted() {
+    return this._controller.signal.aborted;
+  }
+
+  _abortFromOuter(outer) {
+    if (this._settled) return;
+    this._settled = true;
+    this._clearAll();
+    this._controller.abort(outer.reason ?? new Error('aborted by caller'));
+  }
+
+  _fire(code, phase, ms) {
+    if (this._settled) return;
+    this._settled = true;
+    this._clearAll();
+    this.error = new TimeoutError(
+      code,
+      `${phase} deadline of ${ms}ms elapsed`,
+      { phase, ms },
+    );
+    this._controller.abort(this.error);
+  }
+
+  _clearAll() {
+    for (const t of [this._phaseTimer, this._idleTimer, this._totalTimer]) {
+      if (t !== null && t !== undefined) this._clearTimer(t);
+    }
+    this._phaseTimer = this._idleTimer = this._totalTimer = null;
+  }
+
+  /**
+   * Start a bounded phase. Returns a function that ends it. Only one phase runs at a time; a new
+   * phase implicitly ends the previous one, which matches the actual sequence
+   * connect -> handshake -> headers and keeps callers from having to unwind by hand.
+   */
+  beginPhase(name) {
+    this.endPhase();
+    const ms = this.options[`${name}Ms`];
+    if (!ms || ms <= 0) return () => {};
+    this._phaseName = name;
+    const code =
+      name === 'connect' ? codes.TIMEOUT_CONNECT
+      : name === 'handshake' ? codes.TIMEOUT_HANDSHAKE
+      : codes.TIMEOUT_HEADERS;
+    this._phaseTimer = this._setTimer(() => this._fire(code, name, ms), ms);
+    return () => this.endPhase();
+  }
+
+  endPhase() {
+    if (this._phaseTimer !== null) {
+      this._clearTimer(this._phaseTimer);
+      this._phaseTimer = null;
+      this._phaseName = null;
+    }
+  }
+
+  /**
+   * Arm the idle deadline. Call `touch()` on every byte that arrives; each touch restarts the
+   * timer. Nothing here reads a clock, which is what makes it work on a runtime whose clock is
+   * frozen between I/O events.
+   */
+  beginIdle() {
+    this.endPhase();
+    this.touch();
+  }
+
+  touch() {
+    const ms = this.options.idleMs;
+    if (!ms || ms <= 0 || this._settled) return;
+    if (this._idleTimer !== null) this._clearTimer(this._idleTimer);
+    this._idleTimer = this._setTimer(() => this._fire(codes.TIMEOUT_IDLE, 'idle', ms), ms);
+  }
+
+  /** Release every timer. Safe to call more than once; must be called on every exit path. */
+  dispose() {
+    this._settled = true;
+    this._clearAll();
+    if (this._outer && this._onOuterAbort) {
+      this._outer.removeEventListener('abort', this._onOuterAbort);
+      this._outer = null;
+    }
+  }
+
+  /**
+   * Reject as soon as the signal aborts, resolve when `promise` settles first.
+   * The abort reason is preserved so the caller sees the typed TimeoutError, not a generic abort.
+   */
+  race(promise) {
+    if (this.aborted) return Promise.reject(this.signal.reason);
+    return new Promise((resolve, reject) => {
+      const onAbort = () => reject(this.signal.reason);
+      this.signal.addEventListener('abort', onAbort, { once: true });
+      promise.then(
+        (v) => {
+          this.signal.removeEventListener('abort', onAbort);
+          resolve(v);
+        },
+        (e) => {
+          this.signal.removeEventListener('abort', onAbort);
+          reject(e);
+        },
+      );
+    });
+  }
+}
+
+/**
+ * Wrap a body stream so every chunk touches the idle deadline and an abort surfaces as the typed
+ * timeout error rather than a bare AbortError.
+ *
+ * The stream is consumed with a plain reader rather than piped through a TransformStream because
+ * a transform would buffer a chunk ahead, which is exactly the wrong behaviour for an idle
+ * deadline: the timer must be reset by data reaching the consumer, not by data reaching a queue.
+ *
+ * @param {ReadableStream<Uint8Array>} source
+ * @param {DeadlineController} deadlines
+ */
+export function withIdleDeadline(source, deadlines) {
+  const reader = source.getReader();
+  return new ReadableStream({
+    async pull(controller) {
+      try {
+        const { value, done } = await deadlines.race(reader.read());
+        if (done) {
+          deadlines.dispose();
+          controller.close();
+          return;
+        }
+        deadlines.touch();
+        controller.enqueue(value);
+      } catch (e) {
+        deadlines.dispose();
+        try {
+          await reader.cancel(e);
+        } catch {
+          /* the source may already be errored */
+        }
+        controller.error(e);
+      }
+    },
+    async cancel(reason) {
+      deadlines.dispose();
+      try {
+        await reader.cancel(reason);
+      } catch {
+        /* already gone */
+      }
+    },
+  });
+}
+
+/**
+ * One-shot deadline for a promise that has no stream behind it, e.g. a socket's `opened`.
+ * Prefer DeadlineController when several phases share a teardown.
+ */
+export function withDeadline(promise, ms, code, what, env = {}) {
+  if (!ms || ms <= 0) return promise;
+  const setTimer = env.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = env.clearTimer ?? ((id) => clearTimeout(id));
+  return new Promise((resolve, reject) => {
+    const t = setTimer(() => reject(new TimeoutError(code, `${what} did not complete within ${ms}ms`, { ms, what })), ms);
+    promise.then(
+      (v) => {
+        clearTimer(t);
+        resolve(v);
+      },
+      (e) => {
+        clearTimer(t);
+        reject(e);
+      },
+    );
+  });
+}

package/src/warmup-fixture.js

@@ -0,0 +1,85 @@
+// GENERATED by scripts/gen-warmup-fixture.mjs — do not edit by hand; rerun the script.
+//
+// A recorded TLS 1.3 handshake + one HTTP/1.1 exchange between this package's own client and the
+// offline suite's honest test server, over an in-memory pipe. warmup() replays the server's bytes
+// through the real parsers, key schedule, AEAD, trust layer and HTTP head parser.
+//
+// SECURITY NOTE — on the private key below: CLIENT_PRIV_PKCS8 is the fixture client's ephemeral
+// X25519 key, and the chain here is synthetic with a reserved-name subject (warmup.invalid,
+// RFC 2606). Nothing trusts any of this material: the chain anchors only to its own baked root,
+// which is passed explicitly as an anchors-mode trust config inside warmup() and never enters the
+// bundled store; the "traffic" it decrypts is this fixture itself. Possession of the key or chain
+// grants exactly nothing. It exists so the replay is deterministic without calling
+// getRandomValues/generateKey, which the target runtime forbids at module (global) scope.
+
+const B = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+
+export const WARMUP_HOSTNAME = "warmup.invalid";
+export const WARMUP_NOW = 1893456000000; // fixed epoch ms inside the chain's validity window
+
+const CLIENT_PRIV =
+  "MC4CAQAwBQYDK2VuBCIEIPjlXa5xRQTO0OmW85dWmeM6C0AjCqfOKH5MJlnIpT9b";
+const CLIENT_PUB =
+  "vbmT3r0piIyf5GavMXh1RqIsCml4dFibAAgovDW+Vww=";
+const CLIENT_RANDOM =
+  "AwoRGB8mLTQ7QklQV15lbHN6gYiPlp2kq7K5wMfO1dw=";
+const SESSION_ID =
+  "BRAbJjE8R1JdaHN+iZSfqrXAy9bh7PcCDRgjLjlET1o=";
+const CLIENT_HELLO =
+  "AQAA9AMDAwoRGB8mLTQ7QklQV15lbHN6gYiPlp2kq7K5wMfO1dwgBRAbJjE8R1JdaHN+iZSfqrXAy9bh7PcCDRgjLjlET1oADBMB" +
+  "EwLAK8AvwCzAMAEAAJ8AAAATABEAAA53YXJtdXAuaW52YWxpZAAFAAUBAAAAAAAKAAoACAAdABcAGAAZAA0AFgAUBAMFAwYDCAQI" +
+  "BQgGCAcEAQUBBgEAEAALAAkIaHR0cC8xLjEAKwAFBAMEAwMAMwAmACQAHQAgvbmT3r0piIyf5GavMXh1RqIsCml4dFibAAgovDW+" +
+  "VwwALQACAQEAFwAAAAsAAgEA/wEAAQA=";
+const SERVER_BYTES =
+  "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";
+const ROOT_DER =
+  "MIIC2jCCAcKgAwIBAgIBATANBgkqhkiG9w0BAQsFADAeMRwwGgYDVQQDDBNXYXJtdXAgRml4dHVyZSBSb290MB4XDTI1MDEwMTAw" +
+  "MDAwMFoXDTM1MDEwMTAwMDAwMFowHjEcMBoGA1UEAwwTV2FybXVwIEZpeHR1cmUgUm9vdDCCASIwDQYJKoZIhvcNAQEBBQADggEP" +
+  "ADCCAQoCggEBAMlyqJWB5tdme7o+TptR4T2er2MD5gsVcRmg1XWAIHnjY5Wy+cQ9dn670JtY5My0WBX+RSDPFsRzPnimzyLm2Jzs" +
+  "J8xpOMDtfE3/NUjxLSHrhdxJ+gFqoB0j7faIzLar1EXMdlhGCmFtXXoMQyuKhlMRzqP3VpH0N91OkGueQFlJAsuazEf9zm0v6PnV" +
+  "1QuH4X4+/wRYeAjrLmksLkLhI2h/QZ/EwiVwcLQUvPb4kSHeemZKRRXByLAqOBj6g/MqFRkhqiYQmDB4upjBcYHC8Ae9b02hP8vQ" +
+  "q9Dv5pRGloGk7olcviiSTj3YTIFd5Cd7xQZXyE42dJa6C9bZHkgZHPMCAwEAAaMjMCEwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8B" +
+  "Af8EBAMCAgQwDQYJKoZIhvcNAQELBQADggEBAB62L1/vofc1iZN1EoyIdHfgQZS7EtrjO4kkpHJPb2e1AmgvSCGSBC1OBaqlgpcT" +
+  "gSfmwSY7g059w18gaEkBhjm5czUmt+IM1DWir6hLPI//6QizsQo0AatePnMvJYuny9VMG2HWbpY17IKxT3/sG4zID7XtDjycuBkf" +
+  "uy6DN6Qrp0+aqYMfXs28HWwDgf3b7ZjEAwquSQ+dG8Ml36fd8hjydf2VjOl0h5C3xfc88sEEv0BAks11cYjHDT6jHNYYbXfWcesk" +
+  "nflRe2my0pLsKJFzVhQvpWl6Tud5+Im99hi0GMI1L17hMv9YlCGR+vIQsP78y/WTIEHMiFTpCWd1NTY=";
+
+export const WARMUP_FIXTURE = {
+  clientPrivPkcs8: () => B(CLIENT_PRIV),
+  clientPubRaw: () => B(CLIENT_PUB),
+  clientRandom: () => B(CLIENT_RANDOM),
+  legacySessionId: () => B(SESSION_ID),
+  clientHello: () => B(CLIENT_HELLO),
+  serverBytes: () => B(SERVER_BYTES),
+  rootDer: () => B(ROOT_DER),
+};

package/src/warmup.js

@@ -0,0 +1,243 @@
+// Opt-in JIT warmup: replay a recorded TLS 1.3 handshake, proxy CONNECT exchange and HTTP
+// response through this package's REAL drivers — record layer, negotiation, key schedule, AEAD,
+// trust and HTTP parsing — so a fresh isolate's first real request runs code V8 has already
+// executed and tiered.
+//
+// Why this exists. On the primary target runtime, per-request CPU is billed (and on the free
+// plan, enforced at 10 ms) while module-scope evaluation is a separate startup budget — and V8
+// compiles and optimises per function per isolate, ramping over the first ~dozen executions.
+// Measured on the edge, a fresh isolate's first proxied request costs ~46 ms of request CPU
+// against a ~10 ms tiered floor, with ~60-80 ms of excess spread across the early ramp.
+// Executing the hot path at module scope moves that excess into the startup budget.
+//
+// The trade, stated so a reader can decide rather than cargo-cult:
+//   * On plans that do not bill startup CPU (standard Workers), warmup converts billed request
+//     milliseconds into unbilled startup milliseconds. It still spends real wall time at isolate
+//     start and consumes part of the hard startup CPU limit (1 s), so it is wrong where the
+//     startup budget is already tight.
+//   * On deployment modes that bill startup CPU as well (Cloudflare's dynamic Worker loading,
+//     for example), warmup is the same work still paid for, plus wall time — a pure loss. A
+//     library must not make that choice for its consumer, which is why nothing in this package
+//     ever calls warmup() itself: it runs only if the consumer imports and calls it, typically
+//     at module scope of their worker:
+//
+//         import { warmup } from 'tunnelfetch';
+//         await warmup();
+//
+// What it deliberately is NOT:
+//   * Not caching. Every call decodes the fixture and derives everything afresh and retains
+//     nothing; not calling warmup() yields byte-identical behaviour, just slower first
+//     executions. Nothing derived from any trust configuration is kept — the replay verifies its
+//     own synthetic chain against its own baked root through an explicit anchors-mode config
+//     that never touches the bundled store.
+//   * Not a network client. No socket, no randomness, no timers. The runtime forbids
+//     getRandomValues, key generation, timers and I/O at global scope — which is exactly where
+//     this is meant to run — so the replay's nondeterminism was fixed at recording time
+//     (scripts/gen-warmup-fixture.mjs) and shipped as bytes, and the "transport" is a hand-made
+//     reader/writer pair over those bytes: the platform's stream classes are never touched,
+//     because reading them is one of the operations global scope forbids.
+//
+// Coverage, honestly stated: the proxy CONNECT layer, the whole TLS client (connectTls: record
+// layer, both negotiation paths' shared code, transcript, key schedule, AEAD, CertificateVerify
+// and chain validation) and HTTP head parsing/serialisation all run for real. What cannot run
+// at global scope stays cold: the platform-stream plumbing (plaintextDuplex readers, body
+// streams, gzip DecompressionStream, chunked decoding) and the Client facade above
+// openConnection (its URL/pool/deadline glue). The measured effect on the ramp lives with the
+// bench rig, not here.
+
+import { openHttpConnect } from './proxy/http-connect.js';
+import { connectTls } from './tls/connect.js';
+import { buildClientHello, generateKeyShare } from './tls/handshake-messages.js';
+import { TLS12, TLS13 } from './tls/constants.js';
+import { verifyChain } from './trust/index.js';
+import { ByteReader, concat, equal, utf8 } from './util/bytes.js';
+import { serializeRequestHead } from './http1/request.js';
+import { bodyFraming, readResponseHead } from './http1/response.js';
+import { charsetFor, decodeText } from './client/decode.js';
+import { WARMUP_FIXTURE, WARMUP_HOSTNAME, WARMUP_NOW } from './warmup-fixture.js';
+
+/**
+ * A hand-made "readable": satisfies exactly the surface ByteReader uses (getReader().read()),
+ * delivering the given chunks then failing loudly. Not a platform ReadableStream on purpose —
+ * reading one of those is forbidden in the global scope this module targets.
+ * @param {Uint8Array[]} chunks
+ */
+function cannedReadable(chunks) {
+  let i = 0;
+  return {
+    getReader: () => ({
+      read: async () => {
+        if (i < chunks.length) return { value: chunks[i++], done: false };
+        // Past the recording: the parsers and the fixture disagree. Failing beats hanging the
+        // caller's startup on a promise that never settles.
+        throw new Error('warmup fixture exhausted: the recording and the replay disagree');
+      },
+      releaseLock() {},
+      cancel: async () => {},
+    }),
+  };
+}
+
+/** The matching "writable": collects what the client sends. Same duck-typing rationale. */
+function sinkWritable() {
+  const written = [];
+  return {
+    written,
+    getWriter: () => ({
+      write: async (chunk) => { written.push(chunk); },
+      close: async () => {},
+      abort: async () => {},
+      releaseLock() {},
+    }),
+  };
+}
+
+/** A ByteReader over already-decrypted bytes; running past them is a loud error. */
+function preloadedReader(bytes) {
+  const reader = new ByteReader(cannedReadable([]));
+  reader.unshift(bytes);
+  return reader;
+}
+
+const CONNECT_REPLY = 'HTTP/1.1 200 Connection established\r\n\r\n';
+
+/** Tag failures with the replay stage, so `{ ok: false }` names where the runtime said no. */
+async function step(name, fn) {
+  try {
+    return await fn();
+  } catch (e) {
+    if (e && typeof e === 'object' && e.warmupStage === undefined) e.warmupStage = name;
+    throw e;
+  }
+}
+
+/** One full replay: proxy CONNECT, then the recorded TLS handshake, then the HTTP exchange. */
+async function replayOnce() {
+  const F = WARMUP_FIXTURE;
+  const hostname = WARMUP_HOSTNAME;
+
+  // --- drift detector, before anything tries to decrypt -------------------------------------
+  // The recording is only replayable while the ClientHello the package builds is byte-identical
+  // to the one recorded. Any change to the offer (ciphers, groups, extensions, ALPN) fails HERE
+  // with instructions, rather than three stages later as an opaque AEAD error.
+  const { fixedPair } = await step('drift-check', async () => {
+    const clientPriv = await crypto.subtle.importKey(
+      'pkcs8', F.clientPrivPkcs8(), { name: 'X25519' }, false, ['deriveBits']);
+    const clientPub = await crypto.subtle.importKey(
+      'raw', F.clientPubRaw(), { name: 'X25519' }, true, []);
+    const pair = async () => ({ publicKey: clientPub, privateKey: clientPriv });
+    const share = await generateKeyShare(0x001d, { generateKeyPair: pair });
+    const probe = buildClientHello({
+      hostname,
+      keyShares: [share],
+      random: F.clientRandom(),
+      legacySessionId: F.legacySessionId(),
+      versions: [TLS13, TLS12],
+    });
+    if (!equal(probe.message, F.clientHello())) {
+      throw new Error('warmup fixture drift: buildClientHello no longer matches the recording; ' +
+        'rerun scripts/gen-warmup-fixture.mjs');
+    }
+    return { fixedPair: pair };
+  });
+
+  // --- proxy CONNECT layer, for real ---------------------------------------------------------
+  await step('proxy-connect', async () => {
+    const tunnel = await openHttpConnect({
+      proxy: { protocol: 'http', hostname, port: 3128, username: 'warm', password: 'up' },
+      target: { hostname, port: 443 },
+      connect: () => ({
+        readable: cannedReadable([utf8(CONNECT_REPLY)]),
+        writable: sinkWritable(),
+        opened: Promise.resolve({}),
+        close: async () => {},
+      }),
+    });
+    if (tunnel.socket == null) throw new Error('warmup: CONNECT replay produced no tunnel');
+  });
+
+  // --- the whole TLS client over the recorded bytes ------------------------------------------
+  // The transport is hand-made (see cannedReadable): the real record layer, drivers, key
+  // schedule, AEAD, trust and negotiation all execute exactly as in production.
+  const tlsSink = sinkWritable();
+  const session = await step('tls-handshake', () => connectTls({
+    transport: { readable: cannedReadable([F.serverBytes()]), writable: tlsSink },
+    hostname,
+    verifyPeer: (chain, host) => verifyChain({
+      chain, hostname: host, trust: { mode: 'anchors', anchors: [F.rootDer()] }, now: WARMUP_NOW,
+    }),
+    options: { clientRandom: F.clientRandom(), legacySessionId: F.legacySessionId() },
+    deps: { generateKeyPair: fixedPair },
+  }));
+
+  // --- HTTP over the session's record layer directly -----------------------------------------
+  // session.readable/writable are platform streams (forbidden here); session.record is not.
+  return step('http-exchange', async () => {
+    const request = serializeRequestHead({
+      method: 'GET',
+      target: '/',
+      headers: [
+        ['host', hostname], ['accept', '*/*'], ['accept-encoding', 'gzip, deflate'],
+        ['connection', 'keep-alive'],
+      ],
+    });
+    await session.record.writeAppData(request);
+    const plain = [];
+    for (;;) {
+      const chunk = await session.record.readAppData();
+      if (chunk === null) break; // the recorded close_notify
+      plain.push(chunk);
+    }
+    const reader = preloadedReader(concat(plain));
+    const head = await readResponseHead(reader);
+    const framing = bodyFraming({ status: head.status, method: 'GET', headers: head.headers });
+    if (framing.kind !== 'content-length') {
+      throw new Error(`warmup: recorded response framing is ${framing.kind}, expected content-length`);
+    }
+    const body = await reader.readExactly(framing.length, 'warmup response body');
+    const text = decodeText(body, charsetFor(head.headers.get('content-type'), body));
+    // Deliberately NO session.close(): shutdown is the one record-layer path that arms a timer,
+    // and timers are forbidden where this runs. The session owns no real resources to release.
+    return { status: head.status, bodyBytes: text.length, wrote: tlsSink.written.length };
+  });
+}
+
+/**
+ * What one warmup() call reports. `ok` is the only field a caller usually needs; the rest exists
+ * so a failure names the exact problem rather than being a silent no-op.
+ * @typedef {object} WarmupReport
+ * @property {boolean} ok every iteration completed
+ * @property {number} iterations how many replays ran to completion
+ * @property {string | null} error first failure, if any — warmup() itself never throws
+ */
+
+/**
+ * Warm the hot path by replaying a recorded proxy + TLS + HTTP exchange through the real code.
+ * See the module comment for what this buys, what it costs, and when NOT to call it. Never
+ * called by the package itself; call it from module scope of your worker if — and only if —
+ * your deployment does not bill startup CPU.
+ *
+ * Safe by construction: no network, no randomness, no timers, nothing cached, and it never
+ * throws — a runtime that forbids more than expected yields `{ ok: false, error }` and the
+ * package behaves exactly as if warmup() had never been called.
+ *
+ * @param {{ iterations?: number }} [opts] replay count, default 5, clamped to 1..10. One pass
+ *   moves the hot functions out of the interpreter; more passes push V8's tiering further down
+ *   the ramp at proportionally more startup cost. Measured startup cost is roughly 10-20 ms per
+ *   iteration on current edge hardware, against the 1 s startup budget.
+ * @returns {Promise<WarmupReport>}
+ */
+export async function warmup({ iterations = 5 } = {}) {
+  const n = Math.min(10, Math.max(1, Number.isFinite(iterations) ? Math.floor(iterations) : 5));
+  let done = 0;
+  try {
+    for (let i = 0; i < n; i++) {
+      await replayOnce();
+      done++;
+    }
+    return { ok: true, iterations: done, error: null };
+  } catch (e) {
+    const at = e && typeof e === 'object' && e.warmupStage ? `${e.warmupStage}: ` : '';
+    return { ok: false, iterations: done, error: `${at}${e?.message ?? String(e)}` };
+  }
+}