tunnelfetch 1.0.0

package/src/http2/constants.js

@@ -0,0 +1,129 @@
+// HTTP/2 wire constants (RFC 9113), and the deliberately narrow client posture on top of them.
+//
+// This is a client that opens streams and reads responses. It never receives a request, never
+// serves a push, and never prioritises — so the constants for those exist only to NAME what we
+// refuse when a peer sends them, not to act on them.
+//
+// The SETTINGS and window values below are not defaults chosen for taste. They are the exact
+// values curl 8.7.1 / nghttp2 1.69.0 puts on the wire, captured over a real ALPN-negotiated h2
+// handshake. That matters empirically, not aesthetically: the whole reason to implement h2 here
+// is that some sites challenge HTTP/1.1 as a bot signal while letting curl's h2 through, and a
+// naive h2 fingerprint can fail exactly where curl's succeeds. Matching the SETTINGS frame, the
+// initial window sizes, the connection WINDOW_UPDATE, and the pseudo-header order removes the
+// cheapest tells. See the capture note beside `preferredSettingsOrder`.
+
+/** The 24-byte client connection preface (RFC 9113 s3.4). Sent before any frame. */
+export const CONNECTION_PREFACE = Uint8Array.from(
+  'PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n',
+  (c) => c.charCodeAt(0),
+);
+
+/** Frame types (RFC 9113 s6). PRIORITY and PUSH_PROMISE are named to reject, not to honour. */
+export const FRAME = {
+  DATA: 0x0,
+  HEADERS: 0x1,
+  PRIORITY: 0x2,
+  RST_STREAM: 0x3,
+  SETTINGS: 0x4,
+  PUSH_PROMISE: 0x5,
+  PING: 0x6,
+  GOAWAY: 0x7,
+  WINDOW_UPDATE: 0x8,
+  CONTINUATION: 0x9,
+};
+
+/** Reverse map for diagnostics: an unknown type still gets a number. */
+export const FRAME_NAME = Object.fromEntries(Object.entries(FRAME).map(([k, v]) => [v, k]));
+
+/** Frame flags (RFC 9113 s6). The same bit means different things per frame type. */
+export const FLAG = {
+  END_STREAM: 0x1, // DATA, HEADERS
+  ACK: 0x1, // SETTINGS, PING (same bit, different frames)
+  END_HEADERS: 0x4, // HEADERS, CONTINUATION, PUSH_PROMISE
+  PADDED: 0x8, // DATA, HEADERS, PUSH_PROMISE
+  PRIORITY: 0x20, // HEADERS
+};
+
+/** SETTINGS parameter identifiers (RFC 9113 s6.5.2). */
+export const SETTINGS = {
+  HEADER_TABLE_SIZE: 0x1,
+  ENABLE_PUSH: 0x2,
+  MAX_CONCURRENT_STREAMS: 0x3,
+  INITIAL_WINDOW_SIZE: 0x4,
+  MAX_FRAME_SIZE: 0x5,
+  MAX_HEADER_LIST_SIZE: 0x6,
+};
+
+export const SETTINGS_NAME = Object.fromEntries(
+  Object.entries(SETTINGS).map(([k, v]) => [v, k]),
+);
+
+/** Error codes (RFC 9113 s7). Sent in RST_STREAM and GOAWAY; also received in them. */
+export const H2_ERROR = {
+  NO_ERROR: 0x0,
+  PROTOCOL_ERROR: 0x1,
+  INTERNAL_ERROR: 0x2,
+  FLOW_CONTROL_ERROR: 0x3,
+  SETTINGS_TIMEOUT: 0x4,
+  STREAM_CLOSED: 0x5,
+  FRAME_SIZE_ERROR: 0x6,
+  REFUSED_STREAM: 0x7,
+  CANCEL: 0x8,
+  COMPRESSION_ERROR: 0x9,
+  CONNECT_ERROR: 0xa,
+  ENHANCE_YOUR_CALM: 0xb,
+  INADEQUATE_SECURITY: 0xc,
+  HTTP_1_1_REQUIRED: 0xd,
+};
+
+export const H2_ERROR_NAME = Object.fromEntries(
+  Object.entries(H2_ERROR).map(([k, v]) => [v, k]),
+);
+
+// --- protocol-fixed limits ---------------------------------------------------------------------
+
+/** The default SETTINGS_MAX_FRAME_SIZE and its floor (RFC 9113 s6.5.2): 2^14. A peer may raise
+ *  its own limit, but until it says so in SETTINGS we must not send a frame larger than this. */
+export const DEFAULT_MAX_FRAME_SIZE = 16384;
+/** The ceiling a peer may set MAX_FRAME_SIZE to: 2^24 - 1. Beyond it, SETTINGS is a PROTOCOL_ERROR. */
+export const MAX_ALLOWED_FRAME_SIZE = 16777215;
+/** The default per-stream/-connection flow-control window before any SETTINGS/WINDOW_UPDATE. */
+export const DEFAULT_INITIAL_WINDOW = 65535;
+/** The largest a flow-control window may reach; exceeding it is a FLOW_CONTROL_ERROR (s6.9.1). */
+export const MAX_WINDOW = 2147483647; // 2^31 - 1
+
+// --- our client posture (the curl fingerprint) -------------------------------------------------
+
+/**
+ * The SETTINGS we advertise, and the ORDER we advertise them in. Both are matched to curl
+ * 8.7.1 / nghttp2 1.69.0 as captured on the wire:
+ *
+ *   SETTINGS: MAX_CONCURRENT_STREAMS=100, INITIAL_WINDOW_SIZE=10485760, ENABLE_PUSH=0
+ *   emitted in the id order 3, 4, 2 — and nothing else (no HEADER_TABLE_SIZE, no MAX_FRAME_SIZE,
+ *   no MAX_HEADER_LIST_SIZE), so those stay at their protocol defaults exactly as curl leaves them.
+ *
+ * These are the values the SERVER sees and fingerprints on, so they are held fixed here rather
+ * than exposed as knobs. The receive-side buffering they imply is bounded elsewhere (see the
+ * flow-control note in connection.js): a large advertised window is a fingerprint choice, not a
+ * promise to buffer that much before applying backpressure.
+ */
+export const CLIENT_INITIAL_WINDOW_SIZE = 10485760; // 10 MiB, curl's SETTINGS_INITIAL_WINDOW_SIZE
+export const CLIENT_MAX_CONCURRENT_STREAMS = 100; // curl's SETTINGS_MAX_CONCURRENT_STREAMS
+
+/** curl raises the CONNECTION receive window to exactly 1000 MiB with one WINDOW_UPDATE on
+ *  stream 0 right after SETTINGS. The increment below is 1000 MiB - 65535, i.e. what takes the
+ *  default 65535 window up to 1048576000. Sent in the same preface flight, same order as curl. */
+export const CLIENT_CONNECTION_WINDOW = 1048576000; // 1000 MiB
+export const CLIENT_CONNECTION_WINDOW_INCREMENT = CLIENT_CONNECTION_WINDOW - DEFAULT_INITIAL_WINDOW; // 1048510465
+
+/**
+ * The order pseudo-headers are emitted in a request HEADERS block. curl/nghttp2 sends
+ * :method, :scheme, :authority, :path — captured, not guessed. h2 fingerprinters read this order
+ * (the "m,s,a,p" tail of an Akamai-style h2 fingerprint), so it is fixed to match.
+ */
+export const PSEUDO_HEADER_ORDER = [':method', ':scheme', ':authority', ':path'];
+
+/** ALPN identifiers. Offering both and following the server's pick is the whole ALPN contract;
+ *  there is no reconnect-and-retry path if the server picks the other one. */
+export const ALPN_H2 = 'h2';
+export const ALPN_HTTP11 = 'http/1.1';

package/src/http2/frames.js

@@ -0,0 +1,291 @@
+// HTTP/2 frame layer (RFC 9113 s4, s6): the 9-octet header, and pure serialisers / parsers for
+// the frame types a client sends and receives.
+//
+// This file knows nothing about streams, flow control, or state machines — it turns bytes into
+// `{type, flags, streamId, payload}` and back, and validates only what framing itself dictates
+// (a length the type forbids, padding longer than the frame). Everything semantic lives in
+// connection.js. Splitting it this way is what lets the frame reader be run under all chunkings:
+// it must produce identical frames whether the transport hands over one byte or the whole record.
+
+import { Http2Error, codes } from '../errors.js';
+import { UnexpectedEofError, readU16, readU32 } from '../util/bytes.js';
+import { FRAME, FLAG, DEFAULT_MAX_FRAME_SIZE } from './constants.js';
+
+/** The fixed frame header size (RFC 9113 s4.1): 24-bit length, type, flags, 31-bit stream id. */
+export const FRAME_HEADER_SIZE = 9;
+
+/**
+ * One frame off the wire. `payload` aliases the reader's buffer and must not be retained.
+ * @typedef {object} Frame
+ * @property {number} type
+ * @property {number} flags
+ * @property {number} streamId
+ * @property {Uint8Array} payload
+ */
+
+/**
+ * Read exactly one frame. Enforces our advertised SETTINGS_MAX_FRAME_SIZE on receipt: a peer
+ * that sends a larger frame commits a FRAME_SIZE_ERROR (RFC 9113 s4.2), and refusing at the
+ * header — before reading the body — is what bounds how much a hostile peer can make us buffer.
+ * Returns null only on a clean EOF exactly at a frame boundary.
+ *
+ * @param {import('../util/bytes.js').ByteReader} reader
+ * @param {number} maxFrameSize the largest payload we will accept
+ * @returns {Promise<Frame | null>}
+ */
+export async function readFrame(reader, maxFrameSize = DEFAULT_MAX_FRAME_SIZE) {
+  let header;
+  try {
+    header = await reader.readExactly(FRAME_HEADER_SIZE, 'HTTP/2 frame header');
+  } catch (e) {
+    if (e instanceof UnexpectedEofError && e.detail?.got === 0) return null; // clean end
+    throw e;
+  }
+  const length = (header[0] << 16) | (header[1] << 8) | header[2];
+  const type = header[3];
+  const flags = header[4];
+  // The reserved high bit of the stream id is explicitly ignored (RFC 9113 s4.1), never checked.
+  const streamId = readU32(header, 5) & 0x7fffffff;
+  if (length > maxFrameSize) {
+    throw new Http2Error(
+      codes.HTTP2_FRAME_SIZE,
+      `frame length ${length} exceeds SETTINGS_MAX_FRAME_SIZE ${maxFrameSize}`,
+      { length, limit: maxFrameSize, type, streamId },
+    );
+  }
+  const payload = length === 0 ? EMPTY : await reader.readExactly(length, 'HTTP/2 frame payload');
+  return { type, flags, streamId, payload };
+}
+
+const EMPTY = new Uint8Array(0);
+
+// ---------------------------------------------------------------------- serialisers
+
+/** Write a frame header into the first 9 bytes of `out`, at offset `o`. */
+function putHeader(out, o, length, type, flags, streamId) {
+  out[o] = (length >>> 16) & 0xff;
+  out[o + 1] = (length >>> 8) & 0xff;
+  out[o + 2] = length & 0xff;
+  out[o + 3] = type;
+  out[o + 4] = flags;
+  out[o + 5] = (streamId >>> 24) & 0x7f; // clear the reserved bit
+  out[o + 6] = (streamId >>> 16) & 0xff;
+  out[o + 7] = (streamId >>> 8) & 0xff;
+  out[o + 8] = streamId & 0xff;
+}
+
+/**
+ * Serialise one frame (header + payload) into a single buffer.
+ * @param {number} type
+ * @param {number} flags
+ * @param {number} streamId
+ * @param {Uint8Array} payload
+ * @returns {Uint8Array}
+ */
+export function serializeFrame(type, flags, streamId, payload = EMPTY) {
+  const out = new Uint8Array(FRAME_HEADER_SIZE + payload.length);
+  putHeader(out, 0, payload.length, type, flags, streamId);
+  out.set(payload, FRAME_HEADER_SIZE);
+  return out;
+}
+
+/**
+ * A SETTINGS frame. `entries` is an array of [id, value]; order is preserved because it is part
+ * of the client fingerprint. An ACK carries no payload and sets the ACK flag.
+ * @param {Array<[number, number]>} entries
+ * @param {boolean} [ack]
+ * @returns {Uint8Array}
+ */
+export function settingsFrame(entries, ack = false) {
+  if (ack) return serializeFrame(FRAME.SETTINGS, FLAG.ACK, 0, EMPTY);
+  const payload = new Uint8Array(entries.length * 6);
+  let o = 0;
+  for (const [id, value] of entries) {
+    payload[o] = (id >>> 8) & 0xff;
+    payload[o + 1] = id & 0xff;
+    payload[o + 2] = (value >>> 24) & 0xff;
+    payload[o + 3] = (value >>> 16) & 0xff;
+    payload[o + 4] = (value >>> 8) & 0xff;
+    payload[o + 5] = value & 0xff;
+    o += 6;
+  }
+  return serializeFrame(FRAME.SETTINGS, 0, 0, payload);
+}
+
+/** A WINDOW_UPDATE frame (RFC 9113 s6.9). streamId 0 is connection-level. */
+export function windowUpdateFrame(streamId, increment) {
+  const payload = new Uint8Array(4);
+  payload[0] = (increment >>> 24) & 0x7f;
+  payload[1] = (increment >>> 16) & 0xff;
+  payload[2] = (increment >>> 8) & 0xff;
+  payload[3] = increment & 0xff;
+  return serializeFrame(FRAME.WINDOW_UPDATE, 0, streamId, payload);
+}
+
+/** A RST_STREAM frame (RFC 9113 s6.4). */
+export function rstStreamFrame(streamId, errorCode) {
+  const payload = new Uint8Array(4);
+  payload[0] = (errorCode >>> 24) & 0xff;
+  payload[1] = (errorCode >>> 16) & 0xff;
+  payload[2] = (errorCode >>> 8) & 0xff;
+  payload[3] = errorCode & 0xff;
+  return serializeFrame(FRAME.RST_STREAM, 0, streamId, payload);
+}
+
+/** A PING frame (RFC 9113 s6.7). The 8-byte opaque data is echoed on ACK. */
+export function pingFrame(opaque, ack = false) {
+  return serializeFrame(FRAME.PING, ack ? FLAG.ACK : 0, 0, opaque);
+}
+
+/** A GOAWAY frame (RFC 9113 s6.8). */
+export function goawayFrame(lastStreamId, errorCode, debug = EMPTY) {
+  const payload = new Uint8Array(8 + debug.length);
+  payload[0] = (lastStreamId >>> 24) & 0x7f;
+  payload[1] = (lastStreamId >>> 16) & 0xff;
+  payload[2] = (lastStreamId >>> 8) & 0xff;
+  payload[3] = lastStreamId & 0xff;
+  payload[4] = (errorCode >>> 24) & 0xff;
+  payload[5] = (errorCode >>> 16) & 0xff;
+  payload[6] = (errorCode >>> 8) & 0xff;
+  payload[7] = errorCode & 0xff;
+  payload.set(debug, 8);
+  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 } = {}) {
+  let flags = 0;
+  if (endStream) flags |= FLAG.END_STREAM;
+  if (endHeaders) flags |= FLAG.END_HEADERS;
+  return serializeFrame(FRAME.HEADERS, flags, streamId, block);
+}
+
+/** A CONTINUATION frame (RFC 9113 s6.10), for a header block that overflows one frame. */
+export function continuationFrame(streamId, block, endHeaders) {
+  return serializeFrame(FRAME.CONTINUATION, endHeaders ? FLAG.END_HEADERS : 0, streamId, block);
+}
+
+/** A DATA frame (RFC 9113 s6.1). No padding is ever emitted. */
+export function dataFrame(streamId, data, endStream) {
+  return serializeFrame(FRAME.DATA, endStream ? FLAG.END_STREAM : 0, streamId, data);
+}
+
+// ---------------------------------------------------------------------- payload parsers
+
+/**
+ * Strip a DATA/HEADERS PADDED frame's pad length and padding, returning the meaningful slice.
+ * The pad length byte and padding both count against flow control (the caller handles that);
+ * this only removes them from the bytes handed onward. A pad length >= the remaining payload is
+ * a PROTOCOL_ERROR (RFC 9113 s6.1).
+ * @param {Uint8Array} payload
+ * @returns {{ data: Uint8Array, padLength: number }}
+ */
+export function stripPadding(payload) {
+  if (payload.length === 0) {
+    throw new Http2Error(codes.HTTP2_PROTOCOL, 'PADDED frame has no pad length octet');
+  }
+  const padLength = payload[0];
+  if (padLength >= payload.length) {
+    throw new Http2Error(
+      codes.HTTP2_PROTOCOL,
+      `pad length ${padLength} is not smaller than the ${payload.length - 1} bytes that follow it`,
+      { padLength, available: payload.length - 1 },
+    );
+  }
+  return { data: payload.subarray(1, payload.length - padLength), padLength };
+}
+
+/**
+ * The header block fragment inside a HEADERS payload, after removing padding (PADDED) and the
+ * priority fields (PRIORITY). Priority is deprecated (RFC 9113 s5.3.2) and its fields are
+ * discarded, not acted on.
+ * @param {Uint8Array} payload
+ * @param {number} flags
+ * @returns {Uint8Array}
+ */
+export function headersBlockFragment(payload, flags) {
+  let p = payload;
+  if (flags & FLAG.PADDED) p = stripPadding(p).data;
+  if (flags & FLAG.PRIORITY) {
+    if (p.length < 5) {
+      throw new Http2Error(codes.HTTP2_FRAME_SIZE, 'HEADERS PRIORITY block is shorter than 5 bytes');
+    }
+    p = p.subarray(5); // 4-byte stream dependency + 1-byte weight, both ignored
+  }
+  return p;
+}
+
+/**
+ * Parse a SETTINGS payload into [id, value] pairs. Length must be a multiple of 6
+ * (RFC 9113 s6.5); anything else is a FRAME_SIZE_ERROR.
+ * @param {Uint8Array} payload
+ * @returns {Array<[number, number]>}
+ */
+export function parseSettings(payload) {
+  if (payload.length % 6 !== 0) {
+    throw new Http2Error(
+      codes.HTTP2_FRAME_SIZE,
+      `SETTINGS payload of ${payload.length} bytes is not a multiple of 6`,
+      { length: payload.length },
+    );
+  }
+  const out = [];
+  for (let o = 0; o < payload.length; o += 6) {
+    out.push([readU16(payload, o), readU32(payload, o + 2)]);
+  }
+  return out;
+}
+
+/**
+ * Parse a WINDOW_UPDATE payload. Must be exactly 4 bytes; a zero increment is a protocol error
+ * (RFC 9113 s6.9), surfaced by the caller which knows the stream context.
+ * @param {Uint8Array} payload
+ * @returns {number} the 31-bit increment
+ */
+export function parseWindowUpdate(payload) {
+  if (payload.length !== 4) {
+    throw new Http2Error(
+      codes.HTTP2_FRAME_SIZE,
+      `WINDOW_UPDATE payload is ${payload.length} bytes, must be 4`,
+      { length: payload.length },
+    );
+  }
+  return readU32(payload, 0) & 0x7fffffff;
+}
+
+/**
+ * Parse a RST_STREAM payload (exactly 4 bytes: an error code).
+ * @param {Uint8Array} payload
+ * @returns {number}
+ */
+export function parseRstStream(payload) {
+  if (payload.length !== 4) {
+    throw new Http2Error(
+      codes.HTTP2_FRAME_SIZE,
+      `RST_STREAM payload is ${payload.length} bytes, must be 4`,
+      { length: payload.length },
+    );
+  }
+  return readU32(payload, 0);
+}
+
+/**
+ * Parse a GOAWAY payload (RFC 9113 s6.8): last-stream-id, error code, optional debug data.
+ * @param {Uint8Array} payload
+ * @returns {{ lastStreamId: number, errorCode: number, debug: Uint8Array }}
+ */
+export function parseGoaway(payload) {
+  if (payload.length < 8) {
+    throw new Http2Error(
+      codes.HTTP2_FRAME_SIZE,
+      `GOAWAY payload is ${payload.length} bytes, must be at least 8`,
+      { length: payload.length },
+    );
+  }
+  return {
+    lastStreamId: readU32(payload, 0) & 0x7fffffff,
+    errorCode: readU32(payload, 4),
+    debug: payload.subarray(8),
+  };
+}