@sentienguard/apm 1.0.4 → 1.0.6

package/src/circuitBreaker.js

@@ -1,254 +1,264 @@
-/**
- * Circuit Breaker Module
- *
- * Provides circuit breaker functionality using Opossum library.
- * Wraps operations (especially database calls) to prevent cascade failures.
- *
- * Circuit States:
- * - CLOSED: Normal operation, requests pass through
- * - OPEN: Circuit tripped due to failures, requests fail fast
- * - HALF-OPEN: Testing if service recovered, limited requests allowed
- *
- * Usage:
- *   import { createBreaker, wrapMongoOperation } from './circuitBreaker.js';
- *
- *   // Wrap an async operation
- *   const breaker = createBreaker(async () => await db.query(), { name: 'db-query' });
- *   const result = await breaker.fire();
- *
- *   // Or use the MongoDB helper
- *   const findUsers = wrapMongoOperation('User.find', async () => User.find());
- *   const users = await findUsers();
- */
-
-import config, { debug, warn } from './config.js';
-import { getAggregator } from './aggregator.js';
-
-// Store active circuit breakers
-const breakers = new Map();
-
-// Check if opossum is available
-let CircuitBreaker = null;
-
-/**
- * Initialize Opossum (lazy load)
- */
-async function initOpossum() {
-  if (CircuitBreaker) return true;
-
-  try {
-    const opossum = await import('opossum');
-    CircuitBreaker = opossum.default || opossum;
-    debug('Opossum circuit breaker loaded');
-    return true;
-  } catch (err) {
-    debug('Opossum not installed. Circuit breaker disabled. Install with: npm install opossum');
-    return false;
-  }
-}
-
-/**
- * Default circuit breaker options
- */
-function getDefaultOptions() {
-  return {
-    timeout: config.circuitBreaker.timeout,
-    errorThresholdPercentage: config.circuitBreaker.errorThresholdPercentage,
-    resetTimeout: config.circuitBreaker.resetTimeout,
-    volumeThreshold: config.circuitBreaker.volumeThreshold
-  };
-}
-
-/**
- * Create a circuit breaker for an async operation
- *
- * @param {Function} asyncFn - The async function to wrap
- * @param {Object} options - Circuit breaker options
- * @param {string} options.name - Name for the circuit (used for metrics)
- * @param {number} options.timeout - Timeout in ms
- * @param {number} options.errorThresholdPercentage - Error threshold to trip
- * @param {number} options.resetTimeout - Time before attempting recovery
- * @param {Function} options.fallback - Fallback function when circuit is open
- * @returns {Object} Circuit breaker instance or wrapped function if opossum unavailable
- */
-export async function createBreaker(asyncFn, options = {}) {
-  if (!config.circuitBreaker.enabled) {
-    debug('Circuit breaker disabled, returning passthrough');
-    return createPassthrough(asyncFn);
-  }
-
-  const initialized = await initOpossum();
-  if (!initialized) {
-    return createPassthrough(asyncFn);
-  }
-
-  const name = options.name || 'unnamed';
-  const breakerOptions = {
-    ...getDefaultOptions(),
-    ...options,
-    name
-  };
-
-  const breaker = new CircuitBreaker(asyncFn, breakerOptions);
-  const aggregator = getAggregator();
-
-  // Attach event listeners for metrics
-  breaker.on('open', () => {
-    aggregator.recordCircuitState(name, 'open');
-    warn(`Circuit breaker OPEN: ${name}`);
-  });
-
-  breaker.on('halfOpen', () => {
-    aggregator.recordCircuitState(name, 'halfOpen');
-    debug(`Circuit breaker HALF-OPEN: ${name}`);
-  });
-
-  breaker.on('close', () => {
-    aggregator.recordCircuitState(name, 'close');
-    debug(`Circuit breaker CLOSED: ${name}`);
-  });
-
-  breaker.on('fallback', (result) => {
-    debug(`Circuit breaker fallback executed: ${name}`);
-  });
-
-  breaker.on('timeout', () => {
-    debug(`Circuit breaker timeout: ${name}`);
-  });
-
-  breaker.on('reject', () => {
-    debug(`Circuit breaker rejected (circuit open): ${name}`);
-  });
-
-  // Register fallback if provided
-  if (options.fallback) {
-    breaker.fallback(options.fallback);
-  }
-
-  // Store reference
-  breakers.set(name, breaker);
-
-  return breaker;
-}
-
-/**
- * Create a passthrough wrapper when circuit breaker is disabled
- */
-function createPassthrough(asyncFn) {
-  return {
-    fire: (...args) => asyncFn(...args),
-    fallback: () => {},
-    on: () => {},
-    isOpen: () => false,
-    isClosed: () => true,
-    stats: { fires: 0, failures: 0, successes: 0 }
-  };
-}
-
-/**
- * Create a circuit breaker specifically for MongoDB operations
- *
- * @param {string} operationName - Name of the operation (e.g., 'User.find')
- * @param {Function} mongoOperation - The MongoDB operation function
- * @param {Object} options - Additional options
- * @returns {Function} Wrapped function that uses circuit breaker
- */
-export async function wrapMongoOperation(operationName, mongoOperation, options = {}) {
-  const breaker = await createBreaker(mongoOperation, {
-    name: `mongodb:${operationName}`,
-    // MongoDB-specific defaults
-    timeout: options.timeout || config.circuitBreaker.timeout,
-    errorThresholdPercentage: options.errorThresholdPercentage || 50,
-    resetTimeout: options.resetTimeout || 30000,
-    ...options
-  });
-
-  // Return a function that fires the breaker
-  return async function wrappedOperation(...args) {
-    return breaker.fire(...args);
-  };
-}
-
-/**
- * Get a registered circuit breaker by name
- *
- * @param {string} name - Circuit breaker name
- * @returns {Object|null} Circuit breaker instance or null
- */
-export function getBreaker(name) {
-  return breakers.get(name) || null;
-}
-
-/**
- * Get all registered circuit breakers
- *
- * @returns {Map} Map of circuit breaker instances
- */
-export function getAllBreakers() {
-  return new Map(breakers);
-}
-
-/**
- * Get circuit breaker statistics
- *
- * @param {string} name - Circuit breaker name (optional, returns all if not provided)
- * @returns {Object} Statistics object
- */
-export function getBreakerStats(name) {
-  if (name) {
-    const breaker = breakers.get(name);
-    if (!breaker) return null;
-
-    return {
-      name,
-      state: breaker.opened ? 'open' : (breaker.halfOpen ? 'halfOpen' : 'closed'),
-      stats: breaker.stats
-    };
-  }
-
-  // Return stats for all breakers
-  const allStats = {};
-  for (const [breakerName, breaker] of breakers) {
-    allStats[breakerName] = {
-      state: breaker.opened ? 'open' : (breaker.halfOpen ? 'halfOpen' : 'closed'),
-      stats: breaker.stats
-    };
-  }
-  return allStats;
-}
-
-/**
- * Reset a circuit breaker (close it)
- *
- * @param {string} name - Circuit breaker name
- */
-export function resetBreaker(name) {
-  const breaker = breakers.get(name);
-  if (breaker && typeof breaker.close === 'function') {
-    breaker.close();
-    debug(`Circuit breaker reset: ${name}`);
-  }
-}
-
-/**
- * Shutdown all circuit breakers
- */
-export function shutdownBreakers() {
-  for (const [name, breaker] of breakers) {
-    if (typeof breaker.shutdown === 'function') {
-      breaker.shutdown();
-    }
-  }
-  breakers.clear();
-  debug('All circuit breakers shutdown');
-}
-
-export default {
-  createBreaker,
-  wrapMongoOperation,
-  getBreaker,
-  getAllBreakers,
-  getBreakerStats,
-  resetBreaker,
-  shutdownBreakers
-};
+/**
+ * Circuit Breaker Module
+ *
+ * Provides circuit breaker functionality using Opossum library.
+ * Wraps operations (especially database calls) to prevent cascade failures.
+ *
+ * Circuit States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Circuit tripped due to failures, requests fail fast
+ * - HALF-OPEN: Testing if service recovered, limited requests allowed
+ *
+ * Usage:
+ *   import { createBreaker, wrapMongoOperation } from './circuitBreaker.js';
+ *
+ *   // Wrap an async operation
+ *   const breaker = createBreaker(async () => await db.query(), { name: 'db-query' });
+ *   const result = await breaker.fire();
+ *
+ *   // Or use the MongoDB helper
+ *   const findUsers = wrapMongoOperation('User.find', async () => User.find());
+ *   const users = await findUsers();
+ */
+
+import config, { debug, warn } from './config.js';
+import { getAggregator } from './aggregator.js';
+
+// Store active circuit breakers
+const breakers = new Map();
+
+// Check if opossum is available
+let CircuitBreaker = null;
+
+/**
+ * Initialize Opossum (lazy load)
+ */
+async function initOpossum() {
+  if (CircuitBreaker) return true;
+
+  try {
+    const opossum = await import('opossum');
+    CircuitBreaker = opossum.default || opossum;
+    debug('Opossum circuit breaker loaded');
+    return true;
+  } catch (err) {
+    debug('Opossum not installed. Circuit breaker disabled. Install with: npm install opossum');
+    return false;
+  }
+}
+
+/**
+ * Default circuit breaker options
+ */
+function getDefaultOptions() {
+  return {
+    timeout: config.circuitBreaker.timeout,
+    errorThresholdPercentage: config.circuitBreaker.errorThresholdPercentage,
+    resetTimeout: config.circuitBreaker.resetTimeout,
+    volumeThreshold: config.circuitBreaker.volumeThreshold
+  };
+}
+
+/**
+ * Create a circuit breaker for an async operation
+ *
+ * @param {Function} asyncFn - The async function to wrap
+ * @param {Object} options - Circuit breaker options
+ * @param {string} options.name - Name for the circuit (used for metrics)
+ * @param {number} options.timeout - Timeout in ms
+ * @param {number} options.errorThresholdPercentage - Error threshold to trip
+ * @param {number} options.resetTimeout - Time before attempting recovery
+ * @param {Function} options.fallback - Fallback function when circuit is open
+ * @returns {Object} Circuit breaker instance or wrapped function if opossum unavailable
+ */
+export async function createBreaker(asyncFn, options = {}) {
+  if (!config.circuitBreaker.enabled) {
+    debug('Circuit breaker disabled, returning passthrough');
+    return createPassthrough(asyncFn);
+  }
+
+  const initialized = await initOpossum();
+  if (!initialized) {
+    return createPassthrough(asyncFn);
+  }
+
+  const name = options.name || 'unnamed';
+  const breakerOptions = {
+    ...getDefaultOptions(),
+    ...options,
+    name
+  };
+
+  const breaker = new CircuitBreaker(asyncFn, breakerOptions);
+  const aggregator = getAggregator();
+
+  // Attach event listeners for metrics
+  breaker.on('open', () => {
+    aggregator.recordCircuitState(name, 'open');
+    warn(`Circuit breaker OPEN: ${name}`);
+  });
+
+  breaker.on('halfOpen', () => {
+    aggregator.recordCircuitState(name, 'halfOpen');
+    debug(`Circuit breaker HALF-OPEN: ${name}`);
+  });
+
+  breaker.on('close', () => {
+    aggregator.recordCircuitState(name, 'close');
+    debug(`Circuit breaker CLOSED: ${name}`);
+  });
+
+  breaker.on('fallback', (result) => {
+    debug(`Circuit breaker fallback executed: ${name}`);
+  });
+
+  breaker.on('timeout', () => {
+    debug(`Circuit breaker timeout: ${name}`);
+  });
+
+  breaker.on('reject', () => {
+    debug(`Circuit breaker rejected (circuit open): ${name}`);
+  });
+
+  // Register fallback if provided
+  if (options.fallback) {
+    breaker.fallback(options.fallback);
+  }
+
+  // Store reference
+  breakers.set(name, breaker);
+
+  return breaker;
+}
+
+/**
+ * Create a passthrough wrapper when circuit breaker is disabled
+ */
+function createPassthrough(asyncFn) {
+  return {
+    fire: (...args) => asyncFn(...args),
+    fallback: () => {},
+    on: () => {},
+    isOpen: () => false,
+    isClosed: () => true,
+    stats: { fires: 0, failures: 0, successes: 0 }
+  };
+}
+
+/**
+ * Create a circuit breaker specifically for MongoDB operations
+ *
+ * @param {string} operationName - Name of the operation (e.g., 'User.find')
+ * @param {Function} mongoOperation - The MongoDB operation function
+ * @param {Object} options - Additional options
+ * @returns {Function} Wrapped function that uses circuit breaker
+ */
+export async function wrapMongoOperation(operationName, mongoOperation, options = {}) {
+  const breaker = await createBreaker(mongoOperation, {
+    name: `mongodb:${operationName}`,
+    // MongoDB-specific defaults
+    timeout: options.timeout || config.circuitBreaker.timeout,
+    errorThresholdPercentage: options.errorThresholdPercentage || 50,
+    resetTimeout: options.resetTimeout || 30000,
+    ...options
+  });
+
+  // Return a function that fires the breaker
+  return async function wrappedOperation(...args) {
+    return breaker.fire(...args);
+  };
+}
+
+/**
+ * Get a registered circuit breaker by name
+ *
+ * @param {string} name - Circuit breaker name
+ * @returns {Object|null} Circuit breaker instance or null
+ */
+export function getBreaker(name) {
+  return breakers.get(name) || null;
+}
+
+/**
+ * Get all registered circuit breakers
+ *
+ * @returns {Map} Map of circuit breaker instances
+ */
+export function getAllBreakers() {
+  return new Map(breakers);
+}
+
+/**
+ * Get circuit breaker statistics
+ *
+ * @param {string} name - Circuit breaker name (optional, returns all if not provided)
+ * @returns {Object} Statistics object
+ */
+export function getBreakerStats(name) {
+  const getState = (breaker) => {
+    if (breaker.opened) {
+      return 'open';
+    }
+    if (breaker.halfOpen) {
+      return 'halfOpen';
+    }
+    return 'closed';
+  };
+
+  if (name) {
+    const breaker = breakers.get(name);
+    if (!breaker) return null;
+
+    return {
+      name,
+      state: getState(breaker),
+      stats: breaker.stats
+    };
+  }
+
+  // Return stats for all breakers
+  const allStats = {};
+  for (const [breakerName, breaker] of breakers) {
+    allStats[breakerName] = {
+      state: getState(breaker),
+      stats: breaker.stats
+    };
+  }
+  return allStats;
+}
+
+/**
+ * Reset a circuit breaker (close it)
+ *
+ * @param {string} name - Circuit breaker name
+ */
+export function resetBreaker(name) {
+  const breaker = breakers.get(name);
+  if (breaker && typeof breaker.close === 'function') {
+    breaker.close();
+    debug(`Circuit breaker reset: ${name}`);
+  }
+}
+
+/**
+ * Shutdown all circuit breakers
+ */
+export function shutdownBreakers() {
+  for (const [ breaker] of breakers) {
+    if (typeof breaker.shutdown === 'function') {
+      breaker.shutdown();
+    }
+  }
+  breakers.clear();
+  debug('All circuit breakers shutdown');
+}
+
+export default {
+  createBreaker,
+  wrapMongoOperation,
+  getBreaker,
+  getAllBreakers,
+  getBreakerStats,
+  resetBreaker,
+  shutdownBreakers
+};