tunnelfetch 1.6.4 → 1.7.0

package/package.json

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

@@ -516,6 +516,9 @@ function registerHttp2(client, key, conn) {
       ...(client.options.http2HpackIndexing
         ? { hpackIndexing: client.options.http2HpackIndexing }
         : {}),
+      ...(client.options.http2HeadersPriority
+        ? { headersPriority: client.options.http2HeadersPriority }
+        : {}),
       onClose: () => {
         client._h2conns.delete(h2);
         // Only drop the keyed entry if it is still this connection; a newer one may have replaced it.

package/src/http2/connection.js

@@ -266,6 +266,9 @@ export class Http2Connection {
     // fields go into the HPACK dynamic table. Both default to curl's, both captured off the wire.
     this._pseudoHeaderOrder = opts.pseudoHeaderOrder ?? null;
     this._hpackIndexing = opts.hpackIndexing ?? null;
+    // Whether to set PRIORITY on the request HEADERS, and with what. null means do not set it,
+    // which is curl's behaviour and stays the default.
+    this._headersPriority = opts.headersPriority ?? null;
     this._expectFirstSettings = true;
 
     this._fatal = null; // set once; rejects every stream and every future request
@@ -449,14 +452,18 @@ export class Http2Connection {
    *  run is one write, so no other frame can interleave it (RFC 9113 s6.10). */
   _sendHeaderBlock(streamId, block, endStream) {
     const max = this._peerMaxFrameSize;
+    // Priority rides the opening HEADERS and nothing else: a CONTINUATION has no flags but
+    // END_HEADERS (RFC 9113 s6.10), so putting it anywhere else would be malformed rather than
+    // merely wrong-looking.
+    const priority = this._headersPriority;
     if (block.length <= max) {
-      this._write(headersFrame(streamId, block, { endStream, endHeaders: true }));
+      this._write(headersFrame(streamId, block, { endStream, endHeaders: true, priority }));
       return;
     }
     const frames = [];
     let o = 0;
     const first = block.subarray(0, max);
-    frames.push(headersFrame(streamId, first, { endStream, endHeaders: false }));
+    frames.push(headersFrame(streamId, first, { endStream, endHeaders: false, priority }));
     o = max;
     while (o < block.length) {
       const chunk = block.subarray(o, Math.min(o + max, block.length));

package/src/http2/frames.js

@@ -152,13 +152,43 @@ export function goawayFrame(lastStreamId, errorCode, debug = EMPTY) {
   return serializeFrame(FRAME.GOAWAY, 0, 0, payload);
 }
 
-/** A HEADERS frame carrying a full (already-fragmented-if-needed) block. No PADDED, no PRIORITY —
- *  a client that emits neither is exactly what curl does. */
-export function headersFrame(streamId, block, { endStream = false, endHeaders = true } = {}) {
+/**
+ * A HEADERS frame carrying a full (already-fragmented-if-needed) block. Never PADDED.
+ *
+ * PRIORITY is emitted only when `priority` is supplied, because whether a client sends it is part
+ * of its identity: curl does not, Chromium does — flags 0x25 with `80 00 00 00 ff`, captured in
+ * test/tls/_captured-h2.js. RFC 9113 s5.3.2 deprecates the mechanism and this package ignores
+ * every PRIORITY frame it receives, but a frame-level fingerprinter reads whether the flag is set,
+ * so refusing to emit it would make the Chromium identity wrong in a way nothing else could fix.
+ *
+ * The five bytes are exclusive (1 bit) + stream dependency (31) + weight (8). The weight is sent
+ * as-is: RFC 7540 s6.3 defines the wire byte as weight-minus-one, so Chromium's 255 is a weight of
+ * 256, and passing the byte through keeps this function free of an off-by-one nobody would see.
+ *
+ * @param {{ exclusive?: boolean, streamDependency?: number, weight: number } | null} [opts.priority]
+ */
+export function headersFrame(
+  streamId,
+  block,
+  { endStream = false, endHeaders = true, priority = null } = {},
+) {
   let flags = 0;
   if (endStream) flags |= FLAG.END_STREAM;
   if (endHeaders) flags |= FLAG.END_HEADERS;
-  return serializeFrame(FRAME.HEADERS, flags, streamId, block);
+  if (!priority) return serializeFrame(FRAME.HEADERS, flags, streamId, block);
+
+  flags |= FLAG.PRIORITY;
+  const dep = priority.streamDependency ?? 0;
+  const head = new Uint8Array(5);
+  head[0] = ((dep >>> 24) & 0x7f) | (priority.exclusive ? 0x80 : 0);
+  head[1] = (dep >>> 16) & 0xff;
+  head[2] = (dep >>> 8) & 0xff;
+  head[3] = dep & 0xff;
+  head[4] = priority.weight & 0xff;
+  const payload = new Uint8Array(5 + block.length);
+  payload.set(head, 0);
+  payload.set(block, 5);
+  return serializeFrame(FRAME.HEADERS, flags, streamId, payload);
 }
 
 /** A CONTINUATION frame (RFC 9113 s6.10), for a header block that overflows one frame. */

package/src/profiles.js

@@ -117,12 +117,15 @@ export const chrome = Object.freeze({
   // have been right, which is not a reason to have guessed. It is declared explicitly now so the
   // identity states its own value instead of inheriting one by accident.
   http2HpackIndexing: Object.freeze({ ':path': 'without' }),
-  // STILL a real difference, and newly found by the same capture: Chromium sets the PRIORITY flag
-  // on its request HEADERS frame (flags 0x25) and carries the five deprecated priority bytes.
-  // This package never sets it (see frames.js headersFrame), so the frame layout differs from
-  // Chromium's even where every value above it matches. Not in `requires` because it is a framing
-  // detail this package deliberately does not emit — RFC 9113 s5.3.2 deprecates it — but it is a
-  // signal a frame-level fingerprinter reads, and it is written down here rather than discovered.
+  // Chromium sets PRIORITY on its request HEADERS (flags 0x25) and carries the five deprecated
+  // priority bytes: `80 00 00 00 ff`, i.e. exclusive, dependency 0, weight byte 255. Captured, in
+  // test/tls/_captured-h2.js. 1.6.2 found the difference and documented it; 1.6.5 emits it.
+  //
+  // RFC 9113 s5.3.2 deprecates the mechanism and this package still IGNORES every PRIORITY frame it
+  // receives — sending it is a statement about identity, not a request to be prioritised, and those
+  // are different things. curl sets no priority, so `profiles.curl` leaves this unset and the
+  // default stays "do not send".
+  http2HeadersPriority: Object.freeze({ exclusive: true, streamDependency: 0, weight: 255 }),
   //
   // The connection window immediately above was DEAD until 1.6.1 — declared here, copied by
   // nothing, passed by nothing, and read under a different name — so every connection using this
@@ -211,7 +214,7 @@ export function applyProfile(options) {
   // was missing, which made it dead config: the chrome profile declared Chromium's ~15 MiB window
   // and every chrome connection sent curl's 1000 MiB one.
   for (const key of ['headerOrder', 'http2Settings', 'http2ConnectionWindow',
-                     'http2PseudoHeaderOrder', 'http2HpackIndexing']) {
+                     'http2PseudoHeaderOrder', 'http2HpackIndexing', 'http2HeadersPriority']) {
     if (options[key] === undefined && p[key] != null) out[key] = p[key];
   }
   // Profile headers are DEFAULTS: a request that sets its own User-Agent keeps it. They are folded

package/src/util/bytes.js

@@ -398,11 +398,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/http2/connection.d.ts

@@ -79,6 +79,7 @@ export class Http2Connection {
     _settingsFlight: Array<[number, number]> | null;
     _pseudoHeaderOrder: string[] | null;
     _hpackIndexing: Record<string, "without" | "incremental" | "never"> | null;
+    _headersPriority: any;
     _expectFirstSettings: boolean;
     _fatal: any;
     _goaway: {

package/types/http2/frames.d.ts

@@ -42,11 +42,25 @@ export function rstStreamFrame(streamId: any, errorCode: any): Uint8Array<ArrayB
 export function pingFrame(opaque: any, ack?: boolean): Uint8Array<ArrayBufferLike>;
 /** A GOAWAY frame (RFC 9113 s6.8). */
 export function goawayFrame(lastStreamId: any, errorCode: any, debug?: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBufferLike>;
-/** A HEADERS frame carrying a full (already-fragmented-if-needed) block. No PADDED, no PRIORITY —
- *  a client that emits neither is exactly what curl does. */
-export function headersFrame(streamId: any, block: any, { endStream, endHeaders }?: {
+/**
+ * A HEADERS frame carrying a full (already-fragmented-if-needed) block. Never PADDED.
+ *
+ * PRIORITY is emitted only when `priority` is supplied, because whether a client sends it is part
+ * of its identity: curl does not, Chromium does — flags 0x25 with `80 00 00 00 ff`, captured in
+ * test/tls/_captured-h2.js. RFC 9113 s5.3.2 deprecates the mechanism and this package ignores
+ * every PRIORITY frame it receives, but a frame-level fingerprinter reads whether the flag is set,
+ * so refusing to emit it would make the Chromium identity wrong in a way nothing else could fix.
+ *
+ * The five bytes are exclusive (1 bit) + stream dependency (31) + weight (8). The weight is sent
+ * as-is: RFC 7540 s6.3 defines the wire byte as weight-minus-one, so Chromium's 255 is a weight of
+ * 256, and passing the byte through keeps this function free of an off-by-one nobody would see.
+ *
+ * @param {{ exclusive?: boolean, streamDependency?: number, weight: number } | null} [opts.priority]
+ */
+export function headersFrame(streamId: any, block: any, { endStream, endHeaders, priority }?: {
     endStream?: boolean | undefined;
     endHeaders?: boolean | undefined;
+    priority?: null | undefined;
 }): Uint8Array<ArrayBufferLike>;
 /** A CONTINUATION frame (RFC 9113 s6.10), for a header block that overflows one frame. */
 export function continuationFrame(streamId: any, block: any, endHeaders: any): Uint8Array<ArrayBufferLike>;

package/types/profiles.d.ts

@@ -74,6 +74,11 @@ export const chrome: Readonly<{
     http2HpackIndexing: Readonly<{
         ':path': "without";
     }>;
+    http2HeadersPriority: Readonly<{
+        exclusive: true;
+        streamDependency: 0;
+        weight: 255;
+    }>;
     http2PseudoHeaderOrder: readonly string[];
     headerOrder: readonly string[];
     headers: readonly string[][];