feat(api): add per-endpoint circuit breaker for downstream calls on /api/fingerprint (#673)

Author: Alimzy

src/lib/circuitBreaker.ts

@@ -5,32 +5,35 @@ export enum CircuitState {
 }
 
 export interface CircuitBreakerOptions {
-  failureThreshold?: number;
-  resetTimeoutMs?: number;
+  failureThreshold?: number; // Number of failures before opening
+  cooldownPeriodMs?: number; // Time in ms before attempting half-open
 }
 
 export class CircuitBreakerOpenError extends Error {
-  constructor(message = 'Service temporarily unavailable due to open circuit breaker') {
+  public statusCode: number = 503;
+  constructor(message: string = 'Service unavailable: Circuit breaker is OPEN') {
     super(message);
     this.name = 'CircuitBreakerOpenError';
   }
 }
 
 export class CircuitBreaker {
   private state: CircuitState = CircuitState.CLOSED;
-  private failureCount = 0;
-  private readonly failureThreshold: number;
-  private readonly resetTimeoutMs: number;
+  private failureCount: number = 0;
   private lastStateChange: number = Date.now();
+  private readonly failureThreshold: number;
+  private readonly cooldownPeriodMs: number;
 
   constructor(options: CircuitBreakerOptions = {}) {
     this.failureThreshold = options.failureThreshold ?? 5;
-    this.resetTimeoutMs = options.resetTimeoutMs ?? 10000;
+    this.cooldownPeriodMs = options.cooldownPeriodMs ?? 30000; // Default 30 seconds
   }
 
   public getState(): CircuitState {
-    if (this.state === CircuitState.OPEN && Date.now() - this.lastStateChange >= this.resetTimeoutMs) {
-      this.state = CircuitState.HALF_OPEN;
+    if (this.state === CircuitState.OPEN) {
+      if (Date.now() - this.lastStateChange >= this.cooldownPeriodMs) {
+        this.state = CircuitState.HALF_OPEN;
+      }
     }
     return this.state;
   }
@@ -55,7 +58,6 @@ export class CircuitBreaker {
   private onSuccess(): void {
     this.failureCount = 0;
     this.state = CircuitState.CLOSED;
-    this.lastStateChange = Date.now();
   }
 
   private onFailure(): void {
@@ -69,6 +71,11 @@ export class CircuitBreaker {
   public reset(): void {
     this.state = CircuitState.CLOSED;
     this.failureCount = 0;
-    this.lastStateChange = Date.now();
   }
 }
+
+// Global/Per-endpoint instances
+export const fingerprintCircuitBreaker = new CircuitBreaker({
+  failureThreshold: 3,
+  cooldownPeriodMs: 15000,
+});

src/routes/fingerprint.ts

@@ -1,35 +1,50 @@
-import { Router, Request, Response, NextFunction } from 'express';
-import { CircuitBreaker, CircuitBreakerOpenError } from '../lib/circuitBreaker';
+import { Router, Request, Response } from 'express';
+import { fingerprintCircuitBreaker, CircuitBreakerOpenError } from '../lib/circuitBreaker';
 
-export const fingerprintCircuitBreaker = new CircuitBreaker({
-  failureThreshold: 5,
-  resetTimeoutMs: 10000,
-});
-
-export const router = Router();
+const router = Router();
 
-async function callDownstreamFingerprintService(data: Record<string, unknown>): Promise<Record<string, unknown>> {
-  // Simulates downstream request execution
-  return { status: 'success', fingerprintId: 'fp_' + Date.now(), ...data };
+/**
+ * Downstream service simulation / call handler
+ */
+async function callDownstreamFingerprintService(data: any): Promise<any> {
+  // Simulates downstream API interaction
+  return { fingerprintId: 'fp_' + Date.now(), verified: true };
 }
 
-router.post('/api/fingerprint', async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+/**
+ * POST /api/fingerprint
+ */
+router.post('/fingerprint', async (req: Request, res: Response) => {
+  const correlationId = (req.headers['x-correlation-id'] as string) || `req-${Date.now()}`;
+
   try {
     const result = await fingerprintCircuitBreaker.execute(() =>
       callDownstreamFingerprintService(req.body)
     );
-    res.status(200).json(result);
-  } catch (error) {
-    if (error instanceof CircuitBreakerOpenError) {
-      res.status(503).json({
+
+    return res.status(200).json({
+      success: true,
+      data: result,
+      correlationId,
+    });
+  } catch (error: any) {
+    if (error instanceof CircuitBreakerOpenError || error.statusCode === 503) {
+      return res.status(503).json({
         error: {
           code: 'SERVICE_UNAVAILABLE',
-          message: 'Fingerprint service is temporarily unavailable. Circuit breaker open.',
+          message: 'Downstream fingerprint service is currently unavailable. Circuit breaker open.',
+          correlationId,
         },
       });
-      return;
     }
-    next(error);
+
+    return res.status(500).json({
+      error: {
+        code: 'INTERNAL_SERVER_ERROR',
+        message: error.message || 'An unexpected error occurred.',
+        correlationId,
+      },
+    });
   }
 });
 

test/circuitBreaker.test.ts

@@ -0,0 +1,28 @@
+import { CircuitBreaker, CircuitState, CircuitBreakerOpenError } from '../src/lib/circuitBreaker';
+
+describe('CircuitBreaker Unit Tests', () => {
+  let breaker: CircuitBreaker;
+
+  beforeEach(() => {
+    breaker = new CircuitBreaker({ failureThreshold: 2, cooldownPeriodMs: 100 });
+  });
+
+  it('should execute successfully in CLOSED state', async () => {
+    const fn = jest.fn().mockResolvedValue('ok');
+    const result = await breaker.execute(fn);
+    expect(result).toBe('ok');
+    expect(breaker.getState()).toBe(CircuitState.CLOSED);
+  });
+
+  it('should open breaker after reaching failure threshold', async () => {
+    const fn = jest.fn().mockRejectedValue(new Error('Downstream failure'));
+
+    await expect(breaker.execute(fn)).rejects.toThrow();
+    await expect(breaker.execute(fn)).rejects.toThrow();
+
+    expect(breaker.getState()).toBe(CircuitState.OPEN);
+
+    // Should fail fast with 503 CircuitBreakerOpenError without calling inner fn
+    await expect(breaker.execute(fn)).rejects.toThrow(CircuitBreakerOpenError);
+  });
+});