@onlineapps/mq-client-core 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [3.0.1] — 2026-09-14
+
+- **Fixed: `consume()` accepts a TERMINAL queue — one this configuration dead-letters TO — instead of demanding a dead-letter route it must not have.** The d.259 gate refuses a queue for which `queueConfig` declares no `x-dead-letter-exchange`/`-routing-key`, because the policy ends a spent message with `nack(requeue=false)` and the broker drops what it cannot move. True of every working queue — and false of the queues that RECEIVE those moves: `workflow.failed` is named in `x-dead-letter-routing-key` by `workflow.init` and `workflow.control`, `<service>.dlq` by every business template, `workflow.dlq` and `delivery.dlq` by their own families, and the confirmed topology leaves exactly those without a route of their own (`api/docs/governance/confirmations/mq-consumer-contract.md` 002 point 2, 003 point 2 — "workflow.failed and workflow.dlq themselves keep no route"). A dead-letter route on a dead-letter queue is a loop or a chain with no end. So `workflow.failed` — the operator's queue, read by the delivery dispatcher — was unconsumable: `[BaseClient] Cannot consume from queue "workflow.failed": queueConfig declares no dead-letter route`. The gate now asks a second question, `queueConfig.isDeadLetterTarget(queue)`, **derived from the templates** (the set of every declared `x-dead-letter-routing-key`, `{service}` placeholder read through the same `templateShape()` the business templates use) rather than from a list of names that would have to be edited in step with them — the defect d.278 removed from `matchBusinessTemplate()`. The `.dlq` family needs no rule of its own: every `.dlq` this configuration declares is already the target of a declared routing key (measured 2026-09-14). Every other queue with no route is refused exactly as before, with the same sentence. A message that spends its budget on a terminal queue is rejected the same way and then DROPPED by the broker — the end of the chain is the end — never requeued for ever, and the loss is now logged at error level (`Message discarded on terminal queue "<queue>"`, with the queue, the attempts and the error) before the `message_dlq` event is published. Tests: new unit `consume-terminal-queue.test.js` (10 — the derivation from the declared keys, the terminal names and the non-terminal control, `consume('workflow.failed')` and `consume('<svc>.dlq')` attaching, the three refusals that must not change with the refusal verbatim, the discard with its log line and meta, and a routed queue as the control that says nothing about a discard); integration `dead-letter-route-required.integration.test.js` (+2 against the live broker: a message rejected from `<svc>.queue` reaches `<svc>.dlq` and is DELIVERED to a consumer there with `x-death[0].reason = 'rejected'`, and a handler failing on that terminal queue leaves the queue empty with no second delivery after 2 s — the drop no mock can measure). Three tests that encoded the old rule follow the new one: the `<svc>.dlq` refusal leg of `consume-dead-letter-route-required.test.js` (its subject moved to the new file), and the two integration control queues that used a dead-letter queue as "the queue with no route" (`delivery-events-lookup` → `monitoring.workflow`, `queue-declaration-options-one-rail` → `<svc>.events`).
+
+## [3.0.0] — 2026-09-14
+
 - **Changed (BREAKING for a reader of the log, not for a caller): the credential redaction removes the WHOLE userinfo, not just the password.** `utils/redactCredentials.js` masked the password (`amqp://oa_dev:***@queuer:5672`) and kept the account name, while the platform's two other redactors — `shared/service-common/src/redactUrl.js` (d.245/d.245b) and `shared/connector/conn-orch-registry/src/redactUrl.js` (d.446, whose header says plainly that it stayed local because this package masked the password only) — drop the userinfo entirely. One concern, two semantics, which is two rails (`.claude/rules/change-discipline.md` § One rail per concern). The platform one wins: `amqp://queuer:5672/vhost?heartbeat=30`, the account name gone with the password, because a name is the other half of the same credential and a log line needs neither. A value that is not a parseable URL is answered with `<unparseable-url>` instead of being echoed — previously a non-URL string came back verbatim (`api_services_queuer`) or with a `***@` prefix, and an unparseable value is exactly the case where nobody can say whether it holds a credential. `redactConnectionTarget()` still THROWS on a non-string: it guards a declared config key, where a wrong type is a boot-time defect. Tests: unit `redact-credentials.test.js` (rewritten to the new semantics, +6 over the package: the userinfo cases, the transport's `?heartbeat` query as a control, the placeholder cases and the export identity), `connect-credentials-not-logged.test.js` and `one-owner-a-floor-down.test.js` (both now assert the account name is absent too), integration `credential-redaction.integration.test.js` (+2: the LIVE broker accepts the real credential while no logger argument carries either half of it, and a real 403 refusal leaks nothing into the error, the stack or the log) (d.448).
 - **Added:** `redactUrl` and `UNPARSEABLE_PLACEHOLDER` are exports of `src/index.js`. The dependants that render an AMQP URL into a log line or an error message (`conn-orch-registry`, `conn-infra-mq`) each carry a local copy of the same function; a copy can only be replaced by an import if the package declares one (d.448).
 - **Fixed:** a reconnect wait ends only on an error that carries NO publish classification. d.435 taught `_waitForReconnection()` to skip a RETRYABLE publish failure, which left the same defect standing one class of error further out: a `PermanentPublishError` or a `QueueNotFoundError` from a concurrent publish still rejected every waiter, although "no retry will help this message" says nothing about whether the link is coming back. The condition is now the PRESENCE of the classification, not its verdict — `utils/publishErrors.js` sets `retryable` on every error it produces, so an error that never went through that rail carries none, and that absence is the whole test (plus the transport's own typed close, which never ended the wait). No second list of codes. Tests: unit `wait-for-reconnection-not-ended-by-a-foreign-publish.test.js` (+4, both permanent classifications built by the real rail, controls for an unclassified error and for the typed close), integration `…integration.test.js` (+1: the live broker refuses a publish to a name no declaration owns with a real 404, and that real `QueueNotFoundError` is put on the channel during a real outage — a permanent classification cannot arise while the link is down, where everything classifies transient) (d.435b).

package/README.md

@@ -216,6 +216,24 @@ broker cannot be asked, because `checkQueue()` answers with `queue.declare-ok`,
 carries `{ queue, messageCount, consumerCount }` and no arguments (measured, 2026-09-12).
 `queueConfig.getDeadLetterRoute(queue)` is the exported form of the same answer.
 
+**A TERMINAL queue is consumed, and it is not an exception to that rule but its other
+half.** A queue something else dead-letters TO — `<service>.dlq`, `workflow.failed`,
+`workflow.dlq`, `delivery.dlq` — declares no onward route because the topology says it
+must not have one: a dead-letter route on a dead-letter queue closes a loop or starts a
+chain with no end (`api/docs/governance/confirmations/mq-consumer-contract.md` 002
+point 2, 003 point 2). So the gate asks a second question, `queueConfig.isDeadLetterTarget(queue)`,
+derived from the templates themselves — the set of every `x-dead-letter-routing-key` they
+declare, `{service}` placeholder and all — never from a list of names. Every OTHER queue
+with no route is refused exactly as before, with the same sentence.
+
+What a terminal queue does NOT get is a different delivery policy: the budget is counted
+the same way, and a message that spends it is rejected with `nack(requeue=false)` the same
+way. The difference is what the broker then does with it — there is nowhere to move it to,
+so it is **dropped**. That loss is deliberate (the alternative is the endless requeue this
+policy exists to end) and it is never silent: the client logs it at error level, naming
+the queue, the attempts and the error, and the `message_dlq` event is published as for any
+other rejection.
+
 ```javascript
 await client.consume(queue, async (msg, delivery) => {
   // delivery = { attempt, maxAttempts, isFinalAttempt }
@@ -527,12 +545,18 @@ const { queueConfig } = require('@onlineapps/mq-client-core');
 queueConfig.isInfrastructureQueue('workflow.init'); // true
 queueConfig.isBusinessQueue('emailer.workflow');    // true
 queueConfig.getInfrastructureQueueConfig('workflow.init'); // { durable, arguments }
+queueConfig.getDeadLetterRoute('workflow.init');    // { exchange: '', routingKey: 'workflow.failed' }
+queueConfig.isDeadLetterTarget('workflow.failed');  // true — the end of that chain
 ```
 
 - `workflow.failed` carries no `x-message-ttl`. It is read by an operator, not by a
   service, and it has no dead-letter exchange, so a TTL there does not move a message
   anywhere — it deletes it. See
   `api/docs/governance/confirmations/mq-consumer-contract.md` 002.
+- `isDeadLetterTarget()` answers "does this configuration dead-letter TO this name",
+  derived from the declared routing keys rather than from a list. It is what lets
+  `consume()` attach to `workflow.failed` and to any `<service>.dlq` while every other
+  queue with no declared route stays refused — see § `consume()` — the delivery contract.
 
 **That require is the contract.** Reaching into
 `@onlineapps/mq-client-core/src/config/queueConfig` is an internal path the package

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "oa": {
     "category": "connector"

package/src/BaseClient.js

@@ -502,6 +502,14 @@ class BaseClient {
    * `message_dlq` event would report a destination nothing routed to. The fix is
    * always to declare the route, never to consume without one.
    *
+   * The one queue that demand cannot be made of is the END of a chain — a queue
+   * this configuration dead-letters TO (`<service>.dlq`, `workflow.failed`). The
+   * topology withholds its route deliberately, so the gate reads a second,
+   * derived answer (`queueConfig.isDeadLetterTarget()`) and lets its consumer
+   * attach (d.452). A message that spends its budget there is rejected as
+   * anywhere else and then dropped by the broker, with an error line naming the
+   * loss — never an endless requeue. README § `consume()` — the delivery contract.
+   *
    * @param {string} queue - Name of the queue to consume from.
    * @param {function(Object, {attempt: number, maxAttempts: number, isFinalAttempt: boolean}): Promise<void>} messageHandler -
    *   Async function to process each message. Its second argument says which

package/src/config/queueConfig.js

@@ -100,6 +100,10 @@ const TEMPLATE_PLACEHOLDER = /^\{[^.{}]+\}$/;
  * service name, with `null` where the template accepts anything (`registry.events`
  * -> `['registry', 'events']`; a key writing `registry.{kind}` would give
  * `['registry', null]`).
+ *
+ * A declared dead-letter routing key is written in the same notation
+ * (`{service}.dlq`), so `isDeadLetterTarget()` reads it through this one function
+ * rather than through a second placeholder rule.
  */
 const templateShape = (template) =>
   template.split('.').map((part) => (TEMPLATE_PLACEHOLDER.test(part) ? null : part));
@@ -169,6 +173,41 @@ const declaredInfrastructureNames = (config) => {
   return names;
 };
 
+/**
+ * Every name this configuration dead-letters TO — the END of a chain.
+ *
+ * Derived from the declarations themselves: the value of every
+ * `x-dead-letter-routing-key` any section writes, placeholders and all
+ * (`{service}.dlq`, `workflow.failed`, `workflow.dlq`, `delivery.dlq`). A list of
+ * names typed here would have to be edited in step with the templates and could
+ * therefore disagree with them — the defect d.278 removed from
+ * `matchBusinessTemplate()`, and the reason `declaredInfrastructureNames()` above
+ * derives its set the same way.
+ *
+ * The `.dlq` family needs no rule of its own: every `.dlq` this configuration
+ * declares — `workflow.dlq`, `delivery.dlq`, `{service}.dlq` — is already the
+ * target of a declared routing key (measured 2026-09-14), so the set covers it.
+ * A `.dlq` nothing routes to would be a queue with no writer, which is a defect
+ * in the declaration, not a case to paper over here.
+ *
+ * @param {Object} config - The queueConfig object (its sections are read from `this`).
+ * @returns {Set<string>} The routing keys, e.g. `workflow.failed`, `{service}.dlq`.
+ */
+const declaredDeadLetterTargets = (config) => {
+  const targets = new Set();
+
+  for (const section of Object.values(config)) {
+    if (section === null || typeof section !== 'object') continue;
+    for (const entry of Object.values(section)) {
+      if (entry === null || typeof entry !== 'object') continue;
+      const routingKey = entry.arguments && entry.arguments['x-dead-letter-routing-key'];
+      if (typeof routingKey === 'string' && routingKey !== '') targets.add(routingKey);
+    }
+  }
+
+  return targets;
+};
+
 /**
  * The two ways out of "this configuration declares no such queue", named in the
  * refusal itself.
@@ -1222,6 +1261,51 @@ module.exports = {
     return { exchange, routingKey };
   },
 
+  /**
+   * Is this queue the END of a dead-letter chain — a queue something
+   * dead-letters TO?
+   *
+   * The counterpart of `getDeadLetterRoute()`, and the reason a queue may have no
+   * route without that being a defect. `workflow.failed` is named in
+   * `x-dead-letter-routing-key` by `workflow.init` and `workflow.control`;
+   * `{service}.dlq` by every business template; `workflow.dlq` and `delivery.dlq`
+   * by their own families. Giving such a queue a route of its own would either
+   * close a loop or start an endless chain, which is why the confirmed topology
+   * leaves them without one (`docs/governance/confirmations/mq-consumer-contract.md`
+   * 002 point 2, 003 point 2 — "workflow.failed and workflow.dlq themselves keep
+   * no route").
+   *
+   * The consumer's dead-letter gate reads this second question, so a terminal
+   * queue is consumable while every OTHER queue with no declared route stays
+   * refused (`transports/rabbitmqClient.js`, d.452). What happens to a message
+   * that fails there is unchanged and stated in the README: the budget is spent,
+   * `nack(requeue=false)` is issued, the broker DROPS the message — the end of the
+   * chain is the end — and the loss is logged as an error rather than turned into
+   * an endless requeue.
+   *
+   * Derived from the templates (`declaredDeadLetterTargets()`), never from a list
+   * of names: a `{placeholder}` segment matches any one part, exactly as a
+   * business template key does.
+   *
+   * @param {string} queueName - Full queue name.
+   * @returns {boolean} True if this configuration dead-letters to this name.
+   */
+  isDeadLetterTarget(queueName) {
+    if (typeof queueName !== 'string' || queueName === '') return false;
+
+    const parts = queueName.split('.');
+
+    for (const target of declaredDeadLetterTargets(this)) {
+      const shape = templateShape(target);
+      if (shape.length !== parts.length) continue;
+      if (shape.every((part, index) => (part === null ? parts[index] !== '' : part === parts[index]))) {
+        return true;
+      }
+    }
+
+    return false;
+  },
+
   /**
    * Get infrastructure queue configuration by queue name (auto-detect type)
    *

package/src/transports/rabbitmqClient.js

@@ -3073,7 +3073,26 @@ class RabbitMQClient extends EventEmitter {
     // arguments (measured, 2026-09-12 — see queueConfig.getDeadLetterRoute()).
     // The caller's own `queueOptions` do not count either; a route supplied at
     // the call site would be a second declaration of one queue's topology.
-    if (queueConfig.getDeadLetterRoute(queue) === null) {
+    //
+    // The ONE queue this demand cannot be made of is the one at the END of a
+    // chain: a queue something else dead-letters TO. `workflow.failed` is named
+    // in `x-dead-letter-routing-key` by `workflow.init` and `workflow.control`,
+    // `<service>.dlq` by every business template — and the confirmed topology
+    // leaves exactly those without a route of their own, because a dead-letter
+    // route on a dead-letter queue is a loop or a chain with no end
+    // (`mq-consumer-contract` 002 point 2, 003 point 2). Until d.452 the gate
+    // asked only the first question, so the operator's own queue was
+    // unconsumable and its reader — the delivery dispatcher — could not attach
+    // at all. The second question is derived from the templates
+    // (`queueConfig.isDeadLetterTarget()`), never from a list of names, so it
+    // cannot fall behind them; every other queue with no route is refused
+    // exactly as before, with the same sentence.
+    //
+    // A message that spends its budget on a terminal queue is REJECTED as
+    // anywhere else and then dropped by the broker, which is the end of the
+    // chain doing its job. It is never requeued for ever, and the loss is said
+    // out loud in `_rejectDelivery()`.
+    if (queueConfig.getDeadLetterRoute(queue) === null && !queueConfig.isDeadLetterTarget(queue)) {
       throw new ConsumeError(
         `[RabbitMQClient] consume(${queue}): the dead-letter policy needs a dead-letter route and `
           + 'queueConfig declares none for this queue - '
@@ -4136,13 +4155,21 @@ class RabbitMQClient extends EventEmitter {
    * `status`.
    *
    * The `onDeadLetter` hook — and therefore the `message_dlq` event it publishes —
-   * is only ever reached for a message that CAN be dead-lettered: `consume()`
-   * refuses to register a consumer on a queue for which `queueConfig` declares no
+   * is reached for a message that CAN be dead-lettered: `consume()` refuses to
+   * register a consumer on a queue for which `queueConfig` declares no
    * `x-dead-letter-exchange`/`-routing-key` (d.259), so by the time a delivery
    * arrives here the route exists by declaration. Without that gate the same
    * `nack(requeue=false)` made the broker DROP the message while this event
    * announced it had reached `.dlq` — a report of a destination nothing routed to.
    *
+   * ONE class of queue reaches this method with no route, and it is not that
+   * defect: the END of a chain, a queue something else dead-letters TO
+   * (`<service>.dlq`, `workflow.failed`), whose consumer the gate admits on
+   * purpose (d.452). There the rejection does not move the message anywhere — the
+   * broker drops it, because the end of the chain is the end — so the loss is
+   * logged at error level below before monitoring is told. What is NOT done is
+   * inventing a requeue for it: that is the unbounded loop d.198b ended.
+   *
    * @param {Object} args
    * @private
    */
@@ -4178,6 +4205,29 @@ class RabbitMQClient extends EventEmitter {
       return;
     }
 
+    // A TERMINAL queue — one this configuration dead-letters TO — declares no
+    // onward route by design, so the rejection just issued does not MOVE the
+    // message: the broker drops it. That is the end of the chain working as
+    // intended, and the alternative would be the unbounded requeue d.198b ended.
+    // It is still a message the platform has lost, so it is said out loud, at
+    // error level, exactly once, before monitoring is told (d.452).
+    if (queueConfig.getDeadLetterRoute(queue) === null) {
+      this._logger.error(
+        `[RabbitMQClient] [mq-client-core] [CONSUMER] Message discarded on terminal queue "${queue}" - `
+          + 'Expected: a terminal queue is the end of the dead-letter chain, so it declares no onward '
+          + 'route and the broker DROPS what nack(requeue=false) rejects instead of moving it. '
+          + 'Fix: nothing to declare — the delivery budget is spent and the message is deliberately gone '
+          + 'rather than circling for ever; read the error and fix what made the handler fail.',
+        {
+          queue,
+          attempts,
+          maxAttempts,
+          classification,
+          error: error && error.message ? error.message : null
+        }
+      );
+    }
+
     if (onDeadLetter === undefined) {
       // Driving this transport directly is allowed (it is an export of this
       // package), but then nothing owns the monitoring rail, and a message