fastfetch-api-fetch-enhancer 2.0.0

package/src/circuit-breaker.ts

@@ -0,0 +1,154 @@
+/**
+ * FastFetch Circuit Breaker — Finite State Machine implementation.
+ *
+ * Prevents cascading failures by "opening" the circuit after a configurable
+ * number of consecutive failures, then probing with a single request after
+ * the reset timeout before fully re-closing.
+ *
+ * States:
+ *  CLOSED   — normal operation; every request goes through
+ *  OPEN     — requests are immediately rejected (CircuitOpenError)
+ *  HALF_OPEN — one probe request is allowed; success → CLOSED, failure → OPEN
+ */
+
+import { CircuitOpenError } from "./errors.js";
+
+export type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+
+export interface CircuitBreakerOptions {
+  /**
+   * Number of consecutive failures before the circuit opens (default: 5).
+   */
+  threshold?: number;
+  /**
+   * Milliseconds to wait in the OPEN state before transitioning to HALF_OPEN
+   * and allowing a single probe request (default: 30 000 ms = 30 s).
+   */
+  timeout?: number;
+  /** Called when the circuit transitions CLOSED → OPEN. */
+  onOpen?: () => void;
+  /** Called when the circuit transitions HALF_OPEN → CLOSED (recovered). */
+  onClose?: () => void;
+  /** Called when the circuit transitions OPEN → HALF_OPEN (probing). */
+  onHalfOpen?: () => void;
+}
+
+export class CircuitBreaker {
+  private _state: CircuitState = "CLOSED";
+  private consecutiveFailures = 0;
+  private openedAt = 0;
+  private probeInFlight = false;
+
+  private readonly threshold: number;
+  private readonly timeoutMs: number;
+  private readonly onOpen?: () => void;
+  private readonly onClose?: () => void;
+  private readonly onHalfOpen?: () => void;
+
+  constructor(options: CircuitBreakerOptions = {}) {
+    this.threshold = options.threshold ?? 5;
+    this.timeoutMs = options.timeout ?? 30_000;
+    this.onOpen = options.onOpen;
+    this.onClose = options.onClose;
+    this.onHalfOpen = options.onHalfOpen;
+  }
+
+  // ── State accessor ───────────────────────────────────────────────────────
+
+  /**
+   * Current circuit state. Reading this property can trigger an automatic
+   * OPEN → HALF_OPEN transition when the reset timeout has elapsed.
+   */
+  get state(): CircuitState {
+    if (
+      this._state === "OPEN" &&
+      Date.now() - this.openedAt >= this.timeoutMs
+    ) {
+      this._state = "HALF_OPEN";
+      this.probeInFlight = false;
+      this.onHalfOpen?.();
+    }
+    return this._state;
+  }
+
+  // ── Core execute ─────────────────────────────────────────────────────────
+
+  /**
+   * Execute `fn` through the circuit breaker.
+   * - CLOSED → run `fn`, track success/failure
+   * - OPEN → throw `CircuitOpenError` immediately (no network call)
+   * - HALF_OPEN → allow one probe; success closes, failure re-opens
+   */
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    const currentState = this.state; // may trigger OPEN→HALF_OPEN
+
+    if (currentState === "OPEN") {
+      throw new CircuitOpenError();
+    }
+
+    if (currentState === "HALF_OPEN") {
+      // Reject parallel probes — only one probe allowed at a time
+      if (this.probeInFlight) {
+        throw new CircuitOpenError();
+      }
+      this.probeInFlight = true;
+    }
+
+    try {
+      const result = await fn();
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      this.recordFailure();
+      throw err;
+    }
+  }
+
+  // ── Private FSM transitions ──────────────────────────────────────────────
+
+  private recordSuccess(): void {
+    this.consecutiveFailures = 0;
+    this.probeInFlight = false;
+
+    if (this._state === "HALF_OPEN") {
+      this._state = "CLOSED";
+      this.onClose?.();
+    }
+  }
+
+  private recordFailure(): void {
+    this.consecutiveFailures++;
+    this.probeInFlight = false;
+
+    if (this._state === "HALF_OPEN") {
+      // Probe failed — re-open the circuit
+      this._state = "OPEN";
+      this.openedAt = Date.now();
+      return;
+    }
+
+    if (
+      this._state === "CLOSED" &&
+      this.consecutiveFailures >= this.threshold
+    ) {
+      this._state = "OPEN";
+      this.openedAt = Date.now();
+      this.onOpen?.();
+    }
+  }
+
+  // ── Manual controls ──────────────────────────────────────────────────────
+
+  /** Manually reset the circuit to CLOSED. Useful for testing. */
+  reset(): void {
+    this._state = "CLOSED";
+    this.consecutiveFailures = 0;
+    this.openedAt = 0;
+    this.probeInFlight = false;
+  }
+
+  /** Number of consecutive failures recorded since last success. */
+  get failures(): number {
+    return this.consecutiveFailures;
+  }
+}