tunnelfetch 1.6.3 → 1.6.5

package/README.md

@@ -434,10 +434,20 @@ pinned in `test/tls/fingerprint.test.js` and `test/http2/fingerprint.test.js`.
 **The default `SETTINGS` values are this package's, not curl's, and that is a deliberate trade.**
 `profiles.curl` carries curl 8.21.0's real `INITIAL_WINDOW_SIZE` of **64 KiB**, captured and pinned
 in `test/tls/_captured-h2.js`. The connection default without a profile is **10 MiB**, which is what
-curl 8.7.1 sent and what this package keeps for throughput: a 64 KiB stream window means far more
-`WINDOW_UPDATE` round trips on a large body, and the cost work in this README shows body transfer is
-where the money is. **That throughput difference has not been measured**, so if you are moving large
-bodies under `profiles.curl`, measure it before relying on it — or set `http2Settings` yourself.
+curl 8.7.1 sent and what this package keeps: a 64 KiB stream window means one `WINDOW_UPDATE` per
+32 KiB consumed instead of one per 5 MiB.
+
+**Measured, on a 8.7 MB body over h2 against a real origin, both windows interleaved in one
+isolate: the 64 KiB window costs about +1.4 ms of CPU per decompressed MB** — roughly **6–7%** on
+top of the ~21.7 ms/MB this package spends moving a large body. That is the price of the accurate
+fingerprint, and for most callers it is worth paying; if you are moving large bodies and do not need
+to look like curl, set `http2Settings` yourself.
+
+Two cautions on that number. The minimum-of-samples rule this document recommends elsewhere **fails
+here**: with unequal sample counts and a lossy origin the minima moved between +2 ms and +13 ms
+across sweeps, because the arm with more samples gets a lower minimum for free. The figure above is
+p25 and median, which agreed with each other and with the arithmetic — 8.7 MB at a 32 KiB replenish
+threshold is ~276 extra frames, and ~276 × ~47 µs is ~13 ms.
 
 Until 1.6.2 the profile carried curl **8.7.1's** window while presenting curl **8.21.0's**
 ClientHello: one named client, two source versions, and a split identity that only a capture could

package/README.zh-CN.md

@@ -341,9 +341,16 @@ curl（8.7.1 / nghttp2），照线上抓包原样复刻。这么做是实证需
 
 **默认的 `SETTINGS` 取值是本包自己的，不是 curl 的，这是一个有意的取舍。** `profiles.curl` 带的是
 curl 8.21.0 实测的 `INITIAL_WINDOW_SIZE` = **64 KiB**，抓包固化在 `test/tls/_captured-h2.js`。而不加
-profile 时连接的默认值是 **10 MiB**——那是 curl 8.7.1 发的值，本包为吞吐保留它：64 KiB 的流窗口意味着大
-body 上要多得多的 `WINDOW_UPDATE` 往返，而本文档的成本部分已经说明，钱就花在 body 传输上。**这个吞吐差异
-我没有实测过**，所以如果你在 `profiles.curl` 下搬大 body，先测再依赖，或者自己设 `http2Settings`。
+profile 时连接的默认值是 **10 MiB**——那是 curl 8.7.1 发的值，本包保留它：64 KiB 的流窗口意味着每消费
+32 KiB 就发一次 `WINDOW_UPDATE`，而不是每 5 MiB 一次。
+
+**实测:8.7 MB 的 body、走 h2、打真实源站、两档窗口在同一 isolate 里交错——64 KiB 窗口每解压 MB 多花约
+1.4 ms CPU**，相对本包搬大 body 的约 21.7 ms/MB 是**多 6–7%**。这就是准确指纹的价钱,对多数调用方值得付;
+如果你要搬大 body 又不需要长得像 curl，自己设 `http2Settings`。
+
+这个数字有两点要说明。本文档在别处推荐的"取最小值"规则**在这里失效了**:两档样本数不等、源站又有丢失，最小值
+在两轮扫描之间从 +2 ms 跳到 +13 ms——样本多的那一档白得一个更低的最小值。上面的数取自 p25 和中位数，两者一致，
+并且和算术对得上:8.7 MB 在 32 KiB 的补充阈值下约是 276 个额外帧，276 × 约 47 µs 约等于 13 ms。
 
 1.6.2 之前，这个 profile 带着 curl **8.7.1** 的窗口，却呈现 curl **8.21.0** 的 ClientHello：同一个具名
 客户端，两个来源版本——一个只有抓包才能发现的身份分裂，因为两半各自都真的属于某个 curl。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunnelfetch",
-  "version": "1.6.3",
+  "version": "1.6.5",
   "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.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/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[][];