@dotdo/postgres 0.1.0

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

@@ -0,0 +1,339 @@
+/**
+ * Circuit Breaker Pattern for Durable Object Resilience
+ *
+ * @deprecated This module is deprecated and will be removed in a future version.
+ * Please use the circuit breaker from @dotdo/postgres-shared instead:
+ *
+ * ```typescript
+ * // Option 1: Use the base CircuitBreaker with DOCircuitBreakerWrapper
+ * import {
+ *   CircuitBreaker,
+ *   DOCircuitBreakerWrapper,
+ *   CircuitOpenError,
+ * } from '@dotdo/postgres-shared'
+ *
+ * const wrapper = new DOCircuitBreakerWrapper({
+ *   failureThreshold: 5,
+ *   resetTimeoutMs: 30000,
+ *   fallbackResponse: () => new Response('Service unavailable', { status: 503 }),
+ * })
+ * const protectedStub = wrapper.wrap(doStub, 'tenant-123')
+ *
+ * // Option 2: Use the unified circuit breaker
+ * import { createUnifiedCircuitBreaker } from '@dotdo/postgres-shared'
+ *
+ * const cb = createUnifiedCircuitBreaker({
+ *   mode: 'multi',
+ *   failureThreshold: 5,
+ *   resetTimeoutMs: 30000,
+ * })
+ *
+ * // Execute with circuit breaker protection
+ * const result = await cb.execute('tenant-123', async () => doStub.fetch(request))
+ * ```
+ *
+ * Migration notes:
+ * - All types and classes are identical to @dotdo/postgres-shared
+ * - CircuitOpenError is now in @dotdo/postgres-shared/errors
+ * - The API surface is fully compatible
+ *
+ * See packages/shared/src/circuit-breaker.ts for the primary implementation.
+ */
+/**
+ * Circuit breaker states
+ */
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/**
+ * Circuit breaker event types for monitoring
+ */
+export type CircuitBreakerEvent = {
+    type: 'STATE_CHANGE';
+    from: CircuitState;
+    to: CircuitState;
+    instanceId: string;
+    timestamp: number;
+} | {
+    type: 'FAILURE_RECORDED';
+    instanceId: string;
+    failureCount: number;
+    timestamp: number;
+} | {
+    type: 'SUCCESS_RECORDED';
+    instanceId: string;
+    timestamp: number;
+} | {
+    type: 'REQUEST_REJECTED';
+    instanceId: string;
+    state: CircuitState;
+    timestamp: number;
+} | {
+    type: 'HALF_OPEN_TEST';
+    instanceId: string;
+    success: boolean;
+    timestamp: number;
+};
+/**
+ * Metrics collector interface for aggregating circuit breaker metrics
+ */
+export interface CircuitBreakerMetricsCollector {
+    /** Record a state transition */
+    recordStateTransition(instanceId: string, from: CircuitState, to: CircuitState): void;
+    /** Record a failure */
+    recordFailure(instanceId: string, failureCount: number): void;
+    /** Record a success */
+    recordSuccess(instanceId: string): void;
+    /** Record a rejected request */
+    recordRejection(instanceId: string): void;
+    /** Record current backoff timeout for an instance */
+    recordBackoffTimeout(instanceId: string, timeoutMs: number): void;
+    /** Get aggregated metrics summary */
+    getSummary(): CircuitBreakerMetricsSummary;
+}
+/**
+ * Summary of aggregated circuit breaker metrics
+ */
+export interface CircuitBreakerMetricsSummary {
+    totalInstances: number;
+    openCircuits: number;
+    halfOpenCircuits: number;
+    closedCircuits: number;
+    totalFailures: number;
+    totalSuccesses: number;
+    totalRejections: number;
+    averageBackoffMs: number;
+}
+/**
+ * Configuration options for the circuit breaker
+ */
+export interface CircuitBreakerConfig {
+    /** Number of consecutive failures before opening the circuit (default: 5) */
+    failureThreshold?: number;
+    /** Base time in ms to wait before moving from OPEN to HALF_OPEN (default: 30000) */
+    resetTimeoutMs?: number;
+    /** Number of successful requests in HALF_OPEN to close circuit (default: 3) */
+    halfOpenSuccessThreshold?: number;
+    /** Time window in ms for counting failures (default: 60000) */
+    failureWindowMs?: number;
+    /** Optional event handler for circuit breaker events */
+    onEvent?: (event: CircuitBreakerEvent) => void;
+    /** Optional fallback function when circuit is open */
+    fallback?: <T>() => Promise<T>;
+    /** Enable exponential backoff for recovery timeouts (default: true) */
+    enableExponentialBackoff?: boolean;
+    /** Multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+    /** Maximum timeout in ms when using exponential backoff (default: 300000 = 5 minutes) */
+    maxResetTimeoutMs?: number;
+    /** Optional metrics collector for aggregating circuit breaker metrics */
+    metricsCollector?: CircuitBreakerMetricsCollector;
+}
+/**
+ * Statistics for a circuit breaker instance
+ */
+export interface CircuitBreakerStats {
+    state: CircuitState;
+    failureCount: number;
+    successCount: number;
+    lastFailureTime: number | null;
+    lastSuccessTime: number | null;
+    lastStateChangeTime: number;
+    totalRequests: number;
+    totalFailures: number;
+    totalSuccesses: number;
+    totalRejected: number;
+    /** Number of consecutive circuit opens (for exponential backoff tracking) */
+    consecutiveOpens: number;
+    /** Current reset timeout in ms (may be increased due to exponential backoff) */
+    currentResetTimeoutMs: number;
+}
+/**
+ * Error thrown when circuit is open
+ */
+export declare class CircuitOpenError extends Error {
+    readonly instanceId: string;
+    readonly state: CircuitState;
+    readonly retryAfterMs: number;
+    constructor(instanceId: string, state: CircuitState, retryAfterMs: number);
+}
+/**
+ * Circuit Breaker implementation
+ *
+ * Tracks failures per DO instance and manages state transitions.
+ */
+export declare class CircuitBreaker {
+    private config;
+    private instances;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Get or create state for a DO instance
+     */
+    private getInstanceState;
+    /**
+     * Calculate the reset timeout with exponential backoff
+     */
+    private calculateBackoffTimeout;
+    /**
+     * Emit an event if handler is configured
+     */
+    private emitEvent;
+    /**
+     * Transition to a new state
+     */
+    private transitionState;
+    /**
+     * Clean up old failures outside the failure window
+     */
+    private cleanupOldFailures;
+    /**
+     * Get the current state of the circuit for an instance
+     */
+    getState(instanceId: string): CircuitState;
+    /**
+     * Check if a request is allowed to proceed
+     */
+    canExecute(instanceId: string): boolean;
+    /**
+     * Record a successful request
+     */
+    recordSuccess(instanceId: string): void;
+    /**
+     * Record a failed request
+     */
+    recordFailure(instanceId: string): void;
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    execute<T>(instanceId: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get statistics for an instance
+     */
+    getStats(instanceId: string): CircuitBreakerStats;
+    /**
+     * Get statistics for all tracked instances
+     */
+    getAllStats(): Map<string, CircuitBreakerStats>;
+    /**
+     * Manually reset the circuit for an instance
+     */
+    reset(instanceId: string): void;
+    /**
+     * Manually force a circuit to open (useful for maintenance)
+     */
+    forceOpen(instanceId: string): void;
+    /**
+     * Remove tracking for an instance
+     */
+    remove(instanceId: string): boolean;
+    /**
+     * Clear all tracked instances
+     */
+    clear(): void;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): Required<Omit<CircuitBreakerConfig, 'onEvent' | 'fallback' | 'metricsCollector'>>;
+    /**
+     * Get the current backoff timeout for an instance
+     */
+    getBackoffTimeout(instanceId: string): number;
+}
+/**
+ * Default in-memory implementation of CircuitBreakerMetricsCollector
+ *
+ * Provides basic metrics aggregation for monitoring circuit breaker behavior.
+ */
+export declare class DefaultMetricsCollector implements CircuitBreakerMetricsCollector {
+    private stateTransitions;
+    private failures;
+    private successes;
+    private rejections;
+    private backoffTimeouts;
+    private currentStates;
+    recordStateTransition(instanceId: string, from: CircuitState, to: CircuitState): void;
+    recordFailure(instanceId: string, _failureCount: number): void;
+    recordSuccess(instanceId: string): void;
+    recordRejection(instanceId: string): void;
+    recordBackoffTimeout(instanceId: string, timeoutMs: number): void;
+    getSummary(): CircuitBreakerMetricsSummary;
+    /**
+     * Get recent state transitions (useful for debugging)
+     */
+    getRecentTransitions(limit?: number): Array<{
+        instanceId: string;
+        from: CircuitState;
+        to: CircuitState;
+        timestamp: number;
+    }>;
+    /**
+     * Reset all collected metrics
+     */
+    reset(): void;
+}
+/**
+ * Durable Object stub interface (minimal for wrapping)
+ */
+export interface DOStub {
+    fetch(request: Request): Promise<Response>;
+}
+/**
+ * Configuration for the DO Circuit Breaker Wrapper
+ */
+export interface DOCircuitBreakerConfig extends CircuitBreakerConfig {
+    /** Function to get instance ID from a request */
+    getInstanceId?: (request: Request) => string;
+    /** Function to determine if a response should be treated as a failure */
+    isFailure?: (response: Response) => boolean;
+    /** Fallback response when circuit is open */
+    fallbackResponse?: () => Response;
+}
+/**
+ * Wrapper for Durable Object stubs with circuit breaker protection
+ *
+ * Wraps DO stub fetch calls with circuit breaker logic.
+ */
+export declare class DOCircuitBreakerWrapper {
+    private circuitBreaker;
+    private config;
+    constructor(config?: DOCircuitBreakerConfig);
+    /**
+     * Get instance ID from a request
+     */
+    private getInstanceId;
+    /**
+     * Check if a response indicates a failure
+     */
+    private isFailure;
+    /**
+     * Wrap a DO stub with circuit breaker protection
+     */
+    wrap(stub: DOStub, stubId?: string): DOStub;
+    /**
+     * Execute a fetch with circuit breaker protection (without wrapping)
+     */
+    fetch(stub: DOStub, request: Request, stubId?: string): Promise<Response>;
+    /**
+     * Get the underlying circuit breaker
+     */
+    getCircuitBreaker(): CircuitBreaker;
+    /**
+     * Get state for a specific instance
+     */
+    getState(instanceId: string): CircuitState;
+    /**
+     * Get stats for a specific instance
+     */
+    getStats(instanceId: string): CircuitBreakerStats;
+    /**
+     * Get stats for all tracked instances
+     */
+    getAllStats(): Map<string, CircuitBreakerStats>;
+    /**
+     * Reset circuit for an instance
+     */
+    reset(instanceId: string): void;
+    /**
+     * Force circuit open for an instance
+     */
+    forceOpen(instanceId: string): void;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

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

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