@onlineapps/error-handler-core 2.0.1 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [3.0.0] — 2026-09-16
+
+### Removed — **BREAKING** `DLQRouter`: dead-lettering má jednu kolej, a není v tomto balíčku
+
+`DLQRouter` publikoval mrtvou zprávu do `<fronta>.dlq` přímo a vedle toho emitoval
+vlastní událost `message_dlq` se `service_name: 'dlq-router'`. Totéž — odklad zprávy
+do `<služba>.dlq` i událost `message_dlq` — dělá politika `consume()`
+v `@onlineapps/mq-client-core` (počítadlo pokusů v hlavičce, `nack(requeue=false)`).
+Dvě koleje pro jednu věc jsou vada, ne záloha (`.claude/rules/change-discipline.md`
+§ One rail per concern); rozhodl to vlastník v
+`docs/governance/confirmations/mq-consumer-contract.md` 002 bod 3 („the only rail
+for biz and infra alike").
+
+Čtyři otázky § Removing something removes its declaration:
+(1) **vznik** — konektorová DLQ kolej z doby před brokerovou dead-letter politikou;
+(2) **koncept** — nesla ji tato třída, konfirmace 002 bod 3 ji nahradila;
+(3) **proč ji nikdo nečte** — ustoupila rozhodnutí, ne zapomnění: `routeToDLQ(` měl
+2026-09-15 nula volajících mimo tento balíček a `@onlineapps/conn-infra-error-handler`
+(měřeno přes `shared`, `infra`, `api_biz/*`, `fe_adminui`); wrapper volá jen
+`errorHandler.logError`, orchestrátor jen `classifyError`;
+(4) **náhrada je koncepčnější** — ano: broker odkládá, jeden emitor vydává jednu
+událost.
+
+Co odchází s ní, protože jinak by zbyla deklarace bez čtenáře:
+
+- export `DLQRouter` z `src/index.js` a pole `dlqRouter` na instanci `ErrorHandlerCore`;
+- větev `handleError()`, která na akci `dlq` routovala. **Klasifikace zůstává:**
+  `handleError()` dál vrací `{ action: 'dlq' }` — je to rozhodnutí předané volajícímu,
+  ne provedená akce, a nic v tomto balíčku už nepublikuje;
+- klíče `handling.dlqEnabled` a `handling.mqClient` konstruktoru `ErrorHandlerCore`,
+  a klíče `dlqNamePattern` a `emitMonitoringEvents`, které četl jen `DLQRouter`.
+  Oba je posílal `@onlineapps/service-wrapper` (`dlqEnabled` seznamem povolených
+  klíčů `errorHandling`, `mqClient` přiložením k objektu `handling`) — po této
+  změně je nic nečte, a wrapper je proto vyřadil na své straně: `dlqEnabled`
+  v d.493, `handling.mqClient` v d.502;
+- `assertQueuePattern()` z `src/configRanges.js` — `DLQRouter` byl jediný čtenář.
+  `describeValue` a `assertNumberInRange` zůstávají (čtou je `CircuitBreaker`
+  a `UnifiedLogSchema`).
+
+Migrace: volající, který se spoléhal na to, že ho jádro dostane do `.dlq`, nemá co
+měnit — zprávu odkládá konzumentská politika knihovny `@onlineapps/mq-client-core`.
+Volající, který konstruoval `DLQRouter` přímo, ho nemá čím nahradit v tomto balíčku.
+
 ## [2.0.1] — 2026-09-15
 
 ## [2.0.0] — 2026-09-14

package/README.md

@@ -1,5 +1,5 @@
 > Status: current
-> Owns: the platform's error handling itself — classification, retry, circuit breaker, DLQ routing and compensation
+> Owns: the platform's error handling itself — classification, retry, circuit breaker and compensation
 
 <!-- BEGIN GENERATED: library-uniform — regenerate: npx oa-sync-template readme-uniform --all -->
 Uniform: [library/connector](../connector/conn-orch-validator/manifests/library.manifest.json)
@@ -19,7 +19,6 @@ Core error handling functionality for OA Drive microservices. Used by both busin
 - **Error Classification** - Automatic error type detection (TRANSIENT, BUSINESS, FATAL, etc.)
 - **Retry Logic** - Exponential backoff for transient errors
 - **Circuit Breaker** - Protection against cascading failures
-- **DLQ Routing** - Dead letter queue routing for permanent errors
 - **Compensation** - Rollback operations for failed workflows
 - **Unified Logging** - Structured error logging via monitoring-core
 
@@ -54,8 +53,7 @@ const errorHandler = new ErrorHandlerCore({
     retryDelay: 1000,
     retryMultiplier: 2,
     circuitBreakerEnabled: true,
-    dlqEnabled: true,
-    mqClient: mqClient  // Optional, for DLQ routing
+    compensationEnabled: true
   }
 });
 ```
@@ -65,8 +63,8 @@ const errorHandler = new ErrorHandlerCore({
 `executeWithRetry()` loops three times, and a caller driving the loop itself from
 `handleError()`'s `result.shouldRetry` stops after the third as well. The other
 `handling` keys, their defaults and their accepted ranges belong to the component
-that reads each key (`RetryHandler`, `CircuitBreakerManager`, `DLQRouter`); a
-value outside its range is refused in the constructor.
+that reads each key (`RetryHandler`, `CircuitBreakerManager`); a value outside its
+range is refused in the constructor.
 
 ### Log Error
 
@@ -99,6 +97,10 @@ try {
   });
   
   // result.action: 'retry' | 'dlq' | 'throw' | 'continue' | 'compensate'
+  // `dlq` is a CLASSIFICATION handed back to the caller: this package publishes
+  // nothing. A message is dead-lettered by the consumer policy of
+  // `@onlineapps/mq-client-core` — one rail for biz and infra alike
+  // (docs/governance/confirmations/mq-consumer-contract.md 002 bod 3).
   if (result.action === 'retry') {
     await sleep(result.retryDelay);
     // Retry operation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/error-handler-core",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "Core error handling functionality for OA Drive microservices - classification, retry, circuit breaker, DLQ routing",
   "oa": {
     "category": "connector"

package/src/ErrorHandlerCore.js

@@ -1,13 +1,12 @@
 /**
  * Error Handler Core
- * Main class that orchestrates error handling, logging, retry, circuit breaker, DLQ routing
+ * Main class that orchestrates error handling, logging, retry, circuit breaker, compensation
  */
 
 const { ErrorClassifier, ErrorTypes } = require('./ErrorClassifier');
 const UnifiedLogSchema = require('./UnifiedLogSchema');
 const RetryHandler = require('./RetryHandler');
 const CircuitBreakerManager = require('./CircuitBreaker');
-const DLQRouter = require('./DLQRouter');
 const CompensationHandler = require('./CompensationHandler');
 const runtimeCfg = require('./config');
 const { assertNumberInRange } = require('./configRanges');
@@ -24,7 +23,7 @@ class ErrorHandlerCore {
    * @param {Object} config.monitoring - Monitoring instance (monitoring-core)
    * @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.
+   *   here — 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
@@ -38,8 +37,6 @@ class ErrorHandlerCore {
    * @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
    */
@@ -99,7 +96,7 @@ class ErrorHandlerCore {
     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
+    // CircuitBreakerManager); 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({
@@ -114,11 +111,6 @@ class ErrorHandlerCore {
       errorThreshold: handling.errorThreshold,
       resetTimeout: handling.resetTimeout
     });
-    this.dlqRouter = new DLQRouter({
-      dlqEnabled: handling.dlqEnabled !== false,
-      mqClient: handling.mqClient,
-      logger: this.logger
-    });
     this.compensation = new CompensationHandler({
       compensationEnabled: handling.compensationEnabled !== false
     });
@@ -228,16 +220,10 @@ class ErrorHandlerCore {
       maxRetries: this._resolveMaxRetries(context)
     };
     
-    // 5. Execute action
-    if (action.type === 'dlq' && this.dlqRouter.isAvailable()) {
-      await this.dlqRouter.routeToDLQ(
-        context.message || {},
-        error,
-        errorType,
-        context
-      );
-    }
-    
+    // 5. Execute action. `dlq` is a CLASSIFICATION returned to the caller, not
+    // a route taken here: a message is dead-lettered by the consumer policy of
+    // `@onlineapps/mq-client-core` — one rail for biz and infra alike
+    // (`docs/governance/confirmations/mq-consumer-contract.md` 002 bod 3).
     if (action.type === 'compensate' && this.compensation.enabled) {
       const compensationResult = await this.compensation.execute(
         operation,

package/src/configRanges.js

@@ -69,24 +69,4 @@ function assertNumberInRange(context, key, value, spec) {
   }
 }
 
-/**
- * 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 };
+module.exports = { describeValue, assertNumberInRange };

package/src/index.js

@@ -8,7 +8,6 @@ const { ErrorClassifier, ErrorTypes, ErrorCodes } = require('./ErrorClassifier')
 const UnifiedLogSchema = require('./UnifiedLogSchema');
 const RetryHandler = require('./RetryHandler');
 const CircuitBreakerManager = require('./CircuitBreaker');
-const DLQRouter = require('./DLQRouter');
 const CompensationHandler = require('./CompensationHandler');
 const CircuitOpenError = require('./CircuitOpenError');
 
@@ -21,7 +20,6 @@ module.exports = {
   UnifiedLogSchema,
   RetryHandler,
   CircuitBreakerManager,
-  DLQRouter,
   CompensationHandler,
 
   // Typed errors (branch on error.code, never on error.message)

package/src/DLQRouter.js

@@ -1,251 +0,0 @@
-/**
- * Dead Letter Queue Router
- * Routes failed messages to DLQ for manual inspection
- */
-
-const { assertLogger } = require('@onlineapps/logger-contract');
-const { assertNumberInRange, assertQueuePattern } = require('./configRanges');
-
-/**
- * Retries already made before the message was dead-lettered. Read in two places
- * (the DLQ message and the monitoring event), so the rule that reads it lives in
- * one (`.claude/rules/change-discipline.md` § One rail per concern).
- *
- * `??`, not `||`: `retryCount: 0` on the message is a measurement, and `||`
- * skipped it in favour of the context — which is not merely untidy, because
- * `_determineRoutingReason()` compares that number with `maxRetries` and would
- * file the message under a reason nobody produced.
- *
- * @param {Object} message - Original message
- * @param {Object} context - Additional context
- * @returns {number} Accepted retry count
- * @throws {Error} If the value present is not an integer >= 0
- */
-function resolveRetryCount(message, context) {
-  const retryCount = message.retryCount ?? context.retryCount ?? 0;
-  assertNumberInRange('DLQRouter', 'retryCount', retryCount, {
-    integer: true,
-    min: 0,
-    expected: 'an integer >= 0 (the number of retries already made)'
-  });
-  return retryCount;
-}
-
-class DLQRouter {
-  /**
-   * @param {Object} config - Configuration
-   * @param {Object} config.logger - Logger with info/warn/error/debug (required)
-   * @param {boolean} [config.dlqEnabled=true] - Enable DLQ routing
-   * @param {Object} [config.mqClient] - MQ client used to publish to the DLQ
-   * @param {string} [config.dlqNamePattern='{queue}.dlq'] - DLQ naming pattern;
-   *   a non-empty string containing the `{queue}` placeholder
-   * @param {boolean} [config.emitMonitoringEvents=true] - Emit message_dlq events
-   * @throws {Error} If dlqNamePattern cannot name a per-origin queue
-   */
-  constructor(config = {}) {
-    // `dlqNamePattern` and `mqClient` carry their documented defaults as
-    // destructuring defaults, declared here once: a default stands in for a
-    // MISSING key, it never overrules what the caller passed
-    // (`.claude/rules/architecture-principles.md` §3). `logger` is read from
-    // `config` below because assertLogger owns its (absent) default: it throws.
-    const { mqClient = null, dlqNamePattern = '{queue}.dlq' } = config;
-    assertQueuePattern('DLQRouter', 'dlqNamePattern', dlqNamePattern);
-
-    this.enabled = config.dlqEnabled !== false;
-    this.mqClient = mqClient;
-    this.dlqNamePattern = dlqNamePattern;
-    this.emitMonitoringEvents = config.emitMonitoringEvents !== false;
-    // Both failure paths below deliberately swallow their error so that DLQ
-    // routing never breaks error handling; the logger is what keeps them visible.
-    this.logger = assertLogger(
-      'DLQRouter',
-      config.logger,
-      'a DLQ routing failure this router deliberately swallows still reaches the structured log'
-    );
-  }
-  
-  /**
-   * Route message to DLQ
-   * 
-   * @param {Object} message - Original message
-   * @param {string} [message.queue] - Queue the message came from; required
-   *   unless `context.queue` carries it
-   * @param {Error} error - Error that occurred
-   * @param {string} errorType - Classified error type
-   * @param {Object} context - Additional context
-   * @param {string} [context.queue] - Queue of origin, when the message body
-   *   does not carry it
-   * @returns {Promise<void>}
-   * @throws {Error} If neither the message nor the context names the queue
-   */
-  async routeToDLQ(message, error, errorType, context = {}) {
-    if (!this.enabled || !this.mqClient) {
-      return; // DLQ disabled or no MQ client
-    }
-
-    // The queue of origin is the only thing a dead message can be found by, so a
-    // missing one is refused here — before anything is published — rather than
-    // renamed. `… || 'unknown'` used to file every such message in `unknown.dlq`,
-    // a queue nobody is looking in, and said nothing about it. Owner's rule:
-    // no invented value (`api/docs/governance/confirmations/dlq-purge.md` 002).
-    const originalQueue = message.queue ?? context.queue;
-    if (typeof originalQueue !== 'string' || originalQueue.trim() === '') {
-      throw new Error(
-        '[DLQRouter] Missing required field - "queue" must be a non-empty string naming the queue the '
-        + 'message came from; a dead message is found by nothing else. '
-        + 'Fix: pass message.queue, or context.queue when the body does not carry it.'
-      );
-    }
-    const retryCount = resolveRetryCount(message, context);
-    const dlqName = this._generateDLQName(originalQueue);
-    
-    const dlqMessage = {
-      // Original message
-      ...message,
-      
-      // Error details
-      error: {
-        message: error.message,
-        stack: error.stack,
-        // `??`: a code that is present but falsy is a value; `null` is reserved
-        // for the absence of one.
-        code: error.code ?? null,
-        type: errorType,
-        timestamp: new Date().toISOString()
-      },
-      
-      // Routing metadata
-      originalQueue: originalQueue,
-      retryCount,
-      routedAt: new Date().toISOString(),
-      routingReason: this._determineRoutingReason(errorType, context, retryCount)
-    };
-    
-    try {
-      await this.mqClient.publish(dlqName, dlqMessage, {
-        persistent: true
-      });
-      
-      // Emit message_dlq monitoring event
-      if (this.emitMonitoringEvents) {
-        await this._emitDLQEvent(message, dlqName, originalQueue, error, errorType, context, retryCount);
-      }
-    } catch (dlqError) {
-      // If DLQ routing fails, log but don't throw
-      // (we don't want DLQ failures to break error handling)
-      this.logger.error('[DLQRouter] DLQ routing failed', {
-        dlqName,
-        originalQueue,
-        errorType,
-        reason: dlqError.message
-      });
-    }
-  }
-  
-  /**
-   * Emit message_dlq event to monitoring
-   *
-   * @param {number} retryCount - Already resolved and checked by the caller, so
-   *   both records of one dead message state the same number
-   * @private
-   */
-  async _emitDLQEvent(message, dlqName, originalQueue, error, errorType, context, retryCount) {
-    if (!this.mqClient) return;
-
-    // Resolved before the try so the catch below can name the workflow it failed on.
-    //
-    // `null`, not `'unknown'`: a dead-lettered message need not belong to a
-    // workflow, but an absent id is never renamed into one. The consumer of
-    // `monitoring.workflow` takes any non-empty string as a real id
-    // (`infra/api_monitoring/src/consumer/apiflow-extension.js`, readReported +
-    // the MISSING_WORKFLOW_ID gate), so `'unknown'` wrote `workflow_traces` rows
-    // claiming a workflow by that name; `null` is the absence the message
-    // actually states, and that gate counts it as faulty telemetry instead.
-    // Owner: `api/docs/governance/confirmations/dlq-purge.md` 002.
-    const workflowId = message.workflow_id ?? context.workflow_id ?? null;
-
-    try {
-      await this.mqClient.publish('monitoring.workflow', {
-        event_type: 'message_dlq',
-        workflow_id: workflowId,
-        service_name: 'dlq-router',
-        step_id: 'dlq-entry',
-        timestamp: new Date().toISOString(),
-        context: {
-          _dlq: {
-            queue: dlqName,
-            originalQueue: originalQueue,
-            reason: error.message,
-            errorType: errorType,
-            retryCount,
-            routedAt: new Date().toISOString()
-          }
-        },
-        metadata: {
-          dlq_queue: dlqName,
-          original_queue: originalQueue,
-          error_type: errorType
-        }
-      }, { persistent: true });
-      
-      // One per dead-lettered message: a trace of the side effect, not an event
-      // of its own — the published message_dlq event is the record.
-      this.logger.debug('[DLQRouter] message_dlq event emitted', { workflowId, dlqName });
-    } catch (emitError) {
-      // Silent fail - don't break DLQ routing
-      this.logger.warn('[DLQRouter] monitoring event emit failed', {
-        workflowId,
-        dlqName,
-        reason: emitError.message
-      });
-    }
-  }
-  
-  /**
-   * Generate DLQ name from original queue name. The constructor has already
-   * refused a pattern without `{queue}`, so there is no second branch here: the
-   * one this method used to carry returned a pattern-shaped name for every
-   * origin, which is the collapse the check now prevents.
-   * @private
-   */
-  _generateDLQName(originalQueue) {
-    return this.dlqNamePattern.replace('{queue}', originalQueue);
-  }
-  
-  /**
-   * Determine routing reason.
-   *
-   * Takes the SAME resolved `retryCount` the message records. It used to read
-   * `context.retryCount` on its own, so when the number came on the message the
-   * two disagreed: the entry said three retries and the reason said the budget
-   * had nothing to do with it.
-   *
-   * @param {string} errorType - Classified error type
-   * @param {Object} context - Additional context
-   * @param {number} retryCount - Resolved by `resolveRetryCount()`
-   * @returns {string} Routing reason
-   * @private
-   */
-  _determineRoutingReason(errorType, context, retryCount) {
-    if (retryCount >= context.maxRetries) {
-      return 'max_retries_exceeded';
-    }
-    
-    if (['BUSINESS', 'VALIDATION'].includes(errorType)) {
-      return 'permanent_error';
-    }
-    
-    return 'error_handling_decision';
-  }
-  
-  /**
-   * Check if DLQ routing is available
-   * @returns {boolean} True if DLQ is enabled and MQ client available
-   */
-  isAvailable() {
-    return this.enabled && this.mqClient !== null;
-  }
-}
-
-module.exports = DLQRouter;
-