@onlineapps/mq-client-core 2.0.1 → 3.0.0

package/src/config.js

@@ -21,6 +21,35 @@ const runtimeCfg = createRuntimeConfig({
     // Client behavior
     heartbeat: { env: 'RABBITMQ_HEARTBEAT', defaultKey: 'heartbeatSeconds', type: 'number' },
     serviceName: { env: 'SERVICE_NAME', defaultKey: 'serviceName' },
+
+    // Connection-level recovery budget. Resolved here (explicit → env →
+    // module default) instead of an inline `|| 10` in the transport, so the
+    // value has one owner and one documented override path.
+    maxReconnectAttempts: {
+      env: 'RABBITMQ_MAX_RECONNECT_ATTEMPTS',
+      defaultKey: 'maxReconnectAttempts',
+      type: 'number',
+    },
+
+    // How many of those budgets the client spends before it declares the
+    // connection permanently lost. Same class, same three legs, same reason —
+    // one owner and one documented override path (`./defaults.js`).
+    maxReconnectCycles: {
+      env: 'RABBITMQ_MAX_RECONNECT_CYCLES',
+      defaultKey: 'maxReconnectCycles',
+      type: 'number',
+    },
+
+    // Per-message delivery budget of `consume()`: how many times a handler may
+    // run for one message before it is rejected into `<svc>.dlq`. Same class as
+    // the reconnect budget — resolved here (explicit → env → module default) so
+    // the value has one owner and one documented override path, instead of a
+    // literal in the consume path. See ./config/deliveryPolicy.js.
+    maxDeliveryAttempts: {
+      env: 'RABBITMQ_MAX_DELIVERY_ATTEMPTS',
+      defaultKey: 'maxDeliveryAttempts',
+      type: 'number',
+    },
   }
 });
 

package/src/defaults.js

@@ -12,6 +12,49 @@
 module.exports = {
   heartbeatSeconds: 30,
   serviceName: 'oa-service',
+
+  // How many times connection-level recovery retries before the connection is
+  // declared permanently lost. Client BEHAVIOUR, so it is owned here (the same
+  // class as heartbeat) and overridable by RABBITMQ_MAX_RECONNECT_ATTEMPTS or
+  // explicit config — unlike topology, which is never defaulted (see above).
+  // The budget is finite on purpose: an unbounded retry loop keeps a process
+  // alive that can no longer do its job, and a restart re-verifies every
+  // dependency at boot.
+  maxReconnectAttempts: 10,
+
+  // How many RECOVERY CYCLES the client spends before the connection is declared
+  // permanently lost. One cycle is the whole `maxReconnectAttempts` budget above;
+  // the first is started by the death of the connection, every further one by the
+  // next USE of the client (publish, consume, health check) — nothing polls in
+  // between, so a client nobody uses costs nothing while the broker is away.
+  //
+  // The cap exists because the owner forbade both ends of the scale
+  // (`docs/governance/confirmations/mq-client-lifecycle-contract.md` 001 point 3):
+  // "give up forever" after one spent budget is forbidden, and so is retrying
+  // without end, which keeps a process alive that can no longer do its job. This
+  // number is where the two meet.
+  //
+  // The value 3 is not new: it is the same decision `maxDeliveryAttempts` below
+  // already answers with — how many whole retries ONE thing gets before it is
+  // given up on — and two answers to one question must not differ.
+  maxReconnectCycles: 3,
+
+  // How many times a consumer's handler may run for ONE message before the
+  // message is rejected into `<svc>.dlq` (`config/deliveryPolicy.js`). Client
+  // BEHAVIOUR, the same class as the reconnect budget above, so it is owned
+  // here and overridable on all THREE legs the resolver declares — the explicit
+  // `maxDeliveryAttempts` of the client configuration (d.292 §6), the environment
+  // variable RABBITMQ_MAX_DELIVERY_ATTEMPTS, and the narrowest of them, the
+  // per-call `consume(queue, handler, { maxAttempts })`. Never a literal in the
+  // consume path, which is how the value used to be absent altogether: the
+  // transport requeued every failure unconditionally and no message ever reached
+  // the DLQ.
+  //
+  // The value 3 is not new: it is the budget `@onlineapps/error-handler-core`
+  // already declares for the same decision (`src/RetryHandler.js`, `maxRetries = 3`,
+  // "Max attempts; integer >= 1"). Two libraries answering one question must not
+  // answer it differently.
+  maxDeliveryAttempts: 3,
 };
 
 

package/src/index.js

@@ -14,13 +14,15 @@
  */
 
 const BaseClient = require('./BaseClient');
-const RabbitMQClient = require('./transports/rabbitmqClient');
 const {
   ValidationError,
   ConnectionError,
   PublishError,
   ConsumeError,
   SerializationError,
+  CONNECTION_CLOSED_UNEXPECTEDLY,
+  CONSUMER_QUEUE_MISSING,
+  CONSUMER_DEAD_LETTER_ROUTE_MISSING,
 } = require('./utils/errorHandler');
 const {
   TransientPublishError,
@@ -34,6 +36,9 @@ const {
   publishToMonitoringServices,
   isQueueUnavailableError,
 } = require('./monitoring-publish');
+const queueConfig = require('./config/queueConfig');
+const deliveryPolicy = require('./config/deliveryPolicy');
+const { redactUrl, UNPARSEABLE_PLACEHOLDER } = require('./utils/redactCredentials');
 
 // Export BaseClient as default (constructor), with additional named exports
 // NOTE: When destructuring, use: const { BaseClient } = require('@onlineapps/mq-client-core');
@@ -41,7 +46,12 @@ const {
 // BaseClient must be a constructor, so we export it directly and attach other exports as properties
 module.exports = BaseClient;
 module.exports.BaseClient = BaseClient;
-module.exports.RabbitMQClient = RabbitMQClient;
+// NO `RabbitMQClient` export. The transport is chosen by `type` and built by
+// `transports/transportFactory.js` — the only place in the whole workspace that
+// calls `new RabbitMQClient` (measured 2026-09-14). A caller constructing it
+// directly would skip config composition, schema validation and the instance
+// registry `disconnectAll()` is built on, so the export was a door nobody walked
+// through and one that led past the front desk (d.341).
 module.exports.errors = {
   ValidationError,
   ConnectionError,
@@ -49,6 +59,20 @@ module.exports.errors = {
   ConsumeError,
   SerializationError,
 };
+/**
+ * The machine-readable classification of the errors this package emits, for the
+ * listeners that must decide what one MEANS. A decision taken on the message text
+ * breaks the moment somebody rewords the sentence, and nothing reports the break
+ * (`architecture-principles.md` §3) — which is exactly how the client's own reconnect
+ * wait ignored nothing at all for as long as it compared strings (d.164).
+ *
+ * The values are owned by `./utils/errorHandler`; this is a re-export, never a copy.
+ */
+module.exports.errorCodes = Object.freeze({
+  CONNECTION_CLOSED_UNEXPECTEDLY,
+  CONSUMER_QUEUE_MISSING,
+  CONSUMER_DEAD_LETTER_ROUTE_MISSING,
+});
 module.exports.publishErrors = {
   TransientPublishError,
   PermanentPublishError,
@@ -61,4 +85,69 @@ module.exports.monitoring = {
   publishToMonitoringServices,
   isQueueUnavailableError,
 };
+/** The only public way to reach the central queue classification; `src/config/queueConfig` is an internal path, not a contract. */
+module.exports.queueConfig = queueConfig;
+/**
+ * Platform topology names that travel ON THE WIRE between services.
+ *
+ * A name three services must agree on has to have ONE owner, or it has three: batch
+ * 243g-C correctly removed the per-service env override for the health-events
+ * exchange — a name overridden on one side of a fanout loses the events silently —
+ * and then left the literal as a private constant in the registry, the delivery
+ * endpoint and the monitoring consumer. Nothing compared the three (INFRA request
+ * 2026-09-12, `api/shared/TODO.md`).
+ *
+ * Every value is composed from the entry that DECLARES it (`queueConfig.queueName()`),
+ * so it is the same fact as the queue configuration rather than a copy alongside it;
+ * a rename in `queueConfig` moves the export with it and fails fast if the entry is
+ * gone. Frozen, because an importer must not be able to rewrite platform topology.
+ */
+module.exports.topology = Object.freeze({
+  /** Fanout exchange: registry publishes infrastructure health events here. */
+  infrastructureHealthEventsExchange: queueConfig.queueName('infrastructure', 'health.events'),
+  /** The monitoring consumer's queue bound to that exchange. */
+  monitoringInfrastructureHealthEventsQueue: queueConfig.queueName('monitoring', 'infrastructure.health.events'),
+  /** The delivery endpoint's queue bound to that exchange, for WS push. */
+  deliveryHealthEventsQueue: queueConfig.queueName('deliveryEvents', 'health.events'),
+  /**
+   * The delivery endpoint's queue for resource-changed events, bound to the
+   * `monitoring.resource` exchange by the routing pattern `resource.changed.#`.
+   * Declared in `queueConfig` since d.278; the endpoint carries the same literal as
+   * a private default, which is the shape d.270 gave an owner for the health-events
+   * names (`api/docs/governance/confirmations/mq-consumer-contract.md` 003 — the
+   * endpoint declaring its queues from `queueConfig` is INFRA's step).
+   */
+  deliveryResourceEventsQueue: queueConfig.queueName('deliveryEvents', 'resource.events')
+});
+/**
+ * The dead-letter policy of `consume()` as a contract, not as an implementation
+ * detail: `ATTEMPTS_HEADER` is a name that travels ON THE WIRE, so every reader
+ * of a dead-lettered message — the DLQ dashboard, an operator's script, the
+ * monitoring peek — reads it from here instead of retyping the literal. The
+ * classification vocabulary travels with it, because a caller's `classify` must
+ * return one of those two words.
+ */
+module.exports.deliveryPolicy = deliveryPolicy;
+/**
+ * Redaction of the credential a connection URL carries, as a DECLARED export.
+ *
+ * `RABBITMQ_URL` is the single rail for the broker account, so every place that
+ * renders it verbatim leaks that account into the service log and from there into
+ * Loki, where it is durable and searchable. The platform answer is one function:
+ * userinfo out, scheme/host/port/vhost in, and a fixed placeholder for a value that
+ * is not a parseable URL.
+ *
+ * It is exported because it was already written three times — here, in
+ * `shared/service-common/src/redactUrl.js` (d.245/d.245b) and in
+ * `shared/connector/conn-orch-registry/src/redactUrl.js` (d.446), whose header says
+ * plainly that it stayed local only because this package declared no redactor and
+ * masked the password alone. Two semantics for one concern are two rails
+ * (`change-discipline.md` § One rail per concern); d.448 made them one and put it
+ * where a dependant can import it instead of copying it.
+ *
+ * The placeholder travels with the function: a caller comparing against it must
+ * read the same literal, not retype it.
+ */
+module.exports.redactUrl = redactUrl;
+module.exports.UNPARSEABLE_PLACEHOLDER = UNPARSEABLE_PLACEHOLDER;
 

package/src/layers/PublishLayer.js

@@ -5,7 +5,9 @@ const {
   PermanentPublishError,
   QueueNotFoundError,
 } = require('../utils/publishErrors');
+const { ValidationError, PublishError } = require('../utils/errorHandler');
 const MessageBuffer = require('../buffer/MessageBuffer');
+const { assertLogger } = require('@onlineapps/logger-contract');
 
 /**
  * PublishLayer - čistá vrstva pro publish s retry + buffer
@@ -19,7 +21,7 @@ class PublishLayer {
   /**
    * @param {Object} options
    * @param {Object} options.client - Instance RabbitMQClient
-   * @param {Object} [options.logger] - Logger
+   * @param {Object} options.logger - Logger s info/warn/error/debug (povinný)
    * @param {Object} [options.bufferConfig] - Konfigurace pro MessageBuffer
    * @param {boolean} [options.retryEnabled=true] - Zapnout retry
    * @param {number} [options.maxRetries=3] - Max počet pokusů
@@ -29,25 +31,49 @@ class PublishLayer {
    */
   constructor(options = {}) {
     if (!options.client) {
-      throw new Error('PublishLayer requires a client instance');
+      throw new ValidationError(
+        '[PublishLayer] options.client is required - Expected: the RabbitMQClient this layer publishes through. '
+          + 'Fix: construct it as new PublishLayer({ client, logger }).'
+      );
     }
 
     this._client = options.client;
-    this._logger = options.logger || console;
+    this._logger = assertLogger(
+      'PublishLayer',
+      options.logger,
+      'the layer reports every publish retry, every buffered message and every flush',
+      'pass options.logger (the transport forwards the one your service built)'
+    );
 
-    // Retry konfigurace - bere z client config nebo options
+    // Retry configuration: what the caller wrote, else what the CLIENT resolved.
+    // No literal of this layer's own — every one of these numbers is declared and
+    // defaulted in `config/defaultConfig.js`, composed before validation, and the
+    // transport constructor reads it from there (d.292 §5).
+    //
+    // Asked with `=== undefined`, never with `||`. `||` means "if falsy", so the
+    // three numbers below lost a legally written `0` — `publishMaxRetries: 0`
+    // means "do not retry a publish", and it arrived here as 3. d.292 removed
+    // exactly that shape from the transport and said in as many words that this
+    // layer still carried its own copies; this is that floor (d.311).
     this._retryEnabled = options.retryEnabled !== undefined 
       ? options.retryEnabled 
       : (this._client._publishRetryEnabled !== false);
-    this._maxRetries = options.maxRetries || this._client._publishMaxRetries || 3;
-    this._retryBaseDelay = options.retryBaseDelay || this._client._publishRetryBaseDelay || 100;
-    this._retryMaxDelay = options.retryMaxDelay || this._client._publishRetryMaxDelay || 5000;
-    this._retryBackoffMultiplier = options.retryBackoffMultiplier || this._client._publishRetryBackoffMultiplier || 2;
+    this._maxRetries = options.maxRetries !== undefined
+      ? options.maxRetries
+      : this._client._publishMaxRetries;
+    this._retryBaseDelay = options.retryBaseDelay !== undefined
+      ? options.retryBaseDelay
+      : this._client._publishRetryBaseDelay;
+    this._retryMaxDelay = options.retryMaxDelay !== undefined
+      ? options.retryMaxDelay
+      : this._client._publishRetryMaxDelay;
+    this._retryBackoffMultiplier = options.retryBackoffMultiplier !== undefined
+      ? options.retryBackoffMultiplier
+      : this._client._publishRetryBackoffMultiplier;
 
     // Buffer
     this._buffer = new MessageBuffer({
       inMemory: options.bufferConfig?.inMemory,
-      persistent: options.bufferConfig?.persistent,
       logger: this._logger,
     });
   }
@@ -59,14 +85,16 @@ class PublishLayer {
    * @param {Object} [options]
    */
   async publish(queue, buffer, options = {}) {
+    // `priority` still orders the buffer's replay (critical first). What it no
+    // longer does is choose a DIFFERENT buffer: the persistent one was a stub
+    // that stored nothing, so routing critical messages to it dropped them
+    // (d.343).
     const priority = options.priority || 'normal';
-    const usePersistentBuffer =
-      priority === 'critical' && !!this._client._config?.persistentBufferEnabled;
 
     if (this._retryEnabled) {
-      return await this._publishWithRetry(queue, buffer, options, priority, usePersistentBuffer);
+      return await this._publishWithRetry(queue, buffer, options, priority);
     } else {
-      return await this._publishOnce(queue, buffer, options, priority, usePersistentBuffer);
+      return await this._publishOnce(queue, buffer, options, priority);
     }
   }
 
@@ -74,11 +102,11 @@ class PublishLayer {
    * Single publish attempt - deleguje na RabbitMQClient._publishOnce()
    * @private
    */
-  async _publishOnce(queue, buffer, options, priority, usePersistentBuffer) {
+  async _publishOnce(queue, buffer, options, priority) {
     try {
       await this._client._publishOnce(queue, buffer, options);
     } catch (err) {
-      return await this._handlePublishError(err, queue, buffer, options, priority, usePersistentBuffer);
+      return await this._handlePublishError(err, queue, buffer, options, priority);
     }
   }
 
@@ -86,7 +114,7 @@ class PublishLayer {
    * Publish s retry logikou
    * @private
    */
-  async _publishWithRetry(queue, buffer, options, priority, usePersistentBuffer) {
+  async _publishWithRetry(queue, buffer, options, priority) {
     let lastError = null;
     let attempt = 0;
 
@@ -102,7 +130,7 @@ class PublishLayer {
           lastError: lastError?.message
         });
         if (attempt > 1) {
-          this._logger?.log?.(`[PublishLayer] Retry attempt ${attempt}/${this._maxRetries} for queue "${queue}"`);
+          this._logger.debug(`[PublishLayer] Retry attempt ${attempt}/${this._maxRetries} for queue "${queue}"`);
         }
 
         await this._client._publishOnce(queue, buffer, options);
@@ -114,7 +142,7 @@ class PublishLayer {
           totalAttempts: attempt
         });
         if (attempt > 1) {
-          this._logger?.log?.(`[PublishLayer] ✓ Published successfully after ${attempt} attempts for queue "${queue}"`);
+          this._logger.info(`[PublishLayer] ✓ Published successfully after ${attempt} attempts for queue "${queue}"`);
         }
 
         return; // Success
@@ -139,14 +167,14 @@ class PublishLayer {
           if (attempt < this._maxRetries) {
             // Wait for reconnection if in progress
             if (this._client._reconnecting) {
-              this._logger?.log?.(`[PublishLayer] Connection reconnecting, waiting before retry ${attempt + 1}/${this._maxRetries}...`);
+              this._logger.debug(`[PublishLayer] Connection reconnecting, waiting before retry ${attempt + 1}/${this._maxRetries}...`);
               try {
                 await this._client._waitForReconnection();
-                this._logger?.log?.(`[PublishLayer] ✓ Reconnection completed, proceeding with retry ${attempt + 1}/${this._maxRetries}`);
+                this._logger.debug(`[PublishLayer] ✓ Reconnection completed, proceeding with retry ${attempt + 1}/${this._maxRetries}`);
                 continue; // Retry immediately after reconnect
               } catch (reconnectErr) {
                 // Reconnection failed - buffer and fail
-                await this._bufferMessage(queue, buffer, options, priority, usePersistentBuffer, err);
+                await this._bufferMessage(queue, buffer, options, priority, err);
                 this._client.emit('publish:failed', {
                   queue,
                   attempt,
@@ -154,7 +182,13 @@ class PublishLayer {
                   retryable: false,
                   reconnectFailed: true
                 });
-                throw new Error(`Publish failed: reconnection failed after ${attempt} attempts for queue "${queue}": ${reconnectErr.message}`);
+                throw new PublishError(
+                  `[PublishLayer] Publish failed: reconnection failed after ${attempt} attempts for queue "${queue}" - `
+                    + 'Expected: the transport to re-establish the connection before the retry. '
+                    + 'Fix: read error.cause for the reconnect reason; the message itself is buffered, so it is not lost.',
+                  queue,
+                  reconnectErr
+                );
               }
             }
 
@@ -163,13 +197,13 @@ class PublishLayer {
               this._retryBaseDelay * Math.pow(this._retryBackoffMultiplier, attempt - 1),
               this._retryMaxDelay
             );
-            this._logger?.warn?.(`[PublishLayer] Retryable error for queue "${queue}" (attempt ${attempt}/${this._maxRetries}), waiting ${delay}ms before retry: ${err.message}`);
+            this._logger.warn(`[PublishLayer] Retryable error for queue "${queue}" (attempt ${attempt}/${this._maxRetries}), waiting ${delay}ms before retry: ${err.message}`);
             await new Promise(resolve => setTimeout(resolve, delay));
             continue;
           }
 
           // Max retries exceeded - buffer and fail
-          await this._bufferMessage(queue, buffer, options, priority, usePersistentBuffer, err);
+          await this._bufferMessage(queue, buffer, options, priority, err);
           this._client.emit('publish:failed', {
             queue,
             attempt,
@@ -177,7 +211,13 @@ class PublishLayer {
             retryable: true,
             maxRetriesExceeded: true
           });
-          throw new Error(`Publish failed after ${attempt} attempts for queue "${queue}": ${err.message}`);
+          throw new PublishError(
+            `[PublishLayer] Publish failed after ${attempt} attempts for queue "${queue}" - `
+              + 'Expected: a retryable broker error to clear within maxRetries. '
+              + 'Fix: read error.cause for the last broker reason; the message is buffered, so it is not lost.',
+            queue,
+            err
+          );
         }
 
         // Unknown error - fail immediately
@@ -185,21 +225,30 @@ class PublishLayer {
       }
     }
 
-    throw lastError || new Error(`Publish failed for queue "${queue}" after ${attempt} attempts`);
+    throw (
+      lastError
+      || new PublishError(
+        `[PublishLayer] Publish failed for queue "${queue}" after ${attempt} attempts - `
+          + 'Expected: the retry loop to end with either a success or the error of the last attempt. '
+          + 'Fix: this is a defect in PublishLayer, not in the caller — report it with the queue name and attempt count.',
+        queue,
+        null
+      )
+    );
   }
 
   /**
    * Handle publish error - buffer transient errors
    * @private
    */
-  async _handlePublishError(err, queue, buffer, options, priority, usePersistentBuffer) {
+  async _handlePublishError(err, queue, buffer, options, priority) {
     if (err instanceof QueueNotFoundError) {
-      this._logger?.error?.(`[PublishLayer] QueueNotFoundError for '${queue}' (infra=${err.isInfrastructure}): ${err.message}`);
+      this._logger.error(`[PublishLayer] QueueNotFoundError for '${queue}' (infra=${err.isInfrastructure}): ${err.message}`);
       throw err;
     }
 
     if (err instanceof TransientPublishError) {
-      await this._bufferMessage(queue, buffer, options, priority, usePersistentBuffer, err);
+      await this._bufferMessage(queue, buffer, options, priority, err);
       throw err;
     }
 
@@ -210,16 +259,13 @@ class PublishLayer {
    * Buffer message při transient error
    * @private
    */
-  async _bufferMessage(queue, buffer, options, priority, usePersistentBuffer, err) {
+  async _bufferMessage(queue, buffer, options, priority, err) {
     try {
-      await this._buffer.add(queue, buffer, options, {
-        priority,
-        persistent: usePersistentBuffer,
-      });
-      this._logger?.warn?.(`[PublishLayer] Buffered message for queue '${queue}' due to transient error: ${err.message}`);
+      await this._buffer.add(queue, buffer, options, { priority });
+      this._logger.warn(`[PublishLayer] Buffered message for queue '${queue}' due to transient error: ${err.message}`);
       this._client.emit('publish:buffered', { queue });
     } catch (bufferErr) {
-      this._logger?.error?.(`[PublishLayer] Failed to buffer message for queue '${queue}': ${bufferErr.message}`);
+      this._logger.error(`[PublishLayer] Failed to buffer message for queue '${queue}': ${bufferErr.message}`);
     }
   }
 
@@ -232,7 +278,7 @@ class PublishLayer {
       await this._client._publishOnce(queue, buf, mergedOptions);
     });
 
-    this._logger?.info?.(`[PublishLayer] Flushed buffered messages (inMemory=${result.inMemory}, persistent=${result.persistent})`);
+    this._logger.info(`[PublishLayer] Flushed ${result} buffered message(s)`);
     return result;
   }
 }

package/src/monitoring/PublishMonitor.js

@@ -2,15 +2,22 @@
 
 /**
  * PublishMonitor - tracking a metriky pro publish operace
+ *
+ * NO LOGGER. This component counts and answers with return values
+ * (`getMetrics()`, `getPrometheusMetrics()`); it has nothing to report on its
+ * own, and it wrote nothing anywhere. Until 2026-09-07 it took an optional
+ * `options.logger` defaulted to `console` and never called it once — a required
+ * dependency with no consumer, which is the defect owner confirmation
+ * `docs/governance/confirmations/connector-logger-contract.md` 002 named: give
+ * such a logger a real consumer, or drop the declaration. A counter has nothing
+ * to say, so the declaration goes (`change-discipline.md` § Removing something
+ * removes its declaration).
  */
 class PublishMonitor {
   /**
-   * @param {Object} options
-   * @param {Object} [options.logger] - Logger
+   * @param {Object} [options] - Reserved; this monitor takes no dependencies.
    */
   constructor(options = {}) {
-    this._logger = options.logger || console;
-    
     // Metrics
     this._metrics = {
       attempts: 0,