tunnelfetch 1.11.0 → 1.13.0

package/README.zh-CN.md

@@ -117,6 +117,38 @@ await client.close();          // 必须调用：释放池中的 socket
 （第 16 步），所以一个普通名字的 `Secure` cookie 即便是在 https 上设置的，仍可能被 http 覆盖;以及名字加值
 4096 字节的上限（第 4 步）。
 
+### 获取 socket 工厂
+
+`connect` 是参数而不是 import，这是刻意的：它是这个包唯一无法自带的部分，由调用方提供也正是上面每一层都能在
+内存管道上做字节级测试的原因。稳妥地获取一个：
+
+```js
+import { resolveConnect } from 'tunnelfetch';
+
+const connect = await resolveConnect({
+  specifiers: ['cloudflare:sockets'],
+});
+const client = new Client({ connect, proxy: env.PROXY_URL });
+```
+
+第一个能导出可调用函数的 specifier 胜出；全部失败时报错会列出试过的每一个 specifier 及其失败原因——错误在
+启动时就现身，而不是以 "connect is not a function" 的样子从 TLS 层深处冒出来。过程中关掉了两个坑：
+
+1. 导入是动态的，失败会被捕获。某个只在一个运行时上能解析的 specifier，一旦被静态导入，就会让整个包在其它
+   所有平台上无法加载；列着多个运行时的可移植列表则是安全的。
+2. 打包器看不穿变量形式的 specifier。打包部署时直接把 `connect` 传进来，或者给 `resolveConnect` 传一个闭包了
+   字面量的 `importModule`，让打包器看得到：
+
+   ```js
+   const connect = await resolveConnect({
+     importModule: () => import('cloudflare:sockets'),
+   });
+   ```
+
+`normaliseSocket` 把一个运行时 socket 拍平成普通双工对象，`normalisingConnect` 包一层工厂，让每个返回的 socket
+都被拍平。它们的存在是因为 edge 运行时上 socket 的 `readable` 和 `writable` 是原型上的访问器，`{ ...socket }`
+两个都拷不到，第一次读取就会在 TLS 层深处报 `getReader` 的错误。
+
 ### 替换全局 fetch
 
 有的库只会直接调用全局 `fetch`，为它们准备的是：
@@ -517,17 +549,26 @@ CertificateError [CERT_PIN_MISMATCH]: no certificate in the chain matches any co
 
 ### 一个请求要多少
 
-通过代理抓取一个尺寸可控的源站，热态，同一 isolate 上 7 轮以上取中位数，传输走 gzip。最后一列是同样的数字
-换算成速率，那是更值得随身记住的形式：
+通过代理抓取 `sizeorigin/`，传输走 gzip，所有尺寸在**同一次扫描、同一个 isolate** 内跑完，n>=5 取中位数。
+方法写在这里，是因为上一版这张表没有把方法记清楚到能复现的程度：**一个热态页面 = `(reuse=4 - reuse=1) / 3`**，
+也就是连接已经打开之后第 2 到第 4 个页面的成本；最后一列是同一次扫描测出来的新建连接数字。
 
-| Body | 5 页均摊 | 复用连接 | 新建连接 |
+| Body | 热态页面 | 每解压 MB | 新连接上的第一个请求 |
 | --- | --- | --- | --- |
-| 1 KB | 3.2 ms | 1.7 ms | 9.2 ms |
-| 16 KB | 4.6 ms | 3.1 ms | 10.6 ms |
-| 64 KB | 8.2 ms | 6.7 ms | 14.2 ms |
-| 256 KB | 18.2 ms | 16.7 ms | 24.2 ms |
-| 1 MB | 54.8 ms | 53.3 ms | 60.8 ms |
-| 4 MB | 119.8 ms | 118.3 ms | 125.8 ms |
+| 1 KB | **1.3 ms** | — | 8 ms |
+| 16 KB | **2.3 ms** | 149 ms/MB | 9 ms |
+| 64 KB | **6.0 ms** | 96 ms/MB | 13 ms |
+| 256 KB | **14.3 ms** | 57 ms/MB | 28 ms |
+| 1 MB | **36.3 ms** | 36 ms/MB | 59 ms |
+| 4 MB | **102 ms** | 26 ms/MB | 135 ms |
+
+最后一列不是「热态页面 + 一次握手」。4 MB 那一行它比热态页面高 33 ms，而握手只值个位数——因为一条连接上的
+**第一个** body 还要在 V8 把解码循环编译优化之前跑一遍。评估一个新源站要看这一列，不要看第一列。
+
+**2026 年 8 月重测，中间几档动了。** 4 MB 那行几乎原样复现（102 对先前发布的 104）；64 KB 到 1 MB 比这张表
+原先的数字低 20–30%。那**不是**下面讲的 socket 视图大小改动——在同一个 isolate 里 A/B 新旧视图大小，1 MB 热态
+页面只差约 1 ms——所以它要么是单次扫描看不到的日间波动，要么是被取代的那张表取数方式不同。旧数字已经无从复查，
+这正是把方法写在这里的理由。
 
 冷启动成本是**总数**,不是往上面某一行加的增量:
 
@@ -554,35 +595,45 @@ CertificateError [CERT_PIN_MISMATCH]: no certificate in the chain matches any co
 ### 这些折算成多少钱
 
 Workers Standard 每月 $5，含 1000 万请求和 3000 万 CPU 毫秒，超出部分每百万请求 $0.30、每百万 CPU 毫秒
-$0.02。把上面的实测代入，并把冷启动的影响单独列成两组列，这样任一负载「预热与否」的差别是看得见的：
-
-| 工作负载 | CPU/请求 | 1000 万,冷 | 1000 万,预热 | 10 亿,冷 | 10 亿,预热 |
-| --- | --- | --- | --- | --- | --- |
-| 平台 `fetch`,16 KB —— 参照;它用不了代理 | 0.3 ms | $5.00 | $5.00 | $307.40 | $307.40 |
-| 平台 `fetch`,4 MB —— 同一参照,实测 | 3.2 ms | $5.04 | $5.04 | $365.40 | $365.40 |
-| 连接复用,16 KB 页面 | 3.1 ms | $5.90 | $5.24 | $451.20 | $385.20 |
-| 每请求新建连接,16 KB | 10.6 ms | $7.41 | $6.75 | $602.20 | $536.20 |
-| 连接复用,1 MB 页面 | 53.3 ms | $15.94 | $15.28 | $1455.20 | $1389.20 |
-| 每请求新建连接,1 MB | 60.8 ms | $17.45 | $16.79 | $1606.20 | $1540.20 |
-| 连接复用,4 MB 页面 | 118.3 ms | $28.94 | $28.28 | $2755.20 | $2689.20 |
-| 每请求新建连接,4 MB | 125.8 ms | $30.45 | $29.79 | $2906.20 | $2840.20 |
+$0.02。公式就是 `$5 + max(0, 请求数 - 1000万) x $0.30/百万 + max(0, CPU毫秒 - 3000万) x $0.02/百万`，
+没有别的：
+
+| 工作负载 | CPU/请求 | 1000 万/月 | 10 亿/月 |
+| --- | --- | --- | --- |
+| 平台 `fetch`,16 KB —— 参照;它用不了代理 | 0.3 ms | $5.00 | $307.40 |
+| 平台 `fetch`,4 MB —— 同一参照,实测 | 3.2 ms | $5.04 | $365.40 |
+| 连接复用,16 KB 页面 | 2.3 ms | $5.00 | $347.40 |
+| 每请求新建连接,16 KB | 9 ms | $6.20 | $481.40 |
+| 连接复用,1 MB 页面 | 36.3 ms | $11.66 | $1,027.40 |
+| 每请求新建连接,1 MB | 59 ms | $16.20 | $1,481.40 |
+| 连接复用,4 MB 页面 | 102 ms | $24.80 | $2,341.40 |
+| 每请求新建连接,4 MB | 135 ms | $31.40 | $3,001.40 |
+
+那两个 `max(0, ...)` 是新加的。上一版这张表把每一个请求、每一毫秒 CPU 都算了钱，忽略了它自己上面那句话
+描述的免费额度——于是 1000 万/月那一列最多高估了 74%（$8.70，而实际账单是 $5.00），而在 10 亿那一列误差在
+0.2% 以内，因为那时免费额度只是个舍入误差。高估的方向是对本包不利的，大概这就是它活了这么久的原因。
 
 参照那一行给了两个尺寸,因为平台自己的 `fetch` **不是平的**——它按每解压 MB 约 0.82 ms 增长,这是在同一个 CDN 的尺寸阶梯上测的,只有大小在变。把它写成单一的 0.3 ms 再拿去和 4 MB 那一行比,是拿不同的东西相比,而且是**抬高了对手而不是抬高本包**。
 
-这些美元数字跟随上面修正后的 CPU 测量,所以正文偏重的行是 1.4.0 及以前的**两到三倍**。那不是包变慢了,是移除了一个内容压缩比 220:1 的源站。
+这张表原先还按「冷 / 预热」分成两组列。那两组列现在去掉了：新的 CPU 数字全部是热态和新建连接的实测，冷 isolate
+下的同一批负载没有重测过，与其把上一版的冷启动增量套到新基线上凑出四列，不如只写实际测过的两列。冷启动的成本
+在上面那张 `warmup()` 表里，那是一个**总数**，不是往这里某一行上加的增量。
 
 #### Chrome 身份的每个选项各花多少
 
 上面那张表是默认身份:线上 gzip、AES-256-GCM、x25519。Chrome 那一行把所有变化捆在一起,对做决定没什么用。按"连接复用 + 1 MB 页面 + 十亿请求/月 + 已预热"逐项拆开:
 
-| 相对基线的变化 | CPU/请求 | 10 亿/月,已预热 | Δ | 何时才付 |
+| 相对基线的变化 | CPU/请求 | 10 亿/月 | Δ | 何时才付 |
 | --- | --- | --- | --- | --- |
-| 基线 —— gzip、AES-256-GCM、x25519 | 53.3 ms | $1,389 | — | 总是 |
-| 源站发 `br` 而不是 gzip | 57.6 ms | $1,474 | **+$85** | 源站选择发 `br` |
-| 服务器选中 ChaCha20-Poly1305 | 56.3 ms | $1,448 | **+$59** | 服务器优先选它而非 AES |
-| 源站发 `zstd` 而不是 gzip | 56.1 ms | $1,444 | **+$55** | 源站选择发 `zstd` |
-| 协商 X25519MLKEM768,每连接 1 个请求 | 61.0 ms | $1,542 | **+$153** | 每次握手 |
-| 协商 X25519MLKEM768,每连接 20 个请求 | 53.3 ms | $1,390 | **+$0.15** | 同一次握手,摊薄后 |
+| 基线 —— gzip、AES-256-GCM、x25519,热态 | 36.3 ms | $1,027 | — | 总是 |
+| 源站发 `br` 而不是 gzip | 40.5 ms | $1,111 | **+$84** | 源站选择发 `br` |
+| 服务器选中 ChaCha20-Poly1305 | 39.3 ms | $1,086 | **+$59** | 服务器优先选它而非 AES |
+| 源站发 `zstd` 而不是 gzip | 39.1 ms | $1,083 | **+$56** | 源站选择发 `zstd` |
+| 协商 X25519MLKEM768,每连接 1 个请求 | 59.2 ms | $1,484 | **+$3** | 每次握手 |
+| 协商 X25519MLKEM768,每连接 20 个请求 | 36.3 ms | $1,028 | **+$0.15** | 同一次握手,摊薄后 |
+
+ML-KEM 这两行是拿**新建连接**的 1 MB 基线 59 ms（$1,481）来比的，不是拿表头那个热态基线；Δ 列反映的是这一点，
+所以是 $3 而不是旧版写的 $153。那 $153 是「不复用连接」的成本，被算到了后量子密钥交换头上。
 
 **最后两行是同样的 0.15 ms ML-KEM,差别完全来自连接复用**——这才是这张表最值得带走的一条。后量子密钥交换在你让 `Client` 活着时是这里最便宜的东西,在你不这么做时是最贵的,因为它是**每握手**,而其余全是每字节。
 
@@ -655,8 +706,40 @@ CPU 计费，所以十亿请求下「预热」两列省下的每月 $65 是净
 大 body 的"每字节成本"其实不按字节计——按的是流边界穿越次数。这个运行时的 `DecompressionStream` 以
 4096 字节为块产出输出，套接字单次交付也至多 4096 字节，而每一块在运行时与 JS 之间穿越一次都要几十微秒，
 与块大小无关——实测约 **17 µs 一次穿越**，来自同一个 1 MB 分别按 4 KiB（6.0 ms/MB）到 256 KiB
-（1.67 ms/MB）收集的阶梯。因此两条热路径都改为用 BYOB 读来抽干来源：它把已经缓冲的数据一次交付，且只要
-有一个字节就立即以部分填充返回，流式延迟不变。
+（1.67 ms/MB）收集的阶梯。因此两条热路径都改为用 BYOB 读来抽干来源：它把好几块合并成一次穿越，且只要
+有一个字节就立即以部分填充返回，流式延迟不变。合并多少是**传输层**决定的，不是视图决定的——BYOB 读从不
+等着填满——所以视图开得比传输层单次交给你的多，买不到任何东西，只会白付一次分配。4 MB body 上实测的平均
+填充：直连 37 KB，走代理 8 KB。
+
+### 一个在本包赖以存在的那条路径上从未接通的旋钮
+
+`openTunnel` 做完 CONNECT（或 SOCKS5）握手时手里握着一个带缓冲的 reader——对端可能把隧道数据和应答塞在
+同一个 chunk 里——它把这个交出去时包成了 `new ReadableStream({ pull })`。逻辑正确，但那是**普通流，不是
+byte stream**。TLS 记录层要 BYOB reader，要不到就静默降级成 default reader，于是*每一条走代理的连接*都丢了
+BYOB，连带 `tls.pullBytes`（它唯一的职责就是决定 BYOB 视图多大）一起失效。
+
+同源、1 MB 过记录层、同一 isolate、n=15，修复前：
+
+| | `pullBytes: 16 KiB` | `pullBytes: 1 MiB` |
+|---|---|---|
+| 直连 | min 25, p50 31 | min 73, p50 90 |
+| **走代理** | min 95, p50 111 | min 101, p50 121 |
+
+**直连 2.9×，代理 6%**——那个旋钮在代理路径上根本没被读到。连带后果：当初用来定 64 KiB 默认值、标着「对着
+真实代理 socket 扫出来」的那条 U 曲线，是同一个配置的四个采样。
+
+`src/proxy/tunnel.js` 把隧道改成 byte stream，并且在握手剩余字节吐完之后**把调用方自己的视图直接递给
+socket**。旋钮接上之后重扫（1 MB 过记录层，p50）：
+
+| | 8 KiB | **16 KiB** | 32 KiB | 64 KiB | 256 KiB |
+|---|---|---|---|---|---|
+| 直连 | 21 | 20 | 18 | 22 | 40 |
+| 代理 A | 51 | 61 | 61 | 89 | 152 |
+| 代理 B | 68 | 74 | — | 102 | — |
+
+两个独立代理上都单调。默认值因此从 64 KiB 改为 **16 KiB**：三条路径上都在最优列 20% 以内，而 64 KiB 最差
+偏离 45%，分配量还是四分之一，并且正好是一个 TLS 记录。端到端走真 Client + 代理、n=13：1 MB **63 对 78 ms**、
+4 MB **145 对 164 ms**（中位数），4 MB 的最小值在噪声内。
 
 读进去的那个视图是 **16 KiB，而且这个尺寸是扫出来的，不是拍的**。它比看上去重要：输入由一个 JS 任务在与
 拉取方相同的事件循环上泵送，所以读到达时解压器手上通常只压着一两块，读回来就是部分填充——实测一个 1 MB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunnelfetch",
-  "version": "1.11.0",
+  "version": "1.13.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",

package/src/connect.js

@@ -0,0 +1,187 @@
+// Obtaining the host runtime's raw-socket factory.
+//
+// Every layer above this one takes `connect` as an argument, and that is deliberate: it is what
+// keeps src/ free of runtime-specific imports and what makes every protocol path testable over an
+// in-memory pipe. This module does not weaken that. It answers a narrower question that callers
+// kept answering badly by hand:
+//
+//   given a runtime whose socket factory lives behind a module specifier, produce a validated
+//   ConnectFn, or fail with an error that says what was tried.
+//
+// Two rules shape the design.
+//
+//  1. The specifier is DATA, supplied by the caller. No module name is baked in here, because a
+//     name baked in is behaviour conditioned on one vendor's runtime, and this package is not
+//     allowed to have any. The host application knows which runtime it is running on; this module
+//     does not need to guess, and a wrong guess is worse than an argument.
+//
+//  2. The import is dynamic and its failure is caught. A static import of a specifier that only
+//     resolves on one runtime makes this module unloadable everywhere else, which would take the
+//     whole package down with it on every other platform.
+//
+// A BUNDLER CAVEAT that matters more than it looks. The default importer calls `import(spec)` with
+// a variable. Bundlers cannot see through a variable specifier, so they will not include the
+// target module in the output, and on a bundled deployment the import fails at runtime even though
+// the module exists. Where a bundler is in play — which on edge runtimes is nearly always — pass
+// the socket factory straight in as `connect`, or pass an `importModule` that closes over a
+// LITERAL specifier the bundler can see:
+//
+//   resolveConnect({ importModule: () => import('some:sockets') })
+//
+// That is why `connect` is checked first and short-circuits without importing anything: direct
+// injection is the recommended path, and the specifier list is the convenience, not the contract.
+
+import { ConfigError, codes } from './errors.js';
+
+/** @typedef {import('./proxy/index.js').ConnectFn} ConnectFn */
+/** @typedef {import('./proxy/index.js').Duplex} Duplex */
+
+/**
+ * @typedef {object} ResolveConnectOptions
+ * @property {ConnectFn} [connect] an already-obtained socket factory. Checked first and returned
+ *   as-is, so the recommended path costs no import and cannot be defeated by a bundler.
+ * @property {string[]} [specifiers] module specifiers to try, in order. The first module whose
+ *   `exportName` is callable wins.
+ * @property {(specifier: string) => Promise<object>} [importModule] the importer. Defaults to a
+ *   dynamic `import()`; override it to hand the bundler a literal specifier.
+ * @property {string} [exportName] the export to read off each module. Default 'connect'.
+ */
+
+/**
+ * Is `value` shaped like a socket factory? Only callability can be checked without dialling, so
+ * that is what this checks — the duplex contract is enforced when a socket is actually opened.
+ * @param {unknown} value
+ * @returns {value is ConnectFn}
+ */
+export function isConnectFn(value) {
+  return typeof value === 'function';
+}
+
+/**
+ * Resolve a ConnectFn from an injected factory or from the first module specifier that yields one.
+ *
+ * Resolution order, and nothing else is consulted:
+ *   1. `options.connect`, when callable.
+ *   2. each entry of `options.specifiers`, in order.
+ *
+ * Throws ConfigError (CONFIG_UNSATISFIABLE) when nothing resolves, listing every specifier tried
+ * with the reason it failed. A socket factory that cannot be found is a deployment mistake, and a
+ * deployment mistake deserves to name the thing that was missing rather than surface later as
+ * "connect is not a function" from inside the TLS layer.
+ *
+ * @param {ResolveConnectOptions} [options]
+ * @returns {Promise<ConnectFn>}
+ */
+export async function resolveConnect(options = {}) {
+  const { connect, specifiers = [], importModule = defaultImport, exportName = 'connect' } = options;
+
+  if (connect !== undefined && connect !== null) {
+    if (!isConnectFn(connect)) {
+      throw new ConfigError(
+        codes.CONFIG_INVALID,
+        `connect must be a function returning { readable, writable, opened?, close? }, got ` +
+          `${describe(connect)}`,
+      );
+    }
+    return connect;
+  }
+
+  if (!Array.isArray(specifiers)) {
+    throw new ConfigError(codes.CONFIG_INVALID, 'specifiers must be an array of module specifiers');
+  }
+  if (typeof importModule !== 'function') {
+    throw new ConfigError(codes.CONFIG_INVALID, 'importModule must be a function');
+  }
+
+  /** @type {string[]} */
+  const tried = [];
+  for (const specifier of specifiers) {
+    if (typeof specifier !== 'string' || specifier === '') {
+      throw new ConfigError(
+        codes.CONFIG_INVALID,
+        `specifiers must be non-empty strings, got ${describe(specifier)}`,
+      );
+    }
+    let mod;
+    try {
+      mod = await importModule(specifier);
+    } catch (cause) {
+      // Not resolvable on this runtime, which for a portable specifier list is the expected
+      // outcome for every entry but one. Recorded, not thrown.
+      tried.push(`${specifier}: not importable (${cause?.message ?? cause})`);
+      continue;
+    }
+    const candidate = mod?.[exportName] ?? mod?.default?.[exportName];
+    if (isConnectFn(candidate)) return candidate;
+    tried.push(`${specifier}: imported, but has no callable "${exportName}" export`);
+  }
+
+  throw new ConfigError(
+    codes.CONFIG_UNSATISFIABLE,
+    'no socket factory could be resolved. Supply `connect` directly — the raw-TCP socket factory ' +
+      'of the host runtime, returning { readable, writable, opened?, close? } — or name a module ' +
+      'that exports one. ' +
+      (tried.length ? `Tried:\n  ${tried.join('\n  ')}` : 'No specifiers were given.'),
+    { tried },
+  );
+}
+
+/**
+ * Flatten a runtime socket into a plain duplex object.
+ *
+ * Worth its own function because of a trap that has already cost this package a bug: on the edge
+ * runtime a socket's `readable` and `writable` are ACCESSORS ON THE PROTOTYPE, so `{ ...socket }`
+ * copies neither and the first read fails far away, inside the TLS layer, with "Cannot read
+ * properties of undefined (reading 'getReader')". Reading the properties explicitly — which is
+ * what this does — is the only spread-safe way to hand a host socket to code that may copy it.
+ *
+ * @param {Duplex} socket
+ * @returns {Duplex}
+ */
+export function normaliseSocket(socket) {
+  if (!socket || typeof socket !== 'object') {
+    throw new ConfigError(
+      codes.CONFIG_INVALID,
+      `connect must return a socket object, got ${describe(socket)}`,
+    );
+  }
+  const { readable, writable } = socket;
+  if (!readable || typeof readable.getReader !== 'function') {
+    throw new ConfigError(codes.CONFIG_INVALID, 'socket has no ReadableStream `readable`');
+  }
+  if (!writable || typeof writable.getWriter !== 'function') {
+    throw new ConfigError(codes.CONFIG_INVALID, 'socket has no WritableStream `writable`');
+  }
+  return {
+    readable,
+    writable,
+    opened: socket.opened,
+    close: () => socket.close?.(),
+  };
+}
+
+/**
+ * Wrap a ConnectFn so every socket it returns is flattened by normaliseSocket. Useful when the
+ * factory comes from a runtime whose sockets are host objects rather than plain records.
+ * @param {ConnectFn} connect
+ * @returns {ConnectFn}
+ */
+export function normalisingConnect(connect) {
+  if (!isConnectFn(connect)) {
+    throw new ConfigError(codes.CONFIG_INVALID, `connect must be a function, got ${describe(connect)}`);
+  }
+  return (addr, opts) => normaliseSocket(connect(addr, opts));
+}
+
+/** The default importer: a dynamic import a bundler cannot see through. See the header caveat. */
+function defaultImport(specifier) {
+  return import(specifier);
+}
+
+/** A short, safe rendering of a bad argument for an error message. */
+function describe(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  const t = typeof value;
+  return t === 'object' ? 'an object' : t === 'string' ? JSON.stringify(value) : t;
+}

package/src/index.js

@@ -16,6 +16,7 @@ export { warmup } from './warmup.js';
 export { ConnectionPool, poolKey } from './pool.js';
 export { openConnection, targetFromUrl, nativeFetchCanServe } from './transport.js';
 export { openTunnel, parseProxy } from './proxy/index.js';
+export { resolveConnect, isConnectFn, normaliseSocket, normalisingConnect } from './connect.js';
 export { CookieJar } from './client/cookies.js';
 export { verifyChain, rootStoreProvenance } from './trust/index.js';
 

package/src/proxy/http-connect.js

@@ -13,6 +13,7 @@
 
 import { ProxyError, LimitError, codes } from '../errors.js';
 import { ByteReader, ByteWriter, latin1, utf8 } from '../util/bytes.js';
+import { tunnelReadable } from './tunnel.js';
 
 const CRLFCRLF = utf8('\r\n\r\n');
 const MAX_REPLY_HEADER = 32 * 1024;
@@ -194,16 +195,7 @@ function replyError(reply, proxy, target, where) {
  */
 function tunnelFrom(socket, reader) {
   return {
-    readable: new ReadableStream({
-      async pull(controller) {
-        const chunk = await reader.readSome();
-        if (chunk === null) controller.close();
-        else controller.enqueue(chunk);
-      },
-      cancel(reason) {
-        return reader.cancel(reason);
-      },
-    }),
+    readable: tunnelReadable(socket, reader),
     writable: socket.writable,
     opened: socket.opened,
     close: () => socket.close?.(),

package/src/proxy/socks5.js

@@ -14,6 +14,7 @@
 
 import { ProxyError, ConfigError, codes, hex8 } from '../errors.js';
 import { ByteReader, ByteWriter, concat, utf8 } from '../util/bytes.js';
+import { tunnelReadable } from './tunnel.js';
 
 const VERSION = 0x05;
 const AUTH_VERSION = 0x01;
@@ -326,16 +327,7 @@ async function readExactly(reader, n, what, where) {
 /** Bytes that arrived alongside the reply are tunnel payload; the buffered reader carries them. */
 function tunnelFrom(socket, reader) {
   return {
-    readable: new ReadableStream({
-      async pull(controller) {
-        const chunk = await reader.readSome();
-        if (chunk === null) controller.close();
-        else controller.enqueue(chunk);
-      },
-      cancel(reason) {
-        return reader.cancel(reason);
-      },
-    }),
+    readable: tunnelReadable(socket, reader),
     writable: socket.writable,
     opened: socket.opened,
     close: () => socket.close?.(),

package/src/proxy/tunnel.js

@@ -0,0 +1,110 @@
+// The tunnel's readable half, and why it has to be a byte stream.
+//
+// Both dialects finish their handshake holding a buffered reader that may already carry tunnel
+// payload: an HTTP CONNECT reply is read up to its blank line and a SOCKS5 reply to its fixed
+// length, and in both cases the peer is free to have sent application bytes immediately behind it.
+// Those bytes must be delivered first and in order, which is why the socket cannot simply be
+// handed onward.
+//
+// What this replaces was `new ReadableStream({ pull })` — correct, and a plain stream rather than a
+// byte stream. That distinction is invisible until you look at what reads it. The TLS record layer
+// asks for a BYOB reader and quietly falls back to a default one when it cannot have it, so every
+// connection through a proxy lost BYOB reads, and with them `tls.pullBytes`, whose entire job is to
+// decide how much of the socket arrives per boundary crossing.
+//
+// Measured on the edge against one origin, 4 MB, differenced at a single request:
+//
+//     direct     132 socket reads, 31.8 KB average fill
+//     proxied    484 socket reads,  8.7 KB average fill
+//
+// and the knob itself, 1 MB through the record layer, n=15 in one isolate:
+//
+//                       pullBytes 16 KiB     pullBytes 1 MiB
+//     direct            min 25  p50 31       min 73  p50 90     <- 2.9x, the knob works
+//     proxied           min 95  p50 111      min 101 p50 121    <- 6%, the knob is not read
+//
+// So the U-curve recorded against "a real proxied socket" in util/bytes.js was four samples of one
+// configuration. The knob was never reaching the code on that path.
+//
+// The fix is not to copy harder. Once the handshake's leftovers are drained this hands the caller's
+// own view straight to the socket, so a read through a tunnel costs exactly what a read without one
+// costs — no wrapper copy, and the same coalescing.
+
+import { ByteReader } from '../util/bytes.js';
+
+/**
+ * View size handed to a *default* reader of this stream. BYOB readers supply their own view and
+ * never see this; it exists so that a caller which does not do BYOB still gets socket-sized chunks
+ * rather than whatever the transport felt like emitting.
+ */
+const TUNNEL_CHUNK = 65536;
+
+/**
+ * Wrap a proxy handshake's buffered reader plus its socket as one byte stream.
+ *
+ * @param {{ readable: ReadableStream<Uint8Array> }} socket the raw transport
+ * @param {import('../util/bytes.js').ByteReader} reader the handshake's reader, possibly holding
+ *   bytes that belong to the tunnel
+ * @returns {ReadableStream<Uint8Array>}
+ */
+export function tunnelReadable(socket, reader) {
+  /** Taken once `reader` runs dry, after which every read goes straight to the socket. */
+  let direct = null;
+  /** Buffered stand-in for `reader` when the socket turns out not to be a byte stream. */
+  let buffered = reader;
+  let promoted = false;
+
+  // Whether a stream is BYOB-capable can only be discovered by asking it for a BYOB reader, and it
+  // cannot be asked while the handshake's reader holds the lock. So: release (safe only because
+  // the guard below proves nothing is buffered), ask, and on refusal re-take a buffered reader —
+  // which is exactly the shape that was here before, for transports that cannot do better. Every
+  // in-process stream in this package's tests is one of those, so this path is well covered.
+  const promote = () => {
+    if (promoted || buffered.buffered > 0 || buffered.atEof) return;
+    promoted = true;
+    buffered.releaseLock();
+    try {
+      direct = socket.readable.getReader({ mode: 'byob' });
+    } catch {
+      buffered = new ByteReader(socket.readable);
+    }
+  };
+
+  return new ReadableStream({
+    type: 'bytes',
+    autoAllocateChunkSize: TUNNEL_CHUNK,
+    async pull(controller) {
+      // autoAllocateChunkSize guarantees a byobRequest even for a default reader, so there is one
+      // path here rather than two.
+      const req = controller.byobRequest;
+      const view = req.view;
+      promote();
+      if (direct) {
+        const { value, done } = await direct.read(
+          new Uint8Array(view.buffer, view.byteOffset, view.byteLength),
+        );
+        if (done) {
+          // Close first: a BYOB request may only be answered with zero bytes once the stream is
+          // closed, and the read has detached the original view, so the answer has to be the
+          // zero-length view the reader handed back rather than a plain respond(0).
+          controller.close();
+          req.respondWithNewView(value ?? new Uint8Array(0));
+          return;
+        }
+        req.respondWithNewView(value);
+        return;
+      }
+      const chunk = await buffered.readSome(view.byteLength);
+      if (chunk === null) {
+        controller.close();
+        req.respond(0);
+        return;
+      }
+      new Uint8Array(view.buffer, view.byteOffset, view.byteLength).set(chunk);
+      req.respond(chunk.byteLength);
+    },
+    cancel(reason) {
+      return direct ? direct.cancel(reason) : buffered.cancel(reason);
+    },
+  });
+}

package/src/util/bytes.js

@@ -15,16 +15,29 @@ const EMPTY = new Uint8Array(0);
  * so a large view never delays delivery; it only lets bytes the transport has already buffered
  * arrive in one crossing instead of many.
  */
-// Swept on the edge against a real proxied socket, ms of CPU per 4 MB body at the record layer:
+// Swept on the edge, ms of CPU for a 1 MB body at the record layer, p50 of n>=7 in one isolate,
+// each column an independent path against the same origin:
 //
-//     16 KiB  42.0     64 KiB  38.5     256 KiB  46.5     1 MiB  57.0
+//                    8 KiB   16 KiB   32 KiB   64 KiB   256 KiB
+//     direct           21      20       18       22        40
+//     proxy A          51      61       61       89       152
+//     proxy B          68      74        -      102         -
 //
-// A U with its floor on the current value, and going LARGER is worse — 1 MiB costs 48% more than
-// the default, because allocating the view outgrows the boundary crossings it saves. Recorded so
-// the next person to reach for this knob does not have to re-run the sweep to find there is nothing
-// in it: the 42 ms this layer costs on a 4 MB body is the price of moving bytes off a real socket,
-// of which the AEAD is under 2 ms. It is not a tuning problem.
-const BYOB_PULL_BYTES = 65536;
+// Monotonic on both proxies, and shallow on the direct path: too LARGE is what costs, because a
+// BYOB read resolves the instant any byte exists and never waits to fill, so a view bigger than
+// what the transport hands over per read is allocation that is never used. Average fill measured
+// over a 4 MB body: 37 KB direct, 8 KB through a proxy — which is why the two paths want different
+// numbers and why the proxied one wants a small one.
+//
+// 16 KiB is within ~20% of the best figure on all three paths; the 64 KiB that used to sit here is
+// up to 45% off. It is also exactly one TLS record, which is the unit the caller above asks for.
+//
+// The previous value came from a sweep captioned "against a real proxied socket" that reported a
+// clean U with its floor at 64 KiB. That sweep measured nothing: openTunnel wrapped the socket in a
+// plain ReadableStream, so the record layer could not take a BYOB reader on any proxied connection
+// and this constant was never read on that path. The four numbers were four samples of one
+// configuration. See proxy/tunnel.js, which is where that was fixed.
+const BYOB_PULL_BYTES = 16384;
 
 /** Raised when the peer stops sending in the middle of a structure we must read whole. */
 export class UnexpectedEofError extends TunnelFetchError {
@@ -50,21 +63,25 @@ export class UnexpectedEofError extends TunnelFetchError {
  * be retained beyond the caller's immediate use if memory matters.
  *
  * When the source is a byte stream — on the target runtime, a socket's readable is one — the
- * reader pulls with BYOB reads into large fresh views instead of taking the source's own
- * chunking. This is measured, not stylistic: the runtime delivers socket data in chunks of at
- * most 4096 bytes, ~1200 of them for a 4 MB body, and every chunk is a runtime/JS boundary
- * crossing; a BYOB read hands over everything the transport has buffered (up to the view size)
- * in one crossing, and resolves with a partial fill the instant anything at all is available,
- * so delivery latency is unchanged. Sources that are not byte streams (every in-process
+ * reader pulls with BYOB reads instead of taking the source's own chunking. This is measured, not
+ * stylistic: the runtime delivers socket data in chunks of at most 4096 bytes, ~1200 of them for a
+ * 4 MB body, and every chunk is a runtime/JS boundary crossing; a BYOB read collects several of
+ * them into one.
+ *
+ * How MANY it collects is the transport's decision, not the view's. A BYOB read resolves the
+ * instant any byte is available and never waits to fill, so the view is a ceiling that is normally
+ * not reached: measured over a 4 MB body, 37 KB average fill on a direct socket and 8 KB through a
+ * proxy, whatever the view size. Sizing the view far above that buys nothing and costs the
+ * allocation — see BYOB_PULL_BYTES. Sources that are not byte streams (every in-process
  * ReadableStream in this package and its tests) take the default-reader path unchanged.
  */
 export class ByteReader {
   /**
    * @param {ReadableStream<Uint8Array>} readable
-   * @param {number} [pullBytes] size of each BYOB view pulled from the source. Tunable because it
-   *   decides how many times a body crosses the runtime boundary on the way in, and that turned out
-   *   to be the largest single cost in a large response — 42 ms of a 106 ms 4 MB request is socket
-   *   reads and record decryption, of which the AEAD itself is under 2 ms.
+   * @param {number} [pullBytes] size of each BYOB view pulled from the source. Tunable because the
+   *   right value depends on how much the transport hands over per read, and that differs by a
+   *   factor of four between a direct socket and a proxied one — see BYOB_PULL_BYTES for the sweep.
+   *   Ignored on sources that are not byte streams, which take the default-reader path.
    */
   constructor(readable, pullBytes = BYOB_PULL_BYTES) {
     this._pullBytes = pullBytes > 0 ? pullBytes : BYOB_PULL_BYTES;