@sparkleideas/shared 3.0.0-alpha.7

package/src/resilience/bulkhead.ts

@@ -0,0 +1,277 @@
+/**
+ * Bulkhead Pattern
+ *
+ * Isolates failures by limiting concurrent executions.
+ *
+ * @module v3/shared/resilience/bulkhead
+ */
+
+import { EventEmitter } from 'events';
+
+/**
+ * Bulkhead options
+ */
+export interface BulkheadOptions {
+  /** Name for identification */
+  name: string;
+
+  /** Maximum concurrent executions */
+  maxConcurrent: number;
+
+  /** Maximum queue size */
+  maxQueue: number;
+
+  /** Timeout for queued items in ms */
+  queueTimeout: number;
+
+  /** Callback when rejected */
+  onRejected?: (reason: 'full' | 'timeout') => void;
+}
+
+/**
+ * Bulkhead statistics
+ */
+export interface BulkheadStats {
+  active: number;
+  queued: number;
+  maxConcurrent: number;
+  maxQueue: number;
+  completed: number;
+  rejected: number;
+  timedOut: number;
+}
+
+/**
+ * Queued item
+ */
+interface QueuedItem<T> {
+  fn: () => Promise<T>;
+  resolve: (value: T) => void;
+  reject: (error: Error) => void;
+  queuedAt: number;
+  timeoutId?: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Default options
+ */
+const DEFAULT_OPTIONS: Omit<BulkheadOptions, 'name'> = {
+  maxConcurrent: 10,
+  maxQueue: 100,
+  queueTimeout: 30000,
+};
+
+/**
+ * Bulkhead
+ *
+ * Limits concurrent executions to prevent resource exhaustion.
+ *
+ * @example
+ * const bulkhead = new Bulkhead({
+ *   name: 'database',
+ *   maxConcurrent: 10,
+ *   maxQueue: 50,
+ * });
+ *
+ * try {
+ *   const result = await bulkhead.execute(() => dbQuery());
+ * } catch (error) {
+ *   if (error.message.includes('Bulkhead full')) {
+ *     // Handle capacity exceeded
+ *   }
+ * }
+ */
+export class Bulkhead extends EventEmitter {
+  private readonly options: BulkheadOptions;
+  private active = 0;
+  private readonly queue: Array<QueuedItem<unknown>> = [];
+  private completed = 0;
+  private rejected = 0;
+  private timedOut = 0;
+
+  constructor(options: BulkheadOptions) {
+    super();
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+  }
+
+  /**
+   * Execute a function within the bulkhead
+   */
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    // If there's room for execution, run immediately
+    if (this.active < this.options.maxConcurrent) {
+      return this.runNow(fn);
+    }
+
+    // Check if queue is full
+    if (this.queue.length >= this.options.maxQueue) {
+      this.rejected++;
+      this.options.onRejected?.('full');
+      throw new Error(`Bulkhead '${this.options.name}' is full. Max concurrent: ${this.options.maxConcurrent}, queue: ${this.options.maxQueue}`);
+    }
+
+    // Add to queue
+    return this.addToQueue(fn);
+  }
+
+  /**
+   * Get current statistics
+   */
+  getStats(): BulkheadStats {
+    return {
+      active: this.active,
+      queued: this.queue.length,
+      maxConcurrent: this.options.maxConcurrent,
+      maxQueue: this.options.maxQueue,
+      completed: this.completed,
+      rejected: this.rejected,
+      timedOut: this.timedOut,
+    };
+  }
+
+  /**
+   * Check if there's capacity available
+   */
+  hasCapacity(): boolean {
+    return this.active < this.options.maxConcurrent || this.queue.length < this.options.maxQueue;
+  }
+
+  /**
+   * Get available capacity (concurrent + queue)
+   */
+  availableCapacity(): number {
+    const concurrentAvailable = this.options.maxConcurrent - this.active;
+    const queueAvailable = this.options.maxQueue - this.queue.length;
+    return concurrentAvailable + queueAvailable;
+  }
+
+  /**
+   * Reset statistics
+   */
+  resetStats(): void {
+    this.completed = 0;
+    this.rejected = 0;
+    this.timedOut = 0;
+  }
+
+  /**
+   * Run function immediately
+   */
+  private async runNow<T>(fn: () => Promise<T>): Promise<T> {
+    this.active++;
+    this.emit('acquire');
+
+    try {
+      const result = await fn();
+      this.completed++;
+      return result;
+    } finally {
+      this.active--;
+      this.emit('release');
+      this.processQueue();
+    }
+  }
+
+  /**
+   * Add function to queue
+   */
+  private addToQueue<T>(fn: () => Promise<T>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      const item: QueuedItem<T> = {
+        fn,
+        resolve,
+        reject,
+        queuedAt: Date.now(),
+      };
+
+      // Set timeout for queued item
+      item.timeoutId = setTimeout(() => {
+        const index = this.queue.indexOf(item as QueuedItem<unknown>);
+        if (index !== -1) {
+          this.queue.splice(index, 1);
+          this.timedOut++;
+          this.options.onRejected?.('timeout');
+          reject(new Error(`Bulkhead '${this.options.name}' queue timeout after ${this.options.queueTimeout}ms`));
+        }
+      }, this.options.queueTimeout);
+
+      this.queue.push(item as QueuedItem<unknown>);
+      this.emit('queued', { queueLength: this.queue.length });
+    });
+  }
+
+  /**
+   * Process next item in queue
+   */
+  private processQueue(): void {
+    if (this.active >= this.options.maxConcurrent) {
+      return;
+    }
+
+    const item = this.queue.shift();
+    if (!item) {
+      return;
+    }
+
+    // Clear timeout
+    if (item.timeoutId) {
+      clearTimeout(item.timeoutId);
+    }
+
+    // Execute the queued function
+    this.active++;
+    this.emit('acquire');
+
+    item.fn()
+      .then((result) => {
+        this.completed++;
+        item.resolve(result);
+      })
+      .catch((error) => {
+        item.reject(error);
+      })
+      .finally(() => {
+        this.active--;
+        this.emit('release');
+        this.processQueue();
+      });
+  }
+}
+
+/**
+ * Create a semaphore for limiting concurrent access
+ */
+export function createSemaphore(maxConcurrent: number): {
+  acquire: () => Promise<void>;
+  release: () => void;
+  available: () => number;
+} {
+  let current = 0;
+  const waiting: Array<() => void> = [];
+
+  return {
+    async acquire(): Promise<void> {
+      if (current < maxConcurrent) {
+        current++;
+        return;
+      }
+
+      return new Promise<void>((resolve) => {
+        waiting.push(resolve);
+      });
+    },
+
+    release(): void {
+      const next = waiting.shift();
+      if (next) {
+        next();
+      } else {
+        current = Math.max(0, current - 1);
+      }
+    },
+
+    available(): number {
+      return maxConcurrent - current;
+    },
+  };
+}

package/src/resilience/circuit-breaker.ts

@@ -0,0 +1,326 @@
+/**
+ * Circuit Breaker Pattern
+ *
+ * Prevents cascading failures by breaking the circuit after failures.
+ *
+ * @module v3/shared/resilience/circuit-breaker
+ */
+
+import { EventEmitter } from 'events';
+
+/**
+ * Circuit breaker states
+ */
+export enum CircuitBreakerState {
+  /** Circuit is closed, requests flow normally */
+  CLOSED = 'CLOSED',
+
+  /** Circuit is open, requests are rejected immediately */
+  OPEN = 'OPEN',
+
+  /** Circuit is testing if service recovered */
+  HALF_OPEN = 'HALF_OPEN',
+}
+
+/**
+ * Circuit breaker options
+ */
+export interface CircuitBreakerOptions {
+  /** Name for identification */
+  name: string;
+
+  /** Failure threshold before opening circuit (default: 5) */
+  failureThreshold: number;
+
+  /** Success threshold in half-open state to close circuit (default: 3) */
+  successThreshold: number;
+
+  /** Time to wait before testing again in ms (default: 30000) */
+  timeout: number;
+
+  /** Time window to track failures in ms (default: 60000) */
+  rollingWindow: number;
+
+  /** Volume threshold - minimum requests before tripping (default: 10) */
+  volumeThreshold: number;
+
+  /** Custom failure detection */
+  isFailure?: (error: Error) => boolean;
+
+  /** Fallback function when circuit is open */
+  fallback?: <T>(error: Error) => T | Promise<T>;
+
+  /** Callback when state changes */
+  onStateChange?: (from: CircuitBreakerState, to: CircuitBreakerState) => void;
+}
+
+/**
+ * Circuit breaker statistics
+ */
+export interface CircuitBreakerStats {
+  state: CircuitBreakerState;
+  failures: number;
+  successes: number;
+  totalRequests: number;
+  rejectedRequests: number;
+  lastFailure: Date | null;
+  lastSuccess: Date | null;
+  openSince: Date | null;
+}
+
+/**
+ * Default options
+ */
+const DEFAULT_OPTIONS: Omit<CircuitBreakerOptions, 'name'> = {
+  failureThreshold: 5,
+  successThreshold: 3,
+  timeout: 30000,
+  rollingWindow: 60000,
+  volumeThreshold: 10,
+};
+
+/**
+ * Request tracking entry
+ */
+interface RequestEntry {
+  timestamp: number;
+  success: boolean;
+}
+
+/**
+ * Circuit Breaker
+ *
+ * Implements the circuit breaker pattern to prevent cascading failures.
+ *
+ * @example
+ * const breaker = new CircuitBreaker({
+ *   name: 'external-api',
+ *   failureThreshold: 5,
+ *   timeout: 30000,
+ * });
+ *
+ * try {
+ *   const result = await breaker.execute(() => fetchExternalAPI());
+ * } catch (error) {
+ *   if (error.message === 'Circuit is open') {
+ *     // Handle circuit open case
+ *   }
+ * }
+ */
+export class CircuitBreaker extends EventEmitter {
+  private readonly options: CircuitBreakerOptions;
+  private state: CircuitBreakerState = CircuitBreakerState.CLOSED;
+  private requests: RequestEntry[] = [];
+  private halfOpenSuccesses = 0;
+  private openedAt: Date | null = null;
+  private lastFailure: Date | null = null;
+  private lastSuccess: Date | null = null;
+  private rejectedCount = 0;
+  private timeoutId?: ReturnType<typeof setTimeout>;
+
+  constructor(options: CircuitBreakerOptions) {
+    super();
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+  }
+
+  /**
+   * Execute a function through the circuit breaker
+   */
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    // Clean up old requests
+    this.cleanOldRequests();
+
+    // Check if circuit should be tested
+    this.checkState();
+
+    // If open, reject immediately or use fallback
+    if (this.state === CircuitBreakerState.OPEN) {
+      this.rejectedCount++;
+      const error = new Error(`Circuit breaker '${this.options.name}' is open`);
+
+      if (this.options.fallback) {
+        return this.options.fallback(error);
+      }
+
+      throw error;
+    }
+
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+
+      // Check if this should be counted as failure
+      const isFailure = this.options.isFailure?.(err) ?? true;
+
+      if (isFailure) {
+        this.onFailure(err);
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Get current state
+   */
+  getState(): CircuitBreakerState {
+    this.checkState();
+    return this.state;
+  }
+
+  /**
+   * Get statistics
+   */
+  getStats(): CircuitBreakerStats {
+    this.cleanOldRequests();
+
+    return {
+      state: this.state,
+      failures: this.requests.filter((r) => !r.success).length,
+      successes: this.requests.filter((r) => r.success).length,
+      totalRequests: this.requests.length,
+      rejectedRequests: this.rejectedCount,
+      lastFailure: this.lastFailure,
+      lastSuccess: this.lastSuccess,
+      openSince: this.openedAt,
+    };
+  }
+
+  /**
+   * Force reset the circuit breaker
+   */
+  reset(): void {
+    const previousState = this.state;
+    this.state = CircuitBreakerState.CLOSED;
+    this.requests = [];
+    this.halfOpenSuccesses = 0;
+    this.openedAt = null;
+
+    if (this.timeoutId) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = undefined;
+    }
+
+    if (previousState !== this.state) {
+      this.notifyStateChange(previousState, this.state);
+    }
+  }
+
+  /**
+   * Handle successful request
+   */
+  private onSuccess(): void {
+    this.lastSuccess = new Date();
+    this.requests.push({ timestamp: Date.now(), success: true });
+
+    if (this.state === CircuitBreakerState.HALF_OPEN) {
+      this.halfOpenSuccesses++;
+
+      if (this.halfOpenSuccesses >= this.options.successThreshold) {
+        this.transitionTo(CircuitBreakerState.CLOSED);
+        this.halfOpenSuccesses = 0;
+      }
+    }
+  }
+
+  /**
+   * Handle failed request
+   */
+  private onFailure(error: Error): void {
+    this.lastFailure = new Date();
+    this.requests.push({ timestamp: Date.now(), success: false });
+
+    if (this.state === CircuitBreakerState.HALF_OPEN) {
+      // Failed during half-open, go back to open
+      this.transitionTo(CircuitBreakerState.OPEN);
+      this.halfOpenSuccesses = 0;
+      return;
+    }
+
+    // Check if we should open the circuit
+    const failures = this.requests.filter((r) => !r.success).length;
+    const totalRequests = this.requests.length;
+
+    if (
+      totalRequests >= this.options.volumeThreshold &&
+      failures >= this.options.failureThreshold
+    ) {
+      this.transitionTo(CircuitBreakerState.OPEN);
+    }
+  }
+
+  /**
+   * Check if state should change based on timeout
+   */
+  private checkState(): void {
+    if (this.state === CircuitBreakerState.OPEN && this.openedAt) {
+      const elapsed = Date.now() - this.openedAt.getTime();
+
+      if (elapsed >= this.options.timeout) {
+        this.transitionTo(CircuitBreakerState.HALF_OPEN);
+      }
+    }
+  }
+
+  /**
+   * Transition to new state
+   */
+  private transitionTo(newState: CircuitBreakerState): void {
+    const previousState = this.state;
+
+    if (previousState === newState) {
+      return;
+    }
+
+    this.state = newState;
+
+    if (newState === CircuitBreakerState.OPEN) {
+      this.openedAt = new Date();
+      this.scheduleHalfOpen();
+    } else if (newState === CircuitBreakerState.CLOSED) {
+      this.openedAt = null;
+      this.requests = [];
+
+      if (this.timeoutId) {
+        clearTimeout(this.timeoutId);
+        this.timeoutId = undefined;
+      }
+    }
+
+    this.notifyStateChange(previousState, newState);
+  }
+
+  /**
+   * Schedule transition to half-open
+   */
+  private scheduleHalfOpen(): void {
+    if (this.timeoutId) {
+      clearTimeout(this.timeoutId);
+    }
+
+    this.timeoutId = setTimeout(() => {
+      if (this.state === CircuitBreakerState.OPEN) {
+        this.transitionTo(CircuitBreakerState.HALF_OPEN);
+      }
+    }, this.options.timeout);
+  }
+
+  /**
+   * Notify state change
+   */
+  private notifyStateChange(from: CircuitBreakerState, to: CircuitBreakerState): void {
+    this.emit('stateChange', { from, to });
+    this.options.onStateChange?.(from, to);
+  }
+
+  /**
+   * Clean old requests outside rolling window
+   */
+  private cleanOldRequests(): void {
+    const cutoff = Date.now() - this.options.rollingWindow;
+    this.requests = this.requests.filter((r) => r.timestamp >= cutoff);
+  }
+}

package/src/resilience/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Resilience Patterns
+ *
+ * Production-ready resilience utilities:
+ * - Retry with exponential backoff
+ * - Circuit breaker pattern
+ * - Rate limiting
+ *
+ * @module v3/shared/resilience
+ */
+
+// Retry
+export { retry, RetryError } from './retry.js';
+export type { RetryOptions, RetryResult } from './retry.js';
+
+// Circuit Breaker
+export { CircuitBreaker } from './circuit-breaker.js';
+export type { CircuitBreakerOptions, CircuitBreakerStats } from './circuit-breaker.js';
+
+// Rate Limiter
+export { SlidingWindowRateLimiter, TokenBucketRateLimiter } from './rate-limiter.js';
+export type { RateLimiter, RateLimiterOptions, RateLimitResult } from './rate-limiter.js';
+
+// Bulkhead
+export { Bulkhead } from './bulkhead.js';
+export type { BulkheadOptions, BulkheadStats } from './bulkhead.js';