@onlineapps/mq-client-core 5.1.0 → 6.0.0

package/src/layers/PublishLayer.js

@@ -2,10 +2,11 @@
 
 const {
   TransientPublishError,
+  RecoveryEndedPublishError,
   PermanentPublishError,
   QueueNotFoundError,
 } = require('../utils/publishErrors');
-const { ValidationError, PublishError } = require('../utils/errorHandler');
+const { ValidationError, PublishError, carryVerdict } = require('../utils/errorHandler');
 const MessageBuffer = require('../buffer/MessageBuffer');
 const { assertLogger } = require('@onlineapps/logger-contract');
 
@@ -23,6 +24,8 @@ class PublishLayer {
    * @param {Object} options.client - Instance RabbitMQClient
    * @param {Object} options.logger - Logger s info/warn/error/debug (povinný)
    * @param {Object} [options.bufferConfig] - Konfigurace pro MessageBuffer
+   * @param {{setTimeout: Function, clearTimeout: Function}} options.timers - The clock the
+   *   buffer expires its entries on (required, d.1275; the transport passes its own timer rail).
    * @param {boolean} [options.retryEnabled=true] - Zapnout retry
    * @param {number} [options.maxRetries=3] - Max počet pokusů
    * @param {number} [options.retryBaseDelay=100] - Base delay v ms
@@ -114,7 +117,11 @@ class PublishLayer {
     this._buffer = new MessageBuffer({
       inMemory: options.bufferConfig?.inMemory,
       logger: this._logger,
+      timers: options.timers,
     });
+    // Read by the one sentence that tells a caller how long the buffer holds its message
+    // (`_holdOnFailure()`); `InMemoryBuffer` has already refused a missing value above.
+    this._bufferTtlMs = options.bufferConfig.inMemory.ttlMs;
   }
 
   /**
@@ -312,6 +319,21 @@ class PublishLayer {
           throw said(err);
         }
 
+        // The attempt could not get its send channel because the connection stayed down
+        // (B1, d.1300): the recovery it waited for ended in standby or fatal, or none may
+        // start. Retrying NOW is pointless — the next use of the client starts the next
+        // cycle — so the message is held at once, on the same rail as the retry below that
+        // waited for a reconnect and saw it fail. Asked BEFORE the generic transient branch,
+        // because the class is a transient one (the message is held and replayed).
+        if (err instanceof RecoveryEndedPublishError) {
+          throw said(await this._failedAfterRecovery({
+            queue, buffer, options, priority, attempt, transient: err, recoveryError: err.cause || err, sentAny,
+            headline: '[PublishLayer] Publish failed: the recovery this publish waited for ended without a connection '
+              + `(attempt ${attempt} for queue "${queue}") - ${err.message} `
+              + 'Expected: a live connection before the send. '
+          }));
+        }
+
         // Transient errors - check if we should retry or buffer
         if (err instanceof TransientPublishError) {
           // If we have more attempts, retry
@@ -325,23 +347,11 @@ class PublishLayer {
                 continue; // Retry immediately after reconnect
               } catch (reconnectErr) {
                 // Reconnection failed - buffer (unless the caller said not to) and fail
-                const held = await this._holdOnFailure(queue, buffer, options, priority, err, sentAny);
-                this._client.emit('publish:failed', {
-                  queue,
-                  attempt,
-                  error: `Reconnection failed: ${reconnectErr.message}`,
-                  retryable: false,
-                  reconnectFailed: true
-                });
-                const failure = new PublishError(
-                  `[PublishLayer] Publish failed: reconnection failed after ${attempt} attempts for queue "${queue}" - `
+                throw said(await this._failedAfterRecovery({
+                  queue, buffer, options, priority, attempt, transient: err, recoveryError: reconnectErr, sentAny,
+                  headline: `[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; ${held.sentence}`,
-                  queue,
-                  reconnectErr
-                );
-                failure.buffered = held.buffered;
-                throw said(failure);
+                }));
               }
             }
 
@@ -415,6 +425,39 @@ class PublishLayer {
     }
   }
 
+  /**
+   * The one ending for "the recovery this publish depended on did not arrive": hold the
+   * message (unless the caller said not to), report the failure, and build the error the
+   * caller gets — with `buffered` written on it and the verdict of a fatal ending carried on
+   * top (`carryVerdict()`, d.1297/d.1300).
+   *
+   * Two callers, one body (d.1300): the retry that waited for a reconnect in flight and saw
+   * it fail, and the attempt whose send channel could not be had because the connection
+   * stayed down (`RecoveryEndedPublishError`). Until d.1300 only the first held the message;
+   * the second threw the wait's ending raw, so two near-identical situations ended two ways
+   * (INFRA-DOCS ID254 point 1).
+   *
+   * @private
+   * @returns {Promise<PublishError>} the failure to throw; the caller writes `sent` on it
+   */
+  async _failedAfterRecovery({ queue, buffer, options, priority, attempt, transient, recoveryError, sentAny, headline }) {
+    const held = await this._holdOnFailure(queue, buffer, options, priority, transient, sentAny);
+    this._client.emit('publish:failed', {
+      queue,
+      attempt,
+      error: `Reconnection failed: ${recoveryError.message}`,
+      retryable: false,
+      reconnectFailed: true
+    });
+    const failure = new PublishError(
+      `${headline}Fix: read error.cause for the reconnect reason; ${held.sentence}`,
+      queue,
+      recoveryError
+    );
+    failure.buffered = held.buffered;
+    return carryVerdict(failure, recoveryError);
+  }
+
   /**
    * Handle publish error - buffer transient errors
    * @private
@@ -459,8 +502,42 @@ class PublishLayer {
           + 'the caller holds the only copy (error.buffered === false).'
       };
     }
+    // Asked AFTER the caller's explicit choice above (`architecture-principles.md` §8: the
+    // option the caller passed is what its sentence names), and before any hold.
+    // A client that will never reconnect on its own cannot replay anything: the two flushes
+    // are `reconnected` and `unblocked`, and neither comes after the connection is declared
+    // lost, after `disconnect()`, or with `reconnectEnabled: false`. Holding there is a loss
+    // with a delay (reported LOST at TTL), not a safety — so nothing is held, and the error
+    // says so (d.1301, the lead's decision narrowing B1 of d.1300). The transport writes the
+    // fact (`replayable`) where it knows the state; this layer only reads it.
+    if (err instanceof RecoveryEndedPublishError && err.replayable === false) {
+      this._logger.warn(
+        `[PublishLayer] Message for queue '${queue}' NOT buffered: this client will not reconnect, so no replay could come - ${err.message}`
+      );
+      return {
+        buffered: false,
+        sentence: 'the message is NOT buffered: this client will not reconnect on its own (the connection is '
+          + 'permanently lost, the caller closed it, or reconnectEnabled is false), so no reconnect could replay '
+          + 'it — the caller holds the only copy (error.buffered === false).'
+      };
+    }
     if (await this._bufferMessage(queue, buffer, options, priority, err, sent)) {
-      return { buffered: true, sentence: 'the message is buffered, so it is not lost.' };
+      // What the buffer WILL do, and nothing more (d.1275). It used to say "the message is
+      // buffered, so it is not lost" — while the only two flushes are the reconnect and
+      // `unblocked`, so an outage of the publisher channel alone ended with the message
+      // expiring (INFRA 531, W224). Whether a channel recovery should flush too is an open
+      // decision (a sent entry re-sent after it may be a duplicate); until it is made, the
+      // sentence states the gap instead of papering over it.
+      return {
+        buffered: true,
+        sentence: `the message is buffered for up to ${this._bufferTtlMs} ms (publishBufferTtlMs) and `
+          + 'replayed only after a reconnect or after the broker unblocks the connection — a recovered '
+          + 'publisher channel alone does not replay it; if neither comes within that time it expires and '
+          + (sent
+            ? 'is reported as an expired message whose frame had been sent (the broker may hold a copy) '
+            : 'is reported as LOST ')
+          + '(an error line naming the queue or exchange), and nothing replays it then.'
+      };
     }
     return {
       buffered: false,