@foundatiofx/fetchclient 1.0.1 → 1.1.1

package/esm/mod.js

@@ -1,5 +1,7 @@
 export { FetchClient } from "./src/FetchClient.js";
 export { ProblemDetails } from "./src/ProblemDetails.js";
-export { FetchClientCache } from "./src/FetchClientCache.js";
+export { FetchClientCache, } from "./src/FetchClientCache.js";
 export { defaultInstance as defaultProviderInstance, FetchClientProvider, } from "./src/FetchClientProvider.js";
 export * from "./src/DefaultHelpers.js";
+export { CircuitBreaker, groupByDomain as circuitBreakerGroupByDomain, } from "./src/CircuitBreaker.js";
+export { CircuitBreakerMiddleware, CircuitOpenError, createCircuitBreakerMiddleware, createPerDomainCircuitBreakerMiddleware, } from "./src/CircuitBreakerMiddleware.js";

package/esm/src/CircuitBreaker.js

@@ -0,0 +1,356 @@
+/**
+ * Circuit breaker for preventing cascading failures.
+ *
+ * When a service starts failing (returning 5xx errors, timing out, etc.),
+ * the circuit breaker "opens" and blocks further requests for a period,
+ * allowing the service time to recover.
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,    // Open after 5 failures
+ *   openDurationMs: 30000,  // Stay open for 30 seconds
+ *   successThreshold: 2,    // Close after 2 successes in HALF_OPEN
+ * });
+ *
+ * // Before making a request
+ * if (!breaker.isAllowed(url)) {
+ *   // Circuit is open, don't make request
+ *   return;
+ * }
+ *
+ * // After getting a response
+ * if (response.status >= 500) {
+ *   breaker.recordFailure(url);
+ * } else {
+ *   breaker.recordSuccess(url);
+ * }
+ * ```
+ */
+export class CircuitBreaker {
+    #buckets = new Map();
+    #groupOptions = new Map();
+    #options;
+    #onOpen;
+    #onClose;
+    #onHalfOpen;
+    constructor(options) {
+        this.#options = {
+            failureThreshold: options?.failureThreshold ?? 5,
+            failureWindowMs: options?.failureWindowMs ?? 60000,
+            openDurationMs: options?.openDurationMs ?? 30000,
+            successThreshold: options?.successThreshold ?? 2,
+            halfOpenMaxAttempts: options?.halfOpenMaxAttempts ?? 1,
+            getGroupFunc: options?.getGroupFunc ?? (() => "global"),
+            onStateChange: options?.onStateChange,
+        };
+        this.#onOpen = options?.onOpen;
+        this.#onClose = options?.onClose;
+        this.#onHalfOpen = options?.onHalfOpen;
+        // Initialize per-group options
+        if (options?.groups) {
+            for (const [group, groupOpts] of Object.entries(options.groups)) {
+                this.#groupOptions.set(group, groupOpts);
+            }
+        }
+    }
+    /**
+     * Gets the effective options for a group.
+     */
+    #getOptions(group) {
+        const groupOpts = this.#groupOptions.get(group);
+        return {
+            failureThreshold: groupOpts?.failureThreshold ??
+                this.#options.failureThreshold,
+            failureWindowMs: groupOpts?.failureWindowMs ??
+                this.#options.failureWindowMs,
+            openDurationMs: groupOpts?.openDurationMs ?? this.#options.openDurationMs,
+            successThreshold: groupOpts?.successThreshold ??
+                this.#options.successThreshold,
+            halfOpenMaxAttempts: groupOpts?.halfOpenMaxAttempts ??
+                this.#options.halfOpenMaxAttempts,
+            onStateChange: groupOpts?.onStateChange ?? this.#options.onStateChange,
+        };
+    }
+    /**
+     * Gets or creates a bucket for the given group.
+     */
+    #getBucket(group) {
+        let bucket = this.#buckets.get(group);
+        if (!bucket) {
+            bucket = {
+                state: "CLOSED",
+                failures: [],
+                successCount: 0,
+                openedAt: null,
+                halfOpenAttempts: 0,
+            };
+            this.#buckets.set(group, bucket);
+        }
+        return bucket;
+    }
+    /**
+     * Transitions the circuit to a new state.
+     */
+    #transitionTo(group, bucket, newState) {
+        const oldState = bucket.state;
+        if (oldState === newState)
+            return;
+        bucket.state = newState;
+        // Reset state-specific counters
+        if (newState === "OPEN") {
+            bucket.openedAt = Date.now();
+            bucket.successCount = 0;
+            bucket.halfOpenAttempts = 0;
+        }
+        else if (newState === "HALF_OPEN") {
+            bucket.successCount = 0;
+            bucket.halfOpenAttempts = 0;
+        }
+        else if (newState === "CLOSED") {
+            bucket.failures = [];
+            bucket.openedAt = null;
+            bucket.successCount = 0;
+            bucket.halfOpenAttempts = 0;
+        }
+        // Trigger callbacks
+        const opts = this.#getOptions(group);
+        opts.onStateChange?.(oldState, newState);
+        if (newState === "OPEN") {
+            this.#onOpen?.(group);
+        }
+        else if (newState === "CLOSED") {
+            this.#onClose?.(group);
+        }
+        else if (newState === "HALF_OPEN") {
+            this.#onHalfOpen?.(group);
+        }
+    }
+    /**
+     * Cleans up old failures outside the time window.
+     */
+    #cleanupFailures(bucket, windowMs) {
+        const cutoff = Date.now() - windowMs;
+        bucket.failures = bucket.failures.filter((t) => t > cutoff);
+    }
+    /**
+     * Checks if a request to the given URL is allowed.
+     * Call this before making a request.
+     *
+     * @param url - The URL being requested
+     * @returns true if the request is allowed, false if circuit is open
+     */
+    isAllowed(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#getBucket(group);
+        const opts = this.#getOptions(group);
+        switch (bucket.state) {
+            case "CLOSED":
+                return true;
+            case "OPEN": {
+                // Check if enough time has passed to try HALF_OPEN
+                const elapsed = Date.now() - (bucket.openedAt ?? 0);
+                if (elapsed >= opts.openDurationMs) {
+                    this.#transitionTo(group, bucket, "HALF_OPEN");
+                    // Fall through to HALF_OPEN logic
+                }
+                else {
+                    return false;
+                }
+            }
+            // falls through
+            case "HALF_OPEN": {
+                // Allow limited requests in HALF_OPEN
+                if (bucket.halfOpenAttempts < opts.halfOpenMaxAttempts) {
+                    bucket.halfOpenAttempts++;
+                    return true;
+                }
+                return false;
+            }
+        }
+    }
+    /**
+     * Records a successful response.
+     * Call this after receiving a successful (non-failure) response.
+     *
+     * @param url - The URL that was requested
+     */
+    recordSuccess(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#getBucket(group);
+        const opts = this.#getOptions(group);
+        switch (bucket.state) {
+            case "CLOSED":
+                // Success in CLOSED state - nothing special to do
+                // Optionally could reset failure count, but we use time-based cleanup
+                break;
+            case "HALF_OPEN":
+                // Decrement in-flight counter
+                bucket.halfOpenAttempts = Math.max(0, bucket.halfOpenAttempts - 1);
+                bucket.successCount++;
+                // Check if we've had enough successes to close
+                if (bucket.successCount >= opts.successThreshold) {
+                    this.#transitionTo(group, bucket, "CLOSED");
+                }
+                break;
+            case "OPEN":
+                // Shouldn't happen - requests blocked in OPEN
+                break;
+        }
+    }
+    /**
+     * Records a failed response.
+     * Call this after receiving a failure response (5xx, timeout, network error).
+     *
+     * @param url - The URL that was requested
+     */
+    recordFailure(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#getBucket(group);
+        const opts = this.#getOptions(group);
+        switch (bucket.state) {
+            case "CLOSED":
+                // Clean up old failures
+                this.#cleanupFailures(bucket, opts.failureWindowMs);
+                // Record new failure
+                bucket.failures.push(Date.now());
+                // Check if we've hit the threshold
+                if (bucket.failures.length >= opts.failureThreshold) {
+                    this.#transitionTo(group, bucket, "OPEN");
+                }
+                break;
+            case "HALF_OPEN":
+                // Failure in HALF_OPEN - back to OPEN
+                bucket.halfOpenAttempts = Math.max(0, bucket.halfOpenAttempts - 1);
+                this.#transitionTo(group, bucket, "OPEN");
+                break;
+            case "OPEN":
+                // Shouldn't happen - requests blocked in OPEN
+                break;
+        }
+    }
+    /**
+     * Gets the current state of the circuit for a URL.
+     *
+     * @param url - The URL to check
+     * @returns The current circuit state
+     */
+    getState(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#buckets.get(group);
+        if (!bucket)
+            return "CLOSED";
+        // Check for automatic transition to HALF_OPEN
+        if (bucket.state === "OPEN") {
+            const opts = this.#getOptions(group);
+            const elapsed = Date.now() - (bucket.openedAt ?? 0);
+            if (elapsed >= opts.openDurationMs) {
+                return "HALF_OPEN";
+            }
+        }
+        return bucket.state;
+    }
+    /**
+     * Gets the number of failures in the current window for a URL.
+     *
+     * @param url - The URL to check
+     * @returns The failure count
+     */
+    getFailureCount(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#buckets.get(group);
+        if (!bucket)
+            return 0;
+        const opts = this.#getOptions(group);
+        this.#cleanupFailures(bucket, opts.failureWindowMs);
+        return bucket.failures.length;
+    }
+    /**
+     * Gets the time since the circuit opened for a URL.
+     *
+     * @param url - The URL to check
+     * @returns Time in ms since circuit opened, or null if not open
+     */
+    getTimeSinceOpen(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#buckets.get(group);
+        if (!bucket || bucket.openedAt === null)
+            return null;
+        return Date.now() - bucket.openedAt;
+    }
+    /**
+     * Gets the time remaining before the circuit transitions to HALF_OPEN.
+     *
+     * @param url - The URL to check
+     * @returns Time in ms until HALF_OPEN, or null if not applicable
+     */
+    getTimeUntilHalfOpen(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#buckets.get(group);
+        if (!bucket || bucket.state !== "OPEN" || bucket.openedAt === null) {
+            return null;
+        }
+        const opts = this.#getOptions(group);
+        const elapsed = Date.now() - bucket.openedAt;
+        const remaining = opts.openDurationMs - elapsed;
+        return remaining > 0 ? remaining : 0;
+    }
+    /**
+     * Manually resets (closes) the circuit for a URL or all circuits.
+     *
+     * @param url - Optional URL to reset. If omitted, resets all circuits.
+     */
+    reset(url) {
+        if (url !== undefined) {
+            const group = this.#options.getGroupFunc(url);
+            const bucket = this.#buckets.get(group);
+            if (bucket) {
+                this.#transitionTo(group, bucket, "CLOSED");
+            }
+        }
+        else {
+            // Reset all
+            for (const [group, bucket] of this.#buckets) {
+                this.#transitionTo(group, bucket, "CLOSED");
+            }
+        }
+    }
+    /**
+     * Manually trips (opens) the circuit for a URL.
+     *
+     * @param url - The URL to trip the circuit for
+     */
+    trip(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#getBucket(group);
+        this.#transitionTo(group, bucket, "OPEN");
+    }
+    /**
+     * Sets options for a specific group.
+     *
+     * @param group - The group name
+     * @param options - The options to set
+     */
+    setGroupOptions(group, options) {
+        this.#groupOptions.set(group, options);
+    }
+}
+/**
+ * Groups URLs by their domain (hostname).
+ * Useful for per-domain circuit breakers.
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   getGroupFunc: groupByDomain,
+ * });
+ * ```
+ */
+export function groupByDomain(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return "unknown";
+    }
+}

package/esm/src/CircuitBreakerMiddleware.js

@@ -0,0 +1,167 @@
+import { CircuitBreaker, groupByDomain, } from "./CircuitBreaker.js";
+import { ProblemDetails } from "./ProblemDetails.js";
+/**
+ * Error thrown when a request is blocked due to an open circuit.
+ */
+export class CircuitOpenError extends Error {
+    /** The group whose circuit is open */
+    group;
+    /** The current circuit state */
+    state;
+    /** When the circuit was opened (timestamp) */
+    openedAt;
+    /** Suggested retry time in seconds */
+    retryAfter;
+    constructor(group, state, openedAt, retryAfter, message) {
+        super(message ?? `Circuit breaker is open for ${group}`);
+        this.name = "CircuitOpenError";
+        this.group = group;
+        this.state = state;
+        this.openedAt = openedAt;
+        this.retryAfter = retryAfter;
+    }
+}
+/**
+ * Default function to determine if a response is a failure.
+ * Returns true for 5xx server errors and 429 rate limit responses.
+ */
+function defaultIsFailure(response) {
+    return response.status >= 500 || response.status === 429;
+}
+/**
+ * Middleware that implements the circuit breaker pattern.
+ *
+ * When a service starts failing (5xx errors, timeouts, network errors),
+ * the circuit breaker opens and blocks further requests for a period,
+ * returning 503 Service Unavailable immediately without hitting the API.
+ *
+ * @example
+ * ```typescript
+ * const middleware = new CircuitBreakerMiddleware({
+ *   failureThreshold: 5,
+ *   openDurationMs: 30000,
+ * });
+ *
+ * provider.useMiddleware(middleware.middleware());
+ * ```
+ */
+export class CircuitBreakerMiddleware {
+    #circuitBreaker;
+    #throwOnOpen;
+    #errorMessage;
+    #isFailure;
+    #getGroupFunc;
+    #openDurationMs;
+    constructor(options) {
+        this.#circuitBreaker = new CircuitBreaker(options);
+        this.#throwOnOpen = options?.throwOnOpen ?? false;
+        this.#errorMessage = options?.errorMessage;
+        this.#isFailure = options?.isFailure ?? defaultIsFailure;
+        this.#getGroupFunc = options?.getGroupFunc ?? (() => "global");
+        this.#openDurationMs = options?.openDurationMs ?? 30000;
+    }
+    /**
+     * Gets the underlying circuit breaker instance.
+     */
+    get circuitBreaker() {
+        return this.#circuitBreaker;
+    }
+    /**
+     * Creates the middleware function for use with FetchClient.
+     *
+     * @returns The middleware function
+     */
+    middleware() {
+        return async (ctx, next) => {
+            const url = ctx.request.url;
+            const group = this.#getGroupFunc(url);
+            // PRE-REQUEST: Check if circuit allows the request
+            if (!this.#circuitBreaker.isAllowed(url)) {
+                const timeSinceOpen = this.#circuitBreaker.getTimeSinceOpen(url) ?? 0;
+                const retryAfterMs = Math.max(0, this.#openDurationMs - timeSinceOpen);
+                const retryAfterSeconds = Math.ceil(retryAfterMs / 1000);
+                if (this.#throwOnOpen) {
+                    throw new CircuitOpenError(group, this.#circuitBreaker.getState(url), Date.now() - timeSinceOpen, retryAfterSeconds, this.#errorMessage);
+                }
+                // Return synthetic 503 response
+                const problem = new ProblemDetails();
+                problem.status = 503;
+                problem.title = "Service Unavailable";
+                problem.detail = this.#errorMessage ??
+                    `Circuit breaker is open for ${group}. Service may be experiencing issues.`;
+                const headers = new Headers({
+                    "Content-Type": "application/problem+json",
+                    "Retry-After": String(retryAfterSeconds),
+                });
+                const response = new Response(JSON.stringify(problem), {
+                    status: 503,
+                    statusText: "Service Unavailable",
+                    headers,
+                });
+                // Attach problem details like FetchClient does
+                Object.assign(response, { problem, data: null });
+                ctx.response = response;
+                return;
+            }
+            // EXECUTE REQUEST
+            let isNetworkError = false;
+            try {
+                await next();
+            }
+            catch (error) {
+                // Network errors count as failures
+                isNetworkError = true;
+                this.#circuitBreaker.recordFailure(url);
+                throw error;
+            }
+            // POST-RESPONSE: Record result
+            if (!isNetworkError && ctx.response) {
+                if (this.#isFailure(ctx.response)) {
+                    this.#circuitBreaker.recordFailure(url);
+                }
+                else {
+                    this.#circuitBreaker.recordSuccess(url);
+                }
+            }
+        };
+    }
+}
+/**
+ * Creates a circuit breaker middleware with the given options.
+ *
+ * @param options - Circuit breaker configuration
+ * @returns The middleware function
+ *
+ * @example
+ * ```typescript
+ * provider.useMiddleware(createCircuitBreakerMiddleware({
+ *   failureThreshold: 5,
+ *   openDurationMs: 30000,
+ * }));
+ * ```
+ */
+export function createCircuitBreakerMiddleware(options) {
+    const middleware = new CircuitBreakerMiddleware(options);
+    return middleware.middleware();
+}
+/**
+ * Creates a per-domain circuit breaker middleware.
+ * Each domain gets its own circuit breaker.
+ *
+ * @param options - Circuit breaker configuration
+ * @returns The middleware function
+ *
+ * @example
+ * ```typescript
+ * provider.useMiddleware(createPerDomainCircuitBreakerMiddleware({
+ *   failureThreshold: 5,
+ *   openDurationMs: 30000,
+ * }));
+ * ```
+ */
+export function createPerDomainCircuitBreakerMiddleware(options) {
+    return createCircuitBreakerMiddleware({
+        ...options,
+        getGroupFunc: groupByDomain,
+    });
+}

package/esm/src/DefaultHelpers.js

@@ -73,6 +73,13 @@ export function getCurrentProvider() {
     }
     return getCurrentProviderFunc() ?? defaultProvider;
 }
+/**
+ * Gets the cache from the current provider.
+ * @returns The FetchClientCache instance.
+ */
+export function getCache() {
+    return getCurrentProvider().cache;
+}
 /**
  * Sets the function that retrieves the current FetchClientProvider using whatever scoping mechanism is available.
  * @param getProviderFunc - The function that retrieves the current FetchClientProvider.
@@ -130,3 +137,19 @@ export function useRateLimit(options) {
 export function usePerDomainRateLimit(options) {
     getCurrentProvider().usePerDomainRateLimit(options);
 }
+/**
+ * Enables circuit breaker for any FetchClient instances created by the current provider.
+ * The circuit breaker monitors failures and blocks requests when a service is failing.
+ * @param options - The circuit breaker configuration options.
+ */
+export function useCircuitBreaker(options) {
+    getCurrentProvider().useCircuitBreaker(options);
+}
+/**
+ * Enables per-domain circuit breaker for any FetchClient instances created by the current provider.
+ * Each domain gets its own circuit breaker, so failures on one domain don't affect others.
+ * @param options - The circuit breaker configuration options.
+ */
+export function usePerDomainCircuitBreaker(options) {
+    getCurrentProvider().usePerDomainCircuitBreaker(options);
+}

package/esm/src/FetchClient.js

@@ -295,7 +295,7 @@ export class FetchClient {
                     links: parseLinkHeader(response.headers.get("Link")) || {},
                 };
                 if (getOptions?.cacheKey) {
-                    this.cache.set(getOptions.cacheKey, ctx.response, getOptions.cacheDuration);
+                    this.cache.set(getOptions.cacheKey, ctx.response, getOptions.cacheDuration, getOptions.cacheTags);
                 }
             }
             catch (error) {