@teneo-protocol/sdk 1.0.0

package/src/utils/circuit-breaker.test.ts

@@ -0,0 +1,394 @@
+/**
+ * Tests for Circuit Breaker
+ */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { CircuitBreaker, CircuitBreakerError, type CircuitState } from "./circuit-breaker";
+
+describe("CircuitBreaker", () => {
+  describe("constructor", () => {
+    it("should create circuit breaker with default options", () => {
+      const breaker = new CircuitBreaker();
+      const config = breaker.getConfig();
+
+      expect(config.failureThreshold).toBe(5);
+      expect(config.successThreshold).toBe(2);
+      expect(config.timeout).toBe(60000);
+      expect(config.windowSize).toBe(60000);
+    });
+
+    it("should create circuit breaker with custom options", () => {
+      const breaker = new CircuitBreaker({
+        failureThreshold: 3,
+        successThreshold: 1,
+        timeout: 30000,
+        windowSize: 30000
+      });
+      const config = breaker.getConfig();
+
+      expect(config.failureThreshold).toBe(3);
+      expect(config.successThreshold).toBe(1);
+      expect(config.timeout).toBe(30000);
+      expect(config.windowSize).toBe(30000);
+    });
+
+    it("should throw error if failureThreshold is less than 1", () => {
+      expect(() => new CircuitBreaker({ failureThreshold: 0 })).toThrow(
+        "failureThreshold must be at least 1"
+      );
+    });
+
+    it("should throw error if successThreshold is less than 1", () => {
+      expect(() => new CircuitBreaker({ successThreshold: 0 })).toThrow(
+        "successThreshold must be at least 1"
+      );
+    });
+  });
+
+  describe("CLOSED state", () => {
+    let breaker: CircuitBreaker;
+
+    beforeEach(() => {
+      breaker = new CircuitBreaker({ failureThreshold: 3 });
+    });
+
+    it("should start in CLOSED state", () => {
+      const state = breaker.getState();
+      expect(state.state).toBe("CLOSED");
+      expect(state.failureCount).toBe(0);
+    });
+
+    it("should execute operations successfully in CLOSED state", async () => {
+      const operation = vi.fn(async () => "success");
+
+      const result = await breaker.execute(operation);
+
+      expect(result).toBe("success");
+      expect(operation).toHaveBeenCalledTimes(1);
+    });
+
+    it("should track failures in CLOSED state", async () => {
+      const operation = vi.fn(async () => {
+        throw new Error("operation failed");
+      });
+
+      await expect(breaker.execute(operation)).rejects.toThrow("operation failed");
+
+      const state = breaker.getState();
+      expect(state.failureCount).toBe(1);
+      expect(state.state).toBe("CLOSED");
+    });
+
+    it("should open circuit after reaching failure threshold", async () => {
+      const operation = vi.fn(async () => {
+        throw new Error("operation failed");
+      });
+
+      // Fail 3 times (threshold = 3)
+      for (let i = 0; i < 3; i++) {
+        await expect(breaker.execute(operation)).rejects.toThrow("operation failed");
+      }
+
+      const state = breaker.getState();
+      expect(state.state).toBe("OPEN");
+      expect(state.failureCount).toBe(3);
+    });
+
+    it("should only count failures within the time window", async () => {
+      const breaker = new CircuitBreaker({
+        failureThreshold: 3,
+        windowSize: 100 // 100ms window
+      });
+
+      const operation = vi.fn(async () => {
+        throw new Error("failed");
+      });
+
+      // First failure
+      await expect(breaker.execute(operation)).rejects.toThrow("failed");
+      expect(breaker.getState().failureCount).toBe(1);
+
+      // Wait for window to expire
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // Second failure (first should be outside window now)
+      await expect(breaker.execute(operation)).rejects.toThrow("failed");
+      expect(breaker.getState().failureCount).toBe(1);
+      expect(breaker.getState().state).toBe("CLOSED");
+    });
+  });
+
+  describe("OPEN state", () => {
+    let breaker: CircuitBreaker;
+
+    beforeEach(async () => {
+      breaker = new CircuitBreaker({
+        failureThreshold: 2,
+        timeout: 1000
+      });
+
+      // Trigger circuit to open
+      const failOp = vi.fn(async () => {
+        throw new Error("fail");
+      });
+      for (let i = 0; i < 2; i++) {
+        await expect(breaker.execute(failOp)).rejects.toThrow("fail");
+      }
+    });
+
+    it("should be in OPEN state after threshold failures", () => {
+      const state = breaker.getState();
+      expect(state.state).toBe("OPEN");
+    });
+
+    it("should fail fast with CircuitBreakerError in OPEN state", async () => {
+      const operation = vi.fn(async () => "success");
+
+      await expect(breaker.execute(operation)).rejects.toThrow(CircuitBreakerError);
+      await expect(breaker.execute(operation)).rejects.toThrow("Circuit breaker is OPEN");
+
+      // Operation should not be called
+      expect(operation).not.toHaveBeenCalled();
+    });
+
+    it("should transition to HALF_OPEN after timeout", async () => {
+      expect(breaker.getState().state).toBe("OPEN");
+
+      // Wait for timeout
+      await new Promise((resolve) => setTimeout(resolve, 1100));
+
+      // Try operation - should be in HALF_OPEN now
+      const operation = vi.fn(async () => "success");
+      await breaker.execute(operation);
+
+      expect(operation).toHaveBeenCalled();
+    });
+
+    it("should set nextAttemptTime when opening", () => {
+      const state = breaker.getState();
+      expect(state.nextAttemptTime).toBeDefined();
+      expect(state.nextAttemptTime! > Date.now()).toBe(true);
+    });
+  });
+
+  describe("HALF_OPEN state", () => {
+    let breaker: CircuitBreaker;
+
+    beforeEach(async () => {
+      breaker = new CircuitBreaker({
+        failureThreshold: 2,
+        successThreshold: 2,
+        timeout: 100 // Short timeout for testing
+      });
+
+      // Open the circuit
+      const failOp = vi.fn(async () => {
+        throw new Error("fail");
+      });
+      for (let i = 0; i < 2; i++) {
+        await expect(breaker.execute(failOp)).rejects.toThrow("fail");
+      }
+
+      // Wait for timeout to move to HALF_OPEN
+      await new Promise((resolve) => setTimeout(resolve, 150));
+    });
+
+    it("should allow operations in HALF_OPEN state", async () => {
+      const operation = vi.fn(async () => "success");
+
+      const result = await breaker.execute(operation);
+
+      expect(result).toBe("success");
+      expect(operation).toHaveBeenCalled();
+    });
+
+    it("should close circuit after enough successes", async () => {
+      const operation = vi.fn(async () => "success");
+
+      // Need 2 successes (successThreshold = 2)
+      await breaker.execute(operation);
+      expect(breaker.getState().state).toBe("HALF_OPEN");
+
+      await breaker.execute(operation);
+      expect(breaker.getState().state).toBe("CLOSED");
+      expect(breaker.getState().failureCount).toBe(0);
+    });
+
+    it("should reopen circuit on failure in HALF_OPEN", async () => {
+      const operation = vi.fn(async () => {
+        throw new Error("failed again");
+      });
+
+      await expect(breaker.execute(operation)).rejects.toThrow("failed again");
+
+      const state = breaker.getState();
+      expect(state.state).toBe("OPEN");
+      expect(state.nextAttemptTime).toBeDefined();
+    });
+
+    it("should reset success count when reopening", async () => {
+      const successOp = vi.fn(async () => "success");
+      const failOp = vi.fn(async () => {
+        throw new Error("fail");
+      });
+
+      // One success
+      await breaker.execute(successOp);
+      expect(breaker.getState().successCount).toBe(1);
+
+      // Then fail - should reopen and reset success count
+      await expect(breaker.execute(failOp)).rejects.toThrow("fail");
+      expect(breaker.getState().state).toBe("OPEN");
+      expect(breaker.getState().successCount).toBe(0);
+    });
+  });
+
+  describe("reset", () => {
+    it("should reset circuit to CLOSED state", async () => {
+      const breaker = new CircuitBreaker({ failureThreshold: 1 });
+
+      // Open circuit
+      const failOp = vi.fn(async () => {
+        throw new Error("fail");
+      });
+      await expect(breaker.execute(failOp)).rejects.toThrow("fail");
+
+      expect(breaker.getState().state).toBe("OPEN");
+
+      // Reset
+      breaker.reset();
+
+      const state = breaker.getState();
+      expect(state.state).toBe("CLOSED");
+      expect(state.failureCount).toBe(0);
+      expect(state.successCount).toBe(0);
+      expect(state.lastFailureTime).toBeUndefined();
+      expect(state.nextAttemptTime).toBeUndefined();
+    });
+
+    it("should allow operations after reset", async () => {
+      const breaker = new CircuitBreaker({ failureThreshold: 1 });
+
+      // Open circuit
+      await expect(
+        breaker.execute(async () => {
+          throw new Error("fail");
+        })
+      ).rejects.toThrow("fail");
+
+      breaker.reset();
+
+      // Should work now
+      const result = await breaker.execute(async () => "success");
+      expect(result).toBe("success");
+    });
+  });
+
+  describe("getState", () => {
+    it("should return current state and metrics", async () => {
+      const breaker = new CircuitBreaker();
+
+      const state1 = breaker.getState();
+      expect(state1).toMatchObject({
+        state: "CLOSED",
+        failureCount: 0,
+        successCount: 0
+      });
+
+      // Cause a failure
+      await expect(
+        breaker.execute(async () => {
+          throw new Error("fail");
+        })
+      ).rejects.toThrow("fail");
+
+      const state2 = breaker.getState();
+      expect(state2.failureCount).toBe(1);
+      expect(state2.lastFailureTime).toBeDefined();
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle rapid failures", async () => {
+      const breaker = new CircuitBreaker({ failureThreshold: 10 });
+
+      const operation = vi.fn(async () => {
+        throw new Error("fail");
+      });
+
+      // Rapid failures
+      const promises = Array(10)
+        .fill(0)
+        .map(() => breaker.execute(operation).catch(() => {}));
+
+      await Promise.all(promises);
+
+      expect(breaker.getState().state).toBe("OPEN");
+    });
+
+    it("should handle mixed success/failure in CLOSED", async () => {
+      const breaker = new CircuitBreaker({ failureThreshold: 3 });
+
+      let shouldFail = true;
+      const operation = vi.fn(async () => {
+        if (shouldFail) {
+          throw new Error("fail");
+        }
+        return "success";
+      });
+
+      // Fail
+      await expect(breaker.execute(operation)).rejects.toThrow("fail");
+      expect(breaker.getState().failureCount).toBe(1);
+
+      // Succeed
+      shouldFail = false;
+      await breaker.execute(operation);
+      expect(breaker.getState().failureCount).toBe(0);
+
+      // Should still be CLOSED
+      expect(breaker.getState().state).toBe("CLOSED");
+    });
+
+    it("should handle synchronous errors", async () => {
+      const breaker = new CircuitBreaker({ failureThreshold: 1 });
+
+      await expect(
+        breaker.execute(async () => {
+          throw new Error("sync error");
+        })
+      ).rejects.toThrow("sync error");
+
+      expect(breaker.getState().state).toBe("OPEN");
+    });
+
+    it("should handle operations that return undefined", async () => {
+      const breaker = new CircuitBreaker();
+
+      const result = await breaker.execute(async () => undefined);
+
+      expect(result).toBeUndefined();
+      expect(breaker.getState().state).toBe("CLOSED");
+    });
+  });
+
+  describe("CircuitBreakerError", () => {
+    it("should be instanceof Error", () => {
+      const error = new CircuitBreakerError("Test", "OPEN");
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(CircuitBreakerError);
+    });
+
+    it("should have correct name and state", () => {
+      const error = new CircuitBreakerError("Test", "OPEN");
+      expect(error.name).toBe("CircuitBreakerError");
+      expect(error.state).toBe("OPEN");
+    });
+
+    it("should preserve error message", () => {
+      const message = "Custom message";
+      const error = new CircuitBreakerError(message, "OPEN");
+      expect(error.message).toBe(message);
+    });
+  });
+});

package/src/utils/circuit-breaker.ts

@@ -0,0 +1,262 @@
+/**
+ * Circuit Breaker Pattern Implementation
+ * Provides fault tolerance by preventing cascading failures
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Failure threshold exceeded, requests fail fast
+ * - HALF_OPEN: Testing if service recovered, limited requests allowed
+ */
+
+/**
+ * Circuit breaker states
+ */
+export type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+
+/**
+ * Circuit breaker configuration options
+ */
+export interface CircuitBreakerOptions {
+  /** Number of failures before opening circuit (default: 5) */
+  failureThreshold?: number;
+  /** Success count needed to close from half-open (default: 2) */
+  successThreshold?: number;
+  /** Time in ms to wait before trying half-open (default: 60000) */
+  timeout?: number;
+  /** Window size in ms for tracking failures (default: 60000) */
+  windowSize?: number;
+}
+
+/**
+ * Error thrown when circuit is open
+ */
+export class CircuitBreakerError extends Error {
+  constructor(message: string, public readonly state: CircuitState) {
+    super(message);
+    this.name = "CircuitBreakerError";
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, CircuitBreakerError);
+    }
+  }
+}
+
+/**
+ * Circuit breaker for fault tolerance
+ * Prevents cascading failures by failing fast when errors are detected
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   timeout: 60000
+ * });
+ *
+ * try {
+ *   await breaker.execute(async () => {
+ *     return await fetch('https://api.example.com/data');
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerError) {
+ *     console.log('Circuit is open, failing fast');
+ *   }
+ * }
+ * ```
+ */
+export class CircuitBreaker {
+  private state: CircuitState = "CLOSED";
+  private failureCount = 0;
+  private successCount = 0;
+  private lastFailureTime?: number;
+  private nextAttemptTime?: number;
+  private readonly failures: number[] = []; // Timestamps of failures
+
+  private readonly failureThreshold: number;
+  private readonly successThreshold: number;
+  private readonly timeout: number;
+  private readonly windowSize: number;
+
+  /**
+   * Creates a new circuit breaker
+   *
+   * @param options - Configuration options
+   * @throws {Error} If thresholds are less than 1
+   *
+   * @example
+   * ```typescript
+   * const breaker = new CircuitBreaker({
+   *   failureThreshold: 5,  // Open after 5 failures
+   *   successThreshold: 2,  // Close after 2 successes
+   *   timeout: 60000,       // Wait 60s before trying again
+   *   windowSize: 60000     // Track failures in 60s window
+   * });
+   * ```
+   */
+  constructor(options: CircuitBreakerOptions = {}) {
+    this.failureThreshold = options.failureThreshold ?? 5;
+    this.successThreshold = options.successThreshold ?? 2;
+    this.timeout = options.timeout ?? 60000;
+    this.windowSize = options.windowSize ?? 60000;
+
+    if (this.failureThreshold < 1) {
+      throw new Error("CircuitBreaker failureThreshold must be at least 1");
+    }
+    if (this.successThreshold < 1) {
+      throw new Error("CircuitBreaker successThreshold must be at least 1");
+    }
+  }
+
+  /**
+   * Execute an operation through the circuit breaker
+   *
+   * @template T - Return type of the operation
+   * @param operation - Async operation to execute
+   * @returns Promise resolving to operation result
+   * @throws {CircuitBreakerError} If circuit is open
+   * @throws Operation error if operation fails
+   *
+   * @example
+   * ```typescript
+   * const result = await breaker.execute(async () => {
+   *   const response = await fetch(url);
+   *   return await response.json();
+   * });
+   * ```
+   */
+  public async execute<T>(operation: () => Promise<T>): Promise<T> {
+    // Check if we should try to close the circuit
+    this.tryTransitionToHalfOpen();
+
+    // If circuit is open, fail fast
+    if (this.state === "OPEN") {
+      throw new CircuitBreakerError("Circuit breaker is OPEN", this.state);
+    }
+
+    try {
+      const result = await operation();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+
+  /**
+   * Get current circuit breaker state and metrics
+   *
+   * @returns State object with status and counters
+   */
+  public getState(): {
+    state: CircuitState;
+    failureCount: number;
+    successCount: number;
+    lastFailureTime?: number;
+    nextAttemptTime?: number;
+  } {
+    return {
+      state: this.state,
+      failureCount: this.failureCount,
+      successCount: this.successCount,
+      lastFailureTime: this.lastFailureTime,
+      nextAttemptTime: this.nextAttemptTime
+    };
+  }
+
+  /**
+   * Get circuit breaker configuration
+   */
+  public getConfig(): {
+    failureThreshold: number;
+    successThreshold: number;
+    timeout: number;
+    windowSize: number;
+  } {
+    return {
+      failureThreshold: this.failureThreshold,
+      successThreshold: this.successThreshold,
+      timeout: this.timeout,
+      windowSize: this.windowSize
+    };
+  }
+
+  /**
+   * Manually reset the circuit breaker to CLOSED state
+   * Useful for recovery scenarios or testing
+   */
+  public reset(): void {
+    this.state = "CLOSED";
+    this.failureCount = 0;
+    this.successCount = 0;
+    this.lastFailureTime = undefined;
+    this.nextAttemptTime = undefined;
+    this.failures.length = 0;
+  }
+
+  /**
+   * Try to transition from OPEN to HALF_OPEN if timeout has passed
+   */
+  private tryTransitionToHalfOpen(): void {
+    if (this.state === "OPEN" && this.nextAttemptTime) {
+      if (Date.now() >= this.nextAttemptTime) {
+        this.state = "HALF_OPEN";
+        this.successCount = 0;
+      }
+    }
+  }
+
+  /**
+   * Handle successful operation
+   */
+  private onSuccess(): void {
+    if (this.state === "HALF_OPEN") {
+      this.successCount++;
+      if (this.successCount >= this.successThreshold) {
+        // Close the circuit - service has recovered
+        this.state = "CLOSED";
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.failures.length = 0;
+        this.lastFailureTime = undefined;
+        this.nextAttemptTime = undefined;
+      }
+    } else if (this.state === "CLOSED") {
+      // Reset failure count on success in CLOSED state
+      this.failureCount = Math.max(0, this.failureCount - 1);
+    }
+  }
+
+  /**
+   * Handle failed operation
+   */
+  private onFailure(): void {
+    const now = Date.now();
+    this.lastFailureTime = now;
+
+    if (this.state === "HALF_OPEN") {
+      // Failed while testing - reopen circuit
+      this.state = "OPEN";
+      this.nextAttemptTime = now + this.timeout;
+      this.successCount = 0;
+      return;
+    }
+
+    // Track failure with timestamp
+    this.failures.push(now);
+
+    // Remove failures outside the window
+    const windowStart = now - this.windowSize;
+    while (this.failures.length > 0 && this.failures[0]! < windowStart) {
+      this.failures.shift();
+    }
+
+    // Count failures in current window
+    this.failureCount = this.failures.length;
+
+    // Open circuit if threshold exceeded
+    if (this.failureCount >= this.failureThreshold) {
+      this.state = "OPEN";
+      this.nextAttemptTime = now + this.timeout;
+    }
+  }
+}