@onlineapps/mq-client-core 5.0.0 → 6.0.0

package/src/utils/errorHandler.js

@@ -186,7 +186,32 @@ class SerializationError extends Error {
   }
 }
 
+/**
+ * Carry a verdict that is ALREADY written onto the error a caller is about to receive.
+ *
+ * The verdict of a lost connection is written in one place (`RabbitMQClient._failFatally()`,
+ * `_markBrokerRefusal()`: `code: 'MQ_CONNECTION_FATAL'`, `reason`). Every receiver reads it ON
+ * the error it is handed — `BaseClient._consumerRefusal()`, `@onlineapps/service-wrapper`
+ * FÁZE 0.3/0.7 — never down a `cause` chain (a reader walking the chain would be a fallback
+ * over a buried marker, `architecture-principles.md` §3). So every layer that builds an error
+ * AROUND a verdict copies `code` and `reason` onto it with this one function (d.1297 consume,
+ * d.1300 publish); an error that is not a fatal verdict (a spent cycle carries no code, by
+ * contract) leaves the target untouched.
+ *
+ * @param {Error} error - the error being built; `cause` already set by its builder
+ * @param {Error|null|undefined} verdict - what the recovery produced
+ * @returns {Error} the same error, with the verdict readable on top when there is one
+ */
+function carryVerdict(error, verdict) {
+  if (verdict && verdict.code === 'MQ_CONNECTION_FATAL') {
+    error.code = verdict.code;
+    error.reason = verdict.reason;
+  }
+  return error;
+}
+
 module.exports = {
+  carryVerdict,
   ValidationError,
   ConnectionError,
   CONNECTION_CLOSED_UNEXPECTEDLY,

package/src/utils/publishErrors.js

@@ -22,6 +22,54 @@ class TransientPublishError extends Error {
   }
 }
 
+/**
+ * The send channel could not be had because the connection stayed down: the recovery this
+ * attempt waited for ended without a connection (a spent cycle — standby; the last cycle or
+ * a broker refusal — fatal; a wait that completed into a connection already dead again), or
+ * no recovery may start (the client is permanently lost, the caller closed it, recovery is
+ * disabled by configuration).
+ *
+ * A TRANSIENT publish error, by the owner's decision (B1, 2026-10-06, d.1300): the message is
+ * held in the buffer like every other transiently failed message and replayed after the next
+ * `reconnected` / `unblocked` — one rail with the retry that waited for a reconnect and saw it
+ * fail (`PublishLayer`). What sets it apart from the other transient errors, and why it is its
+ * own class: retrying the attempt NOW is pointless and harmful — the next use of the client is
+ * what starts the next recovery cycle, so `PublishLayer` holds the message at once instead of
+ * spending its retry budget (and recovery cycles) on it.
+ *
+ * `cause` is the error that ended the wait when there was one (the fatal verdict is the very
+ * object `onFatal` received), and when that verdict is fatal its `code`/`reason` are carried on
+ * this error too (`errorHandler.carryVerdict()`), so a reader finds them where every reader
+ * looks. A spent cycle carries no code, by contract.
+ */
+class RecoveryEndedPublishError extends TransientPublishError {
+  /**
+   * @param {string} message
+   * @param {Error|undefined} cause - what ended the recovery, when an object exists for it
+   * @param {{replayable: boolean}} verdict - `replayable`: whether a `reconnected` can still
+   *   come on this client without the caller's action — true after a spent cycle (the next
+   *   use starts the next one), false once the client is permanently lost, closed by
+   *   `disconnect()`, or has `reconnectEnabled: false`. It decides whether `PublishLayer`
+   *   holds the message (d.1301): a hold only makes sense where a reconnect can replay it;
+   *   anywhere else it would sit until its TTL and be reported LOST, which is a loss with a
+   *   delay, not a safety. Required: a transient error that cannot say whether a replay can
+   *   come must not be held on a guess.
+   */
+  constructor(message, cause, verdict) {
+    super(message, cause);
+    this.name = 'RecoveryEndedPublishError';
+    if (!verdict || typeof verdict.replayable !== 'boolean') {
+      throw new Error(
+        '[RecoveryEndedPublishError] Missing required field - replayable (boolean) is required. '
+          + 'Expected: true when a reconnected can still come on this client, false when it never will '
+          + '(permanently lost, disconnect(), reconnectEnabled: false). '
+          + 'Fix: pass { replayable } — RabbitMQClient._recoveryEndedForPublish() derives it from the client state.'
+      );
+    }
+    this.replayable = verdict.replayable;
+  }
+}
+
 class PermanentPublishError extends Error {
   /**
    * @param {string} message - Human readable message
@@ -468,6 +516,7 @@ module.exports = {
   missingQueueDefinitionMessage,
   refusedSendMessage,
   TransientPublishError,
+  RecoveryEndedPublishError,
   PermanentPublishError,
   QueueNotFoundError,
   classifyPublishError,