@private.me/xbind 3.0.2 → 3.0.4

package/dist-standalone/cjs/circuit-breaker.js

@@ -1,476 +1 @@
-"use strict";
-/**
- * @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);
- * });
- * ```
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CircuitBreakerManager = exports.CircuitBreaker = void 0;
-exports.createRegistryCircuitBreaker = createRegistryCircuitBreaker;
-exports.createGatewayCircuitBreaker = createGatewayCircuitBreaker;
-exports.createS3CircuitBreaker = createS3CircuitBreaker;
-const shared_1 = require("../_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);
- * }
- * ```
- */
-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 (0, shared_1.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 (0, shared_1.err)('HALF_OPEN_LIMIT_EXCEEDED');
-            }
-        }
-        try {
-            const result = await fn();
-            this.onSuccess();
-            return (0, shared_1.ok)(result);
-        }
-        catch (error) {
-            this.onFailure(error);
-            return (0, shared_1.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;
-        }
-    }
-}
-exports.CircuitBreaker = CircuitBreaker;
-/* ── 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
- */
-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
- */
-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
- */
-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);
- * ```
- */
-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 (0, shared_1.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 (0, shared_1.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 (0, shared_1.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();
-    }
-}
-exports.CircuitBreakerManager = CircuitBreakerManager;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.CircuitBreakerManager=exports.CircuitBreaker=void 0,exports.createRegistryCircuitBreaker=createRegistryCircuitBreaker,exports.createGatewayCircuitBreaker=createGatewayCircuitBreaker,exports.createS3CircuitBreaker=createS3CircuitBreaker;const shared_1=require("../_deps/shared/index.js");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++,(0,shared_1.err)("CIRCUIT_OPEN");if("HALF_OPEN"===this.state){if(this.consecutiveSuccesses+(this.consecutiveFailures>0?1:0)>=this.halfOpenMaxCalls)return this.rejectedCount++,(0,shared_1.err)("HALF_OPEN_LIMIT_EXCEEDED")}try{const t=await e();return this.onSuccess(),(0,shared_1.ok)(t)}catch(e){return this.onFailure(e),(0,shared_1.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)}}function createRegistryCircuitBreaker(e={}){return new CircuitBreaker({name:"registry",failureThreshold:10,recoveryTimeout:12e4,halfOpenMaxCalls:5,successThreshold:3,...e})}function createGatewayCircuitBreaker(e={}){return new CircuitBreaker({name:"gateway",failureThreshold:5,recoveryTimeout:6e4,halfOpenMaxCalls:3,successThreshold:2,...e})}function createS3CircuitBreaker(e={}){return new CircuitBreaker({name:"s3",failureThreshold:3,recoveryTimeout:3e4,halfOpenMaxCalls:2,successThreshold:2,...e})}exports.CircuitBreaker=CircuitBreaker;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):(0,shared_1.err)("Circuit breaker not found: registry")}async executeGateway(e){const t=this.breakers.get("gateway");return t?t.execute(e):(0,shared_1.err)("Circuit breaker not found: gateway")}async executeS3(e){const t=this.breakers.get("s3");return t?t.execute(e):(0,shared_1.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()}}exports.CircuitBreakerManager=CircuitBreakerManager;