tunnelfetch 1.11.0 → 1.13.0

package/README.md

@@ -149,6 +149,42 @@ Two related rules of §5.7 are **not** implemented, and are worth knowing if you
 security: "Leave Secure Cookies Alone" (step 16), so a plain-named `Secure` cookie set over https
 can still be overwritten from http, and the 4096-octet name-plus-value cap (step 4).
 
+### Obtaining the socket factory
+
+`connect` is an argument rather than an import on purpose: it is the one piece this package cannot
+supply itself, and taking it from the caller is what keeps every layer above it testable over an
+in-memory pipe. Resolve one robustly:
+
+```js
+import { resolveConnect } from 'tunnelfetch';
+
+const connect = await resolveConnect({
+  specifiers: ['cloudflare:sockets'],
+});
+const client = new Client({ connect, proxy: env.PROXY_URL });
+```
+
+The first specifier that yields a callable export wins, and a total failure names every specifier
+tried and why it failed — the mistake surfaces at startup, not as "connect is not a function" from
+inside the TLS layer. Two traps are closed on the way:
+
+1. The import is dynamic and its failure is caught. A specifier that only resolves on one runtime,
+   imported statically, makes the whole package unloadable everywhere else; a portable list naming
+   several runtimes is safe.
+2. Bundlers cannot see through a variable specifier. On a bundled deploy pass `connect` straight
+   in, or hand `resolveConnect` an `importModule` that closes over a literal the bundler can see:
+
+   ```js
+   const connect = await resolveConnect({
+     importModule: () => import('cloudflare:sockets'),
+   });
+   ```
+
+`normaliseSocket` flattens one runtime socket into a plain duplex, and `normalisingConnect` wraps a
+factory so every socket it returns is flattened. They exist because on the edge runtime a socket's
+`readable` and `writable` are prototype accessors, so `{ ...socket }` copies neither and the first
+read fails far away, inside the TLS layer, with a complaint about `getReader`.
+
 ### Replacing the global
 
 For libraries that only ever call the bare global:
@@ -783,29 +819,41 @@ the network, which is not billed.
 
 ### What a request costs
 
-Fetching a size-controlled origin through a proxy, warm, medians over seven-plus rounds on one
-isolate, gzip on the wire. The last column is the same numbers as a rate, which is the form worth
-carrying around:
+Fetching `sizeorigin/` through a proxy, gzip on the wire, medians of n>=5 with every size in one
+sweep and one isolate. The method is stated because the last version of this table did not state
+one precisely enough to reproduce: **a warm page is `(reuse=4 - reuse=1) / 3`**, the cost of pages
+two through four down a connection that is already open, and the last column is the fresh-connection
+number the same sweep produced.
 
-| Body | Per request, reusing a connection | Per decompressed MB |
-| --- | --- | --- |
-| 1 KB | **0.5 ms** | — |
-| 16 KB | **3.5 ms** | 224 ms/MB |
-| 64 KB | **7.5 ms** | 120 ms/MB |
-| 256 KB | **20.5 ms** | 82 ms/MB |
-| 1 MB | **51.5 ms** | 51 ms/MB |
-| 4 MB | **104 ms** | 26 ms/MB |
-
-Opening a connection adds **7–12 ms** on top, once, however many requests follow it.
-
-**Read the per-MB column before doing any arithmetic with this table.** It falls 8.6x from end to
-end, so there is no such thing as a per-MB rate for this package. A least-squares line through these
-points is `9.17 + 24.86 x MB`, which predicts 9.17 ms for a 1 KB body against a measured 0.5 — wrong
-by 18x. Any budget built on a single per-MB figure will be badly wrong at one end or the other.
+| Body | Warm page | Per decompressed MB | First request on a new connection |
+| --- | --- | --- | --- |
+| 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 |
+
+The last column is not "warm page plus a handshake". At 4 MB it is 33 ms above the warm page while a
+handshake costs single digits, because the *first* body through a connection also runs the decode
+loop before V8 has tiered it up. Budget a new origin at that column, not at the first one.
+
+**Re-measured August 2026, and the mid-sizes moved.** The 4 MB row reproduced almost exactly
+(102 against a previously published 104); 64 KB through 1 MB came in 20-30% lower than the figures
+this table used to carry. That is not the socket-view change two sections below — A/B-ing the old
+and new view size in one isolate moved a warm 1 MB page by about 1 ms — so it is either day-to-day
+variance beyond what a single sweep can see, or a difference in how the superseded table was taken.
+The old numbers are not recoverable to check, which is the argument for stating the method here.
+
+**Read the per-MB column before doing any arithmetic with this table.** It falls 5.7x from end to
+end, so there is no such thing as a per-MB rate for this package. A least-squares line through the
+16 KB and larger points is `6.30 + 24.30 x MB`, which predicts 6.33 ms for a 1 KB body against a
+measured 1.3 — wrong by 4.9x. Any budget built on a single per-MB figure will be wrong at one end
+or the other.
 
 The reason is that V8 tiers up **inside a single request**. A 1 MB body runs the decode loop
-interpreted the whole way; a 4 MB body pays that for its first megabyte and runs the rest optimised.
-`51.5 + 3 x 17.5 = 104` fits, so the steady-state cost is about **17.5 ms/MB with a ~51 ms entry fee
+interpreted for much of its length; a 4 MB body pays that once and runs the rest optimised.
+`36.3 + 3 x 21.9 = 102` fits, so the steady-state cost is about **22 ms/MB with a ~36 ms entry fee
 per request**. For a size not in the table, interpolate within it rather than extrapolating from a
 rate.
 
@@ -824,11 +872,6 @@ of excess the *whole* ramp contains. These were measured on a small body; a cold
 4 MB request has never been measured and is certainly worse, since far more of the decode loop runs
 interpreted.
 
-Measured through a proxy against a size-controlled origin, eight rounds per size, HTTP/2, gzip on
-the wire. Connection and per-request terms were separated by varying the reuse count rather than
-assumed — two pages against ten gives **9.8 ms to open a connection** and **2.25 ms per further
-request**, and the body cost is what is left.
-
 **These figures replace ones that were measured wrong, and the mistake is worth describing.** The
 origin they came from tiled a 150-byte HTML fragment, which gzip compressed **220:1** — so a "1 MB
 body" was four kilobytes on the wire, and every measurement taken against it priced decompression
@@ -840,19 +883,21 @@ The correction is large. Body-heavy rows are **two to three times** what this ta
 1.4.0, and no amount of care about medians or minimums would have caught it, because the numbers
 were internally consistent — they were answers to the wrong question.
 
-**Read the two right-hand columns as derived, because they are.** Only the pooled column is measured
-per size; "new connection" is the pooled figure plus a flat 7.5 ms and "averaged over 5 pages" is
-the pooled figure plus 1.5 ms, which is why the deltas are identical to one decimal across a 4000×
-range in body size. That 7.5 ms also does not agree with the 9.8 ms quoted just above it, and the
-2.25 ms per further request is larger than the entire 1.7 ms a pooled 1 KB request costs, which
-would make a 1 KB body cost negative. The two came from different sweeps, and combining them is the
-cross-sweep comparison this document tells you never to make. **Treat the connection term as
-somewhere in 7–10 ms and do not do arithmetic with it.**
+That correction is the reason the table above now measures its fresh-connection column instead of
+deriving one. Through 1.11.0 that column was the warm figure plus a flat 7.5 ms and a third column
+was the warm figure plus 1.5 ms, which is why their deltas were identical to one decimal across a
+4000x range in body size — a derived column cannot disagree with its source, so it cannot check it
+either. Both are gone.
+
+The connection term that falls out of the current sweep is **6–7 ms** (1 KB fresh 8 ms against a
+1.3 ms warm page), consistent with the 7–10 ms this section used to advise treating it as, and still
+not something to do arithmetic with: at 4 MB the gap between fresh and warm is 33 ms, and most of
+that is V8 tiering rather than the handshake.
 
-An independent check was quoted here as agreement and is not: a real 3.6 MB file from a CDN cost
-142 ms against the ~120 ms this table predicts for 4 MB. That is the model under-predicting by
-roughly 20%, in the same direction as the error it had just replaced. It belongs here as a caution,
-not as corroboration.
+An independent check was once quoted here as agreement and is not: a real 3.6 MB file from a CDN
+cost 142 ms where the model predicts about 94 ms. It was taken in a different sweep against a
+different origin, so it does not refute the table either — it belongs here as a reminder that a
+single cross-sweep reading cannot confirm or deny anything in this document.
 
 Two further cautions. The 2.76:1 content is slightly *less* compressible than a typical page, so
 these are mildly conservative rather than optimistic. And CPU on this platform varies by up to ~1.5×
@@ -875,6 +920,11 @@ the edge the same way as the rest — differencing two work counts, minimum of s
 | `decoders: { zstd }` | **+2.8 ms/MB** (5.5 against 2.75) | per byte, whenever an origin serves zstd |
 | `profile: chrome` via `tunnelfetch/profile/chrome` | **+3 ms once per isolate** for four WASM modules, then the per-byte rows above as origins use them | |
 
+**The socket read view moved in 1.12.0**, from 64 KiB to 16 KiB, alongside the proxy tunnel becoming
+a byte stream. No API changed and `tls.pullBytes` still overrides it — but on a proxied connection
+that override did nothing before 1.12.0, so anyone who had tuned it was tuning a value nothing read.
+Both are covered below.
+
 Two defaults moved in 1.4.0 and neither is visible in the table above them: matching curl's cipher
 order means AES-256-GCM is negotiated where AES-128-GCM used to be, measured at **+4%** per MB
 (1.50 against 1.45 ms/MB — hardware AES makes the extra rounds cheap), and the ordered header list
@@ -892,19 +942,29 @@ the measurements above, with the charge split out so it is clear what is yours t
 
 | Workload | CPU/request | 10M/mo | 1B/mo |
 | --- | --- | --- | --- |
-| Platform `fetch`, 16 KB — reference; it cannot use a proxy | 0.3 ms | $8.06 | $311.00 |
-| Platform `fetch`, 4 MB — same reference, measured | 3.2 ms | $8.64 | $369.00 |
-| Pooled connection, 16 KB pages | 3.5 ms | $8.70 | $375.00 |
-| New connection per request, 16 KB | 13.5 ms | $10.70 | $575.00 |
-| Pooled connection, 1 MB pages | 51.5 ms | $18.30 | $1,335.00 |
-| New connection per request, 1 MB | 61.5 ms | $20.30 | $1,535.00 |
-| Pooled connection, 4 MB pages | 104 ms | $28.80 | $2,385.00 |
-| New connection per request, 4 MB | 114 ms | $30.80 | $2,585.00 |
-
-These follow the CPU table above and nothing else. An earlier version of this section was computed
-from a superseded set of measurements and was left behind when that table was replaced, so the
-document quoted 118.3 ms and 104 ms for the same row in two places. Any figure here that does not
-fall out of the table above is a bug in this README.
+| Platform `fetch`, 16 KB — reference; it cannot use a proxy | 0.3 ms | $5.00 | $307.40 |
+| Platform `fetch`, 4 MB — same reference, measured | 3.2 ms | $5.04 | $365.40 |
+| Pooled connection, 16 KB pages | 2.3 ms | $5.00 | $347.40 |
+| New connection per request, 16 KB | 9 ms | $6.20 | $481.40 |
+| Pooled connection, 1 MB pages | 36.3 ms | $11.66 | $1,027.40 |
+| New connection per request, 1 MB | 59 ms | $16.20 | $1,481.40 |
+| Pooled connection, 4 MB pages | 102 ms | $24.80 | $2,341.40 |
+| New connection per request, 4 MB | 135 ms | $31.40 | $3,001.40 |
+| Pooled 4 MB, `maxBodyBytes: Infinity` | 70 ms | $18.40 | $1,701.40 |
+
+The last row is the same workload with the decompression-bomb guard off, measured in its own sweep;
+it is the largest configuration-level saving in this document and it is the caller taking
+responsibility for bounding the body themselves. See "Passing the body through" below.
+
+`$5 + max(0, requests - 10M) x $0.30/M + max(0, cpu_ms - 30M) x $0.02/M`, and nothing else. The
+CPU column is the warm-page and fresh-connection columns of the table above; any figure here that
+does not fall out of that table is a bug in this README.
+
+**The `max(0, ...)` is new.** The previous version of this table billed every request and every
+CPU millisecond, ignoring the allowance the sentence above it describes — so it overstated the
+10M/mo column by up to 74% ($8.70 where the bill is $5.00) while being within 0.2% at 1B, where
+the allowance is a rounding error. The overstatement was against this package, not for it, which
+is presumably why it survived several readings.
 
 The reference row is given at two sizes because the platform's own `fetch` is **not flat** — it
 scales at about 0.82 ms per decompressed MB, measured on a size ladder from one CDN so that only the
@@ -929,12 +989,17 @@ pooled 1 MB workload at a billion requests a month, warmed:
 
 | Change from the baseline | CPU/request | 1B/mo | Δ | Paid when |
 | --- | --- | --- | --- | --- |
-| baseline — gzip, AES-256-GCM, x25519 | 51.5 ms | $1,335 | — | always |
-| origin serves `br` instead of gzip | 55.8 ms | $1,421 | **+$86** | the origin chooses `br` |
-| server selects ChaCha20-Poly1305 | 54.5 ms | $1,395 | **+$60** | the server picks it over AES |
-| origin serves `zstd` instead of gzip | 54.3 ms | $1,391 | **+$56** | the origin chooses `zstd` |
-| X25519MLKEM768, 1 request per connection | 59.2 ms | $1,489 | **+$154** | every handshake |
-| X25519MLKEM768, 20 requests per connection | 51.5 ms | $1,335 | **+$0.15** | the same handshake, amortised |
+| baseline — gzip, AES-256-GCM, x25519, warm | 36.3 ms | $1,027 | — | always |
+| origin serves `br` instead of gzip | 40.5 ms | $1,111 | **+$84** | the origin chooses `br` |
+| server selects ChaCha20-Poly1305 | 39.3 ms | $1,086 | **+$59** | the server picks it over AES |
+| origin serves `zstd` instead of gzip | 39.1 ms | $1,083 | **+$56** | the origin chooses `zstd` |
+| X25519MLKEM768, 1 request per connection | 59.2 ms | $1,484 | **+$3** | every handshake |
+| X25519MLKEM768, 20 requests per connection | 36.3 ms | $1,028 | **+$0.15** | the same handshake, amortised |
+
+The ML-KEM rows are measured against the **fresh-connection** 1 MB baseline of 59 ms ($1,481), not
+against the warm one at the top; the Δ column reflects that, which is why it is $3 rather than the
+$154 an earlier version showed. That $154 was the cost of not pooling, attributed to post-quantum
+key exchange.
 
 The last two rows are the same 0.15 ms of ML-KEM, and the difference between them is entirely
 connection reuse — which is the point worth taking from this table. Post-quantum key exchange is
@@ -1020,7 +1085,7 @@ below roughly the size where a single wire read covers the whole body.
 roughly a tenth of the CPU. This package exists because a V8 isolate cannot do that; it is not a
 better way to do it.
 
-The arithmetic is worth being blunt about. A billion 4 MB requests a month costs about **$2,385** of
+The arithmetic is worth being blunt about. A billion 4 MB requests a month costs about **$2,341** of
 Workers CPU. That workload is roughly 386 requests a second and 4.5 Gbps sustained — **three
 dedicated boxes** at Hetzner-class pricing carry it for around **$600**. So for large bodies, buying
 servers is about **four times cheaper**, and the gap widens with body size.
@@ -1075,7 +1140,8 @@ billed native floor.
 The remaining ~30× is the JS-orchestrated record layer, HTTP/2 demultiplexing and stream pipeline —
 roughly **80% of the per-request cost at 4 MB, against 20% for decode**. An earlier version of this
 section put the emphasis on decoding; that was wrong, and it sent optimisation effort at the smaller
-of the two.
+of the two. For which of those three layers the 80% belongs to, see "Which layer the receive path
+actually spends its megabyte on" below — the answer is not the record layer.
 
 What would close it is a primitive that does not exist: a `startTls` that verifies the **origin**
 hostname rather than the `connect()` peer, which would let the platform's own `fetch` run inside the
@@ -1087,9 +1153,12 @@ The runtime's `DecompressionStream` emits 4096-byte chunks and its sockets deliv
 most 4096 bytes, and every chunk that crosses between the runtime and JS costs tens of
 microseconds regardless of size — measured here at about **17 µs per crossing**, from a ladder
 that collects the same 1 MB in 4 KiB chunks (6.0 ms/MB) through 256 KiB chunks (1.67 ms/MB).
-Both hot paths therefore drain their sources with BYOB reads, which hand over everything already
-buffered in one crossing and resolve partially filled the moment any byte exists, so streaming
-latency is unchanged.
+Both hot paths therefore drain their sources with BYOB reads, which collect several of those
+chunks into one crossing and resolve partially filled the moment any byte exists, so streaming
+latency is unchanged. How many they collect is the transport's decision and not the view's — a
+BYOB read never waits to fill — so a view sized far above what the transport actually hands over
+buys nothing and costs the allocation. Measured over a 4 MB body: **37 KB average fill on a direct
+socket, 8 KB through a proxy**.
 
 The view they read into is **16 KiB, and the size was swept rather than assumed**. It matters more
 than it looks. The input is pumped by a JS task on the same event loop as the puller, so the
@@ -1110,14 +1179,299 @@ believed. Correcting it cut the stage **31%**, 18.0 → 12.3 ms/MB, A/B-ed in on
 
 What remains is **not** close to floor, and an earlier version of this section wrongly said it was.
 Native inflate of the same content costs 4.3 ms/MB against the stage's 12.3, so roughly **8 ms/MB
-is this package's own plumbing** — the JS input pump and the output wrapper. Closing that needs a
-redesign rather than a constant, and it is the largest single item left in the body path.
+is this package's own plumbing** — the JS input pump and the output wrapper.
+
+Most of that has since been closed by the native `IdentityTransformStream` relay, **but only for
+`maxBodyBytes: Infinity`**, and the default is 32 MiB. Re-measured on the edge, same op, same
+fixture, same isolate, differenced between a 1 MB and a 4 MB body:
+
+| `maxBodyBytes` | decode stage, ms per decoded MB |
+|---|---|
+| `Infinity` — native relay, no JS in the byte path | **4.3** |
+| 32 MiB (the default) — pull-driven JS wrapper | **7.7** |
+
+Both of those come from an isolated bench, and this document is mostly a record of isolated benches
+being wrong. This one is not: subtracting `depth=passthru` from `depth=full` on a real proxied
+request for a 4 MB body — the `Infinity` path — puts decoding at **18–29 ms**, against the 17 ms the
+4.3 figure predicts, and at 16–25% of the whole request, which is the "20% for decode" claimed
+further up. Two instruments, one answer.
+
+Priced again on a **real proxied 4 MB request** rather than on a fixture, one isolate, n=11, warm
+page as `(reuse=4 - reuse=1)/3`:
+
+| `maxBodyBytes` | warm 4 MB page | first request on a new connection |
+|---|---|---|
+| 16 MiB — the default | min 87, p50 97 ms | 147 ms |
+| `Infinity` | **min 68, p50 70 ms** | 130 ms |
+
+So the bomb guard costs **20-27 ms on a 4 MB body**, 5-7 ms per decoded megabyte — half again what
+the fixture predicted, and the largest single item left in the body path. At a billion 4 MB requests
+a month that is about **$540**. It is the one lever in this document that is available by
+configuration rather than by a release. That is not a bug — the cap is enforced by counting bytes
+and counting requires seeing them in JS — but the size of it was not known before and it is worth
+saying out loud rather than leaving inside a comment. The counting itself is free (7.00 with it,
+7.33 without); it is the wrapper the counting forces that costs. If you are relaying bodies you
+already bound some other way, `maxBodyBytes: Infinity` is worth 43% of this stage.
 
 Importing the package is free. The 121 bundled anchors are base64 strings indexed by a hash of the
 subject DN, and only the one anchor a chain lands on is ever decoded, so startup stays at ~2 ms for
 the 380 KB bundle (133 KB gzipped) and a request that imports but does not use the package costs
 0 ms.
 
+### Which layer the receive path actually spends its megabyte on
+
+Every figure above is measured **through a proxy, against a Cloudflare origin**, which is the shape
+this package exists for and also the shape that makes a per-layer answer impossible: two variables
+move at once. The `wire` ladder in `live/` removes both — one nginx origin that serves the same file
+over `http` and `https`, `Range` requests fixing the wire volume exactly, and no proxy — so the
+rungs differ by exactly one layer each.
+
+Per megabyte of **wire** (not of decompressed body), differenced between a 1 MB and a 4 MB range on
+a **single request**, so no per-request work is inside the division. Three independent sweeps, run
+hours apart:
+
+| rung | ms per wire MB | added by this layer |
+|---|---|---|
+| raw socket, BYOB reads, no TLS | 2.0 – 3.0 | — |
+| + the TLS record layer | 4.7 – 6.7 | +2.7 – 4.3 |
+| + HTTP/2 | 9.3 – 12.0 | **+4.7 – 6.0** |
+| + the `Client`, decoding off | 13.3 – 16.0 | +2.3 – 4.0 |
+
+The origin serves `.gz` files with no `Content-Encoding`, so nothing decodes on any rung and the
+decode stage is not in this table — price it separately from the section above. The top rung runs
+`maxBodyBytes: Infinity`, which also keeps the body cap out of the number.
+
+The absolute values move about 30% between sweeps, which is the run-to-run variance this document
+warns about everywhere else; what does not move is the ordering. **HTTP/2 demultiplexing was the
+largest single layer in all three sweeps** — on its own it costs about as much per wire megabyte as
+the socket and the entire TLS record layer beneath it cost together. (An earlier draft of this
+paragraph said "more than", on two sweeps. The third one does not support that, and the claim it
+does support is strong enough.)
+
+Everything else in this document points the other way — "42 ms of a 106 ms 4 MB request is socket
+reads and record decryption" is the figure the `pullBytes` sweep left behind, and it is what sent
+the last two rounds of optimisation at the record layer. That figure is not wrong for the path it
+was taken on; it just never separated the socket from the parsing, and the separation is where the
+answer was.
+
+### What the proxy costs, and what the origin costs
+
+The ladder above runs without a proxy, which is what makes it a per-layer answer and also what
+makes it unlike the shape this package is for. Run the same rungs three ways — the same nginx origin
+direct and proxied, then a Cloudflare-fronted origin through the same proxy — and the two variables
+separate. Per megabyte of wire, differenced between a 1 MB and a 4 MB body at a single request,
+p50 of n=7-8, all twelve cells in one sweep:
+
+| | socket | + the TLS record layer | total |
+|---|---|---|---|
+| nginx origin, direct | 2.3 | +7.7 | 10.0 |
+| nginx origin, **proxied** | **17.3** | +6.3 | 23.7 |
+| Cloudflare origin, **proxied** | **16.0** | +7.7 | 23.7 |
+
+**The whole proxied-versus-direct gap is the socket rung, and the origin contributes nothing.** The
+two proxied rows agree to within noise, which kills the standing hypothesis that a Cloudflare
+origin's dynamic TLS record sizing was inflating these figures — it is not the origin. And the
+record layer costs the same 6-8 ms per wire megabyte on all three paths: it does not care what is
+in front of it.
+
+The socket rung's 7x is two effects multiplying. Measured over a 4 MB body on the same build:
+
+| | reads | average fill | ms per read |
+|---|---|---|---|
+| direct | 110 | 38 KB | 85 µs |
+| proxied | 494 | 8.5 KB | 140 µs |
+
+**4.5x as many reads, each 1.6x dearer.** The fill is the proxy's relay pacing, not a view-size
+choice — `pullBytes` is already at the measured optimum for it, and raising the view does not raise
+the fill because a BYOB read never waits. There is nothing in this package to change here.
+
+This is also the number that settles the Wasm question below. A Wasm record layer can only replace
+the `+6.3 to 7.7` column, minus the 1.67 ms/MB of AEAD that stays in WebCrypto — and it cannot touch
+the 16-17 ms socket rung at all, because a socket cannot write into linear memory (see below). The
+dominant term on the real path is the one Wasm has no access to.
+
+### A knob that was never connected on the path this package exists for
+
+Running the same ladder **with** a proxy turned up the reason those earlier figures were so much
+larger, and it was not the network.
+
+`openTunnel` finishes a CONNECT (or SOCKS5) handshake holding a buffered reader, because the peer
+may have sent tunnel payload in the same chunk as the reply, and it handed that onward wrapped in
+`new ReadableStream({ pull })`. Correct, and a **plain** stream rather than a byte stream. The TLS
+record layer asks for a BYOB reader and quietly falls back to a default one when it cannot have it,
+so *every proxied connection* lost BYOB reads — and with them `tls.pullBytes`, whose only job is to
+size them.
+
+Same origin, 1 MB through the record layer, n=15 in one isolate, before the fix:
+
+| | `pullBytes: 16 KiB` | `pullBytes: 1 MiB` |
+|---|---|---|
+| direct | min 25, p50 31 | min 73, p50 90 |
+| **proxied** | min 95, p50 111 | min 101, p50 121 |
+
+**2.9× on a direct socket and 6% through a proxy** — the knob was not being read. Which also means
+the sweep that chose the old 64 KiB default, captioned "against a real proxied socket", was four
+samples of one configuration; the clean U it reported was run-to-run noise.
+
+`src/proxy/tunnel.js` makes the tunnel a byte stream and, once the handshake's leftovers are
+drained, hands the caller's own view straight to the socket — so a read through a tunnel costs what
+a read without one costs. With the knob reaching the code, the sweep is worth having:
+
+| ms, 1 MB at the record layer, p50 | 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 | — |
+
+Monotonic on both proxies, shallow on the direct path, and the mechanism is the average-fill figure
+above: too *large* is what costs, because the view is a ceiling that a BYOB read never waits to
+reach. The default is now **16 KiB**, which is within ~20% of the best column on all three paths
+where 64 KiB was up to 45% off, and allocates a quarter as much.
+
+End to end through the real `Client` and a proxy, n=13, 16 KiB against the old 64 KiB: **63 against
+78 ms** for 1 MB and **145 against 164 ms** for 4 MB on the median, and within noise on the minimum
+at 4 MB. Smaller than the record-layer sweep alone suggests, because HTTP/2 and the client plumbing
+above it do not scale with the view — but nothing measured anywhere favours the old value.
+
+This is also a caution about the instrument rather than only about the code. The first attempt at
+the end-to-end A/B reported the two view sizes agreeing to the millisecond, which read as "the
+change does nothing"; the rig was not threading `pullBytes` into the `Client` rung at all, so both
+columns were the same configuration. Two columns agreeing *exactly* is not a null result, it is a
+wiring bug.
+
+The record layer's share is now small enough to break down: of the 2.7–4.3 ms/MB it adds, WebCrypto
+AES-256-GCM over 16 KiB records is **1.67 ms/MB**, so the JavaScript record parsing itself is
+somewhere around **1–3 ms/MB**. That number closes a direction rather than opening one — see below.
+
+The origin here sends 8 KiB DATA frames, so HTTP/2's share works out to roughly 35 µs per frame,
+which is the same order as the ~25–30 µs per stream-boundary crossing measured elsewhere in this
+document. It is not concentrated in any one call: coalescing queued DATA payloads into one enqueue
+was implemented and measured, and it is not the answer. See "Three optimisations that measured as
+nothing", below.
+
+**And now the open question this ladder raises, stated rather than buried.** The whole stack here —
+socket, TLS, HTTP/2, `Client` — comes to 13–16 ms per wire megabyte. The proxied figure for the
+**record layer alone** is 38.5 ms for a 4 MB body, and that body is about 1.45 MB on the wire, so
+roughly 27 ms per wire megabyte for one rung. Two to five times the whole direct-socket stack, for
+a fraction of it.
+
+Something in the proxied path costs several times what the same code costs on a direct socket, and
+the candidates have not been separated: the proxy adds a second TCP hop whose delivery pattern this
+package does not control, and the Cloudflare origin used there sizes its TLS records dynamically and
+chunks a gzip it generates on the fly. Both would raise the per-record and per-crossing counts
+without any code being slower.
+
+**Every dollar figure in this document is derived from the proxied path**, so none of them are
+invalidated by the ladder — they measure what a real request costs, which is what a bill is made of.
+But they should not be read as measuring *this package's code*, and until the proxied path is
+decomposed the same way, "where the cost is" has an answer only for the direct one. Running the
+`wire` ladder against a proxy is the missing experiment; it needs credentials the rig takes as an
+`x-proxy` header and nothing else.
+
+### Moving TLS into WebAssembly: measured, and closed
+
+The idea was to put record framing and buffer management in Wasm and leave the AEAD in JavaScript,
+where `crypto.subtle` reaches AES-NI. The ladders above bound it, and not by finding Wasm slow —
+Wasm is fast. They bound **the prize**, and separately they make **the cost mandatory**.
+
+**The prize.** Everything a Wasm record layer could replace is the JavaScript record parsing: the
+TLS rung minus its AEAD, since a software AES inside Wasm has no AES-NI to reach and would have to
+cross back to `crypto.subtle` anyway. The TLS rung measured +2.7 to 4.3 ms per wire MB in one sweep
+and +6.3 to 7.7 in another; the AEAD is 1.67. So the prize is somewhere in **1–6 ms per wire
+megabyte**, and the spread between sweeps is wider than most of it.
+
+**The cost is not optional.** A socket cannot write into linear memory: a BYOB read detaches the
+view's buffer and a `WebAssembly.Memory` buffer is non-detachable, so the read is refused —
+*"Unable to use non-detachable ArrayBuffer"*, measured on the edge on both the direct and the
+proxied path. Bytes must land in a JavaScript buffer and be copied in. That copy measured
+**2.67–4.67 ms per megabyte**.
+
+Those two ranges overlap. The exercise is somewhere between a wash and a modest win on one rung —
+in exchange for reimplementing TLS record framing in another language and re-deriving in Rust every
+byte of the ClientHello-ordering and cipher-offer work this package exists for.
+
+And it aims at the wrong rung. On the proxied path the socket alone is **16–17 ms per wire MB**,
+two to three times the entire TLS rung, and it is precisely the part the non-detachable buffer puts
+out of reach.
+
+**An earlier version of this analysis reached the opposite conclusion, and the error is worth
+naming.** It put the prize at 24–28 ms per wire MB — a sixfold win against a 4.67 ms boundary — from
+the "42 ms per 4 MB body at the record layer" figure that used to sit in `util/bytes.js`. That
+figure never separated the socket from the parsing on top of it, and it was taken on a proxied path
+where BYOB was silently disabled. Both errors inflated the denominator. The rule that killed the
+idea in the end — *a native layer wins when it replaces a JavaScript one and loses when it is added
+to one* — was stated correctly at the time; the layer being replaced was simply measured at ten
+times its size.
+
+Two things the measurements *do* settle, neither of which changes that:
+
+- The per-crossing cost does not scale with crossings at TLS granularity: splitting the same
+  transfer into 256 crossings of 16 KiB measured identically to one crossing of 4 MB. Whatever a
+  Wasm design cost, it would not be the number of times it crossed.
+- Getting a megabyte into linear memory and walking record-shaped headers over it is **cheap** — so
+  cheap that the loop building the test fixture dominates the same measurement, which is why no
+  single number for it is quoted here. Wasm is not the problem. There is just nothing on this path
+  for it to win.
+
+### Emscripten is not the problem people say it is
+
+Cloudflare's Kitesurf post warns that with "Emscripten (for example) and its many layers of mocked
+dependencies, the compiled binary can get bulky and slow", which is a claim about a toolchain and
+cheap to check. `live/wasm/build.sh` builds the same three functions three ways — all `no_std` /
+freestanding, all importing nothing, all producing bit-identical output on the same input — and then
+runs the same comparison on a **real** primitive: the exact C this package already ships as its
+ChaCha20-Poly1305, recompiled by Emscripten.
+
+| | module | record walk, 4 MB | ChaCha20-Poly1305 seal |
+|---|---|---|---|
+| C, `emcc -O3 -sSTANDALONE_WASM` | **460 B** | 8 ms | **5.00 ms/MB** |
+| Rust, `wasm32-unknown-unknown`, `no_std` | 632 B | 8 ms | — |
+| C, `clang --target=wasm32 -nostdlib` + `rust-lld` | 647 B | 8 ms | — |
+| C, wasi-sdk 25 `-nostdlib` — what ships | 8839 B | — | 5.67 ms/MB |
+| WebCrypto AES-256-GCM, for scale | — | — | 1.67 ms/MB |
+
+Emscripten produced the **smallest** module of the three, and the record walk came back at the same
+millisecond for all three — that column is not a tie broken by rounding, it is three readings that
+never separated across eight interleaved rounds. On the cipher Emscripten came out slightly ahead of
+the wasi-sdk build this package ships, which is inside the noise and not a reason to add a second
+toolchain to the build.
+
+The warning is about what you compile, not what compiles it: drag in a libc, a filesystem shim or a
+`main()` and Emscripten will emulate all of it, and the 8839-byte wasi-sdk row above is itself mostly
+libsodium rather than toolchain. But `-sSTANDALONE_WASM --no-entry` over code that calls nothing
+emits what LLVM would emit anyway. The shipped ChaCha20 stays on wasi-sdk; there is nothing here
+worth a build dependency.
+
+### Three optimisations that measured as nothing
+
+Recorded because each looked obviously right, and because what killed two of them was a counter
+disagreeing with a stopwatch. All three were implemented, measured on the edge, and reverted; none
+of them is in `src/`.
+
+**Recycling the BYOB pull buffer.** `ByteReader` allocates a fresh view for every pull, so the
+`pullBytes` U-curve's right arm is allocation, not boundary crossings. Reusing one store and copying
+the fill out removes that arm completely — at `pullBytes: 1 MiB`, 89 ms → 20 ms for 4 MB. It is also
+**a wash at the then-default 64 KiB** (21 against 23) and *worse* below it, because the copy-out
+stops paying for itself. Since the right answer turned out to be a *smaller* view rather than a
+cheaper large one (see below), making large views cheap buys nothing, and the change was dropped.
+
+**A native `pipeTo` for the decode stage's input.** The output side of `decompressionStage` already
+avoids JavaScript entirely on the uncapped path; the input side is still a JS loop reading the source
+and writing each chunk into the decompressor. Handing the source to `pipeTo` once the 2-byte deflate
+sniff is done removes that loop — and measured identically at 64 KiB and 16 KiB input chunks, ~10%
+better only at 4 KiB. Not worth the change: it moves the source's cancellation from a reader that
+can be cancelled directly to a pipe that can only be aborted through a signal, which is a real
+teardown-semantics change on the body path in exchange for nothing.
+
+**Coalescing HTTP/2 DATA payloads.** One body-stream `pull()` hands over one DATA frame, so a body
+crosses the ReadableStream boundary once per frame — 128 times per MB at this origin. Merging queued
+payloads up to 64 KiB looked like a 40% cut to the HTTP/2 rung across one sweep. It is not: the chunk
+counters came back **identical** with and without it — 512 chunks of 8192 either way — because a
+consumer that keeps up finds exactly one payload queued at every pull, so the merge never runs. Held
+open with an artificial delay so the queue could build, 8x fewer enqueues bought 0.3–1.0 ms/MB of the
+4.7–6.0 that HTTP/2 costs. The apparent win was the minimum of nine integer-millisecond samples
+moving while the median did not.
+
 ### Streaming APIs, and what they cost
 
 An SSE response from an LLM API is the opposite shape to everything else measured here: a small body
@@ -1236,7 +1590,9 @@ CI runs a fixed seed on every commit, as a gate; the scheduled workflow runs thr
 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.
+`probe/results/` the measurements this design rests on. `live/` is the edge interop rig, and
+`sizeorigin/` is the size-controlled origin the cost table is taken against — it lived outside the
+repository until August 2026, was deleted, and took the table's reproducibility with it.
 
 Credentials are read from the environment only. The live suite fails loudly when it is not
 configured rather than skipping: a green tick that means "we did not check" is worse than a red one.