@onlineapps/mq-client-core 4.1.0 → 5.0.0

package/src/index.js

@@ -8,9 +8,6 @@
  * 
  * NOTE: Infrastructure orchestration utilities (waitForInfrastructureReady, initInfrastructureQueues)
  * have been moved to @onlineapps/infrastructure-tools to keep this library focused on core MQ operations.
- * 
- * @version 1.0.49
- * @updated 2024-12-08 - Test publish-library.sh workflow
  */
 
 const BaseClient = require('./BaseClient');
@@ -40,8 +37,19 @@ const {
   buildWorkflowInitiatedEvent,
   publishWorkflowInitiated,
 } = require('./monitoring-initiated');
+const {
+  schedulerRequestQueue,
+  validateRecurrences,
+  buildRecurringRequest,
+  buildEventRequest,
+  buildCancelRequest,
+  publishSchedulerRequest,
+  createSchedulerPublisher,
+  SCHEDULER_REQUEST_INVALID,
+} = require('./scheduler-request');
 const queueConfig = require('./config/queueConfig');
 const deliveryPolicy = require('./config/deliveryPolicy');
+const { decodeMessage } = require('./utils/decodeMessage');
 const { redactUrl, UNPARSEABLE_PLACEHOLDER } = require('@onlineapps/logger-contract');
 
 // Export BaseClient as default (constructor), with additional named exports
@@ -94,6 +102,25 @@ module.exports.monitoring = {
   buildWorkflowInitiatedEvent,
   publishWorkflowInitiated,
 };
+/**
+ * The recurrences a service declares, and how one of them is registered (d.833).
+ *
+ * `docs/architecture/scheduler.md` §7 gives this library the shape of one declared recurrence
+ * and the wrapper the job of re-asserting what the service answers at every boot (one hook,
+ * confirmation `scheduler` 011). The queue name travels with them, so no caller composes
+ * `scheduler.request` itself.
+ */
+module.exports.scheduler = {
+  requestQueue: schedulerRequestQueue,
+  validateRecurrences,
+  buildRecurringRequest,
+  buildEventRequest,
+  buildCancelRequest,
+  publishSchedulerRequest,
+  createSchedulerPublisher,
+  // The code on every refusal of a builder, and on nothing a failed send throws.
+  SCHEDULER_REQUEST_INVALID,
+};
 /** The only public way to reach the central queue classification; `src/config/queueConfig` is an internal path, not a contract. */
 module.exports.queueConfig = queueConfig;
 /**
@@ -149,7 +176,25 @@ module.exports.topology = Object.freeze({
   /** The same consumer's metric-sample intake on that exchange. */
   telemetryMetricsQueue: queueConfig.queueName('telemetry', 'metrics.queue'),
   /** The same consumer's span intake on that exchange. */
-  telemetryTracesQueue: queueConfig.queueName('telemetry', 'traces.queue')
+  telemetryTracesQueue: queueConfig.queueName('telemetry', 'traces.queue'),
+  /**
+   * Topic exchange: every telemetry producer on the platform publishes logs, metrics and
+   * spans here with a routing key of the shape `telemetry.<signal>.<service_name>`, and
+   * the three queues above are bound to it.
+   *
+   * Declared in `queueConfig` since d.708, which ended the state where one name had three
+   * owners: a module constant in the monitoring consumer
+   * (`api/infra/api_monitoring/src/consumer/topology.js`) and a config default in each of
+   * monitoring-core's two publishers. The declaration alone does not finish that move —
+   * the consumer resolves every platform name it does not own through THIS export, and
+   * `src/config/queueConfig` is an internal path rather than a contract (see the note on
+   * the module export above). So the name it must import belongs here, the same step d.461
+   * made for the three queues it is bound to.
+   *
+   * @see api/infra/api_monitoring/src/consumer/index.js — assertMonitoringTopology()
+   * @see api/shared/monitoring/monitoring-core/src/exporters/rabbitmq.js
+   */
+  telemetryExchange: queueConfig.queueName('telemetry', 'exchange')
 });
 /**
  * The dead-letter policy of `consume()` as a contract, not as an implementation
@@ -160,6 +205,24 @@ module.exports.topology = Object.freeze({
  * return one of those two words.
  */
 module.exports.deliveryPolicy = deliveryPolicy;
+/**
+ * The one rail from a delivery to the message it carries.
+ *
+ * `consume()` hands its handler the RAW amqplib delivery, so every consumer wrote that
+ * translation itself: d.788 measured FOUR copies (dispatcher, scheduler, service-wrapper,
+ * registry) which disagree about what happens to a BAD message — dead-letter, loss rail,
+ * `INVALID_JSON` reply, or requeue for ever — and two of which pass a delivery with no
+ * `content` on AS the body.
+ *
+ * The decoding was never the missing part (`utils/serializer.js` has done it all along);
+ * the missing part was this door, because `src/…` is an internal path rather than a
+ * contract. Exported ADDITIVELY: nothing in this package calls it and `consume()` is
+ * unchanged, because converting those four changes the fate of a malformed message —
+ * BREAKING, and for the registry only after its queue has a dead-letter route (d.784).
+ *
+ * @see ./utils/decodeMessage.js — what it refuses, and with which of this package's classes
+ */
+module.exports.decodeMessage = decodeMessage;
 /**
  * Redaction of the credential a connection URL carries, as a DECLARED export.
  *

package/src/layers/PublishLayer.js

@@ -51,10 +51,10 @@ class PublishLayer {
     // 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).
+    // three numbers below lost a legally written `0` — `publishRetryBaseDelay: 0`
+    // means "retry immediately", and it arrived here as 100. 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);
@@ -71,6 +71,45 @@ class PublishLayer {
       ? options.retryBackoffMultiplier
       : this._client._publishRetryBackoffMultiplier;
 
+    // `publishMaxRetries` counts ATTEMPTS, the first one included — that is what the
+    // key means in every place it is written down (`config/configSchema.js`,
+    // `config/defaultConfig.js`, `docs/architecture/mq-publish-reliability.md` § the
+    // config table, `docs/standards/rabbitmq-channel-best-practices.md`), and what
+    // `_publishWithRetry()` below does for every value from 1 up.
+    //
+    // So `0` is not "do not retry" — three comments in this package said it was, and
+    // the loop obeyed the key instead: `while (attempt < this._maxRetries)` never runs
+    // its body, so the message is never offered to the broker, is NOT buffered on the
+    // way out, and the caller is handed an error blaming this layer for a defect its
+    // own configuration caused (measured, d.684). "One attempt, no retry" is `1`, and
+    // leaving the retry rail entirely is `publishRetryEnabled: false`; both are
+    // explicit, and neither needs a magic zero (`architecture-principles.md` §8).
+    //
+    // Refused HERE, at construction, because this is the one place both doors meet —
+    // the caller's `options.maxRetries` and the client's resolved config — and a value
+    // that can only fail is refused before it is used, not when a publish needs it
+    // (§4 fail-fast).
+    //
+    // `config/configSchema.js` refuses the same value too since d.685b (`minimum: 1`),
+    // and that is not a second rail for one concern: the schema answers what may be
+    // WRITTEN in a client's configuration, this answers what may be USED as a number of
+    // attempts — and the second is reachable without the first. Measured 2026-09-20: the
+    // schema is compiled and applied in exactly one place, `BaseClient`'s constructor,
+    // while the only `new RabbitMQClient` in the workspace is
+    // `transports/transportFactory.js`, which validates nothing. The two also answer at
+    // different moments, because `BaseClient` builds the transport in `connect()` rather
+    // than in its constructor — so a client built past the front desk still arrives here
+    // with whatever it was given.
+    if (!Number.isInteger(this._maxRetries) || this._maxRetries < 1) {
+      throw new ValidationError(
+        `[PublishLayer] publishMaxRetries must be at least 1 - got ${JSON.stringify(this._maxRetries)}. `
+          + 'Expected: a whole number of publish attempts, because it counts ATTEMPTS, the first one '
+          + 'included — 0 means the message is never offered to the broker at all. '
+          + 'Fix: write publishMaxRetries: 1 for one attempt and no retry, or publishRetryEnabled: false '
+          + 'to leave the retry rail entirely.'
+      );
+    }
+
     // Buffer
     this._buffer = new MessageBuffer({
       inMemory: options.bufferConfig?.inMemory,
@@ -118,7 +157,48 @@ class PublishLayer {
     let lastError = null;
     let attempt = 0;
 
+    /**
+     * The broker's numbered refusal of THIS message, if it arrived after the confirmation
+     * budget had already answered an attempt.
+     *
+     * Measured (d.801): when the budget is shorter than the broker's answer, the attempt
+     * is answered "transient" while the frame underneath says 404 — and the loop below
+     * used to publish the message again, `publishMaxRetries` times, and then buffer it,
+     * where the flush re-offers it on every reconnect until its TTL drops it. d.801b made
+     * that verdict audible (`publish:refused-late`); this listener is what ACTS on it.
+     *
+     * No new evidence and no new timer: the frame is read where it has always been read
+     * (the transport's `channel._closeError` + `_closeFrameNamesThisSend()`), the event is
+     * the one already emitted, and the subscription lives exactly as long as this publish.
+     */
+    let lateRefusal = null;
+    const onRefusedLate = (event) => {
+      if (event.queue === queue && event.verdict === 'PermanentPublishError' && event.error) {
+        lateRefusal = event.error;
+      }
+    };
+    this._client.on('publish:refused-late', onRefusedLate);
+
+    try {
     while (attempt < this._maxRetries) {
+      // A message the broker has REFUSED is not published again. The question is asked
+      // before every attempt but the first, because the first is what earns the answer.
+      if (attempt > 0 && lateRefusal !== null) {
+        this._logger.warn(
+          `[PublishLayer] The broker refused this message while attempt ${attempt} was in flight, `
+            + `so attempt ${attempt + 1} of ${this._maxRetries} is not made for queue "${queue}" - `
+            + `${lateRefusal.message}`
+        );
+        this._client.emit('publish:failed', {
+          queue,
+          attempt,
+          error: lateRefusal.message,
+          retryable: false,
+          refusedLate: true
+        });
+        throw lateRefusal;
+      }
+
       attempt++;
 
       try {
@@ -133,7 +213,12 @@ class PublishLayer {
           this._logger.debug(`[PublishLayer] Retry attempt ${attempt}/${this._maxRetries} for queue "${queue}"`);
         }
 
-        await this._client._publishOnce(queue, buffer, options);
+        // WHICH attempt this is travels with the send, and is read by exactly one thing:
+        // the transport's report of a broker verdict that arrived after the confirmation
+        // budget had already answered (`publish:refused-late`, d.801b). It reaches no
+        // broker property — `buildAmqpMessageProperties()` copies only the AMQP keys it
+        // declares — and it changes nothing about the publish itself.
+        await this._client._publishOnce(queue, buffer, { ...options, attempt });
 
         // Track success (always emit, even for first attempt)
         this._client.emit('publish:success', {
@@ -198,6 +283,24 @@ class PublishLayer {
               this._retryMaxDelay
             );
             this._logger.warn(`[PublishLayer] Retryable error for queue "${queue}" (attempt ${attempt}/${this._maxRetries}), waiting ${delay}ms before retry: ${err.message}`);
+            // THE BARE TIMER IS THE POINT, and it is not a copy of the transport's rail.
+            //
+            // The transport sleeps through `_setTimeout()`, which files the handle in
+            // `_activeTimers` so that a teardown can END the wait (d.759e). That is right
+            // THERE: what waits is the client's own recovery loop, and a teardown must
+            // stop it. It is wrong HERE, because what waits is the CALLER's `publish()`.
+            // Měřeno d.766 on this runtime: a sleep armed through `_setTimeout()` and
+            // swept by `_clearAllTimers()` mid-wait NEVER settles (the same sleep on the
+            // bare timer always does), so the one rail would turn a disconnect during a
+            // backoff into a `publish()` that never returns. The layer HAS the client
+            // (injected, required in the constructor), so this is a difference of
+            // obligation and not of reach.
+            //
+            // One owner at this level: the retry wait is the layer's, it is always
+            // awaited by the caller, and it always ends.
+            // @see ../transports/rabbitmqClient.js — `_setInterval` / `_clearAllTimers`
+            // @see ../../tests/unit/publish-max-retries-counts-attempts.test.js — the
+            //      control case that fails if this is ever "unified"
             await new Promise(resolve => setTimeout(resolve, delay));
             continue;
           }
@@ -235,6 +338,11 @@ class PublishLayer {
         null
       )
     );
+    } finally {
+      // The subscription lives exactly as long as this publish: no listener survives the
+      // call that opened it, whichever way the loop ended.
+      this._client.removeListener('publish:refused-late', onRefusedLate);
+    }
   }
 
   /**

package/src/monitoring-publish.js

@@ -18,19 +18,66 @@
  *   await publishToMonitoringWorkflow(mqClient, { event_type: 'completed', workflow_id: '...', ... }, logger);
  */
 
-const { PublishError, ConnectionError } = require('./utils/errorHandler');
+const { ConnectionError } = require('./utils/errorHandler');
 const { assertLogger } = require('@onlineapps/logger-contract');
-const { QueueNotFoundError, classifyPublishError } = require('./utils/publishErrors');
+const {
+  AMQP_NOT_FOUND,
+  QueueNotFoundError,
+  TransientPublishError
+} = require('./utils/publishErrors');
 
 /**
- * Check if error indicates queue doesn't exist or RabbitMQ is unavailable
+ * The socket-level codes that mean the broker was not reachable at all. Node sets
+ * them, not this package, and they are codes rather than words.
+ */
+const UNREACHABLE_SOCKET_CODES = new Set(['ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT']);
+
+/**
+ * How deep a cause chain this function is willing to walk.
  *
- * The queue is named because the last question it asks —
- * `classifyPublishError()` — builds a `QueueNotFoundError`, and that error carries
- * a queue name it must be told (d.435); the caller has had it all along.
+ * The measured chain is three links — `PublishError` (BaseClient) → the publish
+ * classification → amqplib's raw error — so the bound is an upper limit on a real
+ * shape, not a guess about an unknown one. It exists because `error.cause` is set by
+ * whoever threw, and a chain that points back at itself would otherwise spin.
+ */
+const MAX_CAUSE_DEPTH = 8;
+
+/**
+ * Does this error — or anything it was caused by — mean the queue was not there to
+ * publish into, or the broker was not reachable?
+ *
+ * DECIDED BY CLASS AND CODE, NEVER BY THE MESSAGE. Until d.676 the decision read
+ * substrings: `'not connected'`, `'Connection closed'`, `'NOT_FOUND'`, `'404'`,
+ * `'no queue'`, `'queue does not exist'`, `'Channel closed'`. Every one of those
+ * sentences belongs to somebody else — amqplib writes the broker's refusal, this
+ * package writes its own — so the classification broke on any rewording and nothing
+ * reported the break (`docs/biz/70-contracts/error-handling.md` §6: "Message-based
+ * routing; breaks on any wording change — branch on `err.code`").
+ *
+ * WHY THE CHAIN AND NOT THE ERROR ITSELF: `BaseClient.publish()` wraps every
+ * transport failure in a `PublishError` and puts the real error in `cause`. So the
+ * object handed to this function is the wrapper, its `instanceof` tests never
+ * matched, and only the substrings ever fired — by accident, because the wrapper's
+ * message quotes the cause's sentence. Two shapes were measured answering `false`
+ * although the queue really was unavailable: a `QueueNotFoundError` with
+ * `kind: 'unowned'`, whose sentence carries none of the substrings, and a
+ * retry-exhausted publish, whose sentence quotes no cause at all.
+ *
+ * The carriers this walks for, and what each stands for:
+ *   - `QueueNotFoundError` — the publish path's own ownership refusal (the queue is
+ *     absent, whichever owner should have created it);
+ *   - `ConnectionError` — the client is not connected, or the connection dropped
+ *     (`CONNECTION_CLOSED_UNEXPECTEDLY`);
+ *   - `TransientPublishError` — the channel or connection went away mid-publish;
+ *     amqplib's `IllegalOperationError` ("Channel closed"), which carries no code of
+ *     its own, reaches here as exactly this class;
+ *   - `code === 404` — amqplib's raw `NOT_FOUND`;
+ *   - `ECONNREFUSED` / `ENOTFOUND` / `ETIMEDOUT` — the broker was unreachable.
  *
  * @param {Error} error - The error a publish to `queueName` produced.
- * @param {string} queueName - The queue that publish was aimed at.
+ * @param {string} queueName - The queue that publish was aimed at. Required since
+ *   d.435 and part of the exported contract; it is what the refusal below names.
+ * @returns {boolean}
  * @private
  */
 function isQueueUnavailableError(error, queueName) {
@@ -43,39 +90,21 @@ function isQueueUnavailableError(error, queueName) {
     );
   }
 
-  if (!error) return false;
-  
-  const errorMessage = error.message || String(error);
-  const errorCode = error.code || '';
-  const errorName = error.name || '';
-  
-  // Connection errors
-  if (error instanceof ConnectionError || 
-      errorCode === 'ECONNREFUSED' || 
-      errorCode === 'ENOTFOUND' || 
-      errorCode === 'ETIMEDOUT' ||
-      errorMessage.includes('not connected') ||
-      errorMessage.includes('Connection closed')) {
-    return true;
-  }
-  
-  // Queue doesn't exist errors
-  if (error instanceof QueueNotFoundError ||
-      errorName === 'QueueNotFoundError' ||
-      errorMessage.includes('NOT_FOUND') || 
-      errorMessage.includes('404') ||
-      errorMessage.includes('no queue') ||
-      errorMessage.includes('queue does not exist') ||
-      errorMessage.includes('Channel closed')) {
-    return true;
-  }
-  
-  // Classify publish errors
-  const classified = classifyPublishError(error, queueName);
-  if (classified instanceof QueueNotFoundError) {
-    return true;
+  let link = error;
+
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH && link instanceof Error; depth += 1) {
+    if (link instanceof QueueNotFoundError
+      || link instanceof ConnectionError
+      || link instanceof TransientPublishError
+      || link.code === AMQP_NOT_FOUND
+      || UNREACHABLE_SOCKET_CODES.has(link.code)) {
+      return true;
+    }
+
+    if (link.cause === link) break;
+    link = link.cause;
   }
-  
+
   return false;
 }
 
@@ -115,6 +144,26 @@ async function publishToMonitoringResilient(mqClient, queueName, message, logger
     return false;
   }
 
+  // The client's own events go out on the client's own channel (d.724). Said here, in the
+  // one place that knows these messages are the client talking about itself; `publish()`
+  // would put them on the channel carrying the caller's business messages, where a
+  // refusal of an event closes the channel and takes those with it (measured d.711).
+  // Reported and skipped rather than thrown, like every other precondition in this
+  // function: it is fail-safe about publishing by contract (§ Principles above), and a
+  // transport without the method would otherwise turn a monitoring event into a caller's
+  // exception.
+  if (typeof mqClient.publishTelemetry !== 'function') {
+    logger.warn(
+      `Monitoring publish skipped: the client has no publishTelemetry() (queue: ${queueName}) - `
+        + 'Expected: a client whose telemetry has a channel of its own, so a refused event cannot '
+        + 'close the channel a business message is waiting on. '
+        + 'Fix: pass a @onlineapps/mq-client-core BaseClient, or a client that forwards '
+        + 'publishTelemetry() to one.',
+      context
+    );
+    return false;
+  }
+
   if (!message || !message.event_type) {
     logger.warn(`Monitoring publish skipped: message missing event_type (queue: ${queueName})`, {
       ...context,
@@ -140,7 +189,7 @@ async function publishToMonitoringResilient(mqClient, queueName, message, logger
     const publishOptions = queueName === 'monitoring.workflow'
       ? { exchange: WORKFLOW_FANOUT, routingKey: '' }
       : {};
-    await mqClient.publish(queueName, message, publishOptions);
+    await mqClient.publishTelemetry(queueName, message, publishOptions);
 
     logger.debug(`Published to ${queueName}`, {
       ...context,