tunnelfetch 1.0.0

package/types/http2/connection.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Build the ordered HPACK field list for a request, pseudo-headers first in curl's order
+ * (:method, :scheme, :authority, :path). :path is emitted "without indexing" and the rest
+ * "incremental", matching the captured curl encoding.
+ *
+ * @param {{ method: string, scheme: string, authority: string, path: string,
+ *   headers: Array<[string, string]> }} req
+ * @returns {import('./hpack.js').HpackField[]}
+ */
+export function buildRequestFields({ method, scheme, authority, path, headers }: {
+    method: string;
+    scheme: string;
+    authority: string;
+    path: string;
+    headers: Array<[string, string]>;
+}): import("./hpack.js").HpackField[];
+/**
+ * @typedef {ReadableStream<Uint8Array> & { completed: Promise<boolean>,
+ *   trailers: Promise<Headers | null> }} BodyStream
+ */
+/**
+ * @typedef {object} Http2ResponseHead
+ * @property {number} status
+ * @property {string} statusText always '' — HTTP/2 has no reason phrase
+ * @property {Headers} headers
+ * @property {string[]} setCookie one entry per set-cookie field, kept separate like the h1 path
+ * @property {'2'} httpVersion
+ * @property {BodyStream} body
+ */
+/**
+ * Raised by request() when the connection cannot take the stream but the request PROVABLY was not
+ * processed (going away, or refused). It mirrors h1's serverNeverSawIt: only a request the server
+ * demonstrably never saw may be re-sent, so client.js can safely open a fresh connection and retry.
+ */
+export class Http2Retryable extends Http2Error {
+}
+/**
+ * @typedef {object} Http2ConnectionOptions
+ * @property {import('../transport.js').ConnectionInfo} [info] provenance attached to responses
+ * @property {number} [initialWindowSize] our SETTINGS_INITIAL_WINDOW_SIZE (receive window per
+ *   stream). Defaults to curl's 10 MiB; tests lower it to exercise flow control.
+ * @property {number} [connectionWindow] the connection receive window we open with a WINDOW_UPDATE
+ *   right after SETTINGS. Defaults to curl's 1000 MiB.
+ * @property {number} [maxConcurrentStreams] our advertised SETTINGS_MAX_CONCURRENT_STREAMS.
+ * @property {number} [maxHeaderTableSize] our advertised SETTINGS_HEADER_TABLE_SIZE.
+ * @property {number} [maxHeaderListSize] self-protection cap on a decoded response header list.
+ * @property {(err: Error | null) => void} [onClose] called once when the connection dies, so a
+ *   registry can drop it.
+ */
+export class Http2Connection {
+    /**
+     * @param {import('./frames.js').ByteDuplex | { readable: ReadableStream<Uint8Array>,
+     *   writable: WritableStream<Uint8Array> }} duplex plaintext transport (a TLS session's
+     *   plaintextDuplex, or a raw socket for cleartext h2 in tests)
+     * @param {Http2ConnectionOptions} [opts]
+     */
+    constructor(duplex: import("./frames.js").ByteDuplex | {
+        readable: ReadableStream<Uint8Array>;
+        writable: WritableStream<Uint8Array>;
+    }, opts?: Http2ConnectionOptions);
+    _reader: ByteReader;
+    _writer: ByteWriter;
+    _closeTransport: () => any;
+    info: import("../transport.js").ConnectionInfo | null;
+    _ourInitialWindow: number;
+    _ourConnWindow: number;
+    _ourMaxConcurrent: number;
+    _ourHeaderTableSize: number;
+    _peerInitialWindow: number;
+    _peerMaxFrameSize: number;
+    _peerMaxConcurrent: number;
+    _peerHeaderTableSize: number;
+    _connRecvWindow: number;
+    _connConsumed: number;
+    _connSendWindow: number;
+    /** @type {Array<() => void>} wakers for senders blocked on the connection window */
+    _connSendWaiters: Array<() => void>;
+    _decoder: HpackDecoder;
+    /** @type {Map<number, any>} live streams by id */
+    _streams: Map<number, any>;
+    _nextStreamId: number;
+    _lastPeerStreamId: number;
+    _continuation: {
+        streamId: any;
+        fragments: Uint8Array<ArrayBuffer>[];
+        endStream: boolean;
+    } | null;
+    _expectFirstSettings: boolean;
+    _fatal: any;
+    _goaway: {
+        lastStreamId: number;
+        errorCode: number;
+    } | null;
+    _closed: boolean;
+    _onClose: ((err: Error | null) => void) | null;
+    _writeChain: Promise<void>;
+    /** Whether a new request may be dispatched onto this connection right now. */
+    canDispatch(): boolean;
+    get activeStreams(): number;
+    _sendPreface(): void;
+    /** Serialise a wire write behind every previous one, so a header block is never split by another
+     *  frame and the preface always leads. Mirrors the record layer's write discipline. */
+    _write(bytes: any): Promise<void>;
+    /**
+     * Open a stream and send a request. Resolves once the response header block (the first non-1xx
+     * HEADERS) has arrived; the body streams after.
+     *
+     * @param {object} req
+     * @param {string} req.method
+     * @param {string} req.scheme
+     * @param {string} req.authority
+     * @param {string} req.path
+     * @param {Array<[string, string]>} req.headers already lowercased, connection-specific ones removed
+     * @param {Uint8Array | null} [req.body] buffered whole by the caller, so send flow control is simple
+     * @param {AbortSignal} [req.signal] aborting it RST_STREAMs the stream and rejects its promises;
+     *   this is how a per-request deadline tears down exactly one stream without touching the others
+     * @returns {Promise<Http2ResponseHead>}
+     */
+    request({ method, scheme, authority, path, headers, body, signal }: {
+        method: string;
+        scheme: string;
+        authority: string;
+        path: string;
+        headers: Array<[string, string]>;
+        body?: Uint8Array<ArrayBufferLike> | null | undefined;
+        signal?: AbortSignal | undefined;
+    }): Promise<Http2ResponseHead>;
+    _createStream(id: any): {
+        id: any;
+        head: {
+            promise: Promise<any>;
+            resolve: undefined;
+            reject: undefined;
+            settled: boolean;
+        };
+        responseReceived: boolean;
+        /** @type {Uint8Array[]} */
+        recvQueue: Uint8Array[];
+        recvEnded: boolean;
+        /** @type {Error | null} */
+        bodyError: Error | null;
+        /** @type {(() => void) | null} */
+        pullWaiter: (() => void) | null;
+        completed: {
+            promise: Promise<any>;
+            resolve: undefined;
+            reject: undefined;
+            settled: boolean;
+        };
+        trailers: {
+            promise: Promise<any>;
+            resolve: undefined;
+            reject: undefined;
+            settled: boolean;
+        };
+        /** @type {Headers | null} */
+        trailerFields: Headers | null;
+        recvWindow: number;
+        recvConsumed: number;
+        sendWindow: number;
+        /** @type {Array<() => void>} */
+        sendWaiters: Array<() => void>;
+        localEnded: boolean;
+        cancelled: boolean;
+        closed: boolean;
+        rstSent: boolean;
+    };
+    /** Send a header block as HEADERS plus CONTINUATION frames if it overflows one frame. The whole
+     *  run is one write, so no other frame can interleave it (RFC 9113 s6.10). */
+    _sendHeaderBlock(streamId: any, block: any, endStream: any): void;
+    /** Send a request body as DATA frames, respecting stream and connection send windows. */
+    _sendBody(streamId: any, body: any, stream: any): Promise<void>;
+    /** Block until either the stream or the connection send window grows (a WINDOW_UPDATE arrives). */
+    _awaitSendWindow(stream: any): Promise<any>;
+    _wakeSendWaiters(stream: any): void;
+    _makeBodyStream(stream: any): ReadableStream<any> & {
+        completed: any;
+        trailers: any;
+    };
+    _wakePull(stream: any): void;
+    /** Called as the CONSUMER drains `n` bytes: reopen the stream and connection receive windows,
+     *  batched so a byte-at-a-time consumer does not produce a WINDOW_UPDATE storm. */
+    _consumeStream(stream: any, n: any): void;
+    _replenish(stream: any, n: any): void;
+    _replenishConn(n: any): void;
+    _readLoop(): Promise<void>;
+    _dispatchFrame(frame: any): void;
+    _onSettings(flags: any, streamId: any, payload: any): void;
+    _onHeaders(flags: any, streamId: any, payload: any): void;
+    _onContinuation(flags: any, payload: any): void;
+    /** A full header block has been assembled: HPACK-decode it (connection-fatal on failure, since
+     *  HPACK state is shared) and route it to the stream as a response head or as trailers. */
+    _completeHeaderBlock(streamId: any, block: any, endStream: any): void;
+    _deliverResponseHead(stream: any, pairs: any, endStream: any): void;
+    _deliverTrailers(stream: any, pairs: any, endStream: any): void;
+    _onData(flags: any, streamId: any, payload: any): void;
+    _onWindowUpdate(streamId: any, payload: any): void;
+    _onRstStream(streamId: any, payload: any): void;
+    _onPing(flags: any, streamId: any, payload: any): void;
+    _onGoaway(payload: any): void;
+    /** Forget a stream: drop it from the table and wake anything blocked on it. */
+    _removeStream(stream: any): void;
+    /** Reject the caller's promises for a stream. Idempotent via the deferreds' settled flags. */
+    _rejectStream(stream: any, err: any): void;
+    /** Send RST_STREAM once, telling the peer to stop spending bandwidth on a stream we gave up on. */
+    _sendRst(stream: any, errorCode: any): void;
+    /** A stream finished cleanly once both halves ended: our request fully sent, END_STREAM received. */
+    _maybeCloseStream(stream: any): void;
+    /** A failure originating with the PEER (its RST_STREAM, its GOAWAY, a connection death): reject
+     *  the caller, never RST back — RFC 9113 s5.4.2 forbids answering a reset with a reset. */
+    _failStream(stream: any, err: any): void;
+    /** A failure originating with US (malformed response, our timeout, flow-control overrun we caught):
+     *  tell the peer with RST_STREAM, then reject the caller. */
+    _resetStream(stream: any, errorCode: any, err: any): void;
+    _die(err: any): void;
+    /**
+     * Graceful shutdown: GOAWAY(NO_ERROR), then close the transport. Any live stream is failed.
+     *
+     * The GOAWAY and the writer close are BEST-EFFORT and are not awaited: a peer that has stopped
+     * reading applies backpressure that never clears, and awaiting a courtesy frame into a full
+     * buffer would hang close() forever — the exact trap the record layer avoids with its grace
+     * window. Only the transport close is awaited, because that is what actually releases the socket.
+     */
+    close(): Promise<void>;
+    _settleResolve(d: any, value: any): void;
+    _settleReject(d: any, err: any): void;
+}
+export type BodyStream = ReadableStream<Uint8Array> & {
+    completed: Promise<boolean>;
+    trailers: Promise<Headers | null>;
+};
+export type Http2ResponseHead = {
+    status: number;
+    /**
+     * always '' — HTTP/2 has no reason phrase
+     */
+    statusText: string;
+    headers: Headers;
+    /**
+     * one entry per set-cookie field, kept separate like the h1 path
+     */
+    setCookie: string[];
+    httpVersion: "2";
+    body: BodyStream;
+};
+export type Http2ConnectionOptions = {
+    /**
+     * provenance attached to responses
+     */
+    info?: import("../transport.js").ConnectionInfo | undefined;
+    /**
+     * our SETTINGS_INITIAL_WINDOW_SIZE (receive window per
+     * stream). Defaults to curl's 10 MiB; tests lower it to exercise flow control.
+     */
+    initialWindowSize?: number | undefined;
+    /**
+     * the connection receive window we open with a WINDOW_UPDATE
+     * right after SETTINGS. Defaults to curl's 1000 MiB.
+     */
+    connectionWindow?: number | undefined;
+    /**
+     * our advertised SETTINGS_MAX_CONCURRENT_STREAMS.
+     */
+    maxConcurrentStreams?: number | undefined;
+    /**
+     * our advertised SETTINGS_HEADER_TABLE_SIZE.
+     */
+    maxHeaderTableSize?: number | undefined;
+    /**
+     * self-protection cap on a decoded response header list.
+     */
+    maxHeaderListSize?: number | undefined;
+    /**
+     * called once when the connection dies, so a
+     * registry can drop it.
+     */
+    onClose?: ((err: Error | null) => void) | undefined;
+};
+import { Http2Error } from '../errors.js';
+import { ByteReader } from '../util/bytes.js';
+import { ByteWriter } from '../util/bytes.js';
+import { HpackDecoder } from './hpack.js';

package/types/http2/constants.d.ts

@@ -0,0 +1,95 @@
+/** The 24-byte client connection preface (RFC 9113 s3.4). Sent before any frame. */
+export const CONNECTION_PREFACE: Uint8Array<ArrayBuffer>;
+export namespace FRAME {
+    let DATA: number;
+    let HEADERS: number;
+    let PRIORITY: number;
+    let RST_STREAM: number;
+    let SETTINGS: number;
+    let PUSH_PROMISE: number;
+    let PING: number;
+    let GOAWAY: number;
+    let WINDOW_UPDATE: number;
+    let CONTINUATION: number;
+}
+/** Reverse map for diagnostics: an unknown type still gets a number. */
+export const FRAME_NAME: {
+    [k: string]: string;
+};
+export namespace FLAG {
+    export let END_STREAM: number;
+    export let ACK: number;
+    export let END_HEADERS: number;
+    export let PADDED: number;
+    let PRIORITY_1: number;
+    export { PRIORITY_1 as PRIORITY };
+}
+export namespace SETTINGS {
+    let HEADER_TABLE_SIZE: number;
+    let ENABLE_PUSH: number;
+    let MAX_CONCURRENT_STREAMS: number;
+    let INITIAL_WINDOW_SIZE: number;
+    let MAX_FRAME_SIZE: number;
+    let MAX_HEADER_LIST_SIZE: number;
+}
+export const SETTINGS_NAME: {
+    [k: string]: string;
+};
+export namespace H2_ERROR {
+    let NO_ERROR: number;
+    let PROTOCOL_ERROR: number;
+    let INTERNAL_ERROR: number;
+    let FLOW_CONTROL_ERROR: number;
+    let SETTINGS_TIMEOUT: number;
+    let STREAM_CLOSED: number;
+    let FRAME_SIZE_ERROR: number;
+    let REFUSED_STREAM: number;
+    let CANCEL: number;
+    let COMPRESSION_ERROR: number;
+    let CONNECT_ERROR: number;
+    let ENHANCE_YOUR_CALM: number;
+    let INADEQUATE_SECURITY: number;
+    let HTTP_1_1_REQUIRED: number;
+}
+export const H2_ERROR_NAME: {
+    [k: string]: string;
+};
+/** 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;
+/**
+ * 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;
+export const CLIENT_MAX_CONCURRENT_STREAMS: 100;
+/** 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;
+export const CLIENT_CONNECTION_WINDOW_INCREMENT: number;
+/**
+ * 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: string[];
+/** 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/types/http2/frames.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 function readFrame(reader: import("../util/bytes.js").ByteReader, maxFrameSize?: number): Promise<Frame | null>;
+/**
+ * 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: number, flags: number, streamId: number, payload?: Uint8Array): Uint8Array;
+/**
+ * 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: Array<[number, number]>, ack?: boolean): Uint8Array;
+/** A WINDOW_UPDATE frame (RFC 9113 s6.9). streamId 0 is connection-level. */
+export function windowUpdateFrame(streamId: any, increment: any): Uint8Array<ArrayBufferLike>;
+/** A RST_STREAM frame (RFC 9113 s6.4). */
+export function rstStreamFrame(streamId: any, errorCode: any): Uint8Array<ArrayBufferLike>;
+/** A PING frame (RFC 9113 s6.7). The 8-byte opaque data is echoed on ACK. */
+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 }?: {
+    endStream?: boolean | undefined;
+    endHeaders?: boolean | 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>;
+/** A DATA frame (RFC 9113 s6.1). No padding is ever emitted. */
+export function dataFrame(streamId: any, data: any, endStream: any): Uint8Array<ArrayBufferLike>;
+/**
+ * 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: Uint8Array): {
+    data: Uint8Array;
+    padLength: number;
+};
+/**
+ * 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: Uint8Array, flags: number): Uint8Array;
+/**
+ * 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: Uint8Array): Array<[number, number]>;
+/**
+ * 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: Uint8Array): number;
+/**
+ * Parse a RST_STREAM payload (exactly 4 bytes: an error code).
+ * @param {Uint8Array} payload
+ * @returns {number}
+ */
+export function parseRstStream(payload: Uint8Array): number;
+/**
+ * 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: Uint8Array): {
+    lastStreamId: number;
+    errorCode: number;
+    debug: Uint8Array;
+};
+/** 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.
+ */
+export type Frame = {
+    type: number;
+    flags: number;
+    streamId: number;
+    payload: Uint8Array;
+};

package/types/http2/hpack.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @typedef {object} HpackField
+ * @property {string} name already lowercased by the caller — HPACK does not case-fold, and
+ *   HTTP/2 forbids uppercase field names on the wire (RFC 9113 s8.2.1)
+ * @property {string} value
+ * @property {'incremental' | 'without' | 'never'} [indexing] how to represent it when it is not a
+ *   full static match. Default 'incremental', which is what curl uses for most fields.
+ */
+/**
+ * Encode an ordered list of header fields into one HPACK block. Order is preserved exactly, which
+ * is load-bearing: HTTP/2 requires all pseudo-headers before regular ones, and the pseudo-header
+ * ORDER is part of the client fingerprint the caller is matching.
+ *
+ * @param {HpackField[]} fields
+ * @returns {Uint8Array}
+ */
+export function encodeHeaderBlock(fields: HpackField[]): Uint8Array;
+/** Default SETTINGS_HEADER_TABLE_SIZE (RFC 9113 s6.5.2): the size we advertise, so the size the
+ *  peer's encoder may fill in our decoder. A size update above this is a COMPRESSION_ERROR. */
+export const DEFAULT_HEADER_TABLE_SIZE: 4096;
+/**
+ * @typedef {object} HpackDecoderOptions
+ * @property {number} [maxTableSize] the SETTINGS_HEADER_TABLE_SIZE we advertised; the dynamic
+ *   table may not exceed it and a size update above it is fatal. Default 4096.
+ * @property {number} [maxHeaderListSize] fail-closed cap on the decoded header list (sum of
+ *   name+value+32 per field). Default 262144. We do not advertise this to the peer, so it is a
+ *   self-protection bound, not a promise; over it is a LimitError.
+ */
+/**
+ * A stateful HPACK decoder. One per connection per direction: the dynamic table is shared state
+ * across every header block on the connection, so a single decoder instance must live as long as
+ * the connection does.
+ */
+export class HpackDecoder {
+    /** @param {HpackDecoderOptions} [opts] */
+    constructor({ maxTableSize, maxHeaderListSize }?: HpackDecoderOptions);
+    /** @type {Array<[string, string, number]>} name, value, entry-size — newest at index 0 */
+    _dynamic: Array<[string, string, number]>;
+    _size: number;
+    _maxSize: number;
+    _limit: number;
+    _maxHeaderListSize: number;
+    /** Current number of entries, exposed for tests that assert eviction. */
+    get dynamicLength(): number;
+    /**
+     * Look up index `i` (RFC 7541 s2.3.3: 1..STATIC_COUNT is static, above that is dynamic,
+     * newest first). Fails closed on 0 and on anything past the end of the dynamic table.
+     * @param {number} i
+     * @returns {[string, string]}
+     */
+    _lookup(i: number): [string, string];
+    /** Insert into the dynamic table, evicting oldest entries until it fits (RFC 7541 s4.4). */
+    _insert(name: any, value: any): void;
+    /** Apply a dynamic table size update (RFC 7541 s6.3), refusing one above what we advertised. */
+    _resize(newSize: any): void;
+    /**
+     * Decode one header block into an ordered list of [name, value] pairs.
+     * @param {Uint8Array} block
+     * @returns {Array<[string, string]>}
+     */
+    decode(block: Uint8Array): Array<[string, string]>;
+    /**
+     * Shared body of the three literal representations: an optionally indexed name, then a value.
+     * @param {(name: string, value: string) => void} add
+     * @param {null | ((name: string, value: string) => void)} index insert into the dynamic table, or null
+     */
+    _literal(block: any, pos: any, prefixBits: any, _fieldIndex: any, add: (name: string, value: string) => void, index: null | ((name: string, value: string) => void)): {
+        pos: number;
+    };
+}
+export type HpackField = {
+    /**
+     * already lowercased by the caller — HPACK does not case-fold, and
+     * HTTP/2 forbids uppercase field names on the wire (RFC 9113 s8.2.1)
+     */
+    name: string;
+    value: string;
+    /**
+     * how to represent it when it is not a
+     * full static match. Default 'incremental', which is what curl uses for most fields.
+     */
+    indexing?: "incremental" | "without" | "never" | undefined;
+};
+export type HpackDecoderOptions = {
+    /**
+     * the SETTINGS_HEADER_TABLE_SIZE we advertised; the dynamic
+     * table may not exceed it and a size update above it is fatal. Default 4096.
+     */
+    maxTableSize?: number | undefined;
+    /**
+     * fail-closed cap on the decoded header list (sum of
+     * name+value+32 per field). Default 262144. We do not advertise this to the peer, so it is a
+     * self-protection bound, not a promise; over it is a LimitError.
+     */
+    maxHeaderListSize?: number | undefined;
+};
+/** RFC 7541 Appendix A. Index 0 is a placeholder so table[i] is the RFC's entry i (1-based). */
+export const STATIC_TABLE: string[][];
+export const STATIC_COUNT: number;

package/types/http2/huffman.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The number of bytes `bytes` would occupy Huffman-encoded, so a caller can choose the shorter
+ * of literal and Huffman exactly the way nghttp2 does (this is what makes curl leave the accept
+ * value un-encoded when its Huffman form is not shorter).
+ * @param {Uint8Array} bytes
+ * @returns {number}
+ */
+export function huffmanEncodedLength(bytes: Uint8Array): number;
+/**
+ * Huffman-encode octets, padding the final byte with the most-significant bits of EOS (all ones)
+ * per RFC 7541 s5.2.
+ * @param {Uint8Array} bytes
+ * @returns {Uint8Array}
+ */
+export function huffmanEncode(bytes: Uint8Array): Uint8Array;
+/**
+ * Huffman-decode octets, failing closed on every error RFC 7541 s5.2 names.
+ * @param {Uint8Array} bytes
+ * @returns {Uint8Array}
+ */
+export function huffmanDecode(bytes: Uint8Array): Uint8Array;

package/types/http2/index.d.ts

@@ -0,0 +1,5 @@
+export { Http2Connection, Http2Retryable, buildRequestFields } from "./connection.js";
+export { HpackDecoder, encodeHeaderBlock } from "./hpack.js";
+export { huffmanDecode, huffmanEncode } from "./huffman.js";
+export { readFrame, serializeFrame, settingsFrame, windowUpdateFrame, dataFrame, headersFrame, parseSettings } from "./frames.js";
+export { ALPN_H2, ALPN_HTTP11 } from "./constants.js";

package/types/index.d.ts

@@ -0,0 +1,17 @@
+export { warmup } from "./warmup.js";
+export { CookieJar } from "./client/cookies.js";
+/**
+ * A ready-made fetch with default options: no proxy, system trust, one connection per call.
+ * Equivalent to httpx.get() versus httpx.Client() — reach for `new Client()` when connection
+ * reuse or a cookie jar matters, which for anything crawl-shaped it does.
+ *
+ * A `connect` function must still be supplied per call (or via `createFetch`) for any request the
+ * platform's own fetch cannot serve; see the README for why that is not defaulted.
+ */
+export const fetch: import("./client.js").FetchLike;
+export { Client, createFetch, install } from "./client.js";
+export { ConnectionPool, poolKey } from "./pool.js";
+export { openConnection, targetFromUrl, nativeFetchCanServe } from "./transport.js";
+export { openTunnel, parseProxy } from "./proxy/index.js";
+export { verifyChain, rootStoreProvenance } from "./trust/index.js";
+export { TunnelFetchError, ProxyError, HttpError, TlsError, TlsUnsupportedError, Http2Error, CertificateError, TimeoutError, LimitError, ConfigError, codes } from "./errors.js";