@vereda/http 1.0.0

package/dist/queue/retry.js

@@ -0,0 +1,259 @@
+import { buildBackoffFn, DEFAULT_MAX_DELAY_MS } from "../core/backoff.js";
+import { CancelledError, CircuitOpenError, DeadlineExceededError, MaxRetriesExceededError, NO_TIMEOUT_CONFIGURED, QueueFullError, RetryableStatusError, TimeoutError, } from "../core/errors.js";
+import { DEFAULT_MAX_RETRIES, isBoundedMs, } from "../core/types.js";
+import { executeRequest } from "./executor.js";
+import { defaultRetryPolicy, shouldRetry } from "./policy.js";
+export async function runRetryLoop(job) {
+    const { url, displayUrl, requestOptions, timeoutConfig, retryConfig, deadlineAt, ticket, controller, middleware, bulkhead, semaphore, circuitBreaker, partition, firstError, initialQueuedMs, onRetry, onSuccess, onFailure, onCancelled, onCleanup, fetch: customFetch, } = job;
+    const maxRetries = retryConfig.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const backoffFn = buildBackoffFn(retryConfig.backoff);
+    const backoffCap = retryConfig.backoff && typeof retryConfig.backoff === "object"
+        ? (retryConfig.backoff.maxDelayMs ?? DEFAULT_MAX_DELAY_MS)
+        : DEFAULT_MAX_DELAY_MS;
+    let lastError = firstError;
+    let totalAttempts = 1; // first attempt already fired client-side
+    let totalQueuedMs = initialQueuedMs; // cumulative bulkhead/semaphore wait across all attempts
+    // Attempt 0's error was already vetted (default policy + retryWhen) by
+    // client.ts's vetoed() before this loop was ever entered — that's what
+    // decided to queue the ticket for retry in the first place. `ctx` is
+    // constant across the loop (derived only from requestOptions/retryConfig),
+    // so it's built once here and reused both by the loop's gate below and by
+    // the final-attempt check after the loop.
+    const ctx = {
+        method: requestOptions.method ?? "GET",
+        headers: requestOptions.headers,
+        idempotent: retryConfig.idempotent,
+    };
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        if (ticket.isCancelled) {
+            onCleanup?.();
+            onCancelled?.(totalAttempts, totalQueuedMs);
+            controller.markDone({
+                success: false,
+                error: new CancelledError(),
+            });
+            return;
+        }
+        const permit = circuitBreaker.tryAcquire();
+        if (!permit) {
+            onCleanup?.();
+            const error = new CircuitOpenError(partition);
+            onFailure?.(error, totalAttempts, totalQueuedMs);
+            controller.markDone({ success: false, error });
+            return;
+        }
+        // Every exit from this iteration settles the permit: an outcome below,
+        // or release() for the veto/cancel/deadline/queue-full paths (B1).
+        try {
+            // Consult the default policy + retryWhen for every retry iteration
+            // *except the first* (attempt 0): that error is always `firstError`,
+            // already vetted by client.ts's vetoed() before this loop was ever
+            // entered. Re-checking it here would call a user-provided retryWhen
+            // twice for the same failed attempt. From attempt 1 on, `lastError`
+            // is a fresh error produced by a retry this loop just ran, so the
+            // gate must run — it's what lets retryWhen limit retries to N+1
+            // attempts total.
+            if (attempt > 0 && !shouldRetry(lastError, attempt, ctx, retryConfig.retryWhen)) {
+                onCleanup?.();
+                onFailure?.(lastError, totalAttempts, totalQueuedMs);
+                controller.markDone({ success: false, error: lastError });
+                return;
+            }
+            // All retries get backoff. Every retry is gated by the policy check above.
+            const delayMs = resolveRetryDelay(lastError, backoffFn, attempt, backoffCap);
+            onRetry?.(attempt, delayMs, lastError);
+            controller.markRetrying(attempt, delayMs);
+            try {
+                await sleep(delayMs, ticket.signal);
+            }
+            catch {
+                // The deadline timer aborts the ticket signal. Distinguish deadline from
+                // user cancellation: deadline only aborts the signal (abortSignal()),
+                // while user cancellation sets _cancelled = true via cancel().
+                onCleanup?.();
+                if (!ticket.isCancelled && isBoundedMs(timeoutConfig.totalMs)) {
+                    const error = new DeadlineExceededError(displayUrl, timeoutConfig.totalMs);
+                    onFailure?.(error, totalAttempts, totalQueuedMs);
+                    controller.markDone({
+                        success: false,
+                        error,
+                    });
+                }
+                else {
+                    onCancelled?.(totalAttempts, totalQueuedMs);
+                    controller.markDone({
+                        success: false,
+                        error: new CancelledError(),
+                    });
+                }
+                return;
+            }
+            if (ticket.isCancelled) {
+                onCleanup?.();
+                onCancelled?.(totalAttempts, totalQueuedMs);
+                controller.markDone({
+                    success: false,
+                    error: new CancelledError(),
+                });
+                return;
+            }
+            totalAttempts++;
+            // Per-attempt bulkhead scheduling: each retry acquires its own slot,
+            // releases it after execution, so other tickets aren't blocked (#5, D4).
+            // The global semaphore is acquired after the partition slot (D4).
+            let result;
+            try {
+                result = await bulkhead.run(() => executeRequest({
+                    url,
+                    options: requestOptions,
+                    timeoutConfig,
+                    retryConfig,
+                    deadlineAt,
+                    displayUrl,
+                    signal: ticket.signal,
+                    attempt: attempt + 1,
+                    ticketId: ticket.id,
+                    partition: bulkhead.name,
+                    fetch: customFetch,
+                }, middleware), semaphore, (queuedMs) => {
+                    totalQueuedMs += queuedMs;
+                }, ticket.signal);
+            }
+            catch (err) {
+                if (err instanceof CancelledError) {
+                    // Cancelled (or deadline-aborted) while still queued for a slot or
+                    // permit (B9): nothing was dispatched, so back out the optimistic
+                    // totalAttempts++ and let the "cancelled" case settle it.
+                    totalAttempts--;
+                    result = { kind: "cancelled" };
+                }
+                else if (err instanceof QueueFullError) {
+                    // Queue is at capacity — bulkhead.run() rejected before task()
+                    // ever ran, so this iteration's optimistic totalAttempts++ above
+                    // must be backed out; it reports attempts actually dispatched.
+                    const attemptsMade = totalAttempts - 1;
+                    onCleanup?.();
+                    if (ticket.isCancelled) {
+                        // cancel() may have resolved the ticket directly (ticket.ts),
+                        // bypassing markDone, while this bulkhead/semaphore acquisition
+                        // was still pending. Match every other cancellation checkpoint
+                        // in this loop: notify via onCancelled, not onFailure, so the
+                        // lifecycle-event stream agrees with the ticket's actual outcome.
+                        onCancelled?.(attemptsMade, totalQueuedMs);
+                    }
+                    else {
+                        // Emit failure here (not in the client's outer .catch) because
+                        // totalQueuedMs — the wait accumulated by retries that already
+                        // ran — only exists in this closure; the outer catch only has
+                        // the first attempt's queuedMs.
+                        onFailure?.(err, attemptsMade, totalQueuedMs);
+                    }
+                    controller.markDone({ success: false, error: err });
+                    throw err;
+                }
+                else {
+                    throw err;
+                }
+            }
+            switch (result.kind) {
+                case "success": {
+                    permit.success();
+                    onCleanup?.();
+                    if (result.result.success) {
+                        onSuccess?.(result.result.raw.status, totalAttempts, totalQueuedMs);
+                    }
+                    controller.markDone(result.result);
+                    return;
+                }
+                case "cancelled":
+                    onCleanup?.();
+                    if (!ticket.isCancelled && isBoundedMs(timeoutConfig.totalMs)) {
+                        const error = new DeadlineExceededError(displayUrl, timeoutConfig.totalMs);
+                        onFailure?.(error, totalAttempts, totalQueuedMs);
+                        controller.markDone({
+                            success: false,
+                            error,
+                        });
+                    }
+                    else {
+                        onCancelled?.(totalAttempts, totalQueuedMs);
+                        controller.markDone({
+                            success: false,
+                            error: new CancelledError(),
+                        });
+                    }
+                    return;
+                case "timeout":
+                    lastError = new TimeoutError(displayUrl, timeoutConfig.attemptMs ?? NO_TIMEOUT_CONFIGURED);
+                    permit.failure(lastError);
+                    break;
+                case "error":
+                    lastError = result.error;
+                    permit.failure(lastError);
+                    break;
+            }
+        }
+        finally {
+            permit.release();
+        }
+    }
+    if (maxRetries === 0) {
+        // Zero retries configured/executed — surface the underlying error raw,
+        // never wrapped in MaxRetriesExceededError.
+        onCleanup?.();
+        onFailure?.(lastError, totalAttempts, totalQueuedMs);
+        controller.markDone({ success: false, error: lastError });
+        return;
+    }
+    // All retries exhausted — total attempts = 1 (first) + maxRetries (loop)
+    totalAttempts = 1 + maxRetries;
+    onCleanup?.();
+    // The final attempt's own error was never run through the gate above —
+    // the loop only checks the *previous* error at the top of each iteration,
+    // and there is no next iteration for this one. If it wouldn't have been
+    // retried anyway (e.g. a non-retryable HttpError, or a ValidationError
+    // from a failed parse), it's terminal on its own merits: surface it raw,
+    // same as a mid-loop veto, instead of wrapping it in
+    // MaxRetriesExceededError. Only genuinely transient exhaustion — the
+    // final error was itself retryable, retries just ran out — gets wrapped.
+    // This intentionally checks the default policy only, not retryWhen:
+    // retryWhen is never consulted for an attempt that has no retries left.
+    if (!defaultRetryPolicy(lastError, maxRetries, ctx)) {
+        onFailure?.(lastError, totalAttempts, totalQueuedMs);
+        controller.markDone({ success: false, error: lastError });
+        return;
+    }
+    const exhaustedError = new MaxRetriesExceededError(totalAttempts, lastError);
+    onFailure?.(exhaustedError, totalAttempts, totalQueuedMs);
+    controller.markDone({
+        success: false,
+        error: exhaustedError,
+    });
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new DOMException("The operation was aborted", "AbortError"));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason ?? new DOMException("The operation was aborted", "AbortError"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Resolve the delay before a retry (decision D3): a Retry-After-derived
+ *  `retryAfterMs` wins when present (capped at `cap`, no jitter), otherwise
+ *  the configured backoff drives the delay. */
+function resolveRetryDelay(lastError, backoffFn, attempt, cap) {
+    if (lastError instanceof RetryableStatusError && lastError.retryAfterMs !== undefined) {
+        return Math.min(lastError.retryAfterMs, cap);
+    }
+    return backoffFn(attempt);
+}
+//# sourceMappingURL=retry.js.map

package/dist/queue/retry.js.map

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

package/dist/queue/semaphore.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A counting semaphore that limits total concurrent executions across all
+ * partitions (the global concurrency cap — decision D1, see
+ * `ClientConfig.concurrency` / `DEFAULT_GLOBAL_CONCURRENCY` for the default).
+ *
+ * Each `acquire()` returns a `release` callback. When no permit is available
+ * the caller is queued (up to `maxQueueSize`, see `ClientConfig.maxQueueSize` /
+ * `DEFAULT_GLOBAL_QUEUE_SIZE`) and resolved when a permit is released.
+ * Exceeding the queue limit rejects immediately with QueueFullError.
+ */
+export declare class Semaphore {
+    private available;
+    private readonly waitQueue;
+    private readonly maxQueueSize;
+    constructor(permits: number, maxQueueSize?: number);
+    /** Number of callers currently waiting for a permit. */
+    get queueLength(): number;
+    /** Number of permits currently free (not held by an in-flight request). */
+    get availablePermits(): number;
+    /** Acquire a permit. Resolves to a `release` function when granted;
+     *  calling `release` more than once is a no-op.
+     *
+     *  If `signal` aborts while the caller is still queued, the waiter is
+     *  removed from the queue — freeing its place for live callers — and the
+     *  promise rejects with `CancelledError` (B9). An already-aborted signal
+     *  rejects immediately without taking a permit. */
+    acquire(signal?: AbortSignal): Promise<() => void>;
+    private releaseOnce;
+    private release;
+    private _drain;
+}
+//# sourceMappingURL=semaphore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore.d.ts","sourceRoot":"","sources":["../../src/queue/semaphore.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,qBAAa,SAAS;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,OAAO,EAAE,MAAM,EAAE,YAAY,SAA4B;IAKrE,wDAAwD;IACxD,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,2EAA2E;IAC3E,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED;;;;;;uDAMmD;IACnD,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IA8BlD,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,MAAM;CAMd"}

package/dist/queue/semaphore.js

@@ -0,0 +1,83 @@
+import { CancelledError, QueueFullError } from "../core/errors.js";
+import { DEFAULT_GLOBAL_QUEUE_SIZE } from "../core/types.js";
+/**
+ * A counting semaphore that limits total concurrent executions across all
+ * partitions (the global concurrency cap — decision D1, see
+ * `ClientConfig.concurrency` / `DEFAULT_GLOBAL_CONCURRENCY` for the default).
+ *
+ * Each `acquire()` returns a `release` callback. When no permit is available
+ * the caller is queued (up to `maxQueueSize`, see `ClientConfig.maxQueueSize` /
+ * `DEFAULT_GLOBAL_QUEUE_SIZE`) and resolved when a permit is released.
+ * Exceeding the queue limit rejects immediately with QueueFullError.
+ */
+export class Semaphore {
+    available;
+    waitQueue = [];
+    maxQueueSize;
+    constructor(permits, maxQueueSize = DEFAULT_GLOBAL_QUEUE_SIZE) {
+        this.available = permits;
+        this.maxQueueSize = maxQueueSize;
+    }
+    /** Number of callers currently waiting for a permit. */
+    get queueLength() {
+        return this.waitQueue.length;
+    }
+    /** Number of permits currently free (not held by an in-flight request). */
+    get availablePermits() {
+        return this.available;
+    }
+    /** Acquire a permit. Resolves to a `release` function when granted;
+     *  calling `release` more than once is a no-op.
+     *
+     *  If `signal` aborts while the caller is still queued, the waiter is
+     *  removed from the queue — freeing its place for live callers — and the
+     *  promise rejects with `CancelledError` (B9). An already-aborted signal
+     *  rejects immediately without taking a permit. */
+    acquire(signal) {
+        if (signal?.aborted) {
+            return Promise.reject(new CancelledError());
+        }
+        if (this.available > 0) {
+            this.available--;
+            return Promise.resolve(this.releaseOnce());
+        }
+        if (this.waitQueue.length >= this.maxQueueSize) {
+            return Promise.reject(new QueueFullError("global", this.waitQueue.length, this.maxQueueSize));
+        }
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                const idx = this.waitQueue.indexOf(grant);
+                if (idx !== -1)
+                    this.waitQueue.splice(idx, 1);
+                reject(new CancelledError());
+            };
+            const grant = () => {
+                signal?.removeEventListener("abort", onAbort);
+                this.available--;
+                resolve(this.releaseOnce());
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            this.waitQueue.push(grant);
+        });
+    }
+    releaseOnce() {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.release();
+        };
+    }
+    release() {
+        this.available++;
+        this._drain();
+    }
+    _drain() {
+        while (this.available > 0 && this.waitQueue.length > 0) {
+            const next = this.waitQueue.shift();
+            next();
+        }
+    }
+}
+//# sourceMappingURL=semaphore.js.map

package/dist/queue/semaphore.js.map

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

package/dist/ticket/ticket.d.ts

@@ -0,0 +1,77 @@
+import type { AppError } from "../core/errors.ts";
+import type { Result } from "../core/types.ts";
+export type TicketStatus = {
+    state: "pending";
+} | {
+    state: "queued";
+} | {
+    state: "retrying";
+    attempt: number;
+} | {
+    state: "done";
+    result: Result<unknown>;
+} | {
+    state: "cancelled";
+};
+export type TicketUpdate = {
+    type: "queued";
+} | {
+    type: "retrying";
+    attempt: number;
+    delayMs: number;
+} | {
+    type: "done";
+    result: Result<unknown>;
+} | {
+    type: "cancelled";
+};
+export interface TicketController<T> {
+    markQueued(): void;
+    markRetrying(attempt: number, delayMs: number): void;
+    markDone(result: Result<T>): void;
+    /** @internal — abort the signal without resolving the ticket. Used by the
+     *  deadline timer so the retry loop can resolve with DeadlineExceededError
+     *  instead of CancelledError. */
+    abortSignal(): void;
+}
+export declare class Ticket<T> {
+    readonly id: string;
+    private readonly emitter;
+    private _status;
+    private _cancelled;
+    private _abortController;
+    private _resolve;
+    private _promise;
+    /** @internal — use `createTicket()` to obtain a ticket and its controller. */
+    constructor(id: string);
+    get status(): TicketStatus;
+    /** Validate and apply a state transition. Returns false (and leaves the
+     *  current state untouched) when `next` is not reachable from the current
+     *  state, so illegal transitions are ignored rather than corrupting state. */
+    private applyTransition;
+    get signal(): AbortSignal;
+    on(event: "done", listener: (result: Result<T>) => void): this;
+    on(event: "error", listener: (error: AppError) => void): this;
+    on(event: "update", listener: (update: TicketUpdate) => void): this;
+    off(event: "done", listener: (result: Result<T>) => void): this;
+    off(event: "error", listener: (error: AppError) => void): this;
+    off(event: "update", listener: (update: TicketUpdate) => void): this;
+    cancel(): void;
+    toPromise(): Promise<Result<T>>;
+    subscribe(): AsyncGenerator<TicketUpdate>;
+    get isCancelled(): boolean;
+    /** True once this ticket has reached a terminal state by any path — a
+     *  normal `done` transition or `cancel()` (which resolves the ticket
+     *  directly, bypassing `done`). A terminal-event emitter must check this
+     *  before firing, or a result racing a concurrent cancel() can emit a
+     *  second, contradictory terminal event for the same ticket. */
+    get isSettled(): boolean;
+    private markQueued;
+    private markRetrying;
+    private markDone;
+}
+export declare function createTicket<T>(id: string): {
+    ticket: Ticket<T>;
+    controller: TicketController<T>;
+};
+//# sourceMappingURL=ticket.d.ts.map

package/dist/ticket/ticket.d.ts.map

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