@hisoka-io/anon-rpc-worker 0.2.0 → 0.4.0

package/src/fetch-map.ts

@@ -27,11 +27,36 @@ export interface NoxHttpPort {
   ): Promise<Uint8Array>;
 }
 
+/** TLS tunnels for fetch hops (src/tls/transport.ts). */
+export interface TunnelHop {
+  /** `"tunnel"` or `"http"` for this hop; throws the call's rejection when the hop may not leave. */
+  route(request: PreparedRequest, hop: number, startedOnTunnel: boolean): "tunnel" | "http";
+  exchange(request: PreparedRequest, budget: CallBudget): Promise<DecodedHttpResponse>;
+}
+
 /** Limits from the worker config. */
 export interface FetchSettings {
   readonly attemptTimeoutMs: number;
   readonly maxRequestBytes: number;
   readonly maxResponseBytes: number;
+  /**
+   * `accept-encoding` sent upstream. Default: `gzip` where the runtime has
+   * `DecompressionStream`, else `identity`.
+   */
+  readonly acceptEncoding?: ReplyEncoding;
+}
+
+/** Reply encodings the worker can ask upstreams for. */
+export type ReplyEncoding = "gzip" | "identity";
+
+/**
+ * `gzip` when this runtime can inflate replies itself. Exits pass bodies
+ * through as the upstream sent them (their HTTP client has no decompression),
+ * so a gzip reply crosses the mixnet compressed: a 414 KB `eth_getLogs` reply
+ * takes about 2 reply packets instead of 14.
+ */
+export function defaultReplyEncoding(): ReplyEncoding {
+  return typeof DecompressionStream === "function" ? "gzip" : "identity";
 }
 
 /** A validated request, ready for the mixnet. */
@@ -74,7 +99,7 @@ const CROSS_ORIGIN_DROPPED_HEADERS = new Set(["authorization", "cookie"]);
  * Request headers never forwarded: the exit drops `host` and `user-agent`
  * itself, framing and hop-by-hop fields belong to the exit's own connection,
  * and cookies, origin and referer would tie calls together or to a page.
- * `accept-encoding` is replaced (see `FORCED_REQUEST_HEADERS`).
+ * `accept-encoding` is replaced (see `defaultReplyEncoding`).
  */
 const DROPPED_REQUEST_HEADERS = new Set([
   "host",
@@ -93,8 +118,8 @@ const DROPPED_REQUEST_HEADERS = new Set([
   "accept-encoding",
 ]);
 
-/** The exit's HTTP client has no decompression, so bodies must come back as sent. */
-const FORCED_REQUEST_HEADERS: readonly [string, string][] = [["accept-encoding", "identity"]];
+/** Content codings the worker inflates. */
+const GZIP_CODINGS: ReadonlySet<string> = new Set(["gzip", "x-gzip"]);
 
 /** Response fields that describe the exit's hop, or that a worker must not hand on. */
 const DROPPED_RESPONSE_HEADERS = new Set([
@@ -126,7 +151,7 @@ export async function prepareRequest(
   if (redirect !== "follow" && redirect !== "manual" && redirect !== "error") {
     throw callError(CALL_CODES.unsupported, 'redirect must be "follow", "manual" or "error"');
   }
-  const headers = prepareHeaders(init?.headers);
+  const headers = prepareHeaders(init?.headers, settings.acceptEncoding ?? defaultReplyEncoding());
   const body = await readBody(init?.body, settings.maxRequestBytes, signal);
   if ((method === "GET" || method === "HEAD") && body.length > 0) {
     throw callError(CALL_CODES.unsupported, `A ${method} request cannot carry a body`);
@@ -167,20 +192,30 @@ export interface CallBudget {
  * need time and writes are never resent (ARCHITECTURE §4.7). The SDK still
  * resends any request whose packet was certainly never sent (a KPS dial or
  * stream-open failure) through another entry.
+ *
+ * With `tunnels`, each hop first asks it for its transport: a hop that goes
+ * through a TLS tunnel is exchanged there, and once one hop did, every later
+ * hop must too.
  */
 export async function sendPrepared(
   request: PreparedRequest,
   port: NoxHttpPort,
   settings: FetchSettings,
   budget: CallBudget,
+  tunnels?: TunnelHop,
 ): Promise<AnonFetchResponse> {
   if (budget.remainingMs() <= 0) throw callError(CALL_CODES.timeout, "The call deadline passed before sending");
   let current = request;
+  let onTunnel = false;
   for (let hop = 0; ; hop++) {
-    const reply = await exchange(current, port, settings, budget);
+    const via = tunnels?.route(current, hop, onTunnel) ?? "http";
+    const reply = tunnels !== undefined && via === "tunnel"
+      ? await tunnels.exchange(current, budget)
+      : await exchange(current, port, settings, budget);
+    if (via === "tunnel") onTunnel = true;
     checkStatus(reply);
     if (!REDIRECT_STATUSES.has(reply.status) || current.redirect === "manual") {
-      return toAnonResponse(reply, current, settings);
+      return finishResponse(reply, current, settings);
     }
     if (current.redirect === "error") {
       throw callError(
@@ -190,9 +225,9 @@ export async function sendPrepared(
     }
     const location = reply.headers.find(([name]) => name.toLowerCase() === "location")?.[1];
     // fetch returns a redirect status without a Location as an ordinary response.
-    if (location === undefined) return toAnonResponse(reply, current, settings);
+    if (location === undefined) return finishResponse(reply, current, settings);
     const next = redirectedRequest(current, reply.status, location);
-    if (next === null) return toAnonResponse(reply, current, settings);
+    if (next === null) return finishResponse(reply, current, settings);
     if (hop + 1 > MAX_REDIRECT_HOPS) {
       throw callError(CALL_CODES.networkError, `Too many redirects: more than ${MAX_REDIRECT_HOPS} hops`);
     }
@@ -290,6 +325,67 @@ function checkStatus(reply: DecodedHttpResponse): void {
   }
 }
 
+/** Inflate a gzip reply (see `inflateReply`), then map it with `toAnonResponse`. */
+export async function finishResponse(
+  reply: DecodedHttpResponse,
+  request: Pick<PreparedRequest, "url">,
+  settings: Pick<FetchSettings, "maxResponseBytes">,
+): Promise<AnonFetchResponse> {
+  checkStatus(reply);
+  if (reply.truncated) {
+    throw callError(CALL_CODES.tooLarge, "The exit cut the response body at its response size limit");
+  }
+  return toAnonResponse(await inflateReply(reply, settings.maxResponseBytes), request, settings);
+}
+
+/**
+ * The reply with a `gzip` body inflated and its `content-encoding` removed;
+ * any other reply unchanged. Inflation stops past `maxBytes` (`too-large`),
+ * so a small compressed reply cannot expand without bound; a corrupt body is
+ * a `protocol-error`.
+ */
+export async function inflateReply(reply: DecodedHttpResponse, maxBytes: number): Promise<DecodedHttpResponse> {
+  const coding = reply.headers.find(([name]) => name.toLowerCase() === "content-encoding")?.[1]?.trim().toLowerCase();
+  if (coding === undefined || !GZIP_CODINGS.has(coding)) return reply;
+  const headers = reply.headers.filter(([name]) => name.toLowerCase() !== "content-encoding");
+  if (reply.body.length === 0) return { ...reply, headers };
+  if (typeof DecompressionStream !== "function") {
+    throw callError(CALL_CODES.protocolError, "The upstream sent a gzip body and this runtime cannot inflate it");
+  }
+  const source = reply.body;
+  const inflated = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(source);
+      controller.close();
+    },
+  }).pipeThrough(new DecompressionStream("gzip") as unknown as TransformStream<Uint8Array, Uint8Array>);
+  const reader = inflated.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    let result: Awaited<ReturnType<typeof reader.read>>;
+    try {
+      result = await reader.read();
+    } catch (error) {
+      throw callError(CALL_CODES.protocolError, "The upstream's gzip body is corrupt", error);
+    }
+    if (result.done) break;
+    total += result.value.length;
+    if (total > maxBytes) {
+      void reader.cancel().catch(() => undefined);
+      throw callError(CALL_CODES.tooLarge, `The response body inflates past ${maxBytes} bytes`);
+    }
+    chunks.push(result.value);
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return { ...reply, headers, body };
+}
+
 /** Map the exit's decoded reply to an `AnonFetchResponse`; `request.url` becomes `url`. */
 export function toAnonResponse(
   reply: DecodedHttpResponse,
@@ -312,7 +408,7 @@ export function toAnonResponse(
     if (lower === "content-encoding" && value.trim().toLowerCase() !== "identity") {
       throw callError(
         CALL_CODES.protocolError,
-        "The upstream sent an encoded body although the request asked for identity; exits cannot decode it",
+        `The upstream sent a ${value.trim()} body; this worker accepts identity and gzip`,
       );
     }
     if (DROPPED_RESPONSE_HEADERS.has(lower) || !TOKEN_RE.test(name) || !FIELD_VALUE_RE.test(value)) continue;
@@ -403,9 +499,9 @@ function normalizeMethod(method: unknown): string {
   return NORMALIZED_METHODS.has(upper) ? upper : method;
 }
 
-/** Keep order and duplicates (the wire type is a list), drop and force per policy. */
-function prepareHeaders(list: HeaderList | undefined): [string, string][] {
-  if (list === undefined) return FORCED_REQUEST_HEADERS.map(([name, value]): [string, string] => [name, value]);
+/** Keep order and duplicates (the wire type is a list), drop per policy, then set `accept-encoding`. */
+function prepareHeaders(list: HeaderList | undefined, encoding: ReplyEncoding): [string, string][] {
+  if (list === undefined) return [["accept-encoding", encoding]];
   if (!Array.isArray(list)) throw callError(CALL_CODES.unsupported, "headers must be a list of [name, value] pairs");
   const out: [string, string][] = [];
   let bytes = 0;
@@ -427,7 +523,7 @@ function prepareHeaders(list: HeaderList | undefined): [string, string][] {
     }
     out.push([name, value]);
   }
-  for (const [name, value] of FORCED_REQUEST_HEADERS) out.push([name, value]);
+  out.push(["accept-encoding", encoding]);
   return out;
 }
 

package/src/local-answers.ts

@@ -0,0 +1,238 @@
+/**
+ * Worker-local answers: JSON-RPC calls whose answer
+ * cannot change are answered from memory instead of crossing the mixnet
+ * again. Fewer queries leave the device, and a hit costs no round trip.
+ *
+ * What is answered locally, per upstream URL and exact params:
+ *
+ * - `eth_chainId` and `net_version`: memoised once a second, independently
+ *   routed request through the mixnet returned the same result (the worker
+ *   sends that check in the background after the first answer).
+ * - Only with `blockHashReads` (off by default, because an answer is not yet
+ *   checked against the block hash): reads addressed by block hash, whose
+ *   result is fixed by the hash:
+ *   `eth_getBlockByHash`, `eth_getBlockReceipts`, `eth_getLogs` with a
+ *   `blockHash` filter, the `…ByBlockHash…` lookups, and EIP-1898 state reads
+ *   (`eth_call`, `eth_getBalance`, `eth_getCode`, `eth_getStorageAt`,
+ *   `eth_getTransactionCount`, `eth_getProof`) whose block is
+ *   `{"blockHash": …}` without `requireCanonical`. They are kept once two
+ *   separate calls returned the same result. Each call takes its own route,
+ *   so a wrong answer is kept only when both calls went through exits that
+ *   returned the same wrong result.
+ *
+ * Only single calls (not batches) with a `result` that is not null are kept;
+ * errors never are, and neither is an empty list for a block-hash read: an
+ * upstream that has not seen the block yet may answer `[]` for its logs or
+ * receipts, and a later call returns the full list. A request with `Cache-Control: no-cache` or `no-store`
+ * always goes through the mixnet. The reply carries the caller's own
+ * JSON-RPC `id`. Memory is bounded by entry count and bytes (oldest out).
+ */
+import type { AnonFetchResponse, HeaderList } from "./spec-types.js";
+import type { PreparedRequest } from "./fetch-map.js";
+
+/** Most answers kept. */
+export const LOCAL_ANSWER_MAX_ENTRIES = 512;
+/** Most result bytes kept in total. */
+export const LOCAL_ANSWER_MAX_BYTES = 4 * 1024 * 1024;
+/** Largest single result kept. */
+export const LOCAL_ANSWER_MAX_ENTRY_BYTES = 512 * 1024;
+/** Matching answers needed before a content-addressed result is served locally. */
+export const LOCAL_ANSWER_CONFIRMATIONS = 2;
+
+const MEMO_METHODS: ReadonlySet<string> = new Set(["eth_chainId", "net_version"]);
+
+/** Methods whose first param is a block hash. */
+const BY_BLOCK_HASH: ReadonlySet<string> = new Set([
+  "eth_getBlockByHash",
+  "eth_getBlockTransactionCountByHash",
+  "eth_getTransactionByBlockHashAndIndex",
+  "eth_getUncleByBlockHashAndIndex",
+  "eth_getUncleCountByBlockHash",
+]);
+
+/** EIP-1898 state reads: the block selector is the last param. */
+const STATE_READS: ReadonlySet<string> = new Set([
+  "eth_call",
+  "eth_getBalance",
+  "eth_getCode",
+  "eth_getStorageAt",
+  "eth_getTransactionCount",
+  "eth_getProof",
+]);
+
+const HASH_RE = /^0x[0-9a-fA-F]{64}$/u;
+
+/** Why a call was or was not answered locally (for debug logs). */
+export type LocalKind = "memo" | "block-hash";
+
+interface Entry {
+  readonly kind: LocalKind;
+  /** The JSON text of `result`. */
+  readonly result: string;
+  readonly headers: HeaderList;
+  confirmations: number;
+}
+
+/** A single JSON-RPC call read from a prepared request. */
+interface Call {
+  readonly key: string;
+  readonly kind: LocalKind;
+  readonly id: unknown;
+}
+
+const decoder = new TextDecoder("utf-8", { fatal: true });
+const encoder = new TextEncoder();
+
+/** Options for {@link LocalAnswers}. */
+export interface LocalAnswersOptions {
+  /** Also keep reads addressed by block hash (see above). Default false. */
+  readonly blockHashReads?: boolean;
+}
+
+export class LocalAnswers {
+  private readonly entries = new Map<string, Entry>();
+  private bytes = 0;
+  private readonly blockHashReads: boolean;
+
+  constructor(options: LocalAnswersOptions = {}) {
+    this.blockHashReads = options.blockHashReads ?? false;
+  }
+
+  /** The cacheable call in `request`, honouring the enabled kinds. */
+  private call(request: PreparedRequest): Call | undefined {
+    const call = cacheableCall(request);
+    if (call === undefined) return undefined;
+    return call.kind === "block-hash" && !this.blockHashReads ? undefined : call;
+  }
+
+  /** The local answer for `request`, if one is confirmed. */
+  lookup(request: PreparedRequest): { response: AnonFetchResponse; kind: LocalKind } | undefined {
+    const call = this.call(request);
+    if (call === undefined) return undefined;
+    const entry = this.entries.get(call.key);
+    if (entry === undefined || !this.served(entry)) return undefined;
+    this.entries.delete(call.key);
+    this.entries.set(call.key, entry);
+    const body = `{"jsonrpc":"2.0","id":${JSON.stringify(call.id ?? null)},"result":${entry.result}}`;
+    return {
+      kind: call.kind,
+      response: { status: 200, headers: entry.headers.map(([name, value]) => [name, value]), body: encoder.encode(body), url: request.url },
+    };
+  }
+
+  /**
+   * Record a mixnet answer. Returns `verify` when the call is a memo method
+   * seen for the first time: the caller sends it once more through the
+   * mixnet and passes that answer here too.
+   */
+  observe(request: PreparedRequest, response: AnonFetchResponse): "verify" | undefined {
+    const call = this.call(request);
+    if (call === undefined || response.status !== 200 || !(response.body instanceof Uint8Array)) return undefined;
+    const result = resultOf(response.body);
+    if (result === undefined || result.length > LOCAL_ANSWER_MAX_ENTRY_BYTES) return undefined;
+    if (call.kind === "block-hash" && result === "[]") return undefined;
+    const existing = this.entries.get(call.key);
+    if (existing !== undefined) {
+      if (existing.result === result) {
+        existing.confirmations += 1;
+      } else {
+        // Two answers disagree: keep neither.
+        this.remove(call.key, existing);
+      }
+      return undefined;
+    }
+    const headers = response.headers.filter(([name]) => name.toLowerCase() === "content-type");
+    this.entries.set(call.key, { kind: call.kind, result, headers, confirmations: 1 });
+    this.bytes += result.length;
+    this.evict();
+    return call.kind === "memo" ? "verify" : undefined;
+  }
+
+  /** Number of answers held (served or awaiting confirmation). */
+  get size(): number {
+    return this.entries.size;
+  }
+
+  private served(entry: Entry): boolean {
+    return entry.confirmations >= LOCAL_ANSWER_CONFIRMATIONS;
+  }
+
+  private remove(key: string, entry: Entry): void {
+    this.entries.delete(key);
+    this.bytes -= entry.result.length;
+  }
+
+  private evict(): void {
+    for (const [key, entry] of this.entries) {
+      if (this.entries.size <= LOCAL_ANSWER_MAX_ENTRIES && this.bytes <= LOCAL_ANSWER_MAX_BYTES) return;
+      this.remove(key, entry);
+    }
+  }
+}
+
+/** The call's cache key and kind, when `request` is one call whose answer is fixed. */
+function cacheableCall(request: PreparedRequest): Call | undefined {
+  if (request.method !== "POST" || request.profile.method === undefined || request.profile.method === "batch") {
+    return undefined;
+  }
+  for (const [name, value] of request.headers) {
+    if (name.toLowerCase() === "cache-control" && /no-cache|no-store/iu.test(value)) return undefined;
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(decoder.decode(request.body));
+  } catch {
+    return undefined;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const call = value as { jsonrpc?: unknown; method?: unknown; params?: unknown; id?: unknown };
+  if (call.jsonrpc !== "2.0" || typeof call.method !== "string" || !("id" in call)) return undefined;
+  const id = call.id;
+  if (id !== null && typeof id !== "string" && typeof id !== "number") return undefined;
+  const params = call.params ?? [];
+  const kind = classify(call.method, params);
+  if (kind === undefined) return undefined;
+  return { key: `${request.url}\n${call.method}\n${JSON.stringify(params)}`, kind, id };
+}
+
+function classify(method: string, params: unknown): LocalKind | undefined {
+  if (MEMO_METHODS.has(method)) return Array.isArray(params) && params.length === 0 ? "memo" : undefined;
+  if (!Array.isArray(params) || params.length === 0) return undefined;
+  const first: unknown = params[0];
+  if (BY_BLOCK_HASH.has(method)) return isHash(first) ? "block-hash" : undefined;
+  if (method === "eth_getBlockReceipts") return isHash(first) || isBlockHashSelector(first) ? "block-hash" : undefined;
+  if (method === "eth_getLogs") {
+    if (typeof first !== "object" || first === null) return undefined;
+    const filter = first as Record<string, unknown>;
+    return isHash(filter["blockHash"]) && filter["fromBlock"] === undefined && filter["toBlock"] === undefined
+      ? "block-hash"
+      : undefined;
+  }
+  if (STATE_READS.has(method)) return isBlockHashSelector(params[params.length - 1]) ? "block-hash" : undefined;
+  return undefined;
+}
+
+function isHash(value: unknown): boolean {
+  return typeof value === "string" && HASH_RE.test(value);
+}
+
+/** EIP-1898 `{"blockHash": …}` without `requireCanonical: true` (whose answer can turn into an error after a reorg). */
+function isBlockHashSelector(value: unknown): boolean {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const selector = value as Record<string, unknown>;
+  return isHash(selector["blockHash"]) && selector["requireCanonical"] !== true && selector["blockNumber"] === undefined;
+}
+
+/** The JSON text of a successful reply's `result` (not null), else undefined. */
+function resultOf(body: Uint8Array): string | undefined {
+  let value: unknown;
+  try {
+    value = JSON.parse(decoder.decode(body));
+  } catch {
+    return undefined;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const reply = value as { result?: unknown; error?: unknown };
+  if (reply.error !== undefined || reply.result === undefined || reply.result === null) return undefined;
+  return JSON.stringify(reply.result);
+}

package/src/tls/channel.ts

@@ -0,0 +1,183 @@
+/**
+ * A TLS session to one host over one tunnel: the handshake exchange, then
+ * HTTP/1.1 requests. Completeness of a response comes from HTTP framing or,
+ * for a close-delimited body, from TLS close_notify; an exit that ends the
+ * stream early produces a truncation error, never a short response.
+ */
+import type { TopologyNode } from "@hisoka-io/nox-client";
+import type { HttpParserLike, HttpReplyHead, NoxTlsBindings, TlsSessionLike } from "./module.js";
+import { Tunnel, TunnelProtocolError, type CopyPolicy, type TunnelDeps, type TunnelPort } from "./tunnel.js";
+
+/** Reply blocks for the handshake exchange: one carries the server flight, the other is the exit's reserve. */
+export const HANDSHAKE_SURBS = 2;
+/** The TLS port every tunnel uses. */
+export const TLS_PORT = 443;
+
+export interface ExchangeTiming {
+  readonly deadlineAt: number;
+  readonly signal?: AbortSignal;
+  readonly background: boolean;
+}
+
+export interface RequestSpec extends ExchangeTiming {
+  /** The encoded HTTP/1.1 request. */
+  readonly http: Uint8Array;
+  readonly headRequest: boolean;
+  readonly maxHeadBytes: number;
+  readonly maxBodyBytes: number;
+  /** Reply blocks for the exchange that carries the request. */
+  readonly surbs: number;
+}
+
+export class TlsChannel {
+  readonly tunnel: Tunnel;
+  readonly openedAt: number;
+  /** Requests sent on this session. */
+  calls = 0;
+  /** Milliseconds spent in the TLS module processing the server's handshake flight. */
+  handshakeCpuMs = 0;
+  /** False once a response asked to close or the stream ended. */
+  private keepAlive = true;
+  private parser: HttpParserLike | undefined;
+  private parserDone = false;
+  private freed = false;
+  private readonly tls: TlsSessionLike;
+
+  constructor(
+    port: TunnelPort,
+    exit: TopologyNode,
+    readonly host: string,
+    policy: CopyPolicy,
+    deps: TunnelDeps,
+    private readonly bindings: NoxTlsBindings,
+  ) {
+    this.tls = bindings.newSession(host);
+    this.openedAt = deps.now();
+    this.tunnel = new Tunnel(port, exit, host, TLS_PORT, policy, deps, (bytes) => this.onBytes(bytes));
+  }
+
+  get exit(): TopologyNode {
+    return this.tunnel.exit;
+  }
+
+  /** TLS version negotiated (`TLSv1_3`, `TLSv1_2`). */
+  get protocol(): string {
+    return this.tls.protocol();
+  }
+
+  /** The session can carry another request. */
+  get reusable(): boolean {
+    return !this.freed && this.keepAlive && !this.tunnel.eof && !this.tls.isClosed();
+  }
+
+  /**
+   * Seq 0: open the tunnel with the ClientHello and process the server's
+   * flight. Afterwards the client's next flight (the TLS 1.3 Finished) waits
+   * in the session until the first request, which travels with it.
+   */
+  async handshake(timing: ExchangeTiming & { readonly openTimeoutMs: number }): Promise<void> {
+    const hello = this.tls.takeOutgoing();
+    const outcome = await this.tunnel.exchange({
+      data: hello,
+      surbs: HANDSHAKE_SURBS,
+      deadlineAt: timing.deadlineAt,
+      background: timing.background,
+      openTimeoutMs: timing.openTimeoutMs,
+      ...(timing.signal === undefined ? {} : { signal: timing.signal }),
+      satisfied: () => this.tls.wantsWrite() || !this.tls.isHandshaking(),
+    });
+    if (outcome === "eof") throw new TunnelProtocolError("The upstream closed the connection during the TLS handshake");
+  }
+
+  /** One HTTP request and its complete response. */
+  async request(spec: RequestSpec): Promise<HttpReplyHead> {
+    this.calls += 1;
+    const parser = this.bindings.newParser(spec.headRequest, spec.maxHeadBytes, spec.maxBodyBytes);
+    this.parser = parser;
+    this.parserDone = false;
+    try {
+      this.tls.writePlaintext(spec.http);
+      for (;;) {
+        const data = this.tls.takeOutgoing();
+        const outcome = await this.tunnel.exchange({
+          data,
+          surbs: spec.surbs,
+          deadlineAt: spec.deadlineAt,
+          background: spec.background,
+          ...(spec.signal === undefined ? {} : { signal: spec.signal }),
+          satisfied: () => this.parserDone || this.tls.wantsWrite(),
+        });
+        if (outcome === "eof") {
+          this.keepAlive = false;
+          this.tls.pushTransportEof();
+          this.feedParser(this.tls.takePlaintext());
+          if (!this.parserDone) {
+            parser.finishOnClose(this.tls.closeNotifyReceived());
+            this.parserDone = true;
+          }
+        }
+        if (this.parserDone) break;
+      }
+      const response = parser.response();
+      if (response === null) throw new TunnelProtocolError("The HTTP parser finished without a response");
+      if (!response.keepAlive) this.keepAlive = false;
+      return response;
+    } finally {
+      this.parser = undefined;
+      parser.free();
+    }
+  }
+
+  /**
+   * Close the tunnel: close_notify when the TLS session can still send one,
+   * and the acknowledgement of every byte received, so the exit drops the
+   * session at once. Nothing waits for it.
+   */
+  teardown(deadlineAt: number): Promise<void> {
+    if (this.freed) return Promise.resolve();
+    this.keepAlive = false;
+    const data = this.tunnel.eof ? new Uint8Array(0) : this.closeNotify();
+    this.free();
+    return this.tunnel.teardown(data, deadlineAt);
+  }
+
+  /** The close_notify record, or nothing when the session can no longer send one. */
+  private closeNotify(): Uint8Array {
+    try {
+      this.tls.close();
+      return this.tls.takeOutgoing();
+    } catch {
+      return new Uint8Array(0);
+    }
+  }
+
+  /** Release the TLS session's WebAssembly memory. */
+  free(): void {
+    if (this.freed) return;
+    this.freed = true;
+    this.tls.free();
+  }
+
+  private onBytes(bytes: Uint8Array): void {
+    if (this.tls.isHandshaking()) {
+      const started = performance.now();
+      this.tls.pushIncoming(bytes);
+      this.handshakeCpuMs += performance.now() - started;
+    } else {
+      this.tls.pushIncoming(bytes);
+    }
+    this.feedParser(this.tls.takePlaintext());
+    if (this.tls.closeNotifyReceived() && this.parser !== undefined && !this.parserDone) {
+      this.parser.finishOnClose(true);
+      this.parserDone = true;
+    }
+  }
+
+  private feedParser(plaintext: Uint8Array): void {
+    if (plaintext.length === 0) return;
+    if (this.parser === undefined || this.parserDone) {
+      throw new TunnelProtocolError(`The upstream sent ${plaintext.length} bytes with no request outstanding`);
+    }
+    this.parserDone = this.parser.push(plaintext);
+  }
+}