@vereda/http 1.0.0

package/dist/queue/bulkhead.js

@@ -0,0 +1,192 @@
+import { CancelledError, QueueFullError } from "../core/errors.js";
+import { DEFAULT_CONCURRENCY, DEFAULT_MAX_QUEUE_SIZE } from "../core/types.js";
+/** 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 const DEFAULT_PARTITION_TTL_MS = 60_000;
+export class Bulkhead {
+    name;
+    concurrency;
+    maxQueueSize;
+    _limitFirstAttempts;
+    running = 0;
+    _waitQueue = [];
+    constructor(name, config = {}) {
+        this.name = name;
+        this.concurrency = config.concurrency ?? DEFAULT_CONCURRENCY;
+        this.maxQueueSize = config.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE;
+        this._limitFirstAttempts = config.limitFirstAttempts ?? false;
+    }
+    get queueSize() {
+        return this._waitQueue.length;
+    }
+    get runningCount() {
+        return this.running;
+    }
+    get concurrencyLimit() {
+        return this.concurrency;
+    }
+    get maxQueueSizeLimit() {
+        return this.maxQueueSize;
+    }
+    get limitFirstAttempts() {
+        return this._limitFirstAttempts;
+    }
+    /** 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(task, semaphore, onDequeue, signal) {
+        const enqueuedAt = Date.now();
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(new CancelledError());
+                return;
+            }
+            const onAbort = () => {
+                const idx = this._waitQueue.indexOf(execute);
+                if (idx !== -1)
+                    this._waitQueue.splice(idx, 1);
+                reject(new CancelledError());
+            };
+            const execute = () => {
+                signal?.removeEventListener("abort", onAbort);
+                this.running++;
+                // `release`, when given, must run BEFORE _releaseSlot(): releasing
+                // the slot synchronously drains the next waiter, which may call
+                // semaphore.acquire() immediately — if the permit hasn't actually
+                // been freed yet (i.e. this ran after _releaseSlot instead of
+                // before), that acquire can spuriously see none available and
+                // reject even though one was about to free.
+                const runTask = (release) => {
+                    onDequeue?.(Date.now() - enqueuedAt);
+                    return task().then((result) => {
+                        release?.();
+                        this._releaseSlot();
+                        resolve(result);
+                    }, (err) => {
+                        release?.();
+                        this._releaseSlot();
+                        reject(err);
+                    });
+                };
+                if (semaphore) {
+                    semaphore.acquire(signal).then((release) => {
+                        // void: outcomes are routed to the outer resolve/reject inside runTask.
+                        void runTask(release);
+                    }, (err) => {
+                        // The partition slot was granted but the global semaphore
+                        // rejected (queue full, or cancelled while waiting for a
+                        // permit) — release the slot we already
+                        // counted, or it leaks as a permanently phantom-running slot.
+                        // Report how long this attempt actually waited before being
+                        // told no; it never reached runTask's own onDequeue call.
+                        onDequeue?.(Date.now() - enqueuedAt);
+                        this._releaseSlot();
+                        reject(err);
+                    });
+                }
+                else {
+                    // void: outcomes are routed to the outer resolve/reject inside runTask.
+                    void runTask();
+                }
+            };
+            if (this.running < this.concurrency) {
+                execute();
+            }
+            else if (this._waitQueue.length < this.maxQueueSize) {
+                signal?.addEventListener("abort", onAbort, { once: true });
+                this._waitQueue.push(execute);
+            }
+            else {
+                reject(new QueueFullError(this.name, this._waitQueue.length, this.maxQueueSize));
+            }
+        });
+    }
+    /** 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. */
+    _releaseSlot() {
+        this.running--;
+        this._drainWaitQueue();
+    }
+    _drainWaitQueue() {
+        while (this.running < this.concurrency && this._waitQueue.length > 0) {
+            const next = this._waitQueue.shift();
+            next();
+        }
+    }
+}
+export class BulkheadRegistry {
+    bulkheads = new Map();
+    ttlMs;
+    globalConfig;
+    partitionConfigs;
+    sweepInterval;
+    semaphore;
+    callCounter = 0;
+    constructor(globalConfig = {}, partitionConfigs = {}, ttlMs = DEFAULT_PARTITION_TTL_MS, semaphore) {
+        this.ttlMs = ttlMs;
+        this.globalConfig = globalConfig;
+        this.partitionConfigs = partitionConfigs;
+        this.sweepInterval = 10;
+        this.semaphore = semaphore;
+    }
+    get(partitionName) {
+        this.callCounter++;
+        if (!this.bulkheads.has(partitionName)) {
+            const partitionConfig = this.partitionConfigs[partitionName] ?? {};
+            const merged = {
+                ...this.globalConfig,
+                ...partitionConfig,
+            };
+            this.bulkheads.set(partitionName, [new Bulkhead(partitionName, merged), Date.now()]);
+        }
+        const [bh] = this.bulkheads.get(partitionName);
+        // Update last accessed time
+        this.bulkheads.set(partitionName, [bh, Date.now()]);
+        // Sweep stale entries periodically
+        if (this.callCounter % this.sweepInterval === 0 || this.bulkheads.size > 100) {
+            this.prune();
+        }
+        return bh;
+    }
+    prune() {
+        const now = Date.now();
+        for (const [key, [, lastAccessed]] of this.bulkheads) {
+            if (now - lastAccessed > this.ttlMs) {
+                this.bulkheads.delete(key);
+            }
+        }
+    }
+    delete(partitionName) {
+        this.bulkheads.delete(partitionName);
+    }
+    getAll() {
+        const result = [];
+        for (const [, [bh]] of this.bulkheads) {
+            result.push({
+                name: bh.name,
+                running: bh.runningCount,
+                queued: bh.queueSize,
+                concurrency: bh.concurrencyLimit,
+                maxQueueSize: bh.maxQueueSizeLimit,
+            });
+        }
+        return result;
+    }
+    getSemaphore() {
+        return this.semaphore;
+    }
+}
+//# sourceMappingURL=bulkhead.js.map

package/dist/queue/bulkhead.js.map

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

package/dist/queue/circuit-breaker.d.ts

@@ -0,0 +1,81 @@
+import type { AppError } from "../core/errors.ts";
+import { type CircuitBreakerConfig, type PartitionConfig } from "../core/types.ts";
+/** One admission through the breaker, returned by `tryAcquire()`. Exactly one
+ *  of its methods takes effect (later calls are no-ops), so a caller can
+ *  report the outcome and still `release()` unconditionally in a `finally`.
+ *  In half-open, the permit owns a trial slot; every exit path — success,
+ *  failure, a non-failure error, cancellation, a veto — must hand it back,
+ *  or the breaker is wedged half-open with no trial slots left (B1). */
+export interface CircuitPermit {
+    /** The attempt succeeded. */
+    success(): void;
+    /** The attempt failed with `error`. Errors the breaker doesn't classify as
+     *  failures (e.g. a 404) count as successes — the host answered. An error
+     *  that shows the attempt never reached the host (e.g. a body factory that
+     *  threw) is ignored instead — same effect as calling `release()` — since
+     *  it carries no information about the host's health. */
+    failure(error: AppError): void;
+    /** The permit was not used to reach the server (cancelled, vetoed, queue
+     *  full…). Frees a half-open trial slot without recording an outcome. */
+    release(): void;
+}
+export declare class CircuitBreaker {
+    private readonly partition;
+    private readonly config;
+    private readonly onStateChange?;
+    private state;
+    private consecutiveFailures;
+    private openedAt;
+    private halfOpenInFlight;
+    /** Bumped on every open -> half-open transition, so a permit can tell
+     *  whether the trial slot it reserved still belongs to the current
+     *  half-open episode or to one that has since ended. */
+    private halfOpenGeneration;
+    private readonly window?;
+    constructor(partition: string, config?: CircuitBreakerConfig, onStateChange?: (partition: string, state: "open" | "closed") => void);
+    /** Whether a request may proceed against this partition right now.
+     *  Always true when the breaker is disabled. Handles the open -> half-open
+     *  transition on `resetTimeoutMs` elapse, and reserves a half-open trial
+     *  slot atomically so concurrent callers don't over-admit trials. */
+    canRequest(): boolean;
+    /** Admit a request, or return `null` when the circuit rejects it. Prefer
+     *  this over the raw `canRequest()`/`record*()` pair: the returned permit
+     *  guarantees a reserved half-open trial slot is always given back. */
+    tryAcquire(): CircuitPermit | null;
+    /** Record a successful attempt outcome. No-op when disabled. */
+    recordSuccess(): void;
+    /** Record a failed attempt outcome. No-op when disabled or when the error
+     *  is not classified as a failure. */
+    recordFailure(error: AppError): void;
+    /** Record a failure the caller has already classified via `isFailure`, so a
+     *  user-supplied classifier runs exactly once per outcome. No-op when disabled. */
+    private recordClassifiedFailure;
+    /** Not consulted for a `NEVER_SENT_KINDS` error (`tryAcquire()` short-circuits
+     *  before calling this) — such an error never reached the host, so there is
+     *  nothing for a caller-supplied classifier to legitimately weigh in on. */
+    private isFailure;
+    /** An attempt reached the server but ended in an error the breaker does
+     *  not count as a failure — e.g. a 404, or a 200 whose body failed `parse`.
+     *  The breaker measures availability, and the host answered, so this is
+     *  recorded as a success in every state (the Resilience4j default for
+     *  unrecorded errors): closed resets the consecutive-failure run and counts
+     *  as a non-failure in the rolling window; a half-open trial closes the
+     *  circuit. Classify it as a failure via `isFailure` to change that. */
+    private recordNeutral;
+    private resetCounters;
+    private evaluateTripCondition;
+}
+export declare class CircuitBreakerRegistry {
+    private readonly breakers;
+    private readonly ttlMs;
+    private readonly globalConfig;
+    private readonly partitionConfigs;
+    private readonly sweepInterval;
+    private readonly onStateChange?;
+    private callCounter;
+    constructor(globalConfig?: CircuitBreakerConfig, partitionConfigs?: Record<string, PartitionConfig>, ttlMs?: number, onStateChange?: (partition: string, state: "open" | "closed") => void);
+    get(partitionName: string): CircuitBreaker;
+    prune(): void;
+    delete(partitionName: string): void;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/queue/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/queue/circuit-breaker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EACN,KAAK,oBAAoB,EAIzB,KAAK,eAAe,EACpB,MAAM,kBAAkB,CAAC;AAoF1B;;;;;wEAKwE;AACxE,MAAM,WAAW,aAAa;IAC7B,6BAA6B;IAC7B,OAAO,IAAI,IAAI,CAAC;IAChB;;;;6DAIyD;IACzD,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B;6EACyE;IACzE,OAAO,IAAI,IAAI,CAAC;CAChB;AAED,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAwD;IAEvF,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,gBAAgB,CAAK;IAC7B;;4DAEwD;IACxD,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAgB;gBAGvC,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,oBAAyB,EACjC,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,KAAK,IAAI;IAUtE;;;yEAGqE;IACrE,UAAU,IAAI,OAAO;IA6BrB;;2EAEuE;IACvE,UAAU,IAAI,aAAa,GAAG,IAAI;IAiDlC,gEAAgE;IAChE,aAAa,IAAI,IAAI;IAiBrB;0CACsC;IACtC,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAMpC;uFACmF;IACnF,OAAO,CAAC,uBAAuB;IAsB/B;;gFAE4E;IAC5E,OAAO,CAAC,SAAS;IAIjB;;;;;;4EAMwE;IACxE,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,qBAAqB;CAU7B;AAQD,qBAAa,sBAAsB;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IACnE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuB;IACpD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkC;IACnE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAwD;IACvF,OAAO,CAAC,WAAW,CAAK;gBAGvB,YAAY,GAAE,oBAAyB,EACvC,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAM,EACtD,KAAK,GAAE,MAAiC,EACxC,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,KAAK,IAAI;IAStE,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc;IAuB1C,KAAK,IAAI,IAAI;IASb,MAAM,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;CAGnC"}

package/dist/queue/circuit-breaker.js

@@ -0,0 +1,283 @@
+import { DEFAULT_FAILURE_THRESHOLD, DEFAULT_HALF_OPEN_MAX_ATTEMPTS, DEFAULT_RESET_TIMEOUT_MS, } from "../core/types.js";
+import { DEFAULT_PARTITION_TTL_MS } from "./bulkhead.js";
+import { RETRIABLE_KINDS } from "./policy.js";
+/** Error kinds that mean the attempt never left the process — no request was
+ *  ever dispatched, so the host's health is untouched. Currently only a body
+ *  factory (`RequestOptions.body` as a function) that threw before `fetch`
+ *  was called (`src/queue/executor.ts`). A raw-`ReadableStream` body is
+ *  rejected even earlier, before the breaker is asked for a permit at all
+ *  (`client.ts` validates it ahead of `tryAcquire()`), so it never reaches
+ *  this classification in the first place. */
+const NEVER_SENT_KINDS = new Set(["configuration"]);
+const DEFAULT_BUCKET_COUNT = 10;
+class RollingWindow {
+    sizeMs;
+    bucketMs;
+    buckets = [];
+    constructor(sizeMs, bucketCount = DEFAULT_BUCKET_COUNT) {
+        this.sizeMs = sizeMs;
+        this.bucketMs = Math.max(1, Math.floor(sizeMs / bucketCount));
+    }
+    recordSuccess(now = Date.now()) {
+        const bucket = this.currentBucket(now);
+        bucket.total++;
+    }
+    recordFailure(now = Date.now()) {
+        const bucket = this.currentBucket(now);
+        bucket.total++;
+        bucket.failures++;
+    }
+    totalRequests(now = Date.now()) {
+        this.prune(now);
+        return this.buckets.reduce((sum, b) => sum + b.total, 0);
+    }
+    failureRate(now = Date.now()) {
+        this.prune(now);
+        const total = this.buckets.reduce((sum, b) => sum + b.total, 0);
+        if (total === 0)
+            return 0;
+        const failures = this.buckets.reduce((sum, b) => sum + b.failures, 0);
+        return (failures / total) * 100;
+    }
+    currentBucket(now) {
+        this.prune(now);
+        const bucketStart = Math.floor(now / this.bucketMs) * this.bucketMs;
+        const last = this.buckets[this.buckets.length - 1];
+        if (last && last.start === bucketStart) {
+            return last;
+        }
+        const bucket = { start: bucketStart, total: 0, failures: 0 };
+        this.buckets.push(bucket);
+        return bucket;
+    }
+    prune(now) {
+        const cutoff = now - this.sizeMs;
+        this.buckets = this.buckets.filter((b) => b.start >= cutoff);
+    }
+}
+export class CircuitBreaker {
+    partition;
+    config;
+    onStateChange;
+    state = "closed";
+    consecutiveFailures = 0;
+    openedAt = 0;
+    halfOpenInFlight = 0;
+    /** Bumped on every open -> half-open transition, so a permit can tell
+     *  whether the trial slot it reserved still belongs to the current
+     *  half-open episode or to one that has since ended. */
+    halfOpenGeneration = 0;
+    window;
+    constructor(partition, config = {}, onStateChange) {
+        this.partition = partition;
+        this.config = config;
+        this.onStateChange = onStateChange;
+        if (config.window) {
+            this.window = new RollingWindow(config.window.sizeMs);
+        }
+    }
+    /** Whether a request may proceed against this partition right now.
+     *  Always true when the breaker is disabled. Handles the open -> half-open
+     *  transition on `resetTimeoutMs` elapse, and reserves a half-open trial
+     *  slot atomically so concurrent callers don't over-admit trials. */
+    canRequest() {
+        if (!this.config.enabled)
+            return true;
+        if (this.state === "open") {
+            const resetTimeoutMs = this.config.resetTimeoutMs ?? DEFAULT_RESET_TIMEOUT_MS;
+            if (Date.now() - this.openedAt >= resetTimeoutMs) {
+                this.state = "half-open";
+                this.halfOpenInFlight = 0;
+                this.halfOpenGeneration++;
+            }
+            else {
+                return false;
+            }
+        }
+        if (this.state === "half-open") {
+            const maxAttempts = this.config.halfOpenMaxAttempts ?? DEFAULT_HALF_OPEN_MAX_ATTEMPTS;
+            if (this.halfOpenInFlight >= maxAttempts) {
+                return false;
+            }
+            // Reserve the slot immediately (side-effecting) so two callers
+            // arriving before either trial resolves can't both be admitted.
+            this.halfOpenInFlight++;
+            return true;
+        }
+        // closed
+        return true;
+    }
+    /** Admit a request, or return `null` when the circuit rejects it. Prefer
+     *  this over the raw `canRequest()`/`record*()` pair: the returned permit
+     *  guarantees a reserved half-open trial slot is always given back. */
+    tryAcquire() {
+        if (!this.canRequest())
+            return null;
+        // null = admitted while closed (or disabled) — no trial slot held.
+        const trialGeneration = this.config.enabled && this.state === "half-open" ? this.halfOpenGeneration : null;
+        const isCurrentTrial = () => trialGeneration !== null && trialGeneration === this.halfOpenGeneration;
+        // A request admitted while closed that completes during a later
+        // half-open episode must not decide that episode: only its own trials do.
+        const mayRecord = () => this.state !== "half-open" || isCurrentTrial();
+        const freeTrialSlot = () => {
+            if (this.state === "half-open" && isCurrentTrial()) {
+                this.halfOpenInFlight = Math.max(0, this.halfOpenInFlight - 1);
+            }
+        };
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            fn();
+        };
+        return {
+            success: () => settle(() => {
+                if (mayRecord())
+                    this.recordSuccess();
+            }),
+            failure: (error) => settle(() => {
+                if (!mayRecord())
+                    return;
+                // Never-sent outcomes are ignored outright — not even isFailure is
+                // consulted, since there is no host-health signal to classify.
+                if (NEVER_SENT_KINDS.has(error.kind)) {
+                    freeTrialSlot();
+                    return;
+                }
+                // Classify once here and record the already-classified failure
+                // directly — `recordFailure()` would consult isFailure a second time.
+                if (this.isFailure(error)) {
+                    this.recordClassifiedFailure();
+                }
+                else {
+                    this.recordNeutral();
+                    freeTrialSlot();
+                }
+            }),
+            release: () => settle(freeTrialSlot),
+        };
+    }
+    /** Record a successful attempt outcome. No-op when disabled. */
+    recordSuccess() {
+        if (!this.config.enabled)
+            return;
+        if (this.state === "half-open") {
+            this.halfOpenInFlight = Math.max(0, this.halfOpenInFlight - 1);
+            this.state = "closed";
+            this.resetCounters();
+            this.onStateChange?.(this.partition, "closed");
+            return;
+        }
+        if (this.state === "closed") {
+            this.consecutiveFailures = 0;
+            this.window?.recordSuccess();
+        }
+    }
+    /** Record a failed attempt outcome. No-op when disabled or when the error
+     *  is not classified as a failure. */
+    recordFailure(error) {
+        if (!this.config.enabled)
+            return;
+        if (!this.isFailure(error))
+            return;
+        this.recordClassifiedFailure();
+    }
+    /** Record a failure the caller has already classified via `isFailure`, so a
+     *  user-supplied classifier runs exactly once per outcome. No-op when disabled. */
+    recordClassifiedFailure() {
+        if (!this.config.enabled)
+            return;
+        if (this.state === "half-open") {
+            this.halfOpenInFlight = Math.max(0, this.halfOpenInFlight - 1);
+            this.state = "open";
+            this.openedAt = Date.now();
+            this.onStateChange?.(this.partition, "open");
+            return;
+        }
+        if (this.state === "closed") {
+            this.consecutiveFailures++;
+            this.window?.recordFailure();
+            if (this.evaluateTripCondition()) {
+                this.state = "open";
+                this.openedAt = Date.now();
+                this.onStateChange?.(this.partition, "open");
+            }
+        }
+    }
+    /** Not consulted for a `NEVER_SENT_KINDS` error (`tryAcquire()` short-circuits
+     *  before calling this) — such an error never reached the host, so there is
+     *  nothing for a caller-supplied classifier to legitimately weigh in on. */
+    isFailure(error) {
+        return this.config.isFailure ? this.config.isFailure(error) : RETRIABLE_KINDS.has(error.kind);
+    }
+    /** An attempt reached the server but ended in an error the breaker does
+     *  not count as a failure — e.g. a 404, or a 200 whose body failed `parse`.
+     *  The breaker measures availability, and the host answered, so this is
+     *  recorded as a success in every state (the Resilience4j default for
+     *  unrecorded errors): closed resets the consecutive-failure run and counts
+     *  as a non-failure in the rolling window; a half-open trial closes the
+     *  circuit. Classify it as a failure via `isFailure` to change that. */
+    recordNeutral() {
+        this.recordSuccess();
+    }
+    resetCounters() {
+        this.consecutiveFailures = 0;
+        this.halfOpenInFlight = 0;
+    }
+    evaluateTripCondition() {
+        const windowConfig = this.config.window;
+        if (this.window && windowConfig) {
+            return (this.window.totalRequests() >= windowConfig.minimumRequests &&
+                this.window.failureRate() > windowConfig.failureRatePercent);
+        }
+        return this.consecutiveFailures >= (this.config.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD);
+    }
+}
+export class CircuitBreakerRegistry {
+    breakers = new Map();
+    ttlMs;
+    globalConfig;
+    partitionConfigs;
+    sweepInterval;
+    onStateChange;
+    callCounter = 0;
+    constructor(globalConfig = {}, partitionConfigs = {}, ttlMs = DEFAULT_PARTITION_TTL_MS, onStateChange) {
+        this.ttlMs = ttlMs;
+        this.globalConfig = globalConfig;
+        this.partitionConfigs = partitionConfigs;
+        this.sweepInterval = 10;
+        this.onStateChange = onStateChange;
+    }
+    get(partitionName) {
+        this.callCounter++;
+        if (!this.breakers.has(partitionName)) {
+            const partitionConfig = this.partitionConfigs[partitionName]?.circuitBreaker ?? {};
+            const merged = {
+                ...this.globalConfig,
+                ...partitionConfig,
+            };
+            this.breakers.set(partitionName, [new CircuitBreaker(partitionName, merged, this.onStateChange), Date.now()]);
+        }
+        const [cb] = this.breakers.get(partitionName);
+        // Update last accessed time
+        this.breakers.set(partitionName, [cb, Date.now()]);
+        // Sweep stale entries periodically
+        if (this.callCounter % this.sweepInterval === 0 || this.breakers.size > 100) {
+            this.prune();
+        }
+        return cb;
+    }
+    prune() {
+        const now = Date.now();
+        for (const [key, [, lastAccessed]] of this.breakers) {
+            if (now - lastAccessed > this.ttlMs) {
+                this.breakers.delete(key);
+            }
+        }
+    }
+    delete(partitionName) {
+        this.breakers.delete(partitionName);
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/queue/circuit-breaker.js.map

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

package/dist/queue/executor.d.ts

@@ -0,0 +1,67 @@
+import type { AppError } from "../core/errors.ts";
+import type { RequestOptions, Result, RetryConfig, TimeoutConfig } from "../core/types.ts";
+export interface ExecuteRequest {
+    url: string;
+    options: RequestOptions<unknown>;
+    timeoutConfig: TimeoutConfig;
+    retryConfig: RetryConfig;
+    signal: AbortSignal;
+    /** Which attempt this is: 0 = the first attempt, 1 = the first retry, etc.
+     *  Exposed to middleware via `RequestContext.attempt`. */
+    attempt: number;
+    ticketId: string;
+    partition: string;
+    /** Absolute `Date.now()` timestamp of the ticket's whole-ticket deadline
+     *  (`startTime + timeout.totalMs`), or undefined when `totalMs` isn't
+     *  bounded. Used only to bound the read window of a Response handed back
+     *  to the caller unread (see `handedOff` in `executeRequest`) — never to
+     *  reclassify an in-attempt timeout. */
+    deadlineAt?: number;
+    /** `url` as it may appear in errors/logs (query- and userinfo-redacted
+     *  unless disabled) — used to build the `TimeoutError`/`DeadlineExceededError`
+     *  that bounds a handed-off Response's body-read window, so that error is
+     *  redacted the same as every other error the client builds. */
+    displayUrl: string;
+    /** Custom fetch function. Falls back to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+}
+export type ExecuteResult = {
+    kind: "success";
+    result: Result<unknown>;
+} | {
+    kind: "timeout";
+} | {
+    kind: "cancelled";
+} | {
+    kind: "error";
+    error: AppError;
+};
+/**
+ * Executes a single HTTP request attempt.
+ * Returns a discriminated union describing what happened,
+ * so the caller (retry loop) can decide whether to retry or resolve.
+ */
+export declare function executeRequest(req: ExecuteRequest, middleware: MiddlewareFn[]): Promise<ExecuteResult>;
+/** What a middleware function sees and can rewrite for a single attempt.
+ *  `headers` is a real `Headers` instance (case-insensitive lookups/sets) and
+ *  is fresh per attempt — mutating it does not affect other attempts or the
+ *  caller's original `RequestOptions`. */
+export interface RequestContext {
+    url: string;
+    method: string;
+    headers: Headers;
+    body?: BodyInit;
+    signal: AbortSignal;
+    /** 0 = the first attempt, 1 = the first retry, etc. */
+    attempt: number;
+    ticketId: string;
+    partition: string;
+}
+export type NextFn = (ctx: RequestContext) => Promise<Response>;
+export type MiddlewareFn = (ctx: RequestContext, next: NextFn) => Promise<Response>;
+export declare function composeMiddleware(middlewares: MiddlewareFn[], core: NextFn): NextFn;
+/** Parse a `Retry-After` header value into a delay in ms, or undefined when
+ *  absent/unparseable. Integer seconds → ms; HTTP-date → ms from now, clamped
+ *  to ≥ 0; anything else (garbage, negative) → undefined. */
+export declare function parseRetryAfter(header: string | null): number | undefined;
+//# sourceMappingURL=executor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/queue/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAWlD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAI3F,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,WAAW,CAAC;IACpB;8DAC0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;4CAIwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;oEAGgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAChC;AAED,MAAM,MAAM,aAAa,GACtB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEtC;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAkO5G;AAMD;;;0CAG0C;AAC1C,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,WAAW,CAAC;IACpB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAChE,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAmBpF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnF;AAMD;;6DAE6D;AAC7D,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CASzE"}