@onlineapps/mq-client-core 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [3.2.0] — 2026-09-15
+
+### Added — dead-letter cesty pro rodiny `monitoring.*` a `telemetry.*` (d.475)
+
+Sedm front, které konzumenti monitoringu čtou — `monitoring.workflow`,
+`monitoring.services`, `monitoring.audit`,
+`monitoring.infrastructure.health.events`, `telemetry.logs.queue`,
+`telemetry.metrics.queue`, `telemetry.traces.queue` — dostalo
+`x-dead-letter-exchange: ''` a `x-dead-letter-routing-key: '<prefix>.dlq'`, a obě
+rodiny svou koncovou frontu: `monitoring.dlq` a `telemetry.dlq`, deklarované
+stejným tvarem jako `workflow.dlq` a `delivery.dlq` (durable, `x-max-length`
+50000, žádné TTL, žádná další cesta). TTL ani strop žádné existující fronty se
+nemění.
+
+Je to mechanické pravidlo konfirmace `mq-consumer-contract` 003 bod 1 použité
+podruhé, přesně jak bod 3 předepsal („`monitoring.*`, `telemetry.*` … dostanou
+`<prefix>.dlq`, až jejich konzumenti přejdou na politiku knihovny") — nová
+konfirmace k tomu nepatří. Do té doby brána d.259 ty konzumenty vůbec nepustila:
+`consume()` odmítá frontu, jejíž deklarace neříká, kam s odmítnutou zprávou.
+
+Ostatní rodiny téže věty — `registry.*`, `validation.*`, `infrastructure.*` —
+cestu **nedostávají**: jejich konzumenti pořád potvrzují na vlastních surových
+kanálech (`infra/api_services_registry/src/listeners/registry.listener.js`,
+`infra/api_services_{registry,validator}/src/services/mqManager.js` — DL-007),
+a `.dlq`, do které nikdo nezapisuje, je fronta bez pisatele.
+
+Fronty zakládá `initInfrastructureQueues()` z deklarace samotné (prochází
+`infrastructurePrefixes()` a klíče sekcí), takže obě nové vzniknou při nejbližším
+bootu jejího jediného volajícího, `infra/api_gateway`. Běžící `monitoring.*`
+a `telemetry.*` fronty nesou staré argumenty, takže je podle konfirmace 003 bodu
+4 čeká smazání a znovuzaložení ve vlně; do té doby je `assertQueue` nad nimi
+s novou deklarací 406.
+
 ## [3.1.0] — 2026-09-15
 
 ### Added — `topology` nese i tři telemetrické fronty (d.461)

package/README.md

@@ -218,7 +218,8 @@ carries `{ queue, messageCount, consumerCount }` and no arguments (measured, 202
 
 **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
+`workflow.dlq`, `delivery.dlq`, `monitoring.dlq`, `telemetry.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)`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "oa": {
     "category": "connector"
@@ -23,7 +23,7 @@
   "author": "OnlineApps",
   "license": "MIT",
   "dependencies": {
-    "@onlineapps/logger-contract": "1.3.0",
+    "@onlineapps/logger-contract": "2.0.0",
     "@onlineapps/runtime-config": "1.2.0",
     "ajv": "^8.12.0",
     "amqplib": "^0.10.3"

package/src/config/queueConfig.js

@@ -613,6 +613,15 @@ module.exports = {
    * 
    * CRITICAL: Monitoring is an infrastructure service, monitoring queues are infrastructure queues!
    * All services (both infrastructure and business) publish monitoring events here.
+   *
+   * Every QUEUE of this family dead-letters to `monitoring.dlq` over the DEFAULT
+   * exchange, where the routing key IS the destination queue's name — the mechanical
+   * rule of confirmation `mq-consumer-contract` 003 point 1, applied here by point 3
+   * ("`monitoring.*` … get `<prefix>.dlq` when their consumers move onto the library
+   * policy"). The exchanges declared alongside them carry no arguments and therefore
+   * no route: an exchange holds nothing to dead-letter.
+   *
+   * @see api/docs/governance/confirmations/mq-consumer-contract.md 003
    */
   monitoring: {
     /**
@@ -627,7 +636,9 @@ module.exports = {
       durable: true,
       arguments: {
         'x-message-ttl': 300000,      // 5 minutes TTL
-        'x-max-length': 10000
+        'x-max-length': 10000,
+        'x-dead-letter-exchange': '',        // Default exchange: routing key IS the queue name
+        'x-dead-letter-routing-key': 'monitoring.dlq'
       }
     },
 
@@ -644,7 +655,9 @@ module.exports = {
       durable: true,
       arguments: {
         'x-message-ttl': 600000,      // 10 minutes TTL (longer for service tracking)
-        'x-max-length': 20000
+        'x-max-length': 20000,
+        'x-dead-letter-exchange': '',
+        'x-dead-letter-routing-key': 'monitoring.dlq'
       }
     },
 
@@ -657,7 +670,9 @@ module.exports = {
       durable: true,
       arguments: {
         'x-message-ttl': 300000,
-        'x-max-length': 50000
+        'x-max-length': 50000,
+        'x-dead-letter-exchange': '',
+        'x-dead-letter-routing-key': 'monitoring.dlq'
       }
     },
 
@@ -674,11 +689,39 @@ module.exports = {
     /**
      * monitoring.infrastructure.health.events - the monitoring consumer's own copy of
      * the infrastructure health events, bound to the infrastructure.health.events
-     * fanout exchange. Declared with `durable` and nothing else, exactly as the
-     * consumer creates it.
+     * fanout exchange.
+     *
+     * It carried `durable` and nothing else — the arguments the consumer asserts it
+     * with (`infra/api_monitoring/src/consumer/index.js`, `assertQueue(queue,
+     * { durable: true })`). It keeps no TTL and no cap, because nothing decided it
+     * should have either; what it gains is the family's dead-letter route, without
+     * which `consume()` refuses to attach a consumer to it at all (d.259).
      */
     'infrastructure.health.events': {
-      durable: true
+      durable: true,
+      arguments: {
+        'x-dead-letter-exchange': '',
+        'x-dead-letter-routing-key': 'monitoring.dlq'
+      }
+    },
+
+    /**
+     * monitoring.dlq - Dead letter queue of the whole monitoring family
+     *
+     * The end of this family's chain: the workflow, services and audit queues and the
+     * consumer's health-events copy all reject into it over the default exchange, so
+     * no binding has to exist for the route to work. Declared with the arguments every
+     * other dead-letter queue carries — durable, capped at the same 50k, no TTL and no
+     * onward route — because the operator's dashboard matches `*.dlq` and a message
+     * that expired there is a message nobody got to decide about (confirmation
+     * `mq-consumer-contract` 002 point 2, 003 point 1).
+     */
+    dlq: {
+      durable: true,
+      arguments: {
+        // No TTL for DLQ - messages should persist
+        'x-max-length': 50000         // Higher limit for DLQ
+      }
     }
   },
 
@@ -690,8 +733,15 @@ module.exports = {
    * own name, and these three queues are bound to it
    * (`docs/standards/monitoring-queues.md`, `docs/architecture/monitoring.md`).
    *
-   * The values are the ones the queues are created with today; this config is their
-   * declaration, so whoever asserts them reads it here rather than retyping it.
+   * The TTL and the cap are the ones the queues are created with today; this config is
+   * their declaration, so whoever asserts them reads it here rather than retyping it.
+   *
+   * Each of the three dead-letters to `telemetry.dlq` over the DEFAULT exchange, where
+   * the routing key IS the destination queue's name — the mechanical rule of
+   * confirmation `mq-consumer-contract` 003 point 1, applied to this family by point 3
+   * as its consumer moves onto the library policy.
+   *
+   * @see api/docs/governance/confirmations/mq-consumer-contract.md 003
    */
   telemetry: {
     /** telemetry.logs.queue - OpenTelemetry log records, drained into Loki. */
@@ -699,7 +749,9 @@ module.exports = {
       durable: true,
       arguments: {
         'x-message-ttl': 60000,       // 1 minute TTL for unprocessed messages
-        'x-max-length': 100000        // Max 100k messages in queue
+        'x-max-length': 100000,       // Max 100k messages in queue
+        'x-dead-letter-exchange': '',        // Default exchange: routing key IS the queue name
+        'x-dead-letter-routing-key': 'telemetry.dlq'
       }
     },
 
@@ -708,7 +760,9 @@ module.exports = {
       durable: true,
       arguments: {
         'x-message-ttl': 60000,
-        'x-max-length': 100000
+        'x-max-length': 100000,
+        'x-dead-letter-exchange': '',
+        'x-dead-letter-routing-key': 'telemetry.dlq'
       }
     },
 
@@ -717,7 +771,25 @@ module.exports = {
       durable: true,
       arguments: {
         'x-message-ttl': 60000,
-        'x-max-length': 100000
+        'x-max-length': 100000,
+        'x-dead-letter-exchange': '',
+        'x-dead-letter-routing-key': 'telemetry.dlq'
+      }
+    },
+
+    /**
+     * telemetry.dlq - Dead letter queue of the whole telemetry family
+     *
+     * The three intake queues reject into it, and it rejects nowhere: same shape as
+     * `workflow.dlq`, `delivery.dlq` and `monitoring.dlq` — durable, capped at 50k, no
+     * TTL, no onward route. A telemetry record the intake cannot process is the one an
+     * operator most needs to look at, and a TTL here would delete it before they did.
+     */
+    dlq: {
+      durable: true,
+      arguments: {
+        // No TTL for DLQ - messages should persist
+        'x-max-length': 50000         // Higher limit for DLQ
       }
     }
   },