tunnelfetch 1.0.1 → 1.1.1

package/types/client.d.ts

@@ -54,8 +54,16 @@ export function install(options?: ClientOptions): () => void;
  *   one across Clients or to persist it.
  * @property {number} [maxRedirects] default 20.
  * @property {number} [maxBodyBytes] enforced from Content-Length before a byte is read.
- * @property {boolean} [decompress] gzip/deflate. Default true. Never `br`; the runtime cannot
- *   decompress it, so it is never advertised either.
+ * @property {boolean} [decompress] gzip/deflate. Default true.
+ * @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
+ *   asked for a coding it cannot decode would turn every such response into garbage. `br` and
+ *   `zstd` are not built in because the runtime's DecompressionStream has neither and this
+ *   package takes no dependencies; supply your own and the cost, and the supply chain, are
+ *   yours and visible. Measured on the edge: WASM brotli decodes at about 2x native gzip, and
+ *   the wire bytes it saves do not pay that back — see the README. The reason to turn it on is
+ *   matching a browser's Accept-Encoding, not saving CPU.
  * @property {boolean} [keepAlive] default true.
  * @property {boolean} [http2] offer HTTP/2 via ALPN and speak it when the server selects it.
  *   Default true. The goal is ACCESS, not speed — some sites treat HTTP/1.1 as a bot signal — and
@@ -75,95 +83,7 @@ export class Client {
      * @param {ClientOptions} [options]
      */
     constructor(options?: ClientOptions);
-    options: {
-        /**
-         * Socket factory. Required for any
-         * request the platform's own `fetch` cannot serve — which is every proxied request, and every
-         * request asking for a trust policy `fetch` cannot express.
-         */
-        connect?: import("./proxy/index.js").ConnectFn | undefined;
-        /**
-         * URL string or
-         * config object; `http:`, `https:`, `socks5:` and `socks5h:`.
-         */
-        proxy?: string | import("./proxy/index.js").ProxyConfig | null | undefined;
-        /**
-         * certificate policy, httpx's
-         * `verify=`. Default `{ mode: 'system' }`.
-         */
-        trust?: import("./trust/index.js").TrustConfig | undefined;
-        /**
-         * handshake knobs.
-         */
-        tls?: import("./tls/connect.js").TlsOptions | undefined;
-        /**
-         * connect / handshake /
-         * headers / idle / total, in ms. The idle gap is the control; total is a backstop.
-         */
-        timeouts?: import("./util/deadline.js").DeadlineOptions | undefined;
-        /**
-         * enable a per-Client cookie jar.
-         */
-        cookies?: boolean | undefined;
-        /**
-         * supply a jar directly, e.g. to share
-         * one across Clients or to persist it.
-         */
-        jar?: CookieJar | undefined;
-        /**
-         * default 20.
-         */
-        maxRedirects?: number | undefined;
-        /**
-         * enforced from Content-Length before a byte is read.
-         */
-        maxBodyBytes?: number | undefined;
-        /**
-         * gzip/deflate. Default true. Never `br`; the runtime cannot
-         * decompress it, so it is never advertised either.
-         */
-        decompress?: boolean | undefined;
-        /**
-         * default true.
-         */
-        keepAlive?: boolean | undefined;
-        /**
-         * offer HTTP/2 via ALPN and speak it when the server selects it.
-         * Default true. The goal is ACCESS, not speed — some sites treat HTTP/1.1 as a bot signal — and
-         * on a CPU-billed runtime h2 costs MORE than h1 (HPACK is extra work). Set false to offer only
-         * `http/1.1`. There is no fallback-and-retry either way: the server's ALPN pick is followed.
-         */
-        http2?: boolean | undefined;
-        /**
-         * never delegate to the platform's fetch, even when it could
-         * serve the request. Mainly for exercising this stack against origins that do not need it.
-         */
-        forceTunnel?: boolean | undefined;
-        /**
-         * delegation target; defaults to `globalThis.fetch`.
-         */
-        nativeFetch?: FetchLike | undefined;
-        /**
-         * connection pool sizing.
-         */
-        pool?: {
-            maxPerKey?: number;
-            maxTotal?: number;
-        } | undefined;
-        limits?: Limits | undefined;
-        /**
-         * injectable randomness and key generation.
-         */
-        deps?: import("./tls/connect.js").TlsDeps | undefined;
-        /**
-         * aborts every request this Client makes.
-         */
-        signal?: AbortSignal | undefined;
-        /**
-         * epoch ms override, for certificate validity in tests.
-         */
-        now?: number | undefined;
-    };
+    options: Readonly<ClientOptions>;
     pool: ConnectionPool;
     /** @type {Map<string, import('./http2/connection.js').Http2Connection>} */
     _h2: Map<string, import("./http2/connection.js").Http2Connection>;
@@ -172,6 +92,8 @@ export class Client {
     jar: CookieJar | null;
     tickets: TicketStore;
     _closed: boolean;
+    /** @type {Set<Promise<void>>} */
+    _inflight: Set<Promise<void>>;
     /**
      * @param {RequestInfo | URL} input
      * @param {RequestInit} [init]
@@ -180,6 +102,16 @@ export class Client {
     fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response & {
         tunnelfetch?: ResponseDetail;
     }>;
+    /**
+     * Resolve once every response body handed out by this Client has finished, one way or another —
+     * read to the end, cancelled, or failed. Deliberately NOT folded into close(): close() is the
+     * forceful teardown, and a teardown that waits on the streams it is tearing down would hang on
+     * any body the caller abandoned. This is for callers that want the graceful order.
+     *
+     * Looping rather than a single Promise.all because a body settling can start another (a redirect
+     * drains its predecessor), and a set sampled once would miss the successor.
+     */
+    idle(): Promise<void>;
     /** Release every pooled socket and shared HTTP/2 connection. A Client that is finished must be
      *  closed or sockets leak for the isolate's lifetime. */
     close(): Promise<void>;
@@ -271,10 +203,21 @@ export type ClientOptions = {
      */
     maxBodyBytes?: number | undefined;
     /**
-     * gzip/deflate. Default true. Never `br`; the runtime cannot
-     * decompress it, so it is never advertised either.
+     * gzip/deflate. Default true.
      */
     decompress?: boolean | undefined;
+    /**
+     * 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
+     * asked for a coding it cannot decode would turn every such response into garbage. `br` and
+     * `zstd` are not built in because the runtime's DecompressionStream has neither and this
+     * package takes no dependencies; supply your own and the cost, and the supply chain, are
+     * yours and visible. Measured on the edge: WASM brotli decodes at about 2x native gzip, and
+     * the wire bytes it saves do not pay that back — see the README. The reason to turn it on is
+     * matching a browser's Accept-Encoding, not saving CPU.
+     */
+    decoders?: Record<string, import("./client/decode.js").BodyDecoder> | undefined;
     /**
      * default true.
      */
@@ -316,8 +259,8 @@ export type ClientOptions = {
      */
     now?: number | undefined;
 };
-import { CookieJar } from './client/cookies.js';
 import { ConnectionPool } from './pool.js';
+import { CookieJar } from './client/cookies.js';
 import { TicketStore } from './tls/tickets.js';
 import { utf8 } from './util/bytes.js';
 export { CookieJar, ConnectionPool, utf8 };

package/types/http2/connection.d.ts

@@ -34,19 +34,6 @@ export function buildRequestFields({ method, scheme, authority, path, headers }:
  */
 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('../tls/connect.js').ByteDuplex | { readable: ReadableStream<Uint8Array>,
@@ -83,8 +70,10 @@ export class Http2Connection {
     _continuation: {
         streamId: any;
         fragments: Uint8Array<ArrayBuffer>[];
+        bytes: number;
         endStream: boolean;
     } | null;
+    _maxHeaderBlockBytes: number;
     _expectFirstSettings: boolean;
     _fatal: any;
     _goaway: {
@@ -137,6 +126,9 @@ export class Http2Connection {
         /** @type {Uint8Array[]} */
         recvQueue: Uint8Array[];
         recvEnded: boolean;
+        /** @type {number | null} declared content-length, null when absent */
+        declaredLength: number | null;
+        receivedLength: number;
         /** @type {Error | null} */
         bodyError: Error | null;
         /** @type {(() => void) | null} */
@@ -187,6 +179,14 @@ export class Http2Connection {
     _dispatchFrame(frame: any): void;
     _onSettings(flags: any, streamId: any, payload: any): void;
     _onHeaders(flags: any, streamId: any, payload: any): void;
+    /**
+     * Enforce the raw header-block cap, killing the connection when it is passed.
+     * Connection-level rather than stream-level on purpose: the fragments are HPACK input, and
+     * abandoning a partial block would leave the shared decoder desynchronised for every other
+     * stream — which RFC 9113 s4.3 makes a connection error in its own right.
+     * @returns {boolean} true when assembly may continue
+     */
+    _headerBlockWithinCap(): boolean;
     _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. */
@@ -225,24 +225,6 @@ export class Http2Connection {
     _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
@@ -270,12 +252,37 @@ export type Http2ConnectionOptions = {
      * self-protection cap on a decoded response header list.
      */
     maxHeaderListSize?: number | undefined;
+    /**
+     * cap on the RAW bytes of one HEADERS+CONTINUATION run,
+     * before HPACK decoding. Default 262144, matching the decoded cap. This is the bound that stops
+     * a CONTINUATION flood; `maxHeaderListSize` cannot, because it is only reachable once the whole
+     * block has been assembled in memory.
+     */
+    maxHeaderBlockBytes?: number | undefined;
     /**
      * called once when the connection dies, so a
      * registry can drop it.
      */
     onClose?: ((err: Error | null) => void) | undefined;
 };
+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;
+};
 import { Http2Error } from '../errors.js';
 import { ByteReader } from '../util/bytes.js';
 import { ByteWriter } from '../util/bytes.js';