@vereda/http 1.0.0

package/dist/core/types.d.ts

@@ -0,0 +1,261 @@
+import type { AppError } from "./errors.ts";
+import type { MetricsSink } from "./metrics.ts";
+export type Result<T> = {
+    success: true;
+    data: T;
+    raw: Response;
+} | {
+    success: false;
+    error: AppError;
+};
+export type ParseFn<T> = (data: unknown) => T;
+export type BackoffFn = (attempt: number) => number;
+export interface BackoffOptions {
+    /** Base delay in ms. @default {@link DEFAULT_BASE_DELAY_MS} */
+    baseDelayMs?: number;
+    /** Maximum delay cap in ms. @default {@link DEFAULT_MAX_DELAY_MS} */
+    maxDelayMs?: number;
+    /** Whether to add jitter. @default {@link DEFAULT_JITTER} */
+    jitter?: boolean;
+}
+export interface TimeoutConfig {
+    /** Per-attempt timeout in ms. Omit to inherit the client-level default;
+     *  `Infinity` explicitly means no per-attempt cap. Also bounds, from
+     *  attempt start, how long the caller has to read the body of a Response
+     *  handed back unread (a success without `parse`, or an `HttpError`'s
+     *  `.response`) before that read is aborted. */
+    attemptMs?: number;
+    /** Whole-ticket deadline in ms. Starts at request(); cancels the ticket
+     *  and resolves with DeadlineExceededError on expiry. Omit (or pass
+     *  `Infinity`) for no total deadline. Also caps how long the caller has
+     *  to read an unread Response's body handed back as above, if that's
+     *  sooner than `attemptMs` would otherwise allow. */
+    totalMs?: number;
+}
+/** `ClientConfig.timeout` variant where `attemptMs` is mandatory. Every
+ *  client must explicitly decide its per-attempt timeout — `Infinity` is a
+ *  legal, deliberate choice to opt out of a cap. This is the one default in
+ *  the library that cannot safely be implicit: every other default (retries,
+ *  concurrency, queue sizes) fails safe when omitted; an omitted timeout
+ *  fails unbounded. Partition- and request-level `timeout` stay optional —
+ *  they inherit this client-level decision unless they override it. */
+export interface ClientTimeoutConfig extends Omit<TimeoutConfig, "attemptMs"> {
+    attemptMs: number;
+}
+/** True when `ms` is a real, finite bound — not omitted and not `Infinity`
+ *  (the explicit "no cap" value). Use instead of `!== undefined` wherever a
+ *  timeout/deadline value is checked, since `Infinity` must be treated the
+ *  same as "not set" everywhere a timer would otherwise be created. */
+export declare function isBoundedMs(ms: number | undefined): ms is number;
+export declare const DEFAULT_RETRY_ON_STATUS: number[];
+/** Default per-partition concurrency limit (decision D1). */
+export declare const DEFAULT_CONCURRENCY = 5;
+/** Default max queued items per partition before rejecting new ones. */
+export declare const DEFAULT_MAX_QUEUE_SIZE = 100;
+export interface PartitionConfig {
+    /** Max concurrent in-flight retries for this partition.
+     *  @default {@link DEFAULT_CONCURRENCY} */
+    concurrency?: number;
+    /** Max number of pending items in the queue before rejecting new ones.
+     *  @default {@link DEFAULT_MAX_QUEUE_SIZE} */
+    maxQueueSize?: number;
+    /** When true, the first attempt also goes through the bulkhead (R6).
+     *  @default false */
+    limitFirstAttempts?: boolean;
+    retry?: RetryConfig;
+    timeout?: TimeoutConfig;
+    circuitBreaker?: CircuitBreakerConfig;
+}
+/** Default consecutive-failure count that trips the circuit open. */
+export declare const DEFAULT_FAILURE_THRESHOLD = 5;
+/** Default ms to stay open before allowing a half-open trial. */
+export declare const DEFAULT_RESET_TIMEOUT_MS = 30000;
+/** Default number of concurrent trial requests allowed while half-open. */
+export declare const DEFAULT_HALF_OPEN_MAX_ATTEMPTS = 1;
+export interface CircuitBreakerConfig {
+    /** @default false */
+    enabled?: boolean;
+    /** Consecutive-failure trip mode (default strategy).
+     *  @default {@link DEFAULT_FAILURE_THRESHOLD} */
+    failureThreshold?: number;
+    /** Rolling-window trip mode. If set, used INSTEAD of failureThreshold. */
+    window?: {
+        sizeMs: number;
+        failureRatePercent: number;
+        minimumRequests: number;
+    };
+    /** ms to stay open before allowing a half-open trial.
+     *  @default {@link DEFAULT_RESET_TIMEOUT_MS} */
+    resetTimeoutMs?: number;
+    /** concurrent trial requests allowed while half-open.
+     *  @default {@link DEFAULT_HALF_OPEN_MAX_ATTEMPTS} */
+    halfOpenMaxAttempts?: number;
+    /** Override default failure classification (network/timeout/retryable_status).
+     *  Not consulted for an error that shows the attempt never reached the host
+     *  (e.g. a body factory that threw before the request was dispatched) —
+     *  those are always ignored, since there is no host-health signal to classify. */
+    isFailure?: (error: AppError) => boolean;
+}
+/** Default number of retries after the first attempt. */
+export declare const DEFAULT_MAX_RETRIES = 3;
+export interface RetryConfig {
+    /** Retries after the first attempt. `MaxRetriesExceededError.attempts` is
+     *  total executions, i.e. `maxRetries + 1`.
+     *  @default {@link DEFAULT_MAX_RETRIES} */
+    maxRetries?: number;
+    /** @default `{ baseDelayMs: 200, maxDelayMs: 30_000, jitter: true }` */
+    backoff?: BackoffFn | BackoffOptions;
+    /** HTTP status codes that trigger retry (e.g. 408, 429, 500, 502, 503, 504).
+     *  @default {@link DEFAULT_RETRY_ON_STATUS} */
+    retryOnStatus?: number[];
+    /** Allows retrying non-idempotent methods (POST/PATCH/CONNECT). An
+     *  `Idempotency-Key` header also enables retries. Default: false. */
+    idempotent?: boolean;
+    /** Optional predicate to decide whether a failed attempt should be retried.
+     *  Called exactly once per failed attempt that could still be retried, with
+     *  the zero-based attempt number:
+     *  - 0 = the first attempt (called client-side before the retry loop)
+     *  - 1, 2, … = retries (called inside the loop, after attempt 0)
+     *  Returning `false` surfaces the error immediately without retrying. Not
+     *  called after the final attempt when no retries remain — there is
+     *  nothing left to decide. */
+    retryWhen?: (error: AppError, attempt: number) => boolean;
+}
+export interface Logger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+export type LifecycleEventMap = {
+    request: {
+        ticketId: string;
+        url: string;
+        method: string;
+        partition: string;
+    };
+    /** Zero-based retry index (0 = first retry after the initial attempt).
+     *  Note: retryWhen's attempt parameter uses a different numbering —
+     *  0 = first attempt, 1 = first retry, etc. */
+    retry: {
+        ticketId: string;
+        url: string;
+        partition: string;
+        attempt: number;
+        delayMs: number;
+        error: AppError;
+    };
+    success: {
+        ticketId: string;
+        url: string;
+        partition: string;
+        attempts: number;
+        durationMs: number;
+        queuedMs: number;
+        statusCode: number;
+    };
+    failure: {
+        ticketId: string;
+        url: string;
+        /** `undefined` only when the URL couldn't be resolved, so no partition
+         *  was ever chosen (no `request` event is emitted in that case either). */
+        partition: string | undefined;
+        attempts: number;
+        durationMs: number;
+        queuedMs: number;
+        error: AppError;
+    };
+    cancelled: {
+        ticketId: string;
+        url: string;
+        partition: string;
+        attempts: number;
+        durationMs: number;
+        queuedMs: number;
+    };
+    circuitOpen: {
+        partition: string;
+    };
+    circuitClose: {
+        partition: string;
+    };
+};
+export interface RequestOptions<T = unknown> {
+    /** @default "GET" */
+    method?: string;
+    headers?: HeadersInit;
+    /** Request body, or a factory that returns a fresh body on every attempt
+     *  (replayable body). A ReadableStream must be supplied via a factory. The
+     *  factory must return a fresh body each invocation — reusing the same
+     *  ReadableStream replays an already-consumed (empty) stream. */
+    body?: BodyInit | (() => BodyInit);
+    /** Named bulkhead partition. Defaults to `host` (hostname + port when non-default). */
+    partition?: string;
+    /** Schema parse function. Use withZod() or custom. */
+    parse?: ParseFn<T>;
+    retry?: RetryConfig;
+    timeout?: TimeoutConfig;
+    /** Signal to cancel the request externally */
+    signal?: AbortSignal;
+}
+/** Request options with `parse` set: the ticket resolves with `data: T`. */
+export type ParsedRequestOptions<T> = Omit<RequestOptions<T>, "parse"> & {
+    parse: ParseFn<T>;
+};
+/** Request options without `parse`: the body is left unread on `raw` and
+ *  `data` is `undefined`. `parse: undefined` is accepted so options can be
+ *  built conditionally. */
+export type UnparsedRequestOptions = Omit<RequestOptions, "parse"> & {
+    parse?: undefined;
+};
+/** Default global concurrency cap across all partitions (decision D1). */
+export declare const DEFAULT_GLOBAL_CONCURRENCY = 50;
+/** Default max requests queued globally, across all partitions, waiting for
+ *  a concurrency permit before new requests are rejected with QueueFullError. */
+export declare const DEFAULT_GLOBAL_QUEUE_SIZE = 100;
+export interface ClientConfig {
+    /** Base URL prepended to all requests */
+    baseUrl?: string;
+    /** Default retry config */
+    retry?: RetryConfig;
+    /** Default timeout config. `attemptMs` is required — pass `Infinity` to
+     *  explicitly opt out of a per-attempt cap, so "no timeout" is always a
+     *  deliberate choice rather than an accidental default. */
+    timeout: ClientTimeoutConfig;
+    /** Global concurrency across all partitions.
+     *  @default {@link DEFAULT_GLOBAL_CONCURRENCY} */
+    concurrency?: number;
+    /** Max requests queued globally (across all partitions) waiting for a
+     *  concurrency permit before new requests are rejected with QueueFullError.
+     *  @default {@link DEFAULT_GLOBAL_QUEUE_SIZE} */
+    maxQueueSize?: number;
+    /** Per-partition overrides. Partitions not listed here use
+     *  `{ concurrency: 5, maxQueueSize: 100 }`.
+     *  @default {} */
+    partitions?: Record<string, PartitionConfig>;
+    /** Default circuit breaker config. Opt-in — inert unless `enabled: true`. */
+    circuitBreaker?: CircuitBreakerConfig;
+    /** Optional structured logger */
+    logger?: Logger;
+    /** Optional metrics sink for counters, histograms, and gauges. */
+    metrics?: MetricsSink;
+    /** Redact query parameter values in logged URLs.
+     *  @default true */
+    redactQuery?: boolean;
+    /** Custom fetch function (defaults to globalThis.fetch). */
+    fetch?: typeof globalThis.fetch;
+}
+/** Options for `HttpClient.close()`.
+ *
+ *  Modelled as a union so the type mirrors the runtime contract: `timeoutMs` is
+ *  required only when draining. A single `{ drain?: boolean; timeoutMs: number }`
+ *  shape made `close({ drain: false })` a type error even though it is the
+ *  documented, working way to close without draining. */
+export type CloseOptions = {
+    drain?: false;
+    timeoutMs?: number;
+} | {
+    drain: true;
+    timeoutMs: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/core/types.js

@@ -0,0 +1,41 @@
+/** True when `ms` is a real, finite bound — not omitted and not `Infinity`
+ *  (the explicit "no cap" value). Use instead of `!== undefined` wherever a
+ *  timeout/deadline value is checked, since `Infinity` must be treated the
+ *  same as "not set" everywhere a timer would otherwise be created. */
+export function isBoundedMs(ms) {
+    return ms !== undefined && Number.isFinite(ms);
+}
+// ---------------------------------------------------------------------------
+// Default retry-on-status codes (D1)
+// ---------------------------------------------------------------------------
+export const DEFAULT_RETRY_ON_STATUS = [408, 425, 429, 500, 502, 503, 504];
+// ---------------------------------------------------------------------------
+// Partition / bulkhead config
+// ---------------------------------------------------------------------------
+/** Default per-partition concurrency limit (decision D1). */
+export const DEFAULT_CONCURRENCY = 5;
+/** Default max queued items per partition before rejecting new ones. */
+export const DEFAULT_MAX_QUEUE_SIZE = 100;
+// ---------------------------------------------------------------------------
+// Circuit breaker config
+// ---------------------------------------------------------------------------
+/** Default consecutive-failure count that trips the circuit open. */
+export const DEFAULT_FAILURE_THRESHOLD = 5;
+/** Default ms to stay open before allowing a half-open trial. */
+export const DEFAULT_RESET_TIMEOUT_MS = 30_000;
+/** Default number of concurrent trial requests allowed while half-open. */
+export const DEFAULT_HALF_OPEN_MAX_ATTEMPTS = 1;
+// ---------------------------------------------------------------------------
+// Retry config
+// ---------------------------------------------------------------------------
+/** Default number of retries after the first attempt. */
+export const DEFAULT_MAX_RETRIES = 3;
+// ---------------------------------------------------------------------------
+// Client config
+// ---------------------------------------------------------------------------
+/** Default global concurrency cap across all partitions (decision D1). */
+export const DEFAULT_GLOBAL_CONCURRENCY = 50;
+/** Default max requests queued globally, across all partitions, waiting for
+ *  a concurrency permit before new requests are rejected with QueueFullError. */
+export const DEFAULT_GLOBAL_QUEUE_SIZE = 100;
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AA4DA;;;uEAGuE;AACvE,MAAM,UAAU,WAAW,CAAC,EAAsB;IACjD,OAAO,EAAE,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,8EAA8E;AAC9E,qCAAqC;AACrC,8EAA8E;AAE9E,MAAM,CAAC,MAAM,uBAAuB,GAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAErF,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E,6DAA6D;AAC7D,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,wEAAwE;AACxE,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAiB1C,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E,qEAAqE;AACrE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAC3C,iEAAiE;AACjE,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAC/C,2EAA2E;AAC3E,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC;AA2BhD,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,yDAAyD;AACzD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAqHrC,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAC7C;iFACiF;AACjF,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAC"}

package/dist/core/validate.d.ts

@@ -0,0 +1,19 @@
+import type { ClientConfig, RequestOptions } from "./types.ts";
+/** Realm-safe ReadableStream detection — instanceof fails across realms
+ *  (vm contexts, other copies of node:stream/web). No non-stream BodyInit
+ *  member has getReader, so duck-typing is safe here. */
+export declare function isReadableStream(body: unknown): body is ReadableStream;
+/** A raw ReadableStream body cannot be replayed across retries, so it must be
+ *  supplied via a factory. Throws ConfigurationError otherwise. */
+export declare function validateRequestBody(body: BodyInit | (() => BodyInit) | undefined): void;
+export declare function validateConfig(config: ClientConfig): void;
+/** Validates a single request's own `timeout`/`retry` options — the raw
+ *  values passed to `client.get()`/`.post()`/etc., before they're merged onto
+ *  partition/client defaults. Reuses the same rules as `validateConfig`, so
+ *  an invalid request-level value (e.g. `timeout: { attemptMs: -5 }`) is
+ *  rejected the same way an invalid client config is, just surfaced as a
+ *  ticket `ConfigurationError` instead of a throw from `create()`. Omitted
+ *  fields stay valid (inherit the client/partition default), and `Infinity`
+ *  stays a legal explicit `attemptMs`/`totalMs`. */
+export declare function validateRequestOptions(options: Pick<RequestOptions, "timeout" | "retry">): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/core/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/core/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEX,YAAY,EAEZ,cAAc,EAGd,MAAM,YAAY,CAAC;AAUpB;;yDAEyD;AACzD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,cAAc,CAEtE;AAED;mEACmE;AACnE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,CAAC,MAAM,QAAQ,CAAC,GAAG,SAAS,GAAG,IAAI,CAIvF;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAuBzD;AAED;;;;;;;oDAOoD;AACpD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,OAAO,CAAC,GAAG,IAAI,CAG/F"}

package/dist/core/validate.js

@@ -0,0 +1,135 @@
+import { ConfigurationError } from "./errors.js";
+// Every numeric check is written so that NaN fails it: `NaN <= 0` is false,
+// so a bare `x <= 0` guard would let NaN through (and `attemptMs: NaN` would
+// silently mean "no timeout"). `!(x > 0)` rejects it.
+function isPositiveInteger(value) {
+    return Number.isInteger(value) && value >= 1;
+}
+/** Realm-safe ReadableStream detection — instanceof fails across realms
+ *  (vm contexts, other copies of node:stream/web). No non-stream BodyInit
+ *  member has getReader, so duck-typing is safe here. */
+export function isReadableStream(body) {
+    return body != null && typeof body.getReader === "function";
+}
+/** A raw ReadableStream body cannot be replayed across retries, so it must be
+ *  supplied via a factory. Throws ConfigurationError otherwise. */
+export function validateRequestBody(body) {
+    if (isReadableStream(body)) {
+        throw new ConfigurationError("body must be supplied as a factory (() => BodyInit) when it is a ReadableStream");
+    }
+}
+export function validateConfig(config) {
+    if (config.baseUrl !== undefined && !URL.canParse(config.baseUrl)) {
+        throw new ConfigurationError("baseUrl must be an absolute URL");
+    }
+    if (config.concurrency !== undefined && !isPositiveInteger(config.concurrency)) {
+        throw new ConfigurationError("concurrency must be a positive integer");
+    }
+    // 0 is valid globally: no waiting, overflow rejects with QueueFullError.
+    if (config.maxQueueSize !== undefined && !(Number.isInteger(config.maxQueueSize) && config.maxQueueSize >= 0)) {
+        throw new ConfigurationError("maxQueueSize must be a non-negative integer");
+    }
+    if (!config.timeout || config.timeout.attemptMs === undefined) {
+        throw new ConfigurationError("timeout.attemptMs is required — pass a positive number, or Infinity to explicitly opt out of a per-attempt timeout");
+    }
+    validateTimeoutConfig(config.timeout, "timeout");
+    validateRetryConfig(config.retry, "retry");
+    validateCircuitBreakerConfig(config.circuitBreaker, "circuitBreaker");
+    validatePartitions(config.partitions);
+}
+/** Validates a single request's own `timeout`/`retry` options — the raw
+ *  values passed to `client.get()`/`.post()`/etc., before they're merged onto
+ *  partition/client defaults. Reuses the same rules as `validateConfig`, so
+ *  an invalid request-level value (e.g. `timeout: { attemptMs: -5 }`) is
+ *  rejected the same way an invalid client config is, just surfaced as a
+ *  ticket `ConfigurationError` instead of a throw from `create()`. Omitted
+ *  fields stay valid (inherit the client/partition default), and `Infinity`
+ *  stays a legal explicit `attemptMs`/`totalMs`. */
+export function validateRequestOptions(options) {
+    validateTimeoutConfig(options.timeout, "request.timeout");
+    validateRetryConfig(options.retry, "request.retry");
+}
+function validateTimeoutConfig(timeout, prefix) {
+    if (!timeout)
+        return;
+    if (timeout.attemptMs !== undefined && !(timeout.attemptMs > 0)) {
+        throw new ConfigurationError(`${prefix}.attemptMs must be positive`);
+    }
+    if (timeout.totalMs !== undefined && !(timeout.totalMs > 0)) {
+        throw new ConfigurationError(`${prefix}.totalMs must be positive`);
+    }
+}
+function validateRetryConfig(retry, prefix) {
+    if (!retry)
+        return;
+    if (retry.maxRetries !== undefined && !(Number.isInteger(retry.maxRetries) && retry.maxRetries >= 0)) {
+        throw new ConfigurationError(`${prefix}.maxRetries must be a non-negative integer`);
+    }
+    if (retry.retryOnStatus !== undefined) {
+        for (const status of retry.retryOnStatus) {
+            if (!Number.isInteger(status) || status < 400 || status > 599) {
+                throw new ConfigurationError(`${prefix}.retryOnStatus must contain only integer HTTP error status codes (400-599)`);
+            }
+        }
+    }
+    if (retry.backoff && typeof retry.backoff === "object") {
+        const { baseDelayMs, maxDelayMs } = retry.backoff;
+        if (baseDelayMs !== undefined && !(baseDelayMs >= 0)) {
+            throw new ConfigurationError(`${prefix}.backoff.baseDelayMs must be non-negative`);
+        }
+        if (maxDelayMs !== undefined && !(maxDelayMs >= 0)) {
+            throw new ConfigurationError(`${prefix}.backoff.maxDelayMs must be non-negative`);
+        }
+        if (baseDelayMs !== undefined && maxDelayMs !== undefined && baseDelayMs > maxDelayMs) {
+            throw new ConfigurationError(`${prefix}.backoff.baseDelayMs must not exceed maxDelayMs`);
+        }
+    }
+}
+function validatePartitions(partitions) {
+    if (!partitions)
+        return;
+    for (const [name, config] of Object.entries(partitions)) {
+        if (config.concurrency !== undefined && !isPositiveInteger(config.concurrency)) {
+            throw new ConfigurationError(`partitions.${name}.concurrency must be a positive integer`);
+        }
+        if (config.maxQueueSize !== undefined && !isPositiveInteger(config.maxQueueSize)) {
+            throw new ConfigurationError(`partitions.${name}.maxQueueSize must be a positive integer`);
+        }
+        validateRetryConfig(config.retry, `partitions.${name}.retry`);
+        validateTimeoutConfig(config.timeout, `partitions.${name}.timeout`);
+        validateCircuitBreakerConfig(config.circuitBreaker, `partitions.${name}.circuitBreaker`);
+    }
+}
+function validateCircuitBreakerConfig(breaker, prefix) {
+    if (!breaker)
+        return;
+    if (breaker.failureThreshold !== undefined && !isPositiveInteger(breaker.failureThreshold)) {
+        throw new ConfigurationError(`${prefix}.failureThreshold must be a positive integer`);
+    }
+    // Finite: the open -> half-open transition is a timer, and an unbounded
+    // reset would keep the circuit open forever.
+    if (breaker.resetTimeoutMs !== undefined &&
+        !(Number.isFinite(breaker.resetTimeoutMs) && breaker.resetTimeoutMs > 0)) {
+        throw new ConfigurationError(`${prefix}.resetTimeoutMs must be a positive finite number`);
+    }
+    // 0 would admit no half-open trial, so the circuit could never close again.
+    if (breaker.halfOpenMaxAttempts !== undefined && !isPositiveInteger(breaker.halfOpenMaxAttempts)) {
+        throw new ConfigurationError(`${prefix}.halfOpenMaxAttempts must be a positive integer`);
+    }
+    if (breaker.isFailure !== undefined && typeof breaker.isFailure !== "function") {
+        throw new ConfigurationError(`${prefix}.isFailure must be a function`);
+    }
+    const { window } = breaker;
+    if (window === undefined)
+        return;
+    if (!(Number.isFinite(window.sizeMs) && window.sizeMs > 0)) {
+        throw new ConfigurationError(`${prefix}.window.sizeMs must be a positive finite number`);
+    }
+    if (!(window.failureRatePercent > 0 && window.failureRatePercent <= 100)) {
+        throw new ConfigurationError(`${prefix}.window.failureRatePercent must be greater than 0 and at most 100`);
+    }
+    if (!isPositiveInteger(window.minimumRequests)) {
+        throw new ConfigurationError(`${prefix}.window.minimumRequests must be a positive integer`);
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/core/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/core/validate.ts"],"names":[],"mappings":"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"}

package/dist/middleware/index.d.ts

@@ -0,0 +1,26 @@
+export type { MiddlewareFn, NextFn, RequestContext } from "../queue/executor.ts";
+/**
+ * Adds a base set of headers to every request. Only sets a header the
+ * request doesn't already have — comparison is case-insensitive, so a
+ * request-level `authorization` header wins over a default `Authorization`.
+ *
+ * @example
+ * client.use(defaultHeaders({ 'X-Api-Key': 'secret' }));
+ */
+export declare function defaultHeaders(headers: HeadersInit): import("../queue/executor.ts").MiddlewareFn;
+/**
+ * Logs request timing to the console (or a provided logger). Logged URLs are
+ * redacted like the client's own (`redactUrl`): query values and userinfo
+ * credentials are replaced with `[redacted]`. Middleware can't see the
+ * client's `redactQuery` setting, so pass `redactQuery: false` here too to
+ * log raw URLs.
+ *
+ * @example
+ * client.use(requestLogger());
+ */
+export declare function requestLogger(options?: {
+    log?: (msg: string, meta: Record<string, unknown>) => void;
+    /** @default true */
+    redactQuery?: boolean;
+}): import("../queue/executor.ts").MiddlewareFn;
+//# sourceMappingURL=index.d.ts.map

package/dist/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEjF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,sBAAsB,EAAE,YAAY,CAShG;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE;IACvC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC3D,oBAAoB;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,sBAAsB,EAAE,YAAY,CAyB9C"}

package/dist/middleware/index.js

@@ -0,0 +1,55 @@
+import { redactUrl } from "../core/redact.js";
+/**
+ * Adds a base set of headers to every request. Only sets a header the
+ * request doesn't already have — comparison is case-insensitive, so a
+ * request-level `authorization` header wins over a default `Authorization`.
+ *
+ * @example
+ * client.use(defaultHeaders({ 'X-Api-Key': 'secret' }));
+ */
+export function defaultHeaders(headers) {
+    return async (ctx, next) => {
+        for (const [key, value] of new Headers(headers)) {
+            if (!ctx.headers.has(key)) {
+                ctx.headers.set(key, value);
+            }
+        }
+        return next(ctx);
+    };
+}
+/**
+ * Logs request timing to the console (or a provided logger). Logged URLs are
+ * redacted like the client's own (`redactUrl`): query values and userinfo
+ * credentials are replaced with `[redacted]`. Middleware can't see the
+ * client's `redactQuery` setting, so pass `redactQuery: false` here too to
+ * log raw URLs.
+ *
+ * @example
+ * client.use(requestLogger());
+ */
+export function requestLogger(options) {
+    // biome-ignore lint/suspicious/noConsole: console is the intended default sink for this opt-in logger middleware; callers override it via options.log.
+    const log = options?.log ?? ((msg, meta) => console.log(msg, meta));
+    const shownUrl = options?.redactQuery === false ? (url) => url : redactUrl;
+    return async (ctx, next) => {
+        const start = Date.now();
+        try {
+            const response = await next(ctx);
+            log("Request completed", {
+                url: shownUrl(ctx.url),
+                status: response.status,
+                durationMs: Date.now() - start,
+            });
+            return response;
+        }
+        catch (err) {
+            log("Request failed", {
+                url: shownUrl(ctx.url),
+                error: err instanceof Error ? err.message : String(err),
+                durationMs: Date.now() - start,
+            });
+            throw err;
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAI9C;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,OAAoB;IAClD,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACjD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3B,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC7B,CAAC;QACF,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;IAClB,CAAC,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,OAI7B;IACA,uJAAuJ;IACvJ,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;IAEpE,MAAM,QAAQ,GAAG,OAAO,EAAE,WAAW,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnF,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,CAAC;YACJ,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;YACjC,GAAG,CAAC,mBAAmB,EAAE;gBACxB,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;gBACtB,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;aAC9B,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC;QACjB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,GAAG,CAAC,gBAAgB,EAAE;gBACrB,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;gBACtB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;gBACvD,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;aAC9B,CAAC,CAAC;YACH,MAAM,GAAG,CAAC;QACX,CAAC;IACF,CAAC,CAAC;AACH,CAAC"}

package/dist/queue/bulkhead.d.ts

@@ -0,0 +1,63 @@
+import { type PartitionConfig } from "../core/types.ts";
+import type { Semaphore } from "./semaphore.ts";
+/** Default TTL (ms) before an idle partition registry entry (bulkhead or
+ *  circuit breaker) is swept from its registry. Shared by both registries
+ *  so the eviction policy stays in one place. */
+export declare const DEFAULT_PARTITION_TTL_MS = 60000;
+export declare class Bulkhead {
+    readonly name: string;
+    private readonly concurrency;
+    private readonly maxQueueSize;
+    private readonly _limitFirstAttempts;
+    private running;
+    private readonly _waitQueue;
+    constructor(name: string, config?: PartitionConfig);
+    get queueSize(): number;
+    get runningCount(): number;
+    get concurrencyLimit(): number;
+    get maxQueueSizeLimit(): number;
+    get limitFirstAttempts(): boolean;
+    /** Acquire a concurrency slot, execute `task`, release the slot.
+     *  Rejects with `QueueFullError` when the queue is at capacity.
+     *  `this.running` is decremented *before* the returned Promise resolves,
+     *  giving consumers an accurate count immediately after `await`.
+     *  When a global `semaphore` is provided, a permit is acquired after the
+     *  partition slot and released before it (D4).
+     *  `onDequeue`, if given, fires once — right before `task()` starts —
+     *  with the ms elapsed since `run()` was called, covering both the
+     *  partition wait and the semaphore wait.
+     *  If `signal` aborts while the caller is still waiting (for a partition
+     *  slot or a global permit), it leaves the queue and the promise rejects
+     *  with `CancelledError` without running `task` (B9). Once `task` has
+     *  started, cancelling it is the task's own job. */
+    run<T>(task: () => Promise<T>, semaphore?: Semaphore, onDequeue?: (queuedMs: number) => void, signal?: AbortSignal): Promise<T>;
+    /** Free a counted slot and hand it to the next waiter, if any. Every path
+     *  that decrements `running` — task success, task failure, and a rejected
+     *  semaphore acquire after the slot was already granted — must go through
+     *  this, or a slot leaks as permanently phantom-running. */
+    private _releaseSlot;
+    private _drainWaitQueue;
+}
+export interface BulkheadSnapshot {
+    name: string;
+    running: number;
+    queued: number;
+    concurrency: number;
+    maxQueueSize: number;
+}
+export declare class BulkheadRegistry {
+    private readonly bulkheads;
+    private readonly ttlMs;
+    private readonly globalConfig;
+    private readonly partitionConfigs;
+    private readonly sweepInterval;
+    private readonly semaphore?;
+    private callCounter;
+    constructor(globalConfig?: PartitionConfig, partitionConfigs?: Record<string, PartitionConfig>, ttlMs?: number, semaphore?: Semaphore);
+    get(partitionName: string): Bulkhead;
+    prune(): void;
+    delete(partitionName: string): void;
+    getAll(): BulkheadSnapshot[];
+    getSemaphore(): Semaphore | undefined;
+}
+//# sourceMappingURL=bulkhead.d.ts.map

package/dist/queue/bulkhead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulkhead.d.ts","sourceRoot":"","sources":["../../src/queue/bulkhead.ts"],"names":[],"mappings":"AACA,OAAO,EAA+C,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACrG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;iDAEiD;AACjD,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,qBAAa,QAAQ;IACpB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAU;IAC9C,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;gBAExC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,eAAoB;IAOtD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,IAAI,kBAAkB,IAAI,OAAO,CAEhC;IAED;;;;;;;;;;;;wDAYoD;IACpD,GAAG,CAAC,CAAC,EACJ,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,SAAS,CAAC,EAAE,SAAS,EACrB,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACtC,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,CAAC,CAAC;IA0Eb;;;gEAG4D;IAC5D,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,eAAe;CAMvB;AAMD,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACrB;AAID,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;IAC9D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkB;IAC/C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkC;IACnE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAY;IACvC,OAAO,CAAC,WAAW,CAAK;gBAGvB,YAAY,GAAE,eAAoB,EAClC,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAM,EACtD,KAAK,GAAE,MAAiC,EACxC,SAAS,CAAC,EAAE,SAAS;IAStB,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,QAAQ;IAuBpC,KAAK,IAAI,IAAI;IASb,MAAM,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;IAInC,MAAM,IAAI,gBAAgB,EAAE;IAc5B,YAAY,IAAI,SAAS,GAAG,SAAS;CAGrC"}