tunnelfetch 1.0.0 → 1.1.0

package/README.md

@@ -2,11 +2,23 @@
 
 [English](README.md) · [简体中文](README.zh-CN.md)
 
+[![CI](https://github.com/latentharbor/tunnelfetch/actions/workflows/ci.yml/badge.svg)](https://github.com/latentharbor/tunnelfetch/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/tunnelfetch)](https://www.npmjs.com/package/tunnelfetch)
+[![license](https://img.shields.io/npm/l/tunnelfetch)](LICENSE)
+
+
 A `fetch`-shaped HTTP client that can route through an HTTP CONNECT, HTTPS, or SOCKS5 proxy on
 runtimes that expose only raw TCP — principally Cloudflare Workers (`workerd`).
 
 Zero dependencies. ESM. No build step. No `node:` imports anywhere in `src/`.
 
+> **Maturity.** This is a new implementation, not a battle-tested one. It implements TLS 1.2/1.3 and
+> certificate validation in userland — a category where good tests are necessary and not sufficient.
+> It has 1132 hermetic tests, RFC vectors, byte-by-byte fragmentation, live edge interop, seeded
+> fuzzing of every peer-facing parser, and 95% line coverage. It has **not** had an external
+> security audit. Treat it as a high-quality implementation worth trying, not as something proven
+> in production. Please report anything you find — see [SECURITY.md](SECURITY.md).
+
 ```js
 import { Client } from 'tunnelfetch';
 import { connect } from 'cloudflare:sockets';
@@ -203,6 +215,69 @@ duration — raise it above your feed's heartbeat interval, or a quiet-but-alive
 Abandoning a stream part-way never returns the connection to the pool: its position is unknown,
 and reusing it would splice the remains of one response onto the next request.
 
+### `br`, `zstd`, and other codings
+
+`gzip` and `deflate` are built in because the runtime decompresses them natively. Anything else is
+pluggable: give `decoders` a function per coding and it is appended to `Accept-Encoding` and applied
+to matching responses. Registering is what makes advertising honest — asking for a coding you cannot
+read turns every such response into garbage, so the two move together and cannot drift.
+
+```js
+import { Client } from 'tunnelfetch';
+import { connect } from 'cloudflare:sockets';
+import { BrotliDecStream, BrotliStreamResultCode, initSync } from 'brotli-dec-wasm/web';
+import wasm from 'brotli-dec-wasm/web/bg.wasm';
+
+// Module scope, so instantiation lands in isolate startup, which this runtime does not bill.
+// Measured on the edge: it costs nothing detectable (12 ms startup with it, 12 ms without).
+initSync({ module: wasm });
+
+const brotli = (stream) => {
+  const dec = new BrotliDecStream();
+  return stream.pipeThrough(new TransformStream({
+    transform(chunk, c) {
+      let r = dec.dec(chunk, 1 << 20);
+      if (r.buf.length) c.enqueue(r.buf);
+      while (r.code === BrotliStreamResultCode.NeedsMoreOutput) {
+        r = dec.dec(new Uint8Array(0), 1 << 20);
+        if (r.buf.length) c.enqueue(r.buf);
+      }
+    },
+  }));
+};
+
+const client = new Client({ connect, proxy, decoders: { br: brotli } });
+// Now sends `Accept-Encoding: gzip, deflate, br` and decodes `Content-Encoding: br`.
+```
+
+Order is registration order after the built-ins, so `{ br, zstd }` produces exactly the
+`gzip, deflate, br, zstd` a Chrome sends — which is the actual reason to do this. This client
+presents curl's TLS and HTTP/2 fingerprints by default, and `gzip, deflate` is what curl sends, so
+the default is already consistent. It stops being consistent the moment you dress the handshake up
+as a browser and leave the header behind.
+
+It is not a saving. Measured on the edge, decoding the same 256 KB page to the same bytes:
+
+| Implementation | Algorithm | ms/MB |
+|---|---|---|
+| `DecompressionStream` — the runtime's own C++ | inflate | **2.5** |
+| WASM brotli (`brotli-dec-wasm`) | brotli | 4.7 |
+| JS inflate (`fflate` / `pako`) | inflate | 7.5 / 8.2 |
+| JS brotli (`brotli`) | brotli | 19.7 |
+
+Two things fall out, and both are worth knowing before reaching for WebAssembly anywhere else in a
+Worker. **WASM is about 4x faster than JavaScript at the same algorithm** (brotli: 4.7 against
+19.7) — so if a coding has no native path, WASM is the right way to add one. And **native is about
+3x faster than JavaScript at the same algorithm** (inflate: 2.5 against 7.5–8.2) — so where a
+native path already exists, nothing in userland improves on it. That is why `gzip` and `deflate`
+are not overridable: replacing them could only ever be slower, and doing it silently is the kind of
+quiet downgrade this package refuses everywhere else.
+
+Brotli itself lands at 1.9x native inflate. That gap is the price of the coding, and the wire bytes
+it saves do not pay it back — see [What this cannot do](#what-this-cannot-do-and-why). Decoder names
+are validated as HTTP tokens, a decoder that throws fails the body closed rather than truncating it,
+and an unregistered coding is still refused.
+
 ### HTTP/2 — access, not speed
 
 The client offers `h2` and `http/1.1` in ALPN by default and speaks whichever the server selects.
@@ -377,8 +452,10 @@ Not implemented, and not planned:
 - **ChaCha20-Poly1305.** It buys nothing: a server can only pick a suite we offered, TLS 1.3
   mandates AES-128-GCM, and AES-GCM is universal in TLS 1.2 deployments. WebCrypto has no
   ChaCha20, so offering it would mean a `node:crypto` dependency for zero compatibility gain.
-- **Client certificates (mTLS), session resumption, 0-RTT, renegotiation.** A `HelloRequest` is
-  refused rather than honoured.
+- **Client certificates (mTLS), 0-RTT, renegotiation.** A `HelloRequest` is refused rather than
+  honoured. 0-RTT is a decision rather than an omission: early data can be replayed, so offering
+  it would let an attacker who captured a POST replay it. (Session resumption itself *is*
+  implemented — a ticket is kept per pool key and offered with `psk_dhe_ke`.)
 - **Revocation fetching (CRL downloads, OCSP responder queries).** Both need network round trips
   mid-handshake, through the proxy, and an OCSP query tells the CA which origins you visit.
   Revocation *is* checked from a **stapled** OCSP response when the server sends one (see Trust
@@ -391,9 +468,29 @@ Not implemented, and not planned:
 - **A public-suffix list for cookies.** Only the "no dot in the domain" guard is implemented, so
   `Domain=com` is refused but `Domain=co.uk` is not. Documented rather than faked.
 - **IDNA.** Pass A-labels (punycode); a non-ASCII hostname is rejected with a message saying so.
-- **`br` and `zstd` content encodings.** The runtime has `DecompressionStream` for gzip, deflate
-  and deflate-raw only. The client therefore never advertises `br` — asking for it would return
-  bytes that cannot be decoded.
+- **`br` and `zstd` out of the box.** The runtime's `DecompressionStream` accepts gzip, deflate and
+  deflate-raw only — measured, not assumed. Neither is *unreachable*, though: register a decoder
+  with [`decoders`](#br-zstd-and-other-codings) and the coding is advertised and decoded. Nothing
+  ships built in, because the only way to get Brotli here is WebAssembly, and a 208 KB binary blob
+  would cost this package both its zero dependencies and its ability to be imported without a
+  bundler. Bringing your own makes that cost, and that supply chain, yours and visible.
+
+  Leaving it off is safe rather than lossy: content negotiation means a server never sends what was
+  not asked for, so a Brotli-serving origin simply returns gzip. What it costs is bandwidth — the
+  same page measured 290 KB as gzip against 99 KB as `br` — and bandwidth is not what this platform
+  bills. Measured on the edge, the trade runs the wrong way: WASM Brotli decodes at about
+  **1.9x** the CPU of the runtime's native inflate, and even on the page with the largest wire
+  saving in a 14-site survey, the 186 KB saved bought back ~1.2 ms while the extra decoding cost
+  several times that. Harder compression makes it worse, not better — brotli quality 11, which is
+  what a CDN serves from cache, is 16% smaller on the wire than quality 5 and **46% more expensive
+  to decode**, because decompression work scales with the OUTPUT bytes and a denser encoding means
+  more work per byte produced. The reason to turn `br` on is matching a browser's
+  `Accept-Encoding`, not saving CPU.
+- **Streaming request bodies.** A request body is read fully into memory before the request is
+  sent, because the framing has to be declared in a `Content-Length` this client can stand behind
+  and because a body may have to be replayed on a redirect. Fine for the JSON an SDK sends; wrong
+  for a large upload, and it means `duplex: 'half'` streaming uploads are not supported. Response
+  bodies are streamed throughout and are never buffered on your behalf.
 - **HTTP/3.** ALPN offers `h2` and `http/1.1` (see [HTTP/2](#http2--access-not-speed)); it does
   not offer `h3`, which is QUIC over UDP and unreachable from a runtime that exposes only raw TCP.
   A server selecting anything the client did not offer fails closed — there is no fallback-and-retry
@@ -405,8 +502,11 @@ Not implemented, and not planned:
 **Sockets cannot cross request contexts.** The pool is per-`Client` and per-invocation by design;
 there is no cross-request connection cache, because the runtime does not permit one.
 
-**Concurrency.** The platform allows six connections simultaneously awaiting response headers.
-A crawler wanting more parallelism must pipeline within that limit.
+**Concurrency.** The limit is six connections **per Worker invocation** simultaneously awaiting
+response headers — not per Worker and not per account, so separate requests to your Worker each get
+their own six. A connection stops occupying a slot the moment its response head arrives, so the
+limit bounds how many handshakes can be in flight at once, not how many bodies can be downloading.
+A crawler wanting more parallelism inside one invocation must pipeline within that limit.
 
 ## Cost on a live Worker
 
@@ -570,8 +670,22 @@ sustained average rather than trusting either the documented number or the burst
 
 WebCrypto (X25519, ECDH P-256/384/521, ECDSA, RSA-PSS, RSASSA-PKCS1, HKDF, HMAC, AES-GCM),
 WHATWG Streams including BYOB readers, `TextEncoder`/`TextDecoder`, `DecompressionStream`, `URL`,
-`Headers`, `Request`, `Response`, `AbortSignal`, `btoa`. All present on workerd, Node ≥ 20, Deno
-and Bun. The only runtime-specific piece is the `connect` function you supply.
+`Headers`, `Request`, `Response`, `AbortSignal`, `btoa`. The only runtime-specific piece is the
+`connect` function you supply.
+
+| Runtime | Offline suite | Notes |
+|---|---|---|
+| Node 22, 24 | **1132 / 1132** | what CI gates on |
+| Node 20 | not supported | `TextDecoder` treats `iso-8859-1` as true ISO-8859-1 instead of aliasing it to windows-1252 as WHATWG requires, so bodies in that charset decode differently. Left maintenance April 2026 |
+| workerd | live edge suite passes | the target runtime; exercised end to end by the scheduled edge job rather than by the offline suite |
+| Deno 2.9 | 999 / 1001 | both failures are in the TLS 1.2 test server's secp521r1 path, not in the package; WebCrypto ECDSA and ECDH on P-521 both work standalone under Deno. Unresolved, so support is not claimed |
+| Bun 1.3 | 1079 / 1082 | a module-resolution difference in one repo-hygiene test, one timing-sensitive deadline test, and the same TLS 1.2 suite test. Unresolved, so support is not claimed |
+
+Node 22 and workerd are the supported pair. Deno and Bun very nearly work and are not tested in CI
+— running the suite there is a good first contribution.
+
+CI runs every version in `engines`, and a repo-hygiene test fails if the two ever disagree — an
+untested support floor is a claim, not a fact.
 
 ## Testing
 
@@ -596,6 +710,26 @@ against independently written test servers — the 1.2 server is built on `node:
 on this package's own primitives, so a client bug cannot be cancelled out by the same bug on the
 server side.
 
+Every parser that consumes bytes a peer controls — X.509, OCSP, HTTP/1.1 heads, chunked bodies,
+HTTP/2 frames, HPACK — is fuzzed against one property: **any input either parses or throws a
+`TunnelFetchError`.** An untyped throw, a `TypeError` from a missing null check or a `RangeError`
+from a bad offset, is a finding: it means a check is missing and every caller relying on the typed
+contract to fail closed will not catch it.
+
+The fuzzer is seeded and dependency-free, so a failure prints the seed, the iteration and the case
+in base64 — reproducible exactly, which a fuzzer whose failures cannot be replayed is not. Targets
+are auto-discovered from `test/fuzz/targets/`; adding one is dropping a file in. The suite also
+fuzzes *itself*: two synthetic targets prove the engine reports an untyped throw and does not report
+a typed one, because a green fuzz run otherwise only proves the fuzzer never looked.
+
+```bash
+FUZZ_ITERATIONS=1000000 node --test test/fuzz/fuzz.test.js   # a soak
+FUZZ_SEED=12345 node --test test/fuzz/fuzz.test.js           # a different corner
+```
+
+CI runs a fixed seed on every commit, as a gate; the scheduled workflow runs three million
+iterations with the run id as the seed, which is the half that searches new ground.
+
 `probe/` holds a reproducible capability probe that emits machine-readable JSON, and
 `probe/results/` the measurements this design rests on. `live/` is the edge interop rig.
 

package/README.zh-CN.md

@@ -2,10 +2,17 @@
 
 [English](README.md) · [简体中文](README.zh-CN.md)
 
+[![CI](https://github.com/latentharbor/tunnelfetch/actions/workflows/ci.yml/badge.svg)](https://github.com/latentharbor/tunnelfetch/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/tunnelfetch)](https://www.npmjs.com/package/tunnelfetch)
+[![license](https://img.shields.io/npm/l/tunnelfetch)](LICENSE)
+
+
 一个 `fetch` 形态的 HTTP 客户端，能在只暴露原始 TCP 的运行时上——主要是 Cloudflare Workers (`workerd`)——通过 HTTP CONNECT、HTTPS 或 SOCKS5 代理发出请求。
 
 零依赖。ESM。无构建步骤。`src/` 中没有任何 `node:` 导入。
 
+> **成熟度。** 这是一个新实现，不是久经沙场的实现。它在用户态实现了 TLS 1.2/1.3 与证书校验——在这个领域，好的测试是必要条件，但不是充分条件。它有 1132 个离线测试、RFC 向量、逐字节分片、真实边缘互操作测试、对每一个面向对端的解析器做种子化 fuzzing，行覆盖率 95%；但它**没有**经过外部安全审计。请把它当作一个值得一试的高质量实现，而不是一个已被生产验证的东西。发现任何问题都欢迎报告——见 [SECURITY.md](SECURITY.md)。
+
 ```js
 import { Client } from 'tunnelfetch';
 import { connect } from 'cloudflare:sockets';
@@ -165,6 +172,53 @@ for await (const chunk of res.body) {
 
 中途放弃一条流，连接绝不会回到池里：它的位置是未知的，复用会把上一个响应的残余拼接到下一个请求上。
 
+### `br`、`zstd` 与其它编码
+
+`gzip` 和 `deflate` 是内置的，因为运行时原生就能解。其余都是可插拔的：给 `decoders` 传一个"每种编码一个函数"的表，该编码就会被追加进 `Accept-Encoding`，并被用于解码匹配的响应。注册这个动作本身，正是"声明"变得诚实的前提——请求一个自己读不了的编码，会把每一个这样的响应变成乱码，所以两者绑在一起、不可能漂移。
+
+```js
+import { Client } from 'tunnelfetch';
+import { connect } from 'cloudflare:sockets';
+import { BrotliDecStream, BrotliStreamResultCode, initSync } from 'brotli-dec-wasm/web';
+import wasm from 'brotli-dec-wasm/web/bg.wasm';
+
+// 放在模块作用域，实例化就落进 isolate 启动阶段，而这个运行时不对启动计费。
+// 边缘实测：这一步的成本测不出来（带它启动 12 ms，不带也是 12 ms）。
+initSync({ module: wasm });
+
+const brotli = (stream) => {
+  const dec = new BrotliDecStream();
+  return stream.pipeThrough(new TransformStream({
+    transform(chunk, c) {
+      let r = dec.dec(chunk, 1 << 20);
+      if (r.buf.length) c.enqueue(r.buf);
+      while (r.code === BrotliStreamResultCode.NeedsMoreOutput) {
+        r = dec.dec(new Uint8Array(0), 1 << 20);
+        if (r.buf.length) c.enqueue(r.buf);
+      }
+    },
+  }));
+};
+
+const client = new Client({ connect, proxy, decoders: { br: brotli } });
+// 此后会发送 `Accept-Encoding: gzip, deflate, br`，并解码 `Content-Encoding: br`。
+```
+
+顺序是内置项之后按注册顺序排，所以 `{ br, zstd }` 得到的正是 Chrome 发的 `gzip, deflate, br, zstd`——而这才是做这件事的真正理由。这个客户端默认呈现 curl 的 TLS 与 HTTP/2 指纹，而 `gzip, deflate` 正是 curl 发的，所以默认状态本就是一致的。它不再一致，恰恰是从你把握手打扮成浏览器、却把这个头留在原地的那一刻开始。
+
+它不是一项省钱优化。边缘实测，把同一个 256 KB 页面解成同样的字节：
+
+| 实现 | 算法 | ms/MB |
+|---|---|---|
+| `DecompressionStream`——运行时自己的 C++ | inflate | **2.5** |
+| WASM brotli（`brotli-dec-wasm`） | brotli | 4.7 |
+| JS inflate（`fflate` / `pako`） | inflate | 7.5 / 8.2 |
+| JS brotli（`brotli`） | brotli | 19.7 |
+
+由此得到两条结论，在 Worker 里任何地方考虑用 WebAssembly 之前都值得知道。**同一算法下 WASM 比 JavaScript 快约 4 倍**（brotli：4.7 对 19.7）——所以某个编码若没有原生实现，WASM 是补上它的正确方式。**同一算法下原生又比 JavaScript 快约 3 倍**（inflate：2.5 对 7.5–8.2）——所以只要已经有原生路径，用户态怎么写都赢不了。这正是 `gzip` 和 `deflate` 不可覆盖的原因：替换它们只可能更慢，而静默地这么做，恰恰是这个包在别处一律拒绝的那种悄悄降级。
+
+brotli 本身落在原生 inflate 的 1.9 倍。这个差价就是这个编码的成本，而它省下的线上字节买不回来——见[这个包做不到什么](#这个包做不到什么为什么)。解码器名字会按 HTTP token 校验；解码器抛错时响应体 fail closed，而不是被截断；未注册的编码依然会被拒绝。
+
 ### HTTP/2 — 要的是访问，不是速度
 
 客户端默认在 ALPN 中同时报出 `h2` 与 `http/1.1`，服务器选中哪个就说哪个。没有单独的 API：
@@ -295,19 +349,22 @@ CertificateError [CERT_PIN_MISMATCH]: no certificate in the chain matches any co
 - **TLS 1.0 / 1.1。** RC4 已被攻破，那里剩下的全是 CBC。浏览器自 2020 年起就拒绝这两个版本。注意其中的区别：*同时也*支持 1.0/1.1 的服务器没有问题，我们会与它协商出 1.2 或 1.3；够不着的只有*除此之外什么都不支持*的服务器。
 - **RSA 密钥传输。** 没有前向保密。
 - **ChaCha20-Poly1305。** 加上它换不来任何东西：服务器只能从我们报出的套件里选，TLS 1.3 强制要求 AES-128-GCM，而 AES-GCM 在 TLS 1.2 的实际部署中无处不在。WebCrypto 没有 ChaCha20，要提供它就得引入 `node:crypto` 依赖，兼容性收益却是零。
-- **客户端证书 (mTLS)、会话恢复、0-RTT、重协商。** 收到 `HelloRequest` 会拒绝，而不是照办。
+- **客户端证书（mTLS）、0-RTT、重协商。** `HelloRequest` 会被拒绝而不是照做。0-RTT 是决定而非遗漏:early data 可被重放，提供它等于让捕获了 POST 的攻击者可以重放它。（会话恢复本身**已经实现**——ticket 按池键保存，用 `psk_dhe_ke` 提供。）
 - **吊销信息的主动获取（下载 CRL、查询 OCSP 应答者）。** 两者都要在握手中途经代理多跑网络往返，而且 OCSP 查询会把你访问的源站告诉 CA。吊销状态**会**从服务器装订（staple）的 OCSP 响应中校验（见上文 Trust 一节）；没有实现、也不打算实现的，是替服务器去取它没有装订的东西。
 - **证书策略处理** (`policyConstraints`、`inhibitAnyPolicy`)。它们永远是 critical 的，所以一旦出现就直接拒绝，而不是被错误地校验过去。
 - **dNSName 与 iPAddress 之外的名称约束。** 标为 *critical* 且指名不支持类型的约束扩展会被拒绝；非 critical 的则按 RFC 5280 允许的那样忽略。
 - **cookie 的 public suffix list。** 只实现了“域名里没有点”这一道防护，所以 `Domain=com` 会被拒绝，`Domain=co.uk` 不会。如实写明，而不是伪造。
 - **IDNA。** 请传 A-label (punycode)；非 ASCII 主机名会被拒绝，并附上说明原因的报错。
-- **`br` 与 `zstd` 内容编码。** 运行时的 `DecompressionStream` 只支持 gzip、deflate 和 deflate-raw。因此客户端从不声明接受 `br`——主动要它，换回来的只会是解不开的字节。
+- **开箱即用的 `br` 与 `zstd`。** 运行时的 `DecompressionStream` 只接受 gzip、deflate 和 deflate-raw——这是实测的，不是假设的。但这两种编码并非够不着：用 [`decoders`](#br-zstd-与其它编码) 注册一个解码器，该编码就会被声明并被解码。包里不内置任何一个，是因为在这个运行时上拿到 Brotli 的唯一途径是 WebAssembly，而一个 208 KB 的二进制块会同时让这个包失去零依赖、以及"不经打包器即可导入"的可移植性。自带解码器，等于把那份成本和那条供应链变成你自己的、并且看得见的。
+
+  不开它是安全的，而不是有损的：内容协商决定了服务器绝不会发送没被请求的编码，所以提供 Brotli 的源站只会返回 gzip。代价是带宽——同一个页面 gzip 是 290 KB，`br` 是 99 KB——而带宽恰恰不是这个平台计费的东西。边缘实测下来，这笔交易是反着的：WASM Brotli 的 CPU 约为运行时原生 inflate 的 **1.9 倍**；即便在 14 个站点里线上字节省得最多的那一个上，省下的 186 KB 只换回约 1.2 ms，而多出来的解压是它的好几倍。而且压得越狠越亏，不是越省——brotli quality 11（CDN 从缓存里发的就是它）比 quality 5 线上小 16%，解码却贵 **46%**，因为解压的工作量跟着**输出**字节走，而更密的编码意味着每产出一个字节要做更多活。开 `br` 的理由是让 `Accept-Encoding` 与浏览器一致，不是省 CPU。
+- **流式请求体。** 请求体会先完整读入内存再发出：一是框定长度需要一个这个客户端敢于担保的 `Content-Length`，二是遇到重定向时可能需要重放。对 SDK 发的那点 JSON 完全够用；对大文件上传就不合适，也意味着不支持 `duplex: 'half'` 的流式上传。响应体则全程流式，任何时候都不会替你缓冲。
 - **HTTP/3。** ALPN 报出的是 `h2` 与 `http/1.1`（见 [HTTP/2](#http2--要的是访问不是速度)）；不报 `h3`——那是跑在 UDP 上的 QUIC，从一个只暴露原始 TCP 的运行时根本够不着。服务器若选中客户端未曾报出的协议，一律 fail closed——任何一层都不存在回退重试。
 - **服务器推送、HTTP/2 优先级与 h2c。** 推送在我们的 SETTINGS 里就是关闭的，收到 `PUSH_PROMISE` 即为连接错误；RFC 9113 的优先级机制已被废弃，PRIORITY 帧一律忽略；h2 只跑在 ALPN 协商出的 TLS 之上，绝不以“prior knowledge”走明文。
 
 **socket 不能跨请求上下文。** 连接池按设计随 `Client`、随单次调用存在；不存在跨请求的连接缓存，因为运行时不允许有。
 
-**并发。** 平台允许同时有六条连接处于等待响应头的状态。想要更高并行度的爬虫，必须在这个限额之内做流水线。
+**并发。** 限制是**每次 Worker 调用**最多六条连接同时处于等待响应头的状态——不是每个 Worker，也不是每个账号，所以打到你 Worker 的不同请求各有各的六条。连接在响应头到达的那一刻就腾出槽位，所以它约束的是「同时能有多少次握手在飞」，而不是「同时能下载多少个 body」。想在一次调用内跑更高并行度的爬虫，必须在这个限额之内做流水线。
 
 ## 线上 Worker 的开销
 
@@ -440,7 +497,19 @@ inflate 本身（约 2 ms/MB）加上把 body 物化成 JS 字符串（约 1.7 m
 
 ## 运行时要求
 
-WebCrypto (X25519、ECDH P-256/384/521、ECDSA、RSA-PSS、RSASSA-PKCS1、HKDF、HMAC、AES-GCM)、含 BYOB reader 的 WHATWG Streams、`TextEncoder`/`TextDecoder`、`DecompressionStream`、`URL`、`Headers`、`Request`、`Response`、`AbortSignal`、`btoa`。这些在 workerd、Node ≥ 20、Deno 与 Bun 上全部具备。唯一与具体运行时绑定的部分，是你自己提供的 `connect` 函数。
+WebCrypto (X25519、ECDH P-256/384/521、ECDSA、RSA-PSS、RSASSA-PKCS1、HKDF、HMAC、AES-GCM)、含 BYOB reader 的 WHATWG Streams、`TextEncoder`/`TextDecoder`、`DecompressionStream`、`URL`、`Headers`、`Request`、`Response`、`AbortSignal`、`btoa`。这些在 workerd 与 Node ≥ 22 上全部具备。唯一与具体运行时绑定的部分，是你自己提供的 `connect` 函数。
+
+| 运行时 | 离线测试 | 说明 |
+|---|---|---|
+| Node 22、24 | **1132 / 1132** | CI 把关的组合 |
+| Node 20 | 不支持 | `TextDecoder` 把 `iso-8859-1` 当作真正的 ISO-8859-1，而没有按 WHATWG 要求别名到 windows-1252，该字符集的响应体解码结果不同。已于 2026 年 4 月结束维护 |
+| workerd | live 边缘测试全过 | 目标运行时；由定时边缘任务端到端验证，不在离线套件里 |
+| Deno 2.9 | 999 / 1001 | 两个失败都落在 TLS 1.2 测试服务器的 secp521r1 路径上，不在包内；Deno 的 WebCrypto ECDSA 与 ECDH 在 P-521 上单独测试都正常。原因未定位，因此不宣称支持 |
+| Bun 1.3 | 1079 / 1082 | 一个 repo-hygiene 测试的模块解析差异、一个对时序敏感的 deadline 测试，以及同一个 TLS 1.2 套件测试。原因未定位，因此不宣称支持 |
+
+受支持的组合是 Node 22 与 workerd。Deno 和 Bun 已经非常接近可用，但没有进 CI——把这套测试在那两个运行时上跑通，是一个很好的首次贡献。
+
+CI 会跑 `engines` 里声明的每一个版本，并且有一个 repo-hygiene 测试在两者不一致时直接失败——一个没人跑过的支持下限，是声称，不是事实。
 
 ## 测试
 
@@ -455,6 +524,17 @@ npm run test:live # explicit; needs TUNNELFETCH_PROXY in the environment
 
 TLS 密钥调度与记录层逐字节钉死在 **RFC 8448** "Example Handshake Traces for TLS 1.3" 上：AEAD 复现出 RFC 里一模一样的密文记录，记录层把 RFC 的完整线上字节在两个方向上原样重放。两个 TLS 驱动都对着独立编写的测试服务器测试——1.2 的服务器建在 `node:crypto` 上，而不是本包自己的原语上，这样客户端的 bug 就不可能被服务器端的同一个 bug 抵消掉。
 
+每一个消费对端字节的解析器——X.509、OCSP、HTTP/1.1 响应头、分块体、HTTP/2 帧、HPACK——都会被 fuzz，断言的属性只有一条：**任意输入，要么解析成功，要么抛出 `TunnelFetchError`。** 抛出未类型化的错误（少了空值检查的 `TypeError`、越界的 `RangeError`）就是一个发现：它意味着某处检查缺失，而所有依赖类型化契约来 fail closed 的调用方都接不住它。
+
+fuzzer 自带种子、零依赖，失败时会打印种子、迭代序号和 base64 的输入——可以精确复现，而无法复现失败的 fuzzer 算不上 fuzzer。目标从 `test/fuzz/targets/` 自动发现，新增一个就是放一个文件进去。这套测试还会 fuzz **它自己**：两个合成目标分别证明引擎能报出未类型化的抛出、且不会误报类型化的抛出——否则一次全绿的 fuzz 只能证明 fuzzer 从来没睁眼。
+
+```bash
+FUZZ_ITERATIONS=1000000 node --test test/fuzz/fuzz.test.js   # 长跑
+FUZZ_SEED=12345 node --test test/fuzz/fuzz.test.js           # 换一个角落
+```
+
+CI 每次提交跑固定种子，作为门禁；定时任务跑三百万次迭代、用 run id 作种子，那才是真正在搜索新地面的那一半。
+
 `probe/` 存放一个可复现的能力探测，输出机器可读的 JSON；`probe/results/` 存放本设计所依据的测量结果。`live/` 是边缘互操作实测环境。
 
 凭据只从环境读取。live 套件在未配置时会大声失败而不是跳过：一个意思是“我们没检查”的绿勾，比红叉更糟。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunnelfetch",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A fetch-shaped HTTP client that can route through HTTP CONNECT / HTTPS / SOCKS5 proxies on runtimes with only raw TCP, such as Cloudflare Workers. Implements TLS in userland because the runtime cannot verify a tunnelled peer.",
   "keywords": [
     "fetch",
@@ -25,7 +25,7 @@
   "type": "module",
   "sideEffects": false,
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "exports": {
     ".": {

package/src/client/decode.js

@@ -6,13 +6,72 @@
 import { HttpError, codes } from '../errors.js';
 
 /**
- * The exact Accept-Encoding value the request layer must send. The target runtime's
+ * What the request layer advertises with no extra decoders registered. The target runtime's
  * DecompressionStream supports ONLY gzip / deflate / deflate-raw (verified empirically);
  * advertising `br` or `zstd` would invite bytes we can never decode, turning every response
  * from a brotli-preferring CDN into garbage. Keep this list and decodeBody in lockstep.
+ *
+ * It is also exactly what curl sends, which matters because this client presents curl's TLS and
+ * HTTP/2 fingerprints by default: a browser-shaped handshake paired with a curl-shaped
+ * Accept-Encoding is a mismatch a bot detector can read straight off the wire.
  */
 export const ACCEPT_ENCODING = 'gzip, deflate';
 
+/** Codings the runtime decodes itself. Not overridable — see acceptEncodingFor. */
+const BUILT_IN = new Set(['gzip', 'x-gzip', 'deflate', 'identity']);
+
+/** An HTTP token, which is what a content-coding name must be (RFC 9110 §5.6.2). */
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9a-z]+$/;
+
+/**
+ * The Accept-Encoding to send given the caller's extra decoders.
+ *
+ * Registering a decoder is what makes advertising its coding honest — the two must move together
+ * or the client asks for bytes it cannot read. Order is registration order after the built-ins,
+ * so a caller matching a browser can produce exactly `gzip, deflate, br, zstd`.
+ *
+ * @param {Record<string, BodyDecoder> | null | undefined} decoders
+ * @returns {string}
+ */
+export function acceptEncodingFor(decoders) {
+  if (!decoders) return ACCEPT_ENCODING;
+  const extra = [];
+  for (const name of Object.keys(decoders)) {
+    const coding = name.toLowerCase();
+    // A name is interpolated into a request header, so anything that is not a bare token could
+    // inject a second header field. Reject at registration rather than at send time.
+    if (!TOKEN.test(coding)) {
+      throw new HttpError(
+        codes.HTTP_CONTENT_ENCODING,
+        `"${name}" is not a valid content-coding name; expected an HTTP token`,
+        { coding: name },
+      );
+    }
+    // A built-in must not be overridable. The runtime decompresses gzip and deflate in its own
+    // native code, measured at roughly a third the CPU of the fastest JavaScript implementations,
+    // so accepting a replacement would silently trade that away — and the two code paths disagreed
+    // about it: this function treated `gzip` as already covered while decodeBody would have used
+    // the caller's function. Refusing here makes both paths say the same thing.
+    if (BUILT_IN.has(coding)) {
+      throw new HttpError(
+        codes.HTTP_CONTENT_ENCODING,
+        `"${coding}" is decoded by the runtime natively and cannot be replaced; remove it from ` +
+          '`decoders`. Only codings this runtime has no decoder for can be supplied.',
+        { coding },
+      );
+    }
+    if (typeof decoders[name] !== 'function') {
+      throw new HttpError(
+        codes.HTTP_CONTENT_ENCODING,
+        `the decoder registered for "${coding}" is not a function`,
+        { coding },
+      );
+    }
+    extra.push(coding);
+  }
+  return extra.length ? `${ACCEPT_ENCODING}, ${extra.join(', ')}` : ACCEPT_ENCODING;
+}
+
 /** Codings that exist and are real but that this runtime cannot decompress. */
 const KNOWN_UNSUPPORTED = new Set(['br', 'zstd', 'compress', 'x-compress']);
 
@@ -192,13 +251,29 @@ function firstBytes(chunks, i) {
 /**
  * Undo the response's Content-Encoding.
  *
+/**
+ * A caller-supplied content decoder: raw coded bytes in, decoded bytes out. Streaming, so a body
+ * is never fully buffered on this client's behalf.
+ * @typedef {(stream: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array>} BodyDecoder
+ */
+
+/**
  * @param {ReadableStream<Uint8Array>} stream the raw body
  * @param {string|null|undefined} contentEncoding the Content-Encoding header value; a
  *   comma-separated list names codings in the order the SERVER applied them, so decoding
  *   applies them in reverse.
+ * @param {Record<string, BodyDecoder> | null} [decoders] caller-supplied codings
  * @returns {ReadableStream<Uint8Array>} decoded bytes
  */
-export function decodeBody(stream, contentEncoding) {
+export function decodeBody(stream, contentEncoding, decoders = null) {
+  /** Look a coding up among the caller's decoders, case-insensitively as the header is. */
+  const custom = (coding) => {
+    if (!decoders) return null;
+    for (const name of Object.keys(decoders)) {
+      if (name.toLowerCase() === coding) return decoders[name];
+    }
+    return null;
+  };
   const codings = (contentEncoding ?? '')
     .split(',')
     .map((c) => c.trim().toLowerCase())
@@ -209,12 +284,17 @@ export function decodeBody(stream, contentEncoding) {
     if (coding === 'gzip' || coding === 'x-gzip' || coding === 'deflate' || coding === 'identity') {
       continue;
     }
+    // A registered decoder is the caller taking responsibility for this coding; it outranks the
+    // built-in refusal, which only ever said "this runtime cannot".
+    if (custom(coding)) continue;
     if (KNOWN_UNSUPPORTED.has(coding)) {
       throw new HttpError(
         codes.HTTP_CONTENT_ENCODING,
-        `Content-Encoding "${coding}" is not decodable: this runtime's DecompressionStream ` +
-          'supports only gzip/deflate/deflate-raw, which is why this client never advertises ' +
-          `"${coding}" in Accept-Encoding — the server should not have sent it`,
+        `Content-Encoding "${coding}" is not decodable: no decoder is registered for it and this ` +
+          "runtime's DecompressionStream " +
+          'supports only gzip/deflate/deflate-raw, which is why this client does not advertise ' +
+          `"${coding}" in Accept-Encoding — the server should not have sent it. Pass ` +
+          `\`decoders: { '${coding}': fn }\` to supply one.`,
         { coding },
       );
     }
@@ -226,6 +306,24 @@ export function decodeBody(stream, contentEncoding) {
   for (let i = codings.length - 1; i >= 0; i--) {
     const coding = codings[i];
     if (coding === 'identity') continue; // no-op by definition
+    // Built-ins take the native path unconditionally; acceptEncodingFor refuses to register one,
+    // and this is the same rule stated where the decoding actually happens, so neither entry
+    // point can be reached with the other's assumption.
+    const fn = BUILT_IN.has(coding) ? null : custom(coding);
+    if (fn) {
+      const staged = fn(out);
+      // A decoder that returns something unreadable would surface far downstream as a confusing
+      // stream error; name it here, where the caller can see which coding misbehaved.
+      if (!staged || typeof staged.getReader !== 'function') {
+        throw new HttpError(
+          codes.HTTP_CONTENT_ENCODING,
+          `the decoder for "${coding}" did not return a ReadableStream`,
+          { coding },
+        );
+      }
+      out = staged;
+      continue;
+    }
     out = decompressionStage(out, coding === 'x-gzip' ? 'gzip' : coding);
   }
   return out;

package/src/client.js

@@ -14,7 +14,7 @@ import { ConfigError, HttpError, TunnelFetchError, codes } from './errors.js';
 import { ByteReader, ByteWriter, UnexpectedEofError, concat, utf8 } from './util/bytes.js';
 import { serializeRequestHead } from './http1/request.js';
 import { bodyFraming, readResponseBody, readResponseHead } from './http1/response.js';
-import { ACCEPT_ENCODING, decodeBody } from './client/decode.js';
+import { acceptEncodingFor, decodeBody } from './client/decode.js';
 import { CookieJar } from './client/cookies.js';
 import { DEFAULT_MAX_REDIRECTS, nextRequest, shouldRedirect } from './client/redirect.js';
 import { ConnectionPool, poolKey } from './pool.js';
@@ -71,8 +71,16 @@ const NULL_BODY_STATUS = new Set([101, 204, 205, 304]);
  *   one across Clients or to persist it.
  * @property {number} [maxRedirects] default 20.
  * @property {number} [maxBodyBytes] enforced from Content-Length before a byte is read.
- * @property {boolean} [decompress] gzip/deflate. Default true. Never `br`; the runtime cannot
- *   decompress it, so it is never advertised either.
+ * @property {boolean} [decompress] gzip/deflate. Default true.
+ * @property {Record<string, import('./client/decode.js').BodyDecoder>} [decoders] extra
+ *   content-codings this client can read, e.g. `{ br: (s) => ... }`. Registering one is what
+ *   makes advertising it honest, so each name is appended to Accept-Encoding — a client that
+ *   asked for a coding it cannot decode would turn every such response into garbage. `br` and
+ *   `zstd` are not built in because the runtime's DecompressionStream has neither and this
+ *   package takes no dependencies; supply your own and the cost, and the supply chain, are
+ *   yours and visible. Measured on the edge: WASM brotli decodes at about 2x native gzip, and
+ *   the wire bytes it saves do not pay that back — see the README. The reason to turn it on is
+ *   matching a browser's Accept-Encoding, not saving CPU.
  * @property {boolean} [keepAlive] default true.
  * @property {boolean} [http2] offer HTTP/2 via ALPN and speak it when the server selects it.
  *   Default true. The goal is ACCESS, not speed — some sites treat HTTP/1.1 as a bot signal — and
@@ -93,7 +101,7 @@ export class Client {
    * @param {ClientOptions} [options]
    */
   constructor(options = {}) {
-    this.options = { ...options };
+    this.options = snapshotOptions(options);
     this.pool = new ConnectionPool(options.pool);
     // HTTP/2 connections are NOT pooled the way h1 is: one connection multiplexes many concurrent
     // streams, so it is not checked out per request. It lives here, keyed exactly like the h1 pool,
@@ -118,6 +126,12 @@ export class Client {
       typeof options.now === 'number' ? { now: () => options.now } : {},
     );
     this._closed = false;
+    // Response bodies that have not finished arriving. `fetch` resolves at the response HEAD, so a
+    // caller holding a Response may still be streaming over a connection this Client owns — and on
+    // HTTP/2 that connection is SHARED and torn down by close(), not checked out of the pool the
+    // way an h1 socket is. Anything that decides when a Client is done needs to see these.
+    /** @type {Set<Promise<void>>} */
+    this._inflight = new Set();
     // Bound so a Client can be handed straight to an SDK expecting a bare function.
     this.fetch = this.fetch.bind(this);
   }
@@ -134,6 +148,19 @@ export class Client {
     return performFetch(this, input, init);
   }
 
+  /**
+   * Resolve once every response body handed out by this Client has finished, one way or another —
+   * read to the end, cancelled, or failed. Deliberately NOT folded into close(): close() is the
+   * forceful teardown, and a teardown that waits on the streams it is tearing down would hang on
+   * any body the caller abandoned. This is for callers that want the graceful order.
+   *
+   * Looping rather than a single Promise.all because a body settling can start another (a redirect
+   * drains its predecessor), and a set sampled once would miss the successor.
+   */
+  async idle() {
+    while (this._inflight.size) await Promise.all([...this._inflight]);
+  }
+
   /** Release every pooled socket and shared HTTP/2 connection. A Client that is finished must be
    *  closed or sockets leak for the isolate's lifetime. */
   async close() {
@@ -156,11 +183,27 @@ export class Client {
 export function createFetch(options = {}) {
   return async function tunnelFetch(input, init) {
     const client = new Client(options);
+    let response;
     try {
-      return await client.fetch(input, init);
-    } finally {
+      response = await client.fetch(input, init);
+    } catch (err) {
       await client.close();
+      throw err;
     }
+    // NOT `finally { await client.close() }`. `fetch` resolves when the response HEAD arrives and
+    // the body is still on the wire, so closing here tore down the connection out from under the
+    // caller — invisibly on HTTP/1.1, where the socket is checked out of the pool and closeAll()
+    // could not reach it, but fatally on HTTP/2, where the connection is shared and close() ends
+    // every stream on it. `res.text()` then failed with HTTP2_PROTOCOL.
+    //
+    // Not awaited, or this would deadlock: the body only drains when the caller reads it, and the
+    // caller cannot read a Response that has not been returned yet.
+    //
+    // A caller who neither reads nor cancels the body would leave the Client open — the same leak
+    // as forgetting to close one — except that the idle deadline aborts a stalled body, which
+    // settles the completion and fires this anyway.
+    void client.idle().then(() => client.close().catch(() => {}));
+    return response;
   };
 }
 
@@ -422,6 +465,48 @@ function registerHttp2(client, key, conn) {
  * @param {unknown} err
  * @returns {boolean}
  */
+/**
+ * Take a private, frozen copy of the security-relevant configuration.
+ *
+ * `{ ...options }` is a SHALLOW copy, so `client.options.trust` stayed the caller's own object: a
+ * caller could flip `revocation` or swap `pins` after construction and the next request would run
+ * under the new policy over a pool of connections verified under the old one. The pool key covers
+ * every field the verifier reads (see trustFingerprint), but a key computed from a mutable object
+ * is only as stable as the object.
+ *
+ * `proxy` is deliberately NOT frozen: openTunnel treats a frozen proxy as already normalised and
+ * skips parseProxy, so freezing a raw object here would bypass its validation entirely. Proxy
+ * identity is part of the pool key on its own, so a changed proxy gets a different key regardless.
+ *
+ * @param {ClientOptions} options
+ * @returns {Readonly<ClientOptions>}
+ */
+function snapshotOptions(options) {
+  const o = { ...options };
+  if (o.trust && typeof o.trust === 'object') {
+    const t = { ...o.trust };
+    if (Array.isArray(t.pins)) t.pins = Object.freeze([...t.pins]);
+    if (Array.isArray(t.anchors)) t.anchors = Object.freeze([...t.anchors]);
+    o.trust = Object.freeze(t);
+  }
+  if (o.tls && typeof o.tls === 'object') o.tls = Object.freeze({ ...o.tls });
+  if (o.timeouts && typeof o.timeouts === 'object') o.timeouts = Object.freeze({ ...o.timeouts });
+  return Object.freeze(o);
+}
+
+/**
+ * Remember a body until it settles. Never rejects: a failed body is still a finished one, and this
+ * set exists to answer "is anything still arriving", not "did it go well".
+ */
+function trackBody(client, completed) {
+  const settled = completed.then(
+    () => {},
+    () => {},
+  );
+  client._inflight.add(settled);
+  settled.then(() => client._inflight.delete(settled));
+}
+
 function serverNeverSawIt(err) {
   if (err instanceof UnexpectedEofError) return err.detail?.got === 0;
   return err instanceof TunnelFetchError && err.code === codes.TLS_TRUNCATED && err.detail?.got === 0;
@@ -493,6 +578,7 @@ async function sendAndReceive(client, conn, current, { key, deadlines, reused })
 
   // The connection goes back to the pool only when the body reaches the end its framing declared.
   // `completed` resolving false means the caller cancelled and the stream position is unknown.
+  trackBody(client, raw.completed);
   raw.completed.then(
     (ok) => {
       deadlines.dispose();
@@ -556,6 +642,7 @@ async function sendAndReceiveH2(client, h2, current, { deadlines }) {
   const raw = head.body;
   // Dispose the per-request deadline once the body is done, however it ends. Unlike h1 there is no
   // pool.release: the connection stays shared and alive for the next stream.
+  trackBody(client, raw.completed);
   raw.completed.then(
     () => deadlines.dispose(),
     () => deadlines.dispose(),
@@ -585,7 +672,7 @@ function buildH2Request(client, current, target) {
 
   if (!headers.has('accept')) headers.set('accept', '*/*');
   if (!headers.has('accept-encoding') && o.decompress !== false) {
-    headers.set('accept-encoding', ACCEPT_ENCODING);
+    headers.set('accept-encoding', acceptEncodingFor(o.decoders));
   }
   if (client.jar) {
     const cookie = client.jar.headerFor(current.url);
@@ -624,7 +711,7 @@ function decodeResponseBody(body, headers, options) {
   if (options.decompress === false) return body;
   const encoding = headers.get('content-encoding');
   if (!encoding) return body;
-  return decodeBody(body, encoding);
+  return decodeBody(body, encoding, options.decoders ?? null);
 }
 
 function buildResponse(headInfo, body, framing, conn) {
@@ -669,7 +756,7 @@ function buildHeaders(client, current, target) {
   if (!headers.has('accept-encoding') && client.options.decompress !== false) {
     // Never advertise br or zstd: the runtime has no DecompressionStream for either, so the
     // reward for asking would be a body we cannot decode.
-    headers.set('accept-encoding', ACCEPT_ENCODING);
+    headers.set('accept-encoding', acceptEncodingFor(client.options.decoders));
   }
   if (client.jar) {
     const cookie = client.jar.headerFor(current.url);

package/src/http2/connection.js

@@ -123,7 +123,7 @@ export class Http2Retryable extends Http2Error {}
 
 export class Http2Connection {
   /**
-   * @param {import('./frames.js').ByteDuplex | { readable: ReadableStream<Uint8Array>,
+   * @param {import('../tls/connect.js').ByteDuplex | { readable: ReadableStream<Uint8Array>,
    *   writable: WritableStream<Uint8Array> }} duplex plaintext transport (a TLS session's
    *   plaintextDuplex, or a raw socket for cleartext h2 in tests)
    * @param {Http2ConnectionOptions} [opts]

package/src/pool.js

@@ -52,15 +52,31 @@ export function poolKey({ scheme, hostname, port, proxy, trust, tls }) {
 
 function trustFingerprint(trust) {
   const mode = trust?.mode ?? 'system';
-  if (mode === 'system') return 'system';
-  if (mode === 'none') return 'none';
+  // The fingerprint must cover exactly the fields the VERIFIER reads for this mode — no fewer, or
+  // a connection validated under one policy serves a request under another; no more, or the pool
+  // is split along axes that make no difference. src/trust/index.js states the set per mode by
+  // rejecting every other key outright (`forbidKeys`), so this mirrors those lists.
+  const rev = `rev=${trust?.revocation ?? 'staple'}`;
+  const pins = `pins=${[...(trust?.pins ?? [])].sort().join(',')}`;
+  // Anchors matter even when they are absent: omitting them means the system store, and a policy
+  // pinned against custom anchors is not the policy pinned against the system store.
+  const anchors =
+    trust?.anchors === undefined
+      ? 'anchors=system'
+      : `anchors=${trust.anchors.length}:${anchorDigest(trust.anchors)}`;
+
+  // 'none' forbids anchors/verify/revocation, so pins are the only thing that can vary — and they
+  // DO vary: pin-only trust still enforces them.
+  if (mode === 'none') return `none|${pins}`;
   if (mode === 'custom') {
     // Two different callbacks are two different policies and we cannot compare functions, so a
     // custom policy never shares a connection. Correct, and cheap: custom trust is rare.
+    // ('custom' forbids anchors/pins/revocation — the callback owns the whole decision.)
     return `custom:${customCounter(trust.verify)}`;
   }
-  if (mode === 'pinned') return `pinned:${[...(trust.pins ?? [])].sort().join(',')}`;
-  if (mode === 'anchors') return `anchors:${(trust.anchors ?? []).length}:${anchorDigest(trust.anchors)}`;
+  if (mode === 'system') return `system|${rev}`;
+  if (mode === 'anchors') return `anchors:${(trust.anchors ?? []).length}:${anchorDigest(trust.anchors)}|${rev}`;
+  if (mode === 'pinned') return `pinned|${pins}|${anchors}|${rev}`;
   return `unknown:${mode}`;
 }
 

package/src/tls/record.js

@@ -81,8 +81,19 @@ async function withGrace(promise, ms) {
 /**
  * Keys for one direction: a TLS 1.3 traffic `secret` (key and IV derived per RFC 8446 s7.3,
  * KeyUpdate rotation possible) or raw TLS 1.2 key_block slices (no forward rotation).
- * @typedef {{ cipher: number, secret: Uint8Array }
- *   | { cipher: number, key: Uint8Array, iv: Uint8Array }} DirectionKeys
+ * Exactly one of the two shapes is valid — a 1.3 `secret`, or a 1.2 `key`+`iv` — and _makeState
+ * enforces that at runtime. It is spelled with optional members rather than as a union because the
+ * setters destructure all four names, and TypeScript cannot destructure a union member that some
+ * branch lacks; a union here emits declarations that do not type-check for a consumer.
+ * @typedef {{ cipher: number, secret?: Uint8Array, key?: Uint8Array, iv?: Uint8Array }} DirectionKeys
+ */
+
+/**
+ * One direction's live protection state. Module-level, not inside the constructor: a typedef
+ * declared in a function body is not in scope where the emitted declaration needs it.
+ * @typedef {null | { aead: import('./aead.js').Aead, seq: bigint, cipher: number,
+ *   hash: import('./keyschedule.js').ScheduleHash,
+ *   secret: Uint8Array | null }} DirectionState
  */
 
 /**
@@ -113,9 +124,6 @@ export class RecordLayer {
     this._onPostHandshake = opts.onPostHandshake ?? null;
 
     this._version = TLS13; // semantics selector; setVersion() pins it when negotiated
-    /** @typedef {null | { aead: import('./aead.js').Aead, seq: bigint, cipher: number,
-     *   hash: import('./keyschedule.js').ScheduleHash,
-     *   secret: Uint8Array | null }} DirectionState */
     /** @type {DirectionState} */
     this._send = null;
     /** @type {DirectionState} */

package/types/client/decode.d.ts

@@ -1,13 +1,31 @@
+/**
+ * The Accept-Encoding to send given the caller's extra decoders.
+ *
+ * Registering a decoder is what makes advertising its coding honest — the two must move together
+ * or the client asks for bytes it cannot read. Order is registration order after the built-ins,
+ * so a caller matching a browser can produce exactly `gzip, deflate, br, zstd`.
+ *
+ * @param {Record<string, BodyDecoder> | null | undefined} decoders
+ * @returns {string}
+ */
+export function acceptEncodingFor(decoders: Record<string, BodyDecoder> | null | undefined): string;
 /**
  * Undo the response's Content-Encoding.
  *
+/**
+ * A caller-supplied content decoder: raw coded bytes in, decoded bytes out. Streaming, so a body
+ * is never fully buffered on this client's behalf.
+ * @typedef {(stream: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array>} BodyDecoder
+ */
+/**
  * @param {ReadableStream<Uint8Array>} stream the raw body
  * @param {string|null|undefined} contentEncoding the Content-Encoding header value; a
  *   comma-separated list names codings in the order the SERVER applied them, so decoding
  *   applies them in reverse.
+ * @param {Record<string, BodyDecoder> | null} [decoders] caller-supplied codings
  * @returns {ReadableStream<Uint8Array>} decoded bytes
  */
-export function decodeBody(stream: ReadableStream<Uint8Array>, contentEncoding: string | null | undefined): ReadableStream<Uint8Array>;
+export function decodeBody(stream: ReadableStream<Uint8Array>, contentEncoding: string | null | undefined, decoders?: Record<string, BodyDecoder> | null): ReadableStream<Uint8Array>;
 /**
  * Extract the charset parameter from a Content-Type value, handling quoting and other
  * parameters: `text/html; boundary=x; charset="ISO-8859-4"` -> 'iso-8859-4'.
@@ -46,9 +64,21 @@ export function charsetFor(contentType: string | null | undefined, bodyPrefix?:
  */
 export function decodeText(bytes: Uint8Array, charset?: string): string;
 /**
- * The exact Accept-Encoding value the request layer must send. The target runtime's
+ * What the request layer advertises with no extra decoders registered. The target runtime's
  * DecompressionStream supports ONLY gzip / deflate / deflate-raw (verified empirically);
  * advertising `br` or `zstd` would invite bytes we can never decode, turning every response
  * from a brotli-preferring CDN into garbage. Keep this list and decodeBody in lockstep.
+ *
+ * It is also exactly what curl sends, which matters because this client presents curl's TLS and
+ * HTTP/2 fingerprints by default: a browser-shaped handshake paired with a curl-shaped
+ * Accept-Encoding is a mismatch a bot detector can read straight off the wire.
  */
 export const ACCEPT_ENCODING: "gzip, deflate";
+/**
+ * Undo the response's Content-Encoding.
+ *
+ * /**
+ * A caller-supplied content decoder: raw coded bytes in, decoded bytes out. Streaming, so a body
+ * is never fully buffered on this client's behalf.
+ */
+export type BodyDecoder = (stream: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array>;

package/types/client.d.ts

@@ -54,8 +54,16 @@ export function install(options?: ClientOptions): () => void;
  *   one across Clients or to persist it.
  * @property {number} [maxRedirects] default 20.
  * @property {number} [maxBodyBytes] enforced from Content-Length before a byte is read.
- * @property {boolean} [decompress] gzip/deflate. Default true. Never `br`; the runtime cannot
- *   decompress it, so it is never advertised either.
+ * @property {boolean} [decompress] gzip/deflate. Default true.
+ * @property {Record<string, import('./client/decode.js').BodyDecoder>} [decoders] extra
+ *   content-codings this client can read, e.g. `{ br: (s) => ... }`. Registering one is what
+ *   makes advertising it honest, so each name is appended to Accept-Encoding — a client that
+ *   asked for a coding it cannot decode would turn every such response into garbage. `br` and
+ *   `zstd` are not built in because the runtime's DecompressionStream has neither and this
+ *   package takes no dependencies; supply your own and the cost, and the supply chain, are
+ *   yours and visible. Measured on the edge: WASM brotli decodes at about 2x native gzip, and
+ *   the wire bytes it saves do not pay that back — see the README. The reason to turn it on is
+ *   matching a browser's Accept-Encoding, not saving CPU.
  * @property {boolean} [keepAlive] default true.
  * @property {boolean} [http2] offer HTTP/2 via ALPN and speak it when the server selects it.
  *   Default true. The goal is ACCESS, not speed — some sites treat HTTP/1.1 as a bot signal — and
@@ -75,95 +83,7 @@ export class Client {
      * @param {ClientOptions} [options]
      */
     constructor(options?: ClientOptions);
-    options: {
-        /**
-         * Socket factory. Required for any
-         * request the platform's own `fetch` cannot serve — which is every proxied request, and every
-         * request asking for a trust policy `fetch` cannot express.
-         */
-        connect?: import("./proxy/index.js").ConnectFn | undefined;
-        /**
-         * URL string or
-         * config object; `http:`, `https:`, `socks5:` and `socks5h:`.
-         */
-        proxy?: string | import("./proxy/index.js").ProxyConfig | null | undefined;
-        /**
-         * certificate policy, httpx's
-         * `verify=`. Default `{ mode: 'system' }`.
-         */
-        trust?: import("./trust/index.js").TrustConfig | undefined;
-        /**
-         * handshake knobs.
-         */
-        tls?: import("./tls/connect.js").TlsOptions | undefined;
-        /**
-         * connect / handshake /
-         * headers / idle / total, in ms. The idle gap is the control; total is a backstop.
-         */
-        timeouts?: import("./util/deadline.js").DeadlineOptions | undefined;
-        /**
-         * enable a per-Client cookie jar.
-         */
-        cookies?: boolean | undefined;
-        /**
-         * supply a jar directly, e.g. to share
-         * one across Clients or to persist it.
-         */
-        jar?: CookieJar | undefined;
-        /**
-         * default 20.
-         */
-        maxRedirects?: number | undefined;
-        /**
-         * enforced from Content-Length before a byte is read.
-         */
-        maxBodyBytes?: number | undefined;
-        /**
-         * gzip/deflate. Default true. Never `br`; the runtime cannot
-         * decompress it, so it is never advertised either.
-         */
-        decompress?: boolean | undefined;
-        /**
-         * default true.
-         */
-        keepAlive?: boolean | undefined;
-        /**
-         * offer HTTP/2 via ALPN and speak it when the server selects it.
-         * Default true. The goal is ACCESS, not speed — some sites treat HTTP/1.1 as a bot signal — and
-         * on a CPU-billed runtime h2 costs MORE than h1 (HPACK is extra work). Set false to offer only
-         * `http/1.1`. There is no fallback-and-retry either way: the server's ALPN pick is followed.
-         */
-        http2?: boolean | undefined;
-        /**
-         * never delegate to the platform's fetch, even when it could
-         * serve the request. Mainly for exercising this stack against origins that do not need it.
-         */
-        forceTunnel?: boolean | undefined;
-        /**
-         * delegation target; defaults to `globalThis.fetch`.
-         */
-        nativeFetch?: FetchLike | undefined;
-        /**
-         * connection pool sizing.
-         */
-        pool?: {
-            maxPerKey?: number;
-            maxTotal?: number;
-        } | undefined;
-        limits?: Limits | undefined;
-        /**
-         * injectable randomness and key generation.
-         */
-        deps?: import("./tls/connect.js").TlsDeps | undefined;
-        /**
-         * aborts every request this Client makes.
-         */
-        signal?: AbortSignal | undefined;
-        /**
-         * epoch ms override, for certificate validity in tests.
-         */
-        now?: number | undefined;
-    };
+    options: Readonly<ClientOptions>;
     pool: ConnectionPool;
     /** @type {Map<string, import('./http2/connection.js').Http2Connection>} */
     _h2: Map<string, import("./http2/connection.js").Http2Connection>;
@@ -172,6 +92,8 @@ export class Client {
     jar: CookieJar | null;
     tickets: TicketStore;
     _closed: boolean;
+    /** @type {Set<Promise<void>>} */
+    _inflight: Set<Promise<void>>;
     /**
      * @param {RequestInfo | URL} input
      * @param {RequestInit} [init]
@@ -180,6 +102,16 @@ export class Client {
     fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response & {
         tunnelfetch?: ResponseDetail;
     }>;
+    /**
+     * Resolve once every response body handed out by this Client has finished, one way or another —
+     * read to the end, cancelled, or failed. Deliberately NOT folded into close(): close() is the
+     * forceful teardown, and a teardown that waits on the streams it is tearing down would hang on
+     * any body the caller abandoned. This is for callers that want the graceful order.
+     *
+     * Looping rather than a single Promise.all because a body settling can start another (a redirect
+     * drains its predecessor), and a set sampled once would miss the successor.
+     */
+    idle(): Promise<void>;
     /** Release every pooled socket and shared HTTP/2 connection. A Client that is finished must be
      *  closed or sockets leak for the isolate's lifetime. */
     close(): Promise<void>;
@@ -271,10 +203,21 @@ export type ClientOptions = {
      */
     maxBodyBytes?: number | undefined;
     /**
-     * gzip/deflate. Default true. Never `br`; the runtime cannot
-     * decompress it, so it is never advertised either.
+     * gzip/deflate. Default true.
      */
     decompress?: boolean | undefined;
+    /**
+     * extra
+     * content-codings this client can read, e.g. `{ br: (s) => ... }`. Registering one is what
+     * makes advertising it honest, so each name is appended to Accept-Encoding — a client that
+     * asked for a coding it cannot decode would turn every such response into garbage. `br` and
+     * `zstd` are not built in because the runtime's DecompressionStream has neither and this
+     * package takes no dependencies; supply your own and the cost, and the supply chain, are
+     * yours and visible. Measured on the edge: WASM brotli decodes at about 2x native gzip, and
+     * the wire bytes it saves do not pay that back — see the README. The reason to turn it on is
+     * matching a browser's Accept-Encoding, not saving CPU.
+     */
+    decoders?: Record<string, import("./client/decode.js").BodyDecoder> | undefined;
     /**
      * default true.
      */
@@ -316,8 +259,8 @@ export type ClientOptions = {
      */
     now?: number | undefined;
 };
-import { CookieJar } from './client/cookies.js';
 import { ConnectionPool } from './pool.js';
+import { CookieJar } from './client/cookies.js';
 import { TicketStore } from './tls/tickets.js';
 import { utf8 } from './util/bytes.js';
 export { CookieJar, ConnectionPool, utf8 };

package/types/http2/connection.d.ts

@@ -49,12 +49,12 @@ export class Http2Retryable extends Http2Error {
  */
 export class Http2Connection {
     /**
-     * @param {import('./frames.js').ByteDuplex | { readable: ReadableStream<Uint8Array>,
+     * @param {import('../tls/connect.js').ByteDuplex | { readable: ReadableStream<Uint8Array>,
      *   writable: WritableStream<Uint8Array> }} duplex plaintext transport (a TLS session's
      *   plaintextDuplex, or a raw socket for cleartext h2 in tests)
      * @param {Http2ConnectionOptions} [opts]
      */
-    constructor(duplex: import("./frames.js").ByteDuplex | {
+    constructor(duplex: import("../tls/connect.js").ByteDuplex | {
         readable: ReadableStream<Uint8Array>;
         writable: WritableStream<Uint8Array>;
     }, opts?: Http2ConnectionOptions);

package/types/tls/record.d.ts

@@ -9,8 +9,18 @@
 /**
  * Keys for one direction: a TLS 1.3 traffic `secret` (key and IV derived per RFC 8446 s7.3,
  * KeyUpdate rotation possible) or raw TLS 1.2 key_block slices (no forward rotation).
- * @typedef {{ cipher: number, secret: Uint8Array }
- *   | { cipher: number, key: Uint8Array, iv: Uint8Array }} DirectionKeys
+ * Exactly one of the two shapes is valid — a 1.3 `secret`, or a 1.2 `key`+`iv` — and _makeState
+ * enforces that at runtime. It is spelled with optional members rather than as a union because the
+ * setters destructure all four names, and TypeScript cannot destructure a union member that some
+ * branch lacks; a union here emits declarations that do not type-check for a consumer.
+ * @typedef {{ cipher: number, secret?: Uint8Array, key?: Uint8Array, iv?: Uint8Array }} DirectionKeys
+ */
+/**
+ * One direction's live protection state. Module-level, not inside the constructor: a typedef
+ * declared in a function body is not in scope where the emitted declaration needs it.
+ * @typedef {null | { aead: import('./aead.js').Aead, seq: bigint, cipher: number,
+ *   hash: import('./keyschedule.js').ScheduleHash,
+ *   secret: Uint8Array | null }} DirectionState
  */
 /**
  * @typedef {object} RecordLayerOptions
@@ -37,25 +47,10 @@ export class RecordLayer {
     _padding: ((type: number, length: number) => number) | null;
     _onPostHandshake: ((msg: HandshakeMessage) => void | Promise<void>) | null;
     _version: number;
-    /** @typedef {null | { aead: import('./aead.js').Aead, seq: bigint, cipher: number,
-     *   hash: import('./keyschedule.js').ScheduleHash,
-     *   secret: Uint8Array | null }} DirectionState */
     /** @type {DirectionState} */
-    _send: {
-        aead: import("./aead.js").Aead;
-        seq: bigint;
-        cipher: number;
-        hash: import("./keyschedule.js").ScheduleHash;
-        secret: Uint8Array | null;
-    } | null;
+    _send: DirectionState;
     /** @type {DirectionState} */
-    _recv: {
-        aead: import("./aead.js").Aead;
-        seq: bigint;
-        cipher: number;
-        hash: import("./keyschedule.js").ScheduleHash;
-        secret: Uint8Array | null;
-    } | null;
+    _recv: DirectionState;
     /** Handshake reassembly. Chunk list, not one growing buffer, so a peer drip-feeding a
      * message in tiny records costs O(records), not O(records^2).
      * @type {Uint8Array[]} */
@@ -323,14 +318,27 @@ export type HandshakeMessage = {
 /**
  * Keys for one direction: a TLS 1.3 traffic `secret` (key and IV derived per RFC 8446 s7.3,
  * KeyUpdate rotation possible) or raw TLS 1.2 key_block slices (no forward rotation).
+ * Exactly one of the two shapes is valid — a 1.3 `secret`, or a 1.2 `key`+`iv` — and _makeState
+ * enforces that at runtime. It is spelled with optional members rather than as a union because the
+ * setters destructure all four names, and TypeScript cannot destructure a union member that some
+ * branch lacks; a union here emits declarations that do not type-check for a consumer.
  */
 export type DirectionKeys = {
     cipher: number;
-    secret: Uint8Array;
-} | {
+    secret?: Uint8Array;
+    key?: Uint8Array;
+    iv?: Uint8Array;
+};
+/**
+ * One direction's live protection state. Module-level, not inside the constructor: a typedef
+ * declared in a function body is not in scope where the emitted declaration needs it.
+ */
+export type DirectionState = null | {
+    aead: import("./aead.js").Aead;
+    seq: bigint;
     cipher: number;
-    key: Uint8Array;
-    iv: Uint8Array;
+    hash: import("./keyschedule.js").ScheduleHash;
+    secret: Uint8Array | null;
 };
 export type RecordLayerOptions = {
     /**