@onlineapps/error-handler-core 1.1.15 → 2.0.0

package/src/UnifiedLogSchema.js

@@ -5,22 +5,64 @@
 
 const os = require('os');
 const runtimeCfg = require('./config');
+const { ErrorTypes } = require('./ErrorClassifier');
+const { describeValue } = require('./configRanges');
+
+/**
+ * Severity per error category.
+ *
+ * The set of categories has ONE owner, the classifier (`ErrorClassifier.js`,
+ * `ErrorTypes`), so this map keys off that declaration rather than repeating the
+ * names — a literal list here would be a second rail
+ * (`.claude/rules/change-discipline.md` § One rail per concern), and the
+ * `|| 'error'` that closed it made the drift silent: a category added at the
+ * owner and forgotten here was filed with a severity nobody chose.
+ */
+const SEVERITY_BY_TYPE = {
+  [ErrorTypes.TRANSIENT]: 'error',
+  [ErrorTypes.BUSINESS]: 'error',
+  [ErrorTypes.FATAL]: 'fatal',
+  [ErrorTypes.VALIDATION]: 'warn',
+  [ErrorTypes.TIMEOUT]: 'error',
+  [ErrorTypes.RATE_LIMIT]: 'warn',
+  [ErrorTypes.UNKNOWN]: 'error'
+};
+
+// Checked at load, not at log time: a category the owner declares and this file
+// does not answer for is a gap in the map, and the place to hear about it is
+// `require()`, once, rather than in one log line out of thousands
+// (`.claude/rules/architecture-principles.md` §4 fail-fast).
+for (const type of Object.values(ErrorTypes)) {
+  if (SEVERITY_BY_TYPE[type] === undefined) {
+    throw new Error(
+      `[UnifiedLogSchema] Missing severity for error type - "${type}" is declared by ErrorClassifier `
+      + 'but has no severity here, and a severity is never guessed. '
+      + `Fix: give "${type}" a severity in SEVERITY_BY_TYPE (UnifiedLogSchema.js).`
+    );
+  }
+}
+
+const ACCEPTED_TYPES = Object.values(ErrorTypes);
 
 class UnifiedLogSchema {
   /**
    * Create unified error log entry
    * 
    * @param {Object} params - Error data
-   * @param {string} params.moduleName - Module/component name
-   * @param {string} params.operation - Operation that failed
-   * @param {Error} params.error - Error object
+   * @param {string} params.moduleName - Module/component name (required; never invented)
+   * @param {string} params.operation - Operation that failed (required; never invented)
+   * @param {Error} params.error - Error object (required; must be an Error)
    * @param {Object} params.context - Additional context
-   * @param {string} params.serviceName - Service name
-   * @param {string} params.serviceVersion - Service version
-   * @param {string} params.environment - Environment (production, staging, etc.)
-   * @param {string} params.errorType - Classified error type
+   * @param {string} params.serviceName - Service name (required; never invented)
+   * @param {string} [params.serviceVersion] - Service version; falls back to the
+   *   declared rail `SERVICE_VERSION` → `defaults.js`, never to a literal here
+   * @param {string} [params.environment] - Environment; same declared rail
+   * @param {string} params.errorType - Classified error type (required; the
+   *   classifier's verdict, never invented here)
    * @param {Object} params.handling - Handling decision
    * @returns {Object} Unified error log entry
+   * @throws {Error} If serviceName, moduleName, operation or errorType is missing
+   *   or not a non-empty string, or if error is not an Error instance
    */
   create(params) {
     const {
@@ -34,49 +76,132 @@ class UnifiedLogSchema {
       errorType,
       handling = {}
     } = params;
-    
+
+    // The service that failed to introduce itself used to be renamed
+    // `unknown-service`, and downstream that reads exactly like a real name. An
+    // identity is never invented (owner, `api/docs/governance/confirmations/
+    // dlq-purge.md` 002); `defaults.js` says the same in words — service
+    // identity is the caller's to provide.
+    if (typeof serviceName !== 'string' || serviceName.trim() === '') {
+      throw new Error(
+        '[UnifiedLogSchema] Missing required field - "serviceName" must be a non-empty string; '
+        + 'it names the service every entry is filed under and is never invented. '
+        + 'Fix: pass params.serviceName (ErrorHandlerCore takes it from config.serviceName).'
+      );
+    }
+
+    // The module and the operation are the caller's input too, for exactly the
+    // reason above: `|| 'unknown-module'` / `|| 'unknown-operation'` filed the
+    // entry under a module and an operation of those names, and downstream that
+    // reads like a real one. The JSDoc has had them as required here, in
+    // `ErrorHandlerCore.logError` and in the `conn-infra-error-handler` wrapper.
+    if (typeof moduleName !== 'string' || moduleName.trim() === '') {
+      throw new Error(
+        '[UnifiedLogSchema] Missing required field - "moduleName" must be a non-empty string naming the '
+        + 'module that failed; it is the caller\'s to provide and is never invented. '
+        + 'Fix: pass params.moduleName (ErrorHandlerCore takes it from errorData.moduleName).'
+      );
+    }
+
+    if (typeof operation !== 'string' || operation.trim() === '') {
+      throw new Error(
+        '[UnifiedLogSchema] Missing required field - "operation" must be a non-empty string naming the '
+        + 'operation that failed; it is the caller\'s to provide and is never invented. '
+        + 'Fix: pass params.operation (ErrorHandlerCore takes it from errorData.operation).'
+      );
+    }
+
+    // An Error always carries `message` and `stack`, so `|| 'Unknown error'`
+    // could only ever fire for something that is NOT an error — and it turned
+    // that caller defect into an entry reading like a real failure with a real
+    // message. What arrives is either an Error or a refusal.
+    if (!(error instanceof Error)) {
+      throw new Error(
+        '[UnifiedLogSchema] Missing required field - "error" must be an Error instance carrying the '
+        + 'message and the stack of the failure; a substitute message would read downstream like a real one. '
+        + 'Fix: pass the caught Error itself (wrap a non-Error rejection in one at the point it is caught).'
+      );
+    }
+
+    // The category is the classifier's word (`ErrorClassifier.classify()` always
+    // returns one, `UNKNOWN` included). `|| 'UNKNOWN'` let the schema speak it
+    // instead, so an entry could claim a classification nobody made.
+    //
+    // One rule, one refusal: the field is acceptable iff it is a category the
+    // classifier declares, so a missing value and an invented one are the same
+    // class of refusal — the stance `configRanges.js` already takes for a wrong
+    // type versus a value out of range.
+    if (!ACCEPTED_TYPES.includes(errorType)) {
+      throw new Error(
+        '[UnifiedLogSchema] Invalid error type - "errorType" must be one of the categories '
+        + `ErrorClassifier declares (${ACCEPTED_TYPES.join(', ')}), got ${describeValue(errorType)}. `
+        + 'Fix: pass params.errorType from ErrorClassifier.classify(error).'
+      );
+    }
+
     // Extract error details
     const errorDetails = {
-      message: error?.message || 'Unknown error',
-      code: error?.code || null,
-      type: errorType || 'UNKNOWN',
-      stack: error?.stack || null
+      message: error.message,
+      // `??`, not `||`: a code that is present but falsy is a value, and the
+      // absence of one is `null`. `||` merged the two.
+      code: error.code ?? null,
+      type: errorType,
+      stack: error.stack ?? null
     };
     
     // Build unified log entry
     return {
       // Core identification
       timestamp: new Date().toISOString(),
-      serviceName: serviceName || 'unknown-service',
-      moduleName: moduleName || 'unknown-module',
-      operation: operation || 'unknown-operation',
-      
+      serviceName,
+      moduleName,
+      operation,
+
       // Error details
       error: errorDetails,
       
       // Context
       context: {
-        workflowId: context.workflowId || null,
-        userId: context.userId || null,
-        requestId: context.requestId || null,
+        // `??` throughout this file wherever `null` states an absence: a present
+        // falsy value is a value. (The `...context` below re-applies whatever the
+        // caller passed, so these three only ever declare the key for an ABSENT
+        // one — the operator makes no difference here, the single shape does.)
+        workflowId: context.workflowId ?? null,
+        userId: context.userId ?? null,
+        requestId: context.requestId ?? null,
         ...context
       },
       
       // Handling decision
       handling: {
-        action: handling.action || 'throw',
-        retryCount: handling.retryCount || null,
-        maxRetries: handling.maxRetries || null,
-        retryDelay: handling.retryDelay || null,
-        circuitBreakerState: handling.circuitBreakerState || null,
-        circuitName: handling.circuitName || null
+        // `null`, not `'throw'`: `logError()` deliberately passes `handling: {}`
+        // because the decision has not been made yet at that point. Writing
+        // `'throw'` there recorded a decision nobody took, and it read exactly
+        // like one that was.
+        action: handling.action ?? null,
+        // `??`: zero retries so far is a measurement, not a missing value. `||`
+        // turned it into `null`, so "nothing has been retried yet" and "we do not
+        // know" became the same entry — the defect d.173 removed in configuration.
+        retryCount: handling.retryCount ?? null,
+        maxRetries: handling.maxRetries ?? null,
+        // Same as retryCount: `retryDelay: 0` is a documented, valid value
+        // (`RetryHandler` accepts `retryDelay >= 0`), and `||` filed it as "we do
+        // not know".
+        retryDelay: handling.retryDelay ?? null,
+        circuitBreakerState: handling.circuitBreakerState ?? null,
+        circuitName: handling.circuitName ?? null
       },
       
       // Metadata
       metadata: {
         severity: this._determineSeverity(errorType),
         environment: runtimeCfg.get('environment', environment),
-        version: serviceVersion || '0.0.0',
+        // The version has a declared default and an env rail of its own
+        // (`defaults.js` + `config.js`, the same one `environment` uses one line
+        // up). The literal that stood here was a second copy of that default —
+        // and it ignored SERVICE_VERSION, so a service that set the variable
+        // still reported 0.0.0.
+        version: runtimeCfg.get('serviceVersion', serviceVersion),
         hostname: os.hostname(),
         pid: process.pid
       }
@@ -84,21 +209,17 @@ class UnifiedLogSchema {
   }
   
   /**
-   * Determine severity from error type
+   * Severity of a category. No fallback and no branch: `create()` has already
+   * refused anything that is not a declared category, and the load-time check
+   * above has already refused a declared category with no severity — so the
+   * lookup cannot miss.
+   *
+   * @param {string} errorType - A category ErrorClassifier declares
+   * @returns {string} Severity for that category
    * @private
    */
   _determineSeverity(errorType) {
-    const severityMap = {
-      FATAL: 'fatal',
-      BUSINESS: 'error',
-      VALIDATION: 'warn',
-      TRANSIENT: 'error',
-      TIMEOUT: 'error',
-      RATE_LIMIT: 'warn',
-      UNKNOWN: 'error'
-    };
-    
-    return severityMap[errorType] || 'error';
+    return SEVERITY_BY_TYPE[errorType];
   }
 }
 

package/src/configRanges.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * Range and shape checks for the configuration this package accepts.
+ *
+ * d.173 stopped a default from overruling an explicit value, so an explicit
+ * value now reaches the component that owns the key. Nothing then checked WHAT
+ * that value was: `maxRetries: 0` produced a loop that never runs and a
+ * `throw lastError` at its end handing the caller `undefined`, and
+ * `rollingCountBuckets: 0` divides the statistics window by zero. The checks
+ * belong in the constructor (`.claude/rules/architecture-principles.md` §4
+ * fail-fast) and live here, once, because three constructors ask the same two
+ * questions — a second copy of one rule is a second rail
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * A wrong type (`'3'`, `NaN`, `null`) is the same class of refusal as a value
+ * out of range: both mean the caller's configuration cannot be honoured, and
+ * silently substituting a default for either is the defect d.173 removed.
+ */
+
+/**
+ * Render a rejected value so the message says what actually arrived — a message
+ * naming only the rule leaves the reader guessing which of their keys is wrong.
+ * Exported because a refusal that is not about a range (`circuitBreakerOptions`
+ * that is not an object) must render the value the same way; two renderings of
+ * one fact would be two rails (`.claude/rules/change-discipline.md`).
+ *
+ * @param {*} value - Value as received
+ * @returns {string} Human-readable rendering, type included
+ */
+function describeValue(value) {
+  if (typeof value === 'string') return `string ${JSON.stringify(value)}`;
+  if (typeof value === 'number') return Number.isNaN(value) ? 'NaN' : `number ${value}`;
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  return `${typeof value} ${String(value)}`;
+}
+
+/**
+ * Refuse anything that is not a finite number inside the declared range.
+ *
+ * @param {string} context - Component raising the refusal (message header per §5)
+ * @param {string} key - Configuration key, spelled as the caller writes it
+ * @param {*} value - Value as received
+ * @param {Object} spec - The rule
+ * @param {string} spec.expected - The rule in words, used in the message
+ * @param {boolean} [spec.integer=false] - Whole numbers only
+ * @param {number} [spec.min] - Inclusive lower bound
+ * @param {number} [spec.exclusiveMin] - Exclusive lower bound
+ * @param {number} [spec.max] - Inclusive upper bound
+ * @throws {Error} If the value is not a finite number satisfying the rule
+ */
+function assertNumberInRange(context, key, value, spec) {
+  const { expected, integer = false, min, exclusiveMin, max } = spec;
+
+  const accepted =
+    typeof value === 'number'
+    && Number.isFinite(value)
+    && (!integer || Number.isInteger(value))
+    && (min === undefined || value >= min)
+    && (exclusiveMin === undefined || value > exclusiveMin)
+    && (max === undefined || value <= max);
+
+  if (!accepted) {
+    throw new Error(
+      `[${context}] Invalid configuration value - "${key}" must be ${expected}, `
+      + `got ${describeValue(value)}. Fix: pass ${expected}, or omit "${key}" to take the documented default.`
+    );
+  }
+}
+
+/**
+ * Refuse a DLQ naming pattern that cannot name a queue: an empty one would send
+ * dead messages to a queue with an empty name, and one without the `{queue}`
+ * placeholder would collapse every origin into a single queue.
+ *
+ * @param {string} context - Component raising the refusal
+ * @param {string} key - Configuration key
+ * @param {*} value - Value as received
+ * @throws {Error} If the value is not a non-empty string containing `{queue}`
+ */
+function assertQueuePattern(context, key, value) {
+  if (typeof value !== 'string' || !value.includes('{queue}')) {
+    throw new Error(
+      `[${context}] Invalid configuration value - "${key}" must be a non-empty string containing `
+      + `the "{queue}" placeholder, got ${describeValue(value)}. `
+      + `Fix: pass a pattern such as "{queue}.dlq", or omit "${key}" to take the documented default.`
+    );
+  }
+}
+
+module.exports = { describeValue, assertNumberInRange, assertQueuePattern };

package/src/index.js

@@ -10,6 +10,7 @@ const RetryHandler = require('./RetryHandler');
 const CircuitBreakerManager = require('./CircuitBreaker');
 const DLQRouter = require('./DLQRouter');
 const CompensationHandler = require('./CompensationHandler');
+const CircuitOpenError = require('./CircuitOpenError');
 
 module.exports = {
   // Main class
@@ -22,6 +23,9 @@ module.exports = {
   CircuitBreakerManager,
   DLQRouter,
   CompensationHandler,
+
+  // Typed errors (branch on error.code, never on error.message)
+  CircuitOpenError,
   
   // Constants
   ErrorTypes,