tunnelfetch 1.0.0

package/types/util/deadline.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Wrap a body stream so every chunk touches the idle deadline and an abort surfaces as the typed
+ * timeout error rather than a bare AbortError.
+ *
+ * The stream is consumed with a plain reader rather than piped through a TransformStream because
+ * a transform would buffer a chunk ahead, which is exactly the wrong behaviour for an idle
+ * deadline: the timer must be reset by data reaching the consumer, not by data reaching a queue.
+ *
+ * @param {ReadableStream<Uint8Array>} source
+ * @param {DeadlineController} deadlines
+ */
+export function withIdleDeadline(source: ReadableStream<Uint8Array>, deadlines: DeadlineController): ReadableStream<any>;
+/**
+ * One-shot deadline for a promise that has no stream behind it, e.g. a socket's `opened`.
+ * Prefer DeadlineController when several phases share a teardown.
+ */
+export function withDeadline(promise: any, ms: any, code: any, what: any, env?: {}): any;
+/**
+ * @typedef {object} DeadlineOptions
+ * @property {number} [connectMs]    TCP connect (and proxy handshake) must complete within this
+ * @property {number} [handshakeMs]  TLS handshake must complete within this
+ * @property {number} [headersMs]    response status line + headers must arrive within this
+ * @property {number} [idleMs]       maximum gap between body chunks
+ * @property {number} [totalMs]      hard ceiling on the whole request; a backstop, not the control
+ */
+export const DEFAULT_DEADLINES: Readonly<{
+    connectMs: 10000;
+    handshakeMs: 15000;
+    headersMs: 30000;
+    idleMs: 60000;
+    totalMs: 0;
+}>;
+/**
+ * Owns every timer for one request and exposes a single AbortSignal that fires when any of them
+ * elapses. Callers abort on the signal rather than each racing their own promise, so a timeout in
+ * one phase tears down the whole connection instead of leaking a socket into the background.
+ */
+export class DeadlineController {
+    /**
+     * @param {DeadlineOptions} options
+     * @param {{ signal?: AbortSignal, setTimer?: typeof setTimeout, clearTimer?: typeof clearTimeout }} [env]
+     */
+    constructor(options?: DeadlineOptions, env?: {
+        signal?: AbortSignal;
+        setTimer?: typeof setTimeout;
+        clearTimer?: typeof clearTimeout;
+    });
+    options: {
+        /**
+         * TCP connect (and proxy handshake) must complete within this
+         */
+        connectMs: number;
+        /**
+         * TLS handshake must complete within this
+         */
+        handshakeMs: number;
+        /**
+         * response status line + headers must arrive within this
+         */
+        headersMs: number;
+        /**
+         * maximum gap between body chunks
+         */
+        idleMs: number;
+        /**
+         * hard ceiling on the whole request; a backstop, not the control
+         */
+        totalMs: number;
+    };
+    _setTimer: typeof setTimeout;
+    _clearTimer: typeof clearTimeout;
+    _controller: AbortController;
+    /** @type {any} */
+    _phaseTimer: any;
+    _phaseName: any;
+    /** @type {any} */
+    _idleTimer: any;
+    _totalTimer: number | null;
+    _settled: boolean;
+    /** @type {TimeoutError|null} */
+    error: TimeoutError | null;
+    _onOuterAbort: (() => void) | undefined;
+    _outer: AbortSignal | undefined;
+    get signal(): AbortSignal;
+    get aborted(): boolean;
+    _abortFromOuter(outer: any): void;
+    _fire(code: any, phase: any, ms: any): void;
+    _clearAll(): void;
+    /**
+     * Start a bounded phase. Returns a function that ends it. Only one phase runs at a time; a new
+     * phase implicitly ends the previous one, which matches the actual sequence
+     * connect -> handshake -> headers and keeps callers from having to unwind by hand.
+     */
+    beginPhase(name: any): () => void;
+    endPhase(): void;
+    /**
+     * Arm the idle deadline. Call `touch()` on every byte that arrives; each touch restarts the
+     * timer. Nothing here reads a clock, which is what makes it work on a runtime whose clock is
+     * frozen between I/O events.
+     */
+    beginIdle(): void;
+    touch(): void;
+    /** Release every timer. Safe to call more than once; must be called on every exit path. */
+    dispose(): void;
+    /**
+     * Reject as soon as the signal aborts, resolve when `promise` settles first.
+     * The abort reason is preserved so the caller sees the typed TimeoutError, not a generic abort.
+     */
+    race(promise: any): Promise<any>;
+}
+export type DeadlineOptions = {
+    /**
+     * TCP connect (and proxy handshake) must complete within this
+     */
+    connectMs?: number | undefined;
+    /**
+     * TLS handshake must complete within this
+     */
+    handshakeMs?: number | undefined;
+    /**
+     * response status line + headers must arrive within this
+     */
+    headersMs?: number | undefined;
+    /**
+     * maximum gap between body chunks
+     */
+    idleMs?: number | undefined;
+    /**
+     * hard ceiling on the whole request; a backstop, not the control
+     */
+    totalMs?: number | undefined;
+};
+import { TimeoutError } from '../errors.js';

package/types/warmup-fixture.d.ts

@@ -0,0 +1,11 @@
+export const WARMUP_HOSTNAME: "warmup.invalid";
+export const WARMUP_NOW: 1893456000000;
+export namespace WARMUP_FIXTURE {
+    function clientPrivPkcs8(): Uint8Array<ArrayBuffer>;
+    function clientPubRaw(): Uint8Array<ArrayBuffer>;
+    function clientRandom(): Uint8Array<ArrayBuffer>;
+    function legacySessionId(): Uint8Array<ArrayBuffer>;
+    function clientHello(): Uint8Array<ArrayBuffer>;
+    function serverBytes(): Uint8Array<ArrayBuffer>;
+    function rootDer(): Uint8Array<ArrayBuffer>;
+}

package/types/warmup.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What one warmup() call reports. `ok` is the only field a caller usually needs; the rest exists
+ * so a failure names the exact problem rather than being a silent no-op.
+ * @typedef {object} WarmupReport
+ * @property {boolean} ok every iteration completed
+ * @property {number} iterations how many replays ran to completion
+ * @property {string | null} error first failure, if any — warmup() itself never throws
+ */
+/**
+ * Warm the hot path by replaying a recorded proxy + TLS + HTTP exchange through the real code.
+ * See the module comment for what this buys, what it costs, and when NOT to call it. Never
+ * called by the package itself; call it from module scope of your worker if — and only if —
+ * your deployment does not bill startup CPU.
+ *
+ * Safe by construction: no network, no randomness, no timers, nothing cached, and it never
+ * throws — a runtime that forbids more than expected yields `{ ok: false, error }` and the
+ * package behaves exactly as if warmup() had never been called.
+ *
+ * @param {{ iterations?: number }} [opts] replay count, default 5, clamped to 1..10. One pass
+ *   moves the hot functions out of the interpreter; more passes push V8's tiering further down
+ *   the ramp at proportionally more startup cost. Measured startup cost is roughly 10-20 ms per
+ *   iteration on current edge hardware, against the 1 s startup budget.
+ * @returns {Promise<WarmupReport>}
+ */
+export function warmup({ iterations }?: {
+    iterations?: number;
+}): Promise<WarmupReport>;
+/**
+ * What one warmup() call reports. `ok` is the only field a caller usually needs; the rest exists
+ * so a failure names the exact problem rather than being a silent no-op.
+ */
+export type WarmupReport = {
+    /**
+     * every iteration completed
+     */
+    ok: boolean;
+    /**
+     * how many replays ran to completion
+     */
+    iterations: number;
+    /**
+     * first failure, if any — warmup() itself never throws
+     */
+    error: string | null;
+};