@daloyjs/core 0.36.0 → 0.37.0

package/dist/fetch-resilience.d.ts

@@ -0,0 +1,295 @@
+/**
+ * `resilientFetch()` — circuit breaker, retry-with-backoff, and per-call
+ * timeout for outbound `fetch`, designed to layer **on top of**
+ * {@link fetchGuard} (which only covers SSRF on egress).
+ *
+ * `fetchGuard()` answers "is this outbound address safe?". This module
+ * answers "is this upstream healthy, and how do we behave when it is
+ * not?" — the operational half of a mature outbound HTTP client
+ * (timeouts that prevent a hung upstream from exhausting your event
+ * loop, bounded retries that ride out a blip without amplifying an
+ * outage, and a circuit breaker that fails fast when an upstream is
+ * clearly down). The two compose: wrap an SSRF-guarded fetch in a
+ * resilient one and you get both safety and resilience with zero runtime
+ * dependencies.
+ *
+ * ```ts
+ * import { fetchGuard, resilientFetch } from "@daloyjs/core";
+ *
+ * const safeFetch = resilientFetch({
+ *   fetch: fetchGuard(),       // SSRF floor underneath
+ *   timeoutMs: 2_000,          // abort any call that stalls past 2s
+ *   retries: 2,                // up to 2 retries on transient failures
+ *   circuitBreaker: { failureThreshold: 5, resetTimeoutMs: 30_000 },
+ * });
+ *
+ * const res = await safeFetch("https://api.example.com/things");
+ * ```
+ *
+ * ## Design notes
+ *
+ * - **Per-call timeout** is enforced with an `AbortController` that is
+ *   combined with any caller-supplied `signal`, so cancellation works in
+ *   both directions. A timeout surfaces as {@link FetchTimeoutError}; a
+ *   caller-initiated abort surfaces as the caller's own `AbortError` and
+ *   is **never** retried or counted as an upstream failure.
+ * - **Retry-with-backoff** only retries idempotent methods
+ *   (`GET`/`HEAD`/`OPTIONS`/`PUT`/`DELETE`) and a conservative set of
+ *   transient statuses (`408`, `429`, `500`, `502`, `503`, `504`) plus
+ *   network errors and timeouts. Backoff is exponential with full
+ *   jitter and honours a `Retry-After` header when present. A
+ *   {@link SsrfBlockedError} is treated as a hard refusal — never
+ *   retried, never trips the breaker.
+ * - **Circuit breaker** is a classic three-state machine
+ *   (`closed → open → half-open`). Consecutive failures past the
+ *   threshold open the circuit; while open every call fails fast with
+ *   {@link CircuitOpenError} until `resetTimeoutMs` elapses, after which
+ *   a limited number of trial requests probe the upstream. The breaker
+ *   is shared across every call made through the returned function, so a
+ *   single hot upstream is protected process-wide.
+ *
+ * @module
+ * @since 0.37.0
+ */
+/**
+ * The three states of a {@link CircuitBreaker}.
+ *
+ * - `closed` — normal operation; calls pass through and failures are
+ *   counted.
+ * - `open` — the upstream is considered down; calls fail fast with
+ *   {@link CircuitOpenError} without touching the network.
+ * - `half-open` — a recovery probe window; a limited number of trial
+ *   calls are allowed through to test whether the upstream has healed.
+ *
+ * @since 0.37.0
+ */
+export type CircuitState = "closed" | "open" | "half-open";
+/**
+ * Thrown by {@link resilientFetch} (and {@link CircuitBreaker.execute})
+ * when the circuit is open and the call is refused without hitting the
+ * network. Distinct from a network failure so callers can render a
+ * dedicated "service temporarily unavailable" path.
+ *
+ * @since 0.37.0
+ */
+export declare class CircuitOpenError extends Error {
+    /** Milliseconds until the breaker will next allow a trial request. */
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number);
+}
+/**
+ * Thrown by {@link resilientFetch} when a single attempt exceeds the
+ * configured `timeoutMs`. A caller-initiated abort (via a `signal`
+ * passed in the request init) surfaces as the caller's own `AbortError`
+ * instead and is never retried.
+ *
+ * @since 0.37.0
+ */
+export declare class FetchTimeoutError extends Error {
+    /** The timeout that was exceeded, in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Tuning for the {@link CircuitBreaker}. All fields are optional and
+ * default to a conservative posture suited to a single upstream.
+ *
+ * @since 0.37.0
+ */
+export interface CircuitBreakerOptions {
+    /**
+     * Number of consecutive failures that trips the breaker from `closed`
+     * to `open`. Default `5`.
+     */
+    failureThreshold?: number;
+    /**
+     * Time the breaker stays `open` before allowing trial requests
+     * (transition to `half-open`), in milliseconds. Default `30_000`.
+     */
+    resetTimeoutMs?: number;
+    /**
+     * Number of concurrent trial requests permitted while `half-open`.
+     * Extra calls during the probe window fail fast with
+     * {@link CircuitOpenError}. Default `1`.
+     */
+    halfOpenMaxAttempts?: number;
+    /**
+     * Number of consecutive trial successes required to close the breaker
+     * again. Default `1`.
+     */
+    successThreshold?: number;
+    /**
+     * Observe state transitions (e.g. to emit a metric or log). Called
+     * synchronously with the previous and next state.
+     */
+    onStateChange?: (next: CircuitState, previous: CircuitState) => void;
+    /**
+     * Monotonic clock, primarily for deterministic tests. Defaults to
+     * `Date.now`.
+     */
+    now?: () => number;
+}
+/**
+ * A standalone three-state circuit breaker. {@link resilientFetch}
+ * builds on this, but it is exported for callers who want to protect a
+ * non-`fetch` dependency (a database driver, a gRPC client, …) with the
+ * same semantics.
+ *
+ * @example
+ * ```ts
+ * const breaker = new CircuitBreaker({ failureThreshold: 3 });
+ * const rows = await breaker.execute(() => db.query("SELECT 1"));
+ * ```
+ *
+ * @since 0.37.0
+ */
+export declare class CircuitBreaker {
+    #private;
+    constructor(options?: CircuitBreakerOptions);
+    /** The breaker's current state, after applying any pending timeout. */
+    get state(): CircuitState;
+    /** Milliseconds until the breaker will next admit a trial request. */
+    get retryAfterMs(): number;
+    /**
+     * Run `fn` under breaker supervision. Throws {@link CircuitOpenError}
+     * immediately when the circuit is open. A thrown error (other than
+     * `CircuitOpenError`) counts as a failure; a returned value counts as
+     * a success. Use {@link recordOutcome} from {@link resilientFetch}
+     * when an HTTP *response* (not a thrown error) should count as a
+     * failure.
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Record an externally-determined outcome. Lets a caller treat a
+     * non-throwing result (e.g. an HTTP 503 response) as a failure while
+     * still flowing the value back. Returns nothing; pair with an explicit
+     * {@link admit}/{@link release} when you need full manual control.
+     */
+    recordOutcome(success: boolean): void;
+    /**
+     * Reserve a breaker slot for a manually-supervised call. Throws
+     * {@link CircuitOpenError} if the circuit will not admit the call.
+     * Must be paired with exactly one {@link recordOutcome} or
+     * {@link release}.
+     */
+    admit(): void;
+    /**
+     * Release a slot reserved by {@link admit} without recording a success
+     * or failure. Use for outcomes that are not an upstream health signal
+     * (a caller-initiated abort, an SSRF refusal). Counts and state are
+     * left untouched aside from freeing a half-open probe slot.
+     */
+    release(): void;
+}
+/**
+ * Context passed to the {@link ResilientFetchOptions.onRetry} hook and
+ * the {@link ResilientFetchOptions.isRetryable} predicate.
+ *
+ * @since 0.37.0
+ */
+export interface RetryContext {
+    /** 1-based attempt number that just failed. */
+    readonly attempt: number;
+    /** The request that was attempted. */
+    readonly request: Request;
+    /** The response received, when the failure was a retryable status. */
+    readonly response?: Response;
+    /** The error thrown, when the failure was a network error or timeout. */
+    readonly error?: unknown;
+}
+/**
+ * Options for {@link resilientFetch}. Every field is optional; the
+ * defaults bias toward safe, low-amplification behaviour.
+ *
+ * @since 0.37.0
+ */
+export interface ResilientFetchOptions {
+    /**
+     * Underlying fetch implementation. Defaults to `globalThis.fetch`.
+     * Pass a {@link fetchGuard} result to keep the SSRF floor underneath
+     * the resilience layer.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Per-attempt timeout in milliseconds. Each retry gets a fresh
+     * timeout. Set `0` to disable. Default `10_000`.
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum number of retries **after** the first attempt. `0` disables
+     * retrying. Default `2` (so up to 3 total attempts).
+     */
+    retries?: number;
+    /**
+     * Base backoff delay in milliseconds for the first retry. Default
+     * `100`.
+     */
+    retryDelayMs?: number;
+    /** Upper bound on any single backoff delay. Default `2_000`. */
+    maxRetryDelayMs?: number;
+    /** Exponential backoff multiplier. Default `2`. */
+    backoffFactor?: number;
+    /**
+     * Apply full jitter (`delay * random()`) to backoff to avoid
+     * thundering-herd retries. Default `true`.
+     */
+    jitter?: boolean;
+    /**
+     * HTTP methods that are safe to retry. Default the idempotent set:
+     * `GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`. Non-idempotent methods
+     * (`POST`, `PATCH`) are never retried unless added here.
+     */
+    retryableMethods?: readonly string[];
+    /**
+     * Response statuses that should be retried. Default
+     * `[408, 429, 500, 502, 503, 504]`.
+     */
+    retryableStatuses?: readonly number[];
+    /**
+     * Honour a `Retry-After` header on a retryable response (seconds or
+     * HTTP-date), capped by `maxRetryDelayMs`. Default `true`.
+     */
+    respectRetryAfter?: boolean;
+    /**
+     * Override the retry decision entirely. Return `true` to retry the
+     * given outcome. When provided, replaces the method/status defaults.
+     */
+    isRetryable?: (context: RetryContext) => boolean;
+    /**
+     * Observe each retry, e.g. to emit a metric. Called with the failed
+     * attempt's context and the delay before the next attempt.
+     */
+    onRetry?: (context: RetryContext, delayMs: number) => void;
+    /**
+     * Circuit breaker configuration, an existing {@link CircuitBreaker}
+     * instance to share across clients, or `false` to disable. Default
+     * enabled with {@link CircuitBreakerOptions} defaults.
+     */
+    circuitBreaker?: CircuitBreakerOptions | CircuitBreaker | false;
+    /**
+     * Response statuses that count as an upstream failure for the circuit
+     * breaker. Default `[500, 502, 503, 504]`. A failing status still
+     * flows back to the caller after retries are exhausted.
+     */
+    circuitBreakerFailureStatuses?: readonly number[];
+    /**
+     * Sleep implementation, primarily for deterministic tests. Receives
+     * the delay and an `AbortSignal` that fires if the caller cancels.
+     * Defaults to a `setTimeout`-based abortable sleep.
+     */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Wrap a `fetch` with per-call timeout, retry-with-backoff, and a shared
+ * circuit breaker. The returned function has the same call signature as
+ * the global `fetch`.
+ *
+ * Layer it over {@link fetchGuard} to keep SSRF protection underneath:
+ *
+ * ```ts
+ * const safeFetch = resilientFetch({ fetch: fetchGuard(), timeoutMs: 2_000 });
+ * ```
+ *
+ * @since 0.37.0
+ */
+export declare function resilientFetch(options?: ResilientFetchOptions): typeof fetch;