@vorionsys/platform-core 0.1.0

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

@@ -0,0 +1,320 @@
+/**
+ * Circuit Breaker pattern implementation for distributed systems
+ *
+ * Provides resilience for external service calls by:
+ * - Tracking failure rates and opening the circuit when threshold is exceeded
+ * - Failing fast when circuit is open to prevent cascading failures
+ * - Testing recovery with half-open state after reset timeout
+ *
+ * State transitions:
+ * CLOSED -> OPEN: When failure count reaches threshold
+ * OPEN -> HALF_OPEN: After reset timeout expires
+ * HALF_OPEN -> CLOSED: On successful call
+ * HALF_OPEN -> OPEN: On failed call
+ *
+ * Per-service configurations allow tuning circuit breaker behavior
+ * based on service characteristics (e.g., database vs. webhook).
+ */
+import type { Redis } from 'ioredis';
+/**
+ * Circuit breaker states
+ */
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/**
+ * Per-service circuit breaker configuration
+ */
+export interface CircuitBreakerConfig {
+    /** Service name identifier */
+    name: string;
+    /** Number of failures before opening the circuit */
+    failureThreshold: number;
+    /** Time in ms before attempting to close the circuit */
+    resetTimeoutMs: number;
+    /** Maximum attempts in half-open state before reopening */
+    halfOpenMaxAttempts: number;
+    /** Time window in ms to monitor for failures */
+    monitorWindowMs: number;
+}
+/**
+ * Default configurations per service type.
+ * These can be overridden via environment variables in config.ts.
+ */
+export declare const CIRCUIT_BREAKER_CONFIGS: Record<string, CircuitBreakerConfig>;
+/**
+ * Circuit breaker configuration options
+ */
+export interface CircuitBreakerOptions {
+    /** Unique name for this circuit breaker (used as Redis key prefix) */
+    name: string;
+    /** Number of failures before opening the circuit (default: 5) */
+    failureThreshold?: number;
+    /** Time in ms before attempting to close the circuit (default: 30000) */
+    resetTimeoutMs?: number;
+    /** Maximum attempts in half-open state before reopening (default: 3) */
+    halfOpenMaxAttempts?: number;
+    /** Time window in ms to monitor for failures (default: 60000) */
+    monitorWindowMs?: number;
+    /** Optional Redis client (uses shared client if not provided) */
+    redis?: Redis;
+    /** Callback when circuit state changes */
+    onStateChange?: (from: CircuitState, to: CircuitState, breaker: CircuitBreaker) => void;
+}
+/**
+ * Result of circuit breaker execution
+ */
+export interface CircuitBreakerResult<T> {
+    success: boolean;
+    result?: T;
+    error?: Error;
+    circuitOpen: boolean;
+}
+/**
+ * Circuit Breaker implementation with Redis-backed state for distributed systems
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   name: 'policy-evaluator',
+ *   failureThreshold: 5,
+ *   resetTimeoutMs: 30000,
+ * });
+ *
+ * const result = await breaker.execute(async () => {
+ *   return await policyEvaluator.evaluateMultiple(policies, context);
+ * });
+ *
+ * if (result.circuitOpen) {
+ *   // Use fallback logic
+ * }
+ * ```
+ */
+export declare class CircuitBreaker {
+    private readonly name;
+    private readonly failureThreshold;
+    private readonly resetTimeoutMs;
+    private readonly halfOpenMaxAttempts;
+    private readonly monitorWindowMs;
+    private readonly redis;
+    private readonly onStateChange?;
+    private localStateCache;
+    private localStateCacheTime;
+    private readonly localStateCacheTtlMs;
+    constructor(options: CircuitBreakerOptions);
+    /**
+     * Get Redis key for this circuit breaker
+     */
+    private getRedisKey;
+    /**
+     * Get the current state from Redis
+     */
+    private getState;
+    /**
+     * Save state to Redis
+     */
+    private setState;
+    /**
+     * Get the current circuit state
+     */
+    getCircuitState(): Promise<CircuitState>;
+    /**
+     * Check if the circuit is currently open (failing fast)
+     */
+    isOpen(): Promise<boolean>;
+    /**
+     * Record a successful call
+     */
+    recordSuccess(): Promise<void>;
+    /**
+     * Record a failed call
+     */
+    recordFailure(): Promise<void>;
+    /**
+     * Execute a function with circuit breaker protection
+     *
+     * @param fn - The function to execute
+     * @returns Result including whether circuit was open
+     */
+    execute<T>(fn: () => Promise<T>): Promise<CircuitBreakerResult<T>>;
+    /**
+     * Force the circuit to open state
+     * Useful for manual intervention or testing
+     */
+    forceOpen(): Promise<void>;
+    /**
+     * Force the circuit to closed state
+     * Useful for manual intervention or testing
+     */
+    forceClose(): Promise<void>;
+    /**
+     * Reset the circuit breaker state completely
+     */
+    reset(): Promise<void>;
+    /**
+     * Get detailed status information for monitoring
+     */
+    getStatus(): Promise<{
+        name: string;
+        state: CircuitState;
+        failureCount: number;
+        failureThreshold: number;
+        resetTimeoutMs: number;
+        halfOpenMaxAttempts: number;
+        halfOpenAttempts: number;
+        monitorWindowMs: number;
+        lastFailureTime: Date | null;
+        openedAt: Date | null;
+        timeUntilReset: number | null;
+        windowStartTime: Date | null;
+    }>;
+    /**
+     * Notify state change callback
+     */
+    private notifyStateChange;
+}
+/**
+ * Factory function to create a circuit breaker with common defaults
+ */
+export declare function createCircuitBreaker(options: CircuitBreakerOptions): CircuitBreaker;
+/**
+ * Set configuration overrides for circuit breakers.
+ * This should be called during application initialization before any circuit breakers are used.
+ *
+ * @example
+ * ```typescript
+ * setCircuitBreakerConfigOverrides({
+ *   database: { failureThreshold: 10, resetTimeoutMs: 60000 },
+ *   redis: { failureThreshold: 20 },
+ * });
+ * ```
+ */
+export declare function setCircuitBreakerConfigOverrides(overrides: Record<string, Partial<CircuitBreakerConfig>>): void;
+/**
+ * Get or create a circuit breaker for a specific service.
+ * Uses the default configuration for the service type, with optional overrides.
+ *
+ * @param serviceName - The name of the service (e.g., 'database', 'redis', 'webhook')
+ * @param onStateChange - Optional callback for state changes
+ * @returns The circuit breaker instance for the service
+ *
+ * @example
+ * ```typescript
+ * const dbBreaker = getCircuitBreaker('database');
+ * const result = await dbBreaker.execute(async () => {
+ *   return await db.query('SELECT * FROM users');
+ * });
+ * ```
+ */
+export declare function getCircuitBreaker(serviceName: string, onStateChange?: (from: CircuitState, to: CircuitState, breaker: CircuitBreaker) => void): CircuitBreaker;
+/**
+ * Get all registered circuit breakers with their current status.
+ * Useful for health checks and monitoring dashboards.
+ *
+ * @returns Map of service names to their circuit breaker status
+ */
+export declare function getAllCircuitBreakerStatuses(): Promise<Map<string, Awaited<ReturnType<CircuitBreaker['getStatus']>>>>;
+/**
+ * Reset a specific circuit breaker by service name.
+ * Useful for manual recovery during incidents.
+ *
+ * @param serviceName - The service name to reset
+ * @returns True if the circuit breaker was found and reset
+ */
+export declare function resetCircuitBreaker(serviceName: string): Promise<boolean>;
+/**
+ * Clear all circuit breakers from the registry.
+ * Primarily for testing purposes.
+ */
+export declare function clearCircuitBreakerRegistry(): void;
+/**
+ * Error thrown when a circuit breaker is open and blocking execution.
+ * This error allows callers to distinguish circuit breaker rejections
+ * from actual execution failures.
+ */
+export declare class CircuitBreakerOpenError extends Error {
+    readonly serviceName: string;
+    readonly circuitState: CircuitState;
+    constructor(serviceName: string, circuitState?: CircuitState);
+}
+/**
+ * Callback type for recording circuit breaker metrics.
+ * This allows the circuit breaker module to emit metrics without
+ * depending directly on the metrics module (avoiding circular deps).
+ */
+export type CircuitBreakerMetricsCallback = {
+    recordStateChange: (serviceName: string, fromState: CircuitState, toState: CircuitState) => void;
+    recordFailure: (serviceName: string) => void;
+    recordSuccess: (serviceName: string) => void;
+    updateState: (serviceName: string, state: CircuitState) => void;
+};
+/**
+ * Set the metrics callback for circuit breaker operations.
+ * This should be called during application initialization to wire up
+ * Prometheus metrics without creating circular dependencies.
+ *
+ * @param callback - The metrics callback functions
+ */
+export declare function setCircuitBreakerMetricsCallback(callback: CircuitBreakerMetricsCallback): void;
+/**
+ * Execute a function with circuit breaker protection.
+ *
+ * This is a convenience wrapper that:
+ * 1. Gets or creates the appropriate circuit breaker for the service
+ * 2. Executes the function through the circuit breaker
+ * 3. Records metrics for state changes, successes, and failures
+ * 4. Throws CircuitBreakerOpenError when the circuit is open
+ *
+ * @param serviceName - The service name identifier (must match CIRCUIT_BREAKER_CONFIGS keys)
+ * @param fn - The async function to execute
+ * @returns The result of the function
+ * @throws CircuitBreakerOpenError when the circuit is open
+ * @throws The original error if the function fails
+ *
+ * @example
+ * ```typescript
+ * // Protect a database call
+ * const result = await withCircuitBreaker('database', async () => {
+ *   return await db.query('SELECT * FROM users WHERE id = $1', [userId]);
+ * });
+ *
+ * // Protect an external API call
+ * try {
+ *   const data = await withCircuitBreaker('gdprService', async () => {
+ *     return await gdprApi.exportUserData(userId);
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerOpenError) {
+ *     // Handle circuit open - use fallback or return cached data
+ *     return cachedData;
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export declare function withCircuitBreaker<T>(serviceName: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Execute a function with circuit breaker protection, returning a result object
+ * instead of throwing on circuit open.
+ *
+ * This variant is useful when you want to handle circuit open gracefully
+ * without try/catch.
+ *
+ * @param serviceName - The service name identifier
+ * @param fn - The async function to execute
+ * @returns Result object with success flag, result/error, and circuitOpen indicator
+ *
+ * @example
+ * ```typescript
+ * const result = await withCircuitBreakerResult('auditService', async () => {
+ *   return await auditService.record(event);
+ * });
+ *
+ * if (result.circuitOpen) {
+ *   // Queue for retry later
+ *   await queueForRetry(event);
+ * } else if (!result.success) {
+ *   logger.error({ error: result.error }, 'Audit failed');
+ * }
+ * ```
+ */
+export declare function withCircuitBreakerResult<T>(serviceName: string, fn: () => Promise<T>): Promise<CircuitBreakerResult<T>>;
+//# sourceMappingURL=circuit-breaker.d.ts.map

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

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