@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/circuit-breaker.js

@@ -1 +1,468 @@
-import{ok,err}from"./_deps/shared/index.js";export class CircuitBreaker{state="CLOSED";consecutiveFailures=0;consecutiveSuccesses=0;successCount=0;failureCount=0;rejectedCount=0;lastOpenedAt;lastClosedAt;recoveryTimer;failureThreshold;recoveryTimeout;halfOpenMaxCalls;successThreshold;name;onStateChange;onOpen;onClose;onHalfOpen;constructor(e={}){this.failureThreshold=e.failureThreshold??5,this.recoveryTimeout=e.recoveryTimeout??6e4,this.halfOpenMaxCalls=e.halfOpenMaxCalls??3,this.successThreshold=e.successThreshold??2,this.name=e.name??"default",this.onStateChange=e.onStateChange,this.onOpen=e.onOpen,this.onClose=e.onClose,this.onHalfOpen=e.onHalfOpen}async execute(e){if("OPEN"===this.state)return this.rejectedCount++,err("CIRCUIT_OPEN");if("HALF_OPEN"===this.state){if(this.consecutiveSuccesses+(this.consecutiveFailures>0?1:0)>=this.halfOpenMaxCalls)return this.rejectedCount++,err("HALF_OPEN_LIMIT_EXCEEDED")}try{const t=await e();return this.onSuccess(),ok(t)}catch(e){return this.onFailure(e),err("EXECUTION_FAILED")}}getMetrics(){return{state:this.state,successCount:this.successCount,failureCount:this.failureCount,rejectedCount:this.rejectedCount,consecutiveFailures:this.consecutiveFailures,consecutiveSuccesses:this.consecutiveSuccesses,lastOpenedAt:this.lastOpenedAt,lastClosedAt:this.lastClosedAt,name:this.name}}getState(){return this.state}reset(){this.clearRecoveryTimer(),this.transitionTo("CLOSED","manual reset"),this.consecutiveFailures=0,this.consecutiveSuccesses=0}forceOpen(e="manual intervention"){this.transitionTo("OPEN",e),this.scheduleRecovery()}dispose(){this.clearRecoveryTimer()}onSuccess(){this.successCount++,this.consecutiveFailures=0,"HALF_OPEN"===this.state&&(this.consecutiveSuccesses++,this.consecutiveSuccesses>=this.successThreshold&&(this.transitionTo("CLOSED",`${this.consecutiveSuccesses} consecutive successes`),this.consecutiveSuccesses=0))}onFailure(e){if(this.failureCount++,this.consecutiveFailures++,this.consecutiveSuccesses=0,"CLOSED"===this.state&&this.consecutiveFailures>=this.failureThreshold){const e=`${this.consecutiveFailures} consecutive failures`;this.transitionTo("OPEN",e),this.scheduleRecovery()}"HALF_OPEN"===this.state&&(this.transitionTo("OPEN","failure in HALF_OPEN state"),this.scheduleRecovery())}transitionTo(e,t){const s=this.state;s!==e&&(this.state=e,"OPEN"===e?(this.lastOpenedAt=Date.now(),this.onOpen?.(t)):"CLOSED"===e?(this.lastClosedAt=Date.now(),this.onClose?.()):"HALF_OPEN"===e&&this.onHalfOpen?.(),this.onStateChange?.(s,e,t))}scheduleRecovery(){this.clearRecoveryTimer(),this.recoveryTimer=setTimeout(()=>{"OPEN"===this.state&&this.transitionTo("HALF_OPEN","recovery timeout elapsed")},this.recoveryTimeout),this.recoveryTimer.unref&&this.recoveryTimer.unref()}clearRecoveryTimer(){this.recoveryTimer&&(clearTimeout(this.recoveryTimer),this.recoveryTimer=void 0)}}export function createRegistryCircuitBreaker(e={}){return new CircuitBreaker({name:"registry",failureThreshold:10,recoveryTimeout:12e4,halfOpenMaxCalls:5,successThreshold:3,...e})}export function createGatewayCircuitBreaker(e={}){return new CircuitBreaker({name:"gateway",failureThreshold:5,recoveryTimeout:6e4,halfOpenMaxCalls:3,successThreshold:2,...e})}export function createS3CircuitBreaker(e={}){return new CircuitBreaker({name:"s3",failureThreshold:3,recoveryTimeout:3e4,halfOpenMaxCalls:2,successThreshold:2,...e})}export class CircuitBreakerManager{breakers=new Map;constructor(){this.breakers.set("registry",createRegistryCircuitBreaker()),this.breakers.set("gateway",createGatewayCircuitBreaker()),this.breakers.set("s3",createS3CircuitBreaker())}async executeRegistry(e){const t=this.breakers.get("registry");return t?t.execute(e):err("Circuit breaker not found: registry")}async executeGateway(e){const t=this.breakers.get("gateway");return t?t.execute(e):err("Circuit breaker not found: gateway")}async executeS3(e){const t=this.breakers.get("s3");return t?t.execute(e):err("Circuit breaker not found: s3")}getMetrics(e){return this.breakers.get(e)?.getMetrics()}getAllMetrics(){const e={};for(const[t,s]of this.breakers.entries())e[t]=s.getMetrics();return e}getOrCreate(e,t){let s=this.breakers.get(e);return s||(s=new CircuitBreaker({...t,name:e}),this.breakers.set(e,s)),s}resetAll(){for(const e of this.breakers.values())e.reset()}dispose(){for(const e of this.breakers.values())e.dispose();this.breakers.clear()}}
+/**
+ * @module circuit-breaker
+ * Circuit breaker pattern for enhanced fault tolerance
+ *
+ * Protects external service calls (registry, gateway, S3) from cascading failures
+ * by automatically opening circuits after repeated failures and closing them after
+ * recovery periods.
+ *
+ * Architecture:
+ * - CLOSED: Normal operation, all requests pass through
+ * - OPEN: Circuit tripped, fast-fail all requests without calling service
+ * - HALF_OPEN: Testing recovery, allow limited requests to probe service health
+ *
+ * Features:
+ * - Automatic state transitions based on failure thresholds
+ * - Exponential backoff for recovery attempts
+ * - Per-service circuit isolation
+ * - Metrics integration for monitoring
+ * - Type-safe error handling
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   recoveryTimeout: 60000,
+ *   halfOpenMaxCalls: 3,
+ * });
+ *
+ * const result = await breaker.execute(async () => {
+ *   return await registryClient.lookup(did);
+ * });
+ * ```
+ */
+import { ok, err } from"./_deps/shared/index.js";
+/* ── Implementation ── */
+/**
+ * Circuit breaker for protecting external service calls.
+ *
+ * Implements the circuit breaker pattern to prevent cascading failures
+ * when external services (registry, gateway, S3) become unavailable.
+ *
+ * State transitions:
+ * - CLOSED → OPEN: After failureThreshold consecutive failures
+ * - OPEN → HALF_OPEN: After recoveryTimeout milliseconds
+ * - HALF_OPEN → CLOSED: After successThreshold successful calls
+ * - HALF_OPEN → OPEN: On any failure
+ *
+ * @example
+ * ```typescript
+ * // Create circuit breaker for registry calls
+ * const registryBreaker = new CircuitBreaker({
+ *   name: 'registry',
+ *   failureThreshold: 5,
+ *   recoveryTimeout: 60000,
+ * });
+ *
+ * // Execute protected call
+ * const result = await registryBreaker.execute(async () => {
+ *   return await registry.lookup(did);
+ * });
+ *
+ * if (!result.ok) {
+ *   console.error('Circuit breaker error:', result.error);
+ * }
+ * ```
+ */
+export class CircuitBreaker {
+    state = 'CLOSED';
+    consecutiveFailures = 0;
+    consecutiveSuccesses = 0;
+    successCount = 0;
+    failureCount = 0;
+    rejectedCount = 0;
+    lastOpenedAt;
+    lastClosedAt;
+    recoveryTimer;
+    failureThreshold;
+    recoveryTimeout;
+    halfOpenMaxCalls;
+    successThreshold;
+    name;
+    onStateChange;
+    onOpen;
+    onClose;
+    onHalfOpen;
+    /**
+     * Create a new circuit breaker.
+     *
+     * @param options - Circuit breaker configuration
+     */
+    constructor(options = {}) {
+        this.failureThreshold = options.failureThreshold ?? 5;
+        this.recoveryTimeout = options.recoveryTimeout ?? 60000;
+        this.halfOpenMaxCalls = options.halfOpenMaxCalls ?? 3;
+        this.successThreshold = options.successThreshold ?? 2;
+        this.name = options.name ?? 'default';
+        this.onStateChange = options.onStateChange;
+        this.onOpen = options.onOpen;
+        this.onClose = options.onClose;
+        this.onHalfOpen = options.onHalfOpen;
+    }
+    /**
+     * Execute a function with circuit breaker protection.
+     *
+     * If the circuit is OPEN, immediately returns an error without calling the function.
+     * If the circuit is HALF_OPEN, limits the number of concurrent calls.
+     * If the circuit is CLOSED, executes the function normally.
+     *
+     * @param fn - Async function to execute
+     * @returns Result of function execution or circuit breaker error
+     */
+    async execute(fn) {
+        // Check if circuit is open
+        if (this.state === 'OPEN') {
+            this.rejectedCount++;
+            return err('CIRCUIT_OPEN');
+        }
+        // Check if we've exceeded half-open call limit
+        // Use total calls attempted (success + failure) not just counter
+        if (this.state === 'HALF_OPEN') {
+            const totalAttempts = this.consecutiveSuccesses + (this.consecutiveFailures > 0 ? 1 : 0);
+            if (totalAttempts >= this.halfOpenMaxCalls) {
+                this.rejectedCount++;
+                return err('HALF_OPEN_LIMIT_EXCEEDED');
+            }
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return ok(result);
+        }
+        catch (error) {
+            this.onFailure(error);
+            return err('EXECUTION_FAILED');
+        }
+    }
+    /**
+     * Get current circuit breaker metrics.
+     *
+     * @returns Current metrics snapshot
+     */
+    getMetrics() {
+        return {
+            state: this.state,
+            successCount: this.successCount,
+            failureCount: this.failureCount,
+            rejectedCount: this.rejectedCount,
+            consecutiveFailures: this.consecutiveFailures,
+            consecutiveSuccesses: this.consecutiveSuccesses,
+            lastOpenedAt: this.lastOpenedAt,
+            lastClosedAt: this.lastClosedAt,
+            name: this.name,
+        };
+    }
+    /**
+     * Get current circuit state.
+     *
+     * @returns Current state (CLOSED, OPEN, or HALF_OPEN)
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Manually reset the circuit breaker to CLOSED state.
+     *
+     * Useful for testing or manual recovery scenarios.
+     * Clears all counters and timers.
+     */
+    reset() {
+        this.clearRecoveryTimer();
+        this.transitionTo('CLOSED', 'manual reset');
+        this.consecutiveFailures = 0;
+        this.consecutiveSuccesses = 0;
+    }
+    /**
+     * Manually open the circuit breaker.
+     *
+     * Useful for maintenance windows or manual intervention.
+     *
+     * @param reason - Optional reason for opening circuit
+     */
+    forceOpen(reason = 'manual intervention') {
+        this.transitionTo('OPEN', reason);
+        this.scheduleRecovery();
+    }
+    /**
+     * Dispose of the circuit breaker and clean up resources.
+     *
+     * Clears any pending recovery timers.
+     */
+    dispose() {
+        this.clearRecoveryTimer();
+    }
+    /* ── Private Methods ── */
+    /**
+     * Handle successful execution.
+     */
+    onSuccess() {
+        this.successCount++;
+        this.consecutiveFailures = 0;
+        if (this.state === 'HALF_OPEN') {
+            this.consecutiveSuccesses++;
+            // Close circuit if we've reached success threshold
+            if (this.consecutiveSuccesses >= this.successThreshold) {
+                this.transitionTo('CLOSED', `${this.consecutiveSuccesses} consecutive successes`);
+                this.consecutiveSuccesses = 0;
+            }
+        }
+    }
+    /**
+     * Handle failed execution.
+     *
+     * @param _error - Error that occurred (unused but kept for potential future logging)
+     */
+    onFailure(_error) {
+        this.failureCount++;
+        this.consecutiveFailures++;
+        this.consecutiveSuccesses = 0;
+        // Open circuit if we've exceeded failure threshold in CLOSED state
+        if (this.state === 'CLOSED' && this.consecutiveFailures >= this.failureThreshold) {
+            const reason = `${this.consecutiveFailures} consecutive failures`;
+            this.transitionTo('OPEN', reason);
+            this.scheduleRecovery();
+        }
+        // Reopen circuit on any failure in HALF_OPEN state
+        if (this.state === 'HALF_OPEN') {
+            this.transitionTo('OPEN', 'failure in HALF_OPEN state');
+            this.scheduleRecovery();
+        }
+    }
+    /**
+     * Transition to a new state.
+     *
+     * @param newState - Target state
+     * @param reason - Reason for transition
+     */
+    transitionTo(newState, reason) {
+        const oldState = this.state;
+        if (oldState === newState) {
+            return;
+        }
+        this.state = newState;
+        // Update timestamps
+        if (newState === 'OPEN') {
+            this.lastOpenedAt = Date.now();
+            this.onOpen?.(reason);
+        }
+        else if (newState === 'CLOSED') {
+            this.lastClosedAt = Date.now();
+            this.onClose?.();
+        }
+        else if (newState === 'HALF_OPEN') {
+            this.onHalfOpen?.();
+        }
+        // Invoke state change callback
+        this.onStateChange?.(oldState, newState, reason);
+    }
+    /**
+     * Schedule automatic recovery from OPEN to HALF_OPEN state.
+     */
+    scheduleRecovery() {
+        this.clearRecoveryTimer();
+        this.recoveryTimer = setTimeout(() => {
+            if (this.state === 'OPEN') {
+                this.transitionTo('HALF_OPEN', 'recovery timeout elapsed');
+            }
+        }, this.recoveryTimeout);
+        // Don't prevent Node.js from exiting
+        if (this.recoveryTimer.unref) {
+            this.recoveryTimer.unref();
+        }
+    }
+    /**
+     * Clear any pending recovery timer.
+     */
+    clearRecoveryTimer() {
+        if (this.recoveryTimer) {
+            clearTimeout(this.recoveryTimer);
+            this.recoveryTimer = undefined;
+        }
+    }
+}
+/* ── Service-Specific Circuit Breakers ── */
+/**
+ * Create a circuit breaker configured for registry operations.
+ *
+ * Registry operations have:
+ * - Higher failure threshold (10) - registry is critical, tolerate transient failures
+ * - Longer recovery timeout (2 minutes) - DNS/network issues take time
+ * - More half-open probes (5) - verify stability before full recovery
+ *
+ * @param options - Optional overrides
+ * @returns Configured circuit breaker for registry calls
+ */
+export function createRegistryCircuitBreaker(options = {}) {
+    return new CircuitBreaker({
+        name: 'registry',
+        failureThreshold: 10,
+        recoveryTimeout: 120000, // 2 minutes
+        halfOpenMaxCalls: 5,
+        successThreshold: 3,
+        ...options,
+    });
+}
+/**
+ * Create a circuit breaker configured for gateway operations.
+ *
+ * Gateway operations have:
+ * - Medium failure threshold (5) - gateway should be reliable
+ * - Standard recovery timeout (1 minute)
+ * - Standard half-open probes (3)
+ *
+ * @param options - Optional overrides
+ * @returns Configured circuit breaker for gateway calls
+ */
+export function createGatewayCircuitBreaker(options = {}) {
+    return new CircuitBreaker({
+        name: 'gateway',
+        failureThreshold: 5,
+        recoveryTimeout: 60000, // 1 minute
+        halfOpenMaxCalls: 3,
+        successThreshold: 2,
+        ...options,
+    });
+}
+/**
+ * Create a circuit breaker configured for S3 storage operations.
+ *
+ * S3 operations have:
+ * - Lower failure threshold (3) - storage failures are serious
+ * - Shorter recovery timeout (30 seconds) - AWS S3 recovers quickly
+ * - Fewer half-open probes (2) - S3 is usually reliable
+ *
+ * @param options - Optional overrides
+ * @returns Configured circuit breaker for S3 calls
+ */
+export function createS3CircuitBreaker(options = {}) {
+    return new CircuitBreaker({
+        name: 's3',
+        failureThreshold: 3,
+        recoveryTimeout: 30000, // 30 seconds
+        halfOpenMaxCalls: 2,
+        successThreshold: 2,
+        ...options,
+    });
+}
+/* ── Multi-Service Circuit Breaker Manager ── */
+/**
+ * Manages multiple circuit breakers for different services.
+ *
+ * Provides centralized access to service-specific circuit breakers
+ * and aggregated metrics across all circuits.
+ *
+ * @example
+ * ```typescript
+ * const manager = new CircuitBreakerManager();
+ *
+ * // Execute registry call with protection
+ * const result = await manager.executeRegistry(async () => {
+ *   return await registry.lookup(did);
+ * });
+ *
+ * // Get all metrics
+ * const metrics = manager.getAllMetrics();
+ * console.log('Registry state:', metrics.registry.state);
+ * ```
+ */
+export class CircuitBreakerManager {
+    breakers = new Map();
+    constructor() {
+        // Initialize default breakers
+        this.breakers.set('registry', createRegistryCircuitBreaker());
+        this.breakers.set('gateway', createGatewayCircuitBreaker());
+        this.breakers.set('s3', createS3CircuitBreaker());
+    }
+    /**
+     * Execute a function with registry circuit breaker protection.
+     *
+     * @param fn - Async function to execute
+     * @returns Result of function execution or circuit breaker error
+     */
+    async executeRegistry(fn) {
+        const breaker = this.breakers.get('registry');
+        if (!breaker) {
+            return err('Circuit breaker not found: registry');
+        }
+        return breaker.execute(fn);
+    }
+    /**
+     * Execute a function with gateway circuit breaker protection.
+     *
+     * @param fn - Async function to execute
+     * @returns Result of function execution or circuit breaker error
+     */
+    async executeGateway(fn) {
+        const breaker = this.breakers.get('gateway');
+        if (!breaker) {
+            return err('Circuit breaker not found: gateway');
+        }
+        return breaker.execute(fn);
+    }
+    /**
+     * Execute a function with S3 circuit breaker protection.
+     *
+     * @param fn - Async function to execute
+     * @returns Result of function execution or circuit breaker error
+     */
+    async executeS3(fn) {
+        const breaker = this.breakers.get('s3');
+        if (!breaker) {
+            return err('Circuit breaker not found: s3');
+        }
+        return breaker.execute(fn);
+    }
+    /**
+     * Get metrics for a specific circuit breaker.
+     *
+     * @param name - Circuit breaker name
+     * @returns Metrics or undefined if breaker not found
+     */
+    getMetrics(name) {
+        return this.breakers.get(name)?.getMetrics();
+    }
+    /**
+     * Get metrics for all circuit breakers.
+     *
+     * @returns Map of circuit name to metrics
+     */
+    getAllMetrics() {
+        const metrics = {};
+        for (const [name, breaker] of this.breakers.entries()) {
+            metrics[name] = breaker.getMetrics();
+        }
+        return metrics;
+    }
+    /**
+     * Get or create a custom circuit breaker.
+     *
+     * @param name - Circuit breaker name
+     * @param options - Optional configuration (used only on first access)
+     * @returns Circuit breaker instance
+     */
+    getOrCreate(name, options) {
+        let breaker = this.breakers.get(name);
+        if (!breaker) {
+            breaker = new CircuitBreaker({ ...options, name });
+            this.breakers.set(name, breaker);
+        }
+        return breaker;
+    }
+    /**
+     * Reset all circuit breakers to CLOSED state.
+     */
+    resetAll() {
+        for (const breaker of this.breakers.values()) {
+            breaker.reset();
+        }
+    }
+    /**
+     * Dispose of all circuit breakers and clean up resources.
+     */
+    dispose() {
+        for (const breaker of this.breakers.values()) {
+            breaker.dispose();
+        }
+        this.breakers.clear();
+    }
+}