tunnelfetch 1.6.5 → 1.8.0

package/README.md

@@ -716,14 +716,27 @@ Fetching a size-controlled origin through a proxy, warm, medians over seven-plus
 isolate, gzip on the wire. The last column is the same numbers as a rate, which is the form worth
 carrying around:
 
-| Body | Averaged over 5 pages | Reusing a connection | New connection |
-| --- | --- | --- | --- |
-| 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 |
+| 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.
+
+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
+per request**. For a size not in the table, interpolate within it rather than extrapolating from a
+rate.
 
 The cold-start cost is a **total**, not something to add to a row above:
 
@@ -924,6 +937,49 @@ the edge: receiving a 4 MB body **uncompressed** costs the same as receiving the
 the bytes through the entire receive pipeline. **Leave compression on.** The fixed ~2 ms only wins
 below roughly the size where a single wire read covers the whole body.
 
+### When not to use this package
+
+**If you can run Node, run Node — and then you do not need this package at all.** `undici` with a
+`ProxyAgent` does the same job over `node:tls`, which verifies whatever hostname you name, in C, at
+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
+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.
+
+Two things flip that back:
+
+* **Egress.** Workers does not bill bandwidth. If those bytes have to leave your own servers again,
+  1.45 PB/month is free on an unmetered box and about **$130,000** on AWS. Price your transfer
+  before pricing your CPU — it can dwarf everything above.
+* **Body size.** Under roughly **128 KB** the per-request cost is small enough that Workers wins on
+  price *and* gives you 300+ locations, no operations and no capacity planning. At 16 KB the same
+  billion requests is **$375**.
+
+So: small bodies at the edge is what this package is for. Large bodies through a proxy, from a
+runtime that could have used native TLS, is the case where it is the wrong tool and the bill says so.
+
+### Passing the body through instead of decoding it
+
+If you are forwarding a response rather than reading it, `decompress: 'passthrough'` asks for gzip as
+usual and hands back the **coded** bytes with their `Content-Encoding` and `Content-Length` intact,
+so the next hop can relay them:
+
+```js
+new Client({ connect, proxy, decompress: 'passthrough' });
+```
+
+Measured end to end on a 4 MB body: **118 ms decoding against 82.5 ms passing through, 30% cheaper**,
+with 2.76x fewer bytes on the wire at the same time.
+
+**This only helps if you never need the plaintext.** If you parse, extract or transform the body, the
+decode is work you owe — passthrough just moves it downstream, where you or your caller pays the same.
+It is not a general optimisation. Note also that `decompress: false` is *not* a weaker version of
+this: it also drops gzip from `Accept-Encoding`, so the origin sends plaintext and the wire grows
+2.76x. It loses on both sides.
+
 ### Cost parity with the platform's `fetch` is not reachable, and here is the floor
 
 Two independent investigations reached this separately, which is the main reason it is stated this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunnelfetch",
-  "version": "1.6.5",
+  "version": "1.8.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/client/decode.js

@@ -190,17 +190,53 @@ function decompressionStage(source, coding, maxBytes = Infinity) {
   })();
   ready.catch(() => {});
 
+  // The fast path: hand the decompressor's output to the runtime and never touch a chunk in JS.
+  //
+  // Measured on the edge, CPU per MB of decompressed output, all shapes interleaved in one isolate:
+  //
+  //     this wrapper, BYOB reads + counting        7.00
+  //     the same wrapper with counting removed     7.33   (counting is free; the WRAPPER is not)
+  //     a standard `new TransformStream()` hop    13.33   (JS-backed: every 4 KiB chunk queues)
+  //     an IdentityTransformStream hop             3.67   (native, and BYOB on its readable)
+  //     DecompressionStream + native collect       3.33   (the floor)
+  //
+  // So a native identity hop is 48% cheaper than this wrapper and lands within noise of the floor,
+  // while the standard TransformStream — the obvious way to write the same thing — is nearly twice
+  // as expensive as doing nothing at all. The difference is that one is C++ and one is JavaScript;
+  // nothing about the API surface says so.
+  //
+  // It applies only when there is no cap, and that is not a limitation to be worked around: the cap
+  // is enforced by counting bytes, counting requires seeing them in JS, and seeing them in JS is
+  // exactly the cost being removed. The two are mutually exclusive. `maxBodyBytes: Infinity` is
+  // already a caller saying they will bound the body themselves, so giving that caller the fast
+  // path is coherent — you gave up the guard, you get the speed — rather than a compromise.
+  if (maxBytes === Infinity && typeof globalThis.IdentityTransformStream === 'function') {
+    const relay = new globalThis.IdentityTransformStream();
+    (async () => {
+      const ds = await ready;
+      if (ds === null) {
+        await relay.writable.close().catch(() => {});
+        return;
+      }
+      // preventAbort: pipeTo's default is to abort the destination with the SOURCE's error, which
+      // would hand the consumer a bare zlib message from a stream it never asked about. Keeping
+      // the abort here is what lets the coding be named, the same as on the wrapper path.
+      await ds.readable.pipeTo(relay.writable, { preventAbort: true });
+      if (pumpDone) await pumpDone;
+      await relay.writable.close();
+    })().catch(async (e) => {
+      // The consumer sees the same typed error it would have seen through the wrapper; the relay is
+      // errored rather than closed so a truncated body can never read as a complete one.
+      await srcReader.cancel(wrapCoding(coding, e)).catch(() => {});
+      await relay.writable.abort(wrapCoding(coding, e)).catch(() => {});
+    });
+    return relay.readable;
+  }
+
   /** @type {ReadableStreamBYOBReader | ReadableStreamDefaultReader<Uint8Array> | null} */
   let out = null;
   let byob = false;
-  const wrap = (e) =>
-    e instanceof HttpError
-      ? e
-      : new HttpError(
-          codes.HTTP_CONTENT_ENCODING,
-          `decoding "${coding}" failed: ${e?.message ?? e}`,
-          { coding },
-        );
+  const wrap = (e) => wrapCoding(coding, e);
 
   return new ReadableStream({
     async pull(c) {
@@ -334,6 +370,14 @@ function capDecodedOutput(source, coding, maxBytes) {
   });
 }
 
+/** Name the coding in a decode failure, so a caller sees which one misbehaved rather than a bare
+ *  zlib message from somewhere downstream. */
+function wrapCoding(coding, e) {
+  return e instanceof HttpError
+    ? e
+    : new HttpError(codes.HTTP_CONTENT_ENCODING, `decoding "${coding}" failed: ${e?.message ?? e}`, { coding });
+}
+
 /** Byte at logical offset `i` across the buffered head chunks. */
 function firstBytes(chunks, i) {
   for (const c of chunks) {

package/src/client.js

@@ -98,7 +98,11 @@ const DEFAULT_MAX_BODY_BYTES = 32 * 1024 * 1024;
  *   again on the DECODED output — a compressed body within the cap can decompress far past it, and
  *   a registered decoder's output is bounded by it too. Pass `Infinity` to opt out, which is the
  *   right choice for streaming large files and the wrong one for fetching URLs you do not control.
- * @property {boolean} [decompress] gzip/deflate. Default true.
+ * @property {boolean | 'passthrough'} [decompress] gzip/deflate. Default true. `false` neither
+ *   advertises nor decodes a coding, so the origin sends plaintext and the wire grows.
+ *   `'passthrough'` advertises gzip as usual but hands the CODED body back with its
+ *   `Content-Encoding` intact — 30% cheaper on a 4 MB body and 2.76x fewer wire bytes, and correct
+ *   only for a caller that forwards the body rather than reading it.
  * @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
@@ -744,7 +748,7 @@ async function sendAndReceive(client, conn, current, { key, deadlines, reused })
   deadlines.beginIdle();
   const guarded = framing.kind === 'none' ? raw : withIdleDeadline(raw, deadlines);
   const decoded = decodeResponseBody(guarded, headInfo.headers, o);
-  return buildResponse(headInfo, decoded, framing, conn);
+  return buildResponse(headInfo, decoded, framing, conn, o.decompress === 'passthrough');
 }
 
 // ------------------------------------------------------------------ one request/response over h2
@@ -801,7 +805,7 @@ async function sendAndReceiveH2(client, h2, current, { deadlines }) {
   const guarded = withIdleDeadline(raw, deadlines);
   const decoded = decodeResponseBody(guarded, head.headers, o);
   const framing = { kind: 'h2', keepAliveEligible: false };
-  return buildResponse(head, decoded, framing, h2);
+  return buildResponse(head, decoded, framing, h2, client.options.decompress === 'passthrough');
 }
 
 /**
@@ -859,22 +863,39 @@ function wantsKeepAlive(headInfo) {
 }
 
 function decodeResponseBody(body, headers, options) {
-  if (options.decompress === false) return body;
+  // `false` means "do not ask for a coding and do not decode one". `'passthrough'` means "ask for
+  // gzip as usual, then hand the CODED bytes back with their Content-Encoding intact".
+  //
+  // The two are not variations on each other. `false` also drops gzip from Accept-Encoding, so the
+  // origin sends plaintext and the wire grows 2.76x on typical content — it loses on both sides.
+  // Passthrough is the combination a forwarding proxy actually wants, and until now it could only
+  // be assembled by setting `decompress: false` and then writing the Accept-Encoding header back on
+  // by hand, per request, which nothing documented.
+  //
+  // Measured end to end on a 4 MB body through a proxy: 118 ms decoding, 82.5 ms passing through —
+  // 30% — and 2.76x fewer bytes on the wire at the same time. But it only helps a caller who never
+  // needs the plaintext: if you parse the body, the decode is work you owe, not overhead, and
+  // passthrough merely moves it downstream.
+  if (options.decompress === false || options.decompress === 'passthrough') return body;
   const encoding = headers.get('content-encoding');
   if (!encoding) return body;
   return decodeBody(body, encoding, options.decoders ?? null, options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES);
 }
 
-function buildResponse(headInfo, body, framing, conn) {
+function buildResponse(headInfo, body, framing, conn, coded = false) {
   const headers = new Headers();
   for (const [k, v] of headInfo.headers) {
     if (k === 'set-cookie') continue;
     headers.append(k, v);
   }
   for (const c of headInfo.setCookie ?? []) headers.append('set-cookie', c);
-  if (headers.has('content-encoding')) {
+  if (headers.has('content-encoding') && !coded) {
     // The bytes handed to the caller are decoded, so a byte count describing the encoded form
     // would be a lie. Content-Encoding stays as information about what was on the wire.
+    //
+    // Under `decompress: 'passthrough'` the bytes are NOT decoded, so the length describes exactly
+    // what the caller holds and keeping it is what makes forwarding possible: a proxy that relays
+    // this Response needs a Content-Length that agrees with its body.
     headers.delete('content-length');
   }
 

package/src/tls/connect.js

@@ -265,6 +265,7 @@ export async function connectTls({ transport, hostname, verifyPeer, options = {}
   const record = new RecordLayer(transport, {
     maxHandshakeMessage: options.maxHandshakeMessage,
     maxKeyUpdates: options.maxKeyUpdates,
+    pullBytes: options.pullBytes,
     // ChaCha20-Poly1305 has no WebCrypto path here; its seal/open are injected via deps.aead and
     // threaded to every createAead. Null for the AES-GCM-only default, which needs nothing.
     aeadImpls: deps.aead ?? null,

package/src/tls/record.js

@@ -118,7 +118,7 @@ export class RecordLayer {
    * @param {RecordLayerOptions} [opts]
    */
   constructor({ readable, writable }, opts = {}) {
-    this._r = new ByteReader(readable);
+    this._r = new ByteReader(readable, opts.pullBytes);
     this._w = new ByteWriter(writable);
     this._maxHandshakeMessage = opts.maxHandshakeMessage ?? 1 << 17;
     this._maxKeyUpdates = opts.maxKeyUpdates ?? 32;

package/src/util/bytes.js

@@ -15,6 +15,15 @@ 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:
+//
+//     16 KiB  42.0     64 KiB  38.5     256 KiB  46.5     1 MiB  57.0
+//
+// 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;
 
 /** Raised when the peer stops sending in the middle of a structure we must read whole. */
@@ -50,8 +59,15 @@ export class UnexpectedEofError extends TunnelFetchError {
  * ReadableStream in this package and its tests) take the default-reader path unchanged.
  */
 export class ByteReader {
-  /** @param {ReadableStream<Uint8Array>} readable */
-  constructor(readable) {
+  /**
+   * @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.
+   */
+  constructor(readable, pullBytes = BYOB_PULL_BYTES) {
+    this._pullBytes = pullBytes > 0 ? pullBytes : BYOB_PULL_BYTES;
     /** @type {ReadableStreamBYOBReader | null} */
     this._byob = null;
     try {
@@ -100,7 +116,7 @@ export class ByteReader {
   async _pull() {
     if (this._eof) return false;
     const { value, done } = this._byob
-      ? await this._byob.read(new Uint8Array(BYOB_PULL_BYTES))
+      ? await this._byob.read(new Uint8Array(this._pullBytes))
       : await this._reader.read();
     if (done) {
       this._eof = true;
@@ -398,11 +414,39 @@ export function equal(a, b) {
  */
 export function timingSafeEqual(a, b) {
   if (a.byteLength !== b.byteLength) return false;
+  // Prefer the runtime's own, which is compiled rather than interpreted and therefore actually has
+  // the property this function is named for. `crypto.subtle.timingSafeEqual` is a non-standard
+  // Cloudflare extension, so it is FEATURE-DETECTED rather than assumed — this package runs on
+  // Node, Deno and Bun as well, and inferring a capability from a runtime name is the mistake it
+  // refuses to make everywhere else. Detected once, at module load, because doing it per call would
+  // put a property lookup on a path whose whole point is uniform timing.
+  if (NATIVE_TIMING_SAFE_EQUAL) return NATIVE_TIMING_SAFE_EQUAL(a, b);
   let diff = 0;
   for (let i = 0; i < a.byteLength; i++) diff |= a[i] ^ b[i];
   return diff === 0;
 }
 
+/**
+ * The runtime's constant-time compare, bound once, or null where there is none.
+ *
+ * Bound with a probe rather than a typeof check: a property that exists but throws on real input
+ * would otherwise be discovered inside a TLS Finished verification, where the failure mode is a
+ * dead connection on a path that is supposed to be the careful one.
+ */
+const NATIVE_TIMING_SAFE_EQUAL = (() => {
+  const fn = globalThis.crypto?.subtle?.timingSafeEqual;
+  if (typeof fn !== 'function') return null;
+  try {
+    const one = Uint8Array.of(1, 2, 3);
+    const two = Uint8Array.of(1, 2, 4);
+    if (fn.call(globalThis.crypto.subtle, one, one) !== true) return null;
+    if (fn.call(globalThis.crypto.subtle, one, two) !== false) return null;
+  } catch {
+    return null;
+  }
+  return (a, b) => fn.call(globalThis.crypto.subtle, a, b);
+})();
+
 const HEX = '0123456789abcdef';
 /**
  * @param {Uint8Array} bytes

package/types/client.d.ts

@@ -58,7 +58,11 @@ export function install(options?: ClientOptions): () => void;
  *   again on the DECODED output — a compressed body within the cap can decompress far past it, and
  *   a registered decoder's output is bounded by it too. Pass `Infinity` to opt out, which is the
  *   right choice for streaming large files and the wrong one for fetching URLs you do not control.
- * @property {boolean} [decompress] gzip/deflate. Default true.
+ * @property {boolean | 'passthrough'} [decompress] gzip/deflate. Default true. `false` neither
+ *   advertises nor decodes a coding, so the origin sends plaintext and the wire grows.
+ *   `'passthrough'` advertises gzip as usual but hands the CODED body back with its
+ *   `Content-Encoding` intact — 30% cheaper on a 4 MB body and 2.76x fewer wire bytes, and correct
+ *   only for a caller that forwards the body rather than reading it.
  * @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
@@ -239,9 +243,13 @@ export type ClientOptions = {
      */
     maxBodyBytes?: number | undefined;
     /**
-     * gzip/deflate. Default true.
+     * gzip/deflate. Default true. `false` neither
+     * advertises nor decodes a coding, so the origin sends plaintext and the wire grows.
+     * `'passthrough'` advertises gzip as usual but hands the CODED body back with its
+     * `Content-Encoding` intact — 30% cheaper on a 4 MB body and 2.76x fewer wire bytes, and correct
+     * only for a caller that forwards the body rather than reading it.
      */
-    decompress?: boolean | undefined;
+    decompress?: boolean | "passthrough" | undefined;
     /**
      * extra
      * content-codings this client can read, e.g. `{ br: (s) => ... }`. Registering one is what

package/types/util/bytes.d.ts

@@ -83,8 +83,15 @@ export class UnexpectedEofError extends TunnelFetchError {
  * ReadableStream in this package and its tests) take the default-reader path unchanged.
  */
 export class ByteReader {
-    /** @param {ReadableStream<Uint8Array>} readable */
-    constructor(readable: ReadableStream<Uint8Array>);
+    /**
+     * @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.
+     */
+    constructor(readable: ReadableStream<Uint8Array>, pullBytes?: number);
+    _pullBytes: number;
     /** @type {ReadableStreamBYOBReader | null} */
     _byob: ReadableStreamBYOBReader | null;
     _reader: ReadableStreamBYOBReader | ReadableStreamDefaultReader<Uint8Array<ArrayBufferLike>> | null;