@onlineapps/error-handler-core 1.1.15 → 2.0.0

package/src/ErrorClassifier.js

@@ -31,6 +31,13 @@ const ErrorCodes = {
   503: ErrorTypes.TRANSIENT,
   504: ErrorTypes.TIMEOUT,
   
+  // Circuit breaker refusal (CircuitOpenError) -> TRANSIENT: the state heals
+  // itself once the breaker's resetTimeout elapses, so retrying is allowed.
+  // Pinned by code, never by message wording — the word "resetTimeout" in the
+  // fix hint would otherwise read as TIMEOUT via the patterns below.
+  // @see api/docs/governance/confirmations/circuit-open-classification.md
+  CIRCUIT_OPEN: ErrorTypes.TRANSIENT,
+
   // Business errors
   400: ErrorTypes.VALIDATION,
   401: ErrorTypes.BUSINESS,
@@ -62,9 +69,16 @@ class ErrorClassifier {
       return ErrorCodes[error.code];
     }
     
-    // 3. Check HTTP status
-    if (error.statusCode && ErrorCodes[error.statusCode]) {
-      return ErrorCodes[error.statusCode];
+    // 3. Check HTTP status — `status`, the field the error contract names.
+    // A branded business error carries `code` (string) and `status` (number);
+    // `statusCode` was the Express-layer spelling and no producer feeds it into
+    // this classifier (the orchestrator's non-2xx error sets both names, and its
+    // own branch calls `classify` — a method the connector does not expose —
+    // so it never arrives here either). One name, no `status || statusCode`
+    // chain (`architecture-principles.md` §3).
+    // @see api/docs/biz/70-contracts/error-handling.md
+    if (error.status && ErrorCodes[error.status]) {
+      return ErrorCodes[error.status];
     }
     
     // 4. Check message patterns

package/src/ErrorHandlerCore.js

@@ -10,6 +10,8 @@ const CircuitBreakerManager = require('./CircuitBreaker');
 const DLQRouter = require('./DLQRouter');
 const CompensationHandler = require('./CompensationHandler');
 const runtimeCfg = require('./config');
+const { assertNumberInRange } = require('./configRanges');
+const { assertLogger } = require('@onlineapps/logger-contract');
 
 class ErrorHandlerCore {
   /**
@@ -20,28 +22,74 @@ class ErrorHandlerCore {
    * @param {string} [config.serviceVersion] - Service version
    * @param {string} [config.environment] - Environment
    * @param {Object} config.monitoring - Monitoring instance (monitoring-core)
-   * @param {Object} [config.handling] - Error handling configuration
-   * @param {number} [config.handling.maxRetries=3] - Max retry attempts
-   * @param {number} [config.handling.retryDelay=1000] - Initial retry delay
-   * @param {number} [config.handling.retryMultiplier=2] - Backoff multiplier
+   * @param {Object} config.logger - Logger with info/warn/error/debug (required).
+   *   Used only where an error is deliberately swallowed — a monitoring outage
+   *   here, a DLQ routing failure in DLQRouter — so it cannot vanish with it.
+   * @param {Object} [config.handling] - Error handling configuration. Every key
+   *   below is optional and this class declares NO default for any of them: the
+   *   value, its documented default and its accepted range belong to the
+   *   component that reads the key, and are documented there once — repeating
+   *   the numbers here made a second rail that d.173 already found lying.
+   * @param {number} [config.handling.maxRetries] - see `RetryHandler`
+   * @param {number} [config.handling.retryDelay] - see `RetryHandler`
+   * @param {number} [config.handling.retryMultiplier] - see `RetryHandler`
+   * @param {number} [config.handling.maxRetryDelay] - see `RetryHandler`
+   * @param {number} [config.handling.circuitTimeout] - `timeout`, see `CircuitBreakerManager`
+   * @param {number} [config.handling.errorThreshold] - see `CircuitBreakerManager`
+   * @param {number} [config.handling.resetTimeout] - see `CircuitBreakerManager`
    * @param {boolean} [config.handling.circuitBreakerEnabled=true] - Enable circuit breaker
    * @param {boolean} [config.handling.dlqEnabled=true] - Enable DLQ routing
    * @param {Object} [config.handling.mqClient] - MQ client for DLQ
    * @param {boolean} [config.handling.compensationEnabled=true] - Enable compensation
+   * @throws {Error} If a handling value is outside the range its component declares
    */
   constructor(config) {
     if (!config.serviceName) {
-      throw new Error('serviceName is required');
+      throw new Error(
+        '[ErrorHandlerCore] Missing required config key - serviceName is required. '
+        + 'Fix: pass config.serviceName; it labels every log line this handler writes.'
+      );
     }
     
     if (!config.monitoring) {
-      throw new Error('monitoring instance is required (monitoring-core)');
+      throw new Error(
+        '[ErrorHandlerCore] Missing dependency - monitoring instance is required (monitoring-core). '
+        + 'Fix: pass config.monitoring; without it no error this handler sees reaches a log.'
+      );
     }
-    
+
+    // A monitoring instance that implements neither shape can never carry a log
+    // line. It used to be discovered at the first logError(), which then dumped
+    // JSON to stdout; the constructor is where it belongs (§4 fail-fast, §3 no
+    // fallback). Both shapes stay accepted — monitoring-core exposes
+    // `.logger.error()`, the conn-base-monitoring wrapper a bare `.error()`.
+    const monitoringCanLog =
+      (config.monitoring.logger && typeof config.monitoring.logger.error === 'function')
+      || typeof config.monitoring.error === 'function';
+    if (!monitoringCanLog) {
+      throw new Error(
+        '[ErrorHandlerCore] monitoring instance cannot log - Expected: monitoring.logger.error() '
+        + '(monitoring-core) or monitoring.error() (conn-base-monitoring) as a function. '
+        + 'Fix: pass an initialised monitoring instance.'
+      );
+    }
+
+    this.logger = assertLogger(
+      'ErrorHandlerCore',
+      config.logger,
+      'a monitoring outage this handler deliberately swallows still reaches the structured log'
+    );
+
     this.serviceName = config.serviceName;
+    // One rail, the one d.178 introduced: `runtimeCfg.resolve` already prefers
+    // the explicit value over the env variable and the env variable over the
+    // declared default. The `config.x || resolved.x` that stood here re-asked the
+    // same question a second time and, being `||`, would have thrown away an
+    // explicit falsy answer — `.claude/rules/change-discipline.md`
+    // § One rail per concern.
     const resolved = runtimeCfg.resolve(config);
-    this.serviceVersion = config.serviceVersion || resolved.serviceVersion;
-    this.environment = config.environment || resolved.environment;
+    this.serviceVersion = resolved.serviceVersion;
+    this.environment = resolved.environment;
     this.monitoring = config.monitoring;
     
     const handling = config.handling || {};
@@ -49,21 +97,27 @@ class ErrorHandlerCore {
     // Initialize components
     this.classifier = new ErrorClassifier();
     this.logSchema = new UnifiedLogSchema();
+    // Values are forwarded as given — `undefined` included. The default for
+    // each key is declared once, by the component that owns it (RetryHandler,
+    // CircuitBreakerManager, DLQRouter); re-stating the same numbers here made
+    // two rails for one fact and, being `||`, turned an explicit 0 into the
+    // default before the owning class ever saw it.
     this.retryHandler = new RetryHandler({
-      maxRetries: handling.maxRetries || 3,
-      retryDelay: handling.retryDelay || 1000,
-      retryMultiplier: handling.retryMultiplier || 2,
-      maxRetryDelay: handling.maxRetryDelay || 30000
+      maxRetries: handling.maxRetries,
+      retryDelay: handling.retryDelay,
+      retryMultiplier: handling.retryMultiplier,
+      maxRetryDelay: handling.maxRetryDelay
     });
     this.circuitBreaker = new CircuitBreakerManager({
       circuitBreakerEnabled: handling.circuitBreakerEnabled !== false,
-      timeout: handling.circuitTimeout || 10000,
-      errorThreshold: handling.errorThreshold || 50,
-      resetTimeout: handling.resetTimeout || 30000
+      timeout: handling.circuitTimeout,
+      errorThreshold: handling.errorThreshold,
+      resetTimeout: handling.resetTimeout
     });
     this.dlqRouter = new DLQRouter({
       dlqEnabled: handling.dlqEnabled !== false,
-      mqClient: handling.mqClient || null
+      mqClient: handling.mqClient,
+      logger: this.logger
     });
     this.compensation = new CompensationHandler({
       compensationEnabled: handling.compensationEnabled !== false
@@ -72,7 +126,8 @@ class ErrorHandlerCore {
   
   /**
    * Log error using monitoring connector
-   * Always works: console (via monitoring) + RabbitMQ (if available)
+   * Writes through the monitoring instance; a monitoring outage falls to the
+   * injected logger rather than to stdout.
    * 
    * @param {Object} errorData - Error data
    * @param {string} errorData.moduleName - Module name
@@ -100,34 +155,33 @@ class ErrorHandlerCore {
       handling: {} // Will be filled by handleError
     });
     
-    // Log via monitoring connector
-    // Monitoring connector has fallback to console if not initialized
+    // Log via monitoring connector. Which of the two shapes is present was settled
+    // in the constructor, so there is no third branch left to fall back to.
     const logMessage = `[${moduleName}] ${operation} failed: ${error.message}`;
-    
+
     try {
-      // Use monitoring logger (monitoring-core returns instance with logger property)
-      // logger.error() always logs to console, optionally to RabbitMQ
-      if (this.monitoring.logger && this.monitoring.logger.error) {
+      if (this.monitoring.logger && typeof this.monitoring.logger.error === 'function') {
+        // monitoring-core: instance with a logger property
         this.monitoring.logger.error(logMessage, {
           ...errorLog,
           severity: errorLog.metadata.severity
         });
-      } else if (this.monitoring.error) {
-        // Fallback: direct error method (conn-base-monitoring wrapper)
+      } else {
+        // conn-base-monitoring wrapper: direct error method
         this.monitoring.error(logMessage, {
           ...errorLog,
           severity: errorLog.metadata.severity
         });
-      } else {
-        // Last resort: console
-        console.error(JSON.stringify(errorLog, null, 2));
       }
     } catch (logError) {
-      // If monitoring fails, fallback to console
-      console.error('[ErrorHandlerCore] Monitoring log failed, using console:', logError.message);
-      console.error(JSON.stringify(errorLog, null, 2));
+      // Swallowed on purpose: a monitoring outage must not break error handling.
+      // The injected logger is the only reason the lost entry stays visible.
+      this.logger.error('[ErrorHandlerCore] Monitoring log failed', {
+        reason: logError.message,
+        errorLog
+      });
     }
-    
+
     return errorLog;
   }
   
@@ -139,9 +193,12 @@ class ErrorHandlerCore {
    * @param {string} errorData.operation - Operation name
    * @param {Error} errorData.error - Error object
    * @param {Object} [errorData.context] - Additional context
-   * @param {number} [errorData.context.retryCount] - Current retry count
-   * @param {number} [errorData.context.maxRetries] - Max retries
+   * @param {number} [errorData.context.retryCount=0] - Retries already made
+   *   before this failure; integer >= 0
+   * @param {number} [errorData.context.maxRetries] - Attempt budget for this
+   *   call, see `RetryHandler`; integer >= 1
    * @returns {Promise<Object>} Handling result
+   * @throws {Error} If context.retryCount or context.maxRetries is outside its range
    */
   async handleError(errorData) {
     const { moduleName, operation, error, context = {} } = errorData;
@@ -167,8 +224,8 @@ class ErrorHandlerCore {
       errorType,
       shouldRetry: action.shouldRetry || false,
       retryDelay: action.retryDelay || null,
-      retryCount: context.retryCount || 0,
-      maxRetries: context.maxRetries || this.retryHandler.maxRetries
+      retryCount: this._resolveRetryCount(context),
+      maxRetries: this._resolveMaxRetries(context)
     };
     
     // 5. Execute action
@@ -193,20 +250,69 @@ class ErrorHandlerCore {
   }
   
   /**
-   * Determine action based on error type
+   * Attempt budget for ONE call: the caller's `context.maxRetries` when they
+   * passed one, otherwise the handler's own. `??`, not `||`, and validated by
+   * the component that owns the key — a 0 from the caller used to fall through
+   * to the instance value, so a caller asking for no retries silently got three.
+   *
+   * @param {Object} context - Call context
+   * @returns {number} Accepted attempt budget
+   * @throws {Error} If context.maxRetries is outside its range
+   * @private
+   */
+  _resolveMaxRetries(context) {
+    const maxRetries = context.maxRetries ?? this.retryHandler.maxRetries;
+    RetryHandler.assertMaxRetries('ErrorHandlerCore', 'context.maxRetries', maxRetries);
+    return maxRetries;
+  }
+
+  /**
+   * Retries already made before the failure being handled. It decides whether
+   * another attempt is left, so it is checked like any other number the caller
+   * supplies (§4 fail-fast); `|| 0` used to read every nonsense value as "none
+   * yet" and started the budget over.
+   *
+   * @param {Object} context - Call context
+   * @returns {number} Accepted retry count
+   * @throws {Error} If context.retryCount is not an integer >= 0
+   * @private
+   */
+  _resolveRetryCount(context) {
+    const retryCount = context.retryCount ?? 0;
+    assertNumberInRange('ErrorHandlerCore', 'context.retryCount', retryCount, {
+      integer: true,
+      min: 0,
+      expected: 'an integer >= 0 (the number of retries already made)'
+    });
+    return retryCount;
+  }
+
+  /**
+   * Determine action based on error type.
+   *
+   * `maxRetries` is a budget of ATTEMPTS — the meaning `RetryHandler` documents
+   * ("Max attempts"), the meaning its range message states ("the number of
+   * attempts") and the meaning `ErrorClassifier.shouldRetry` uses. This method
+   * used to compare `retryCount < maxRetries`, i.e. read the same key as a
+   * budget of RETRIES, one more than the loop in `RetryHandler.executeWithRetry`
+   * ever ran: `maxRetries: 3` meant three calls there and four here.
+   *
    * @private
    */
   _determineAction(errorType, context) {
-    const retryCount = context.retryCount || 0;
-    const maxRetries = context.maxRetries || this.retryHandler.maxRetries;
-    
+    const retryCount = this._resolveRetryCount(context);
+    const maxAttempts = this._resolveMaxRetries(context);
+    // The failure being handled IS an attempt, so the attempts made so far are
+    // the retries plus the original call.
+    const attemptsMade = retryCount + 1;
+
     switch (errorType) {
       case ErrorTypes.TRANSIENT:
       case ErrorTypes.TIMEOUT:
       case ErrorTypes.RATE_LIMIT:
-        // Retry if under max retries
-        if (retryCount < maxRetries) {
-          const delay = this.retryHandler.calculateBackoff(retryCount + 1);
+        // Retry while the attempt budget still has room
+        if (attemptsMade < maxAttempts) {
+          const delay = this.retryHandler.calculateBackoff(attemptsMade);
           return {
             type: 'retry',
             shouldRetry: true,
@@ -243,9 +349,10 @@ class ErrorHandlerCore {
    */
   async executeWithRetry(options) {
     const { moduleName, operation, fn, context = {} } = options;
-    
+    const maxRetries = this._resolveMaxRetries(context);
+
     return await this.retryHandler.executeWithRetry(fn, {
-      maxRetries: context.maxRetries || this.retryHandler.maxRetries,
+      maxRetries,
       onRetry: async (error, attempt, delay) => {
         // Log each retry attempt
         await this.logError({
@@ -255,7 +362,7 @@ class ErrorHandlerCore {
           context: {
             ...context,
             retryCount: attempt,
-            maxRetries: context.maxRetries || this.retryHandler.maxRetries
+            maxRetries
           }
         });
       }

package/src/RetryHandler.js

@@ -3,14 +3,84 @@
  * Implements exponential backoff retry logic
  */
 
+const { assertNumberInRange } = require('./configRanges');
+
+/**
+ * The retry budget is a number of ATTEMPTS, so 1 is the smallest meaningful
+ * value: `executeWithRetry` loops `attempt = 1 .. maxRetries`. Spelled once,
+ * here, because ErrorHandlerCore validates the same key when a caller overrides
+ * it per call — see `RetryHandler.assertMaxRetries`.
+ */
+const MAX_RETRIES_RULE = {
+  integer: true,
+  min: 1,
+  expected: 'an integer >= 1 (the number of attempts)'
+};
+
 class RetryHandler {
-  constructor(config = {}) {
-    this.maxRetries = config.maxRetries || 3;
-    this.retryDelay = config.retryDelay || 1000;
-    this.retryMultiplier = config.retryMultiplier || 2;
-    this.maxRetryDelay = config.maxRetryDelay || 30000;
+  /**
+   * Every key is optional and its default is declared HERE, once — this class
+   * owns them. Written as destructuring defaults, not `||`: a default may only
+   * stand in for a MISSING key, never overrule an explicit 0 (a caller asking
+   * for no delay got 1000 ms instead). See
+   * `.claude/rules/architecture-principles.md` §3.
+   *
+   * A value outside its documented range is refused here rather than carried
+   * into the loop: `maxRetries: 0` used to be swallowed by `||`, and once d.173
+   * let it through it produced a loop running zero times and a `throw undefined`
+   * (`.claude/rules/architecture-principles.md` §4).
+   *
+   * @param {Object} [config] - Retry configuration
+   * @param {number} [config.maxRetries=3] - Max attempts; integer >= 1
+   * @param {number} [config.retryDelay=1000] - Initial delay in ms; >= 0
+   * @param {number} [config.retryMultiplier=2] - Backoff multiplier; >= 1
+   * @param {number} [config.maxRetryDelay=30000] - Delay ceiling in ms; >= retryDelay
+   * @throws {Error} If any value is not a finite number inside its range
+   */
+  constructor({
+    maxRetries = 3,
+    retryDelay = 1000,
+    retryMultiplier = 2,
+    maxRetryDelay = 30000
+  } = {}) {
+    RetryHandler.assertMaxRetries('RetryHandler', 'maxRetries', maxRetries);
+    assertNumberInRange('RetryHandler', 'retryDelay', retryDelay, {
+      min: 0,
+      expected: 'a number >= 0 (milliseconds)'
+    });
+    assertNumberInRange('RetryHandler', 'retryMultiplier', retryMultiplier, {
+      min: 1,
+      expected: 'a number >= 1'
+    });
+    // Checked against retryDelay, not against 0: a ceiling below the floor makes
+    // calculateBackoff() return the ceiling on every attempt, so the initial
+    // delay the caller asked for would never be waited even once.
+    assertNumberInRange('RetryHandler', 'maxRetryDelay', maxRetryDelay, {
+      min: retryDelay,
+      expected: `a number >= retryDelay (${retryDelay})`
+    });
+
+    this.maxRetries = maxRetries;
+    this.retryDelay = retryDelay;
+    this.retryMultiplier = retryMultiplier;
+    this.maxRetryDelay = maxRetryDelay;
   }
-  
+
+  /**
+   * Apply the retry-budget rule to a value, wherever it was configured: this
+   * constructor, a per-call `options.maxRetries`, or ErrorHandlerCore's
+   * `context.maxRetries`. One rule, one place; the caller supplies the header
+   * and the key so the message names what the caller actually wrote.
+   *
+   * @param {string} context - Component raising the refusal
+   * @param {string} key - Key as the caller spells it
+   * @param {*} value - Value as received
+   * @throws {Error} If the value is not an integer >= 1
+   */
+  static assertMaxRetries(context, key, value) {
+    assertNumberInRange(context, key, value, MAX_RETRIES_RULE);
+  }
+
   /**
    * Calculate exponential backoff delay
    * 
@@ -35,21 +105,27 @@ class RetryHandler {
    * 
    * @param {Function} fn - Async function to execute
    * @param {Object} options - Retry options
-   * @param {number} [options.maxRetries] - Override max retries
+   * @param {number} [options.maxRetries] - Override max attempts; integer >= 1
    * @param {Function} [options.onRetry] - Callback on retry (error, attempt, delay)
    * @returns {Promise<*>} Function result
    * @throws {Error} Last error if all retries fail
+   * @throws {Error} If options.maxRetries is outside its range — before fn runs
    */
   async executeWithRetry(fn, options = {}) {
-    const maxAttempts = options.maxRetries || this.maxRetries;
-    let lastError;
-    
+    // `??`, not `||`: the override is taken when the caller passed one, and an
+    // out-of-range override is refused rather than silently replaced by the
+    // instance value. The check also covers the instance value, which the
+    // constructor has already accepted, so it can only ever fire for an override.
+    const maxAttempts = options.maxRetries ?? this.maxRetries;
+    RetryHandler.assertMaxRetries('RetryHandler', 'options.maxRetries', maxAttempts);
+
+    // No `lastError` and no throw after the loop: with maxAttempts >= 1 the loop
+    // always either returns or throws, and the trailing `throw lastError` it used
+    // to end with handed the caller `undefined` for maxAttempts 0.
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
       try {
         return await fn();
       } catch (error) {
-        lastError = error;
-        
         // If last attempt, throw
         if (attempt === maxAttempts) {
           throw error;
@@ -65,8 +141,6 @@ class RetryHandler {
         await this.sleep(delay);
       }
     }
-    
-    throw lastError;
   }
 }