@onlineapps/mq-client-core 4.0.0 → 4.0.1

package/CHANGELOG.md

@@ -4,6 +4,76 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [4.0.1] — 2026-09-17
+
+### Fixed — zrušení konzumenta brokerem přestalo být tiché (d.605)
+
+`basic.cancel` od brokera — smazaná fronta, přesun fronty při HA failoveru
+(`x-cancel-on-ha-failover`) — doručí amqplib do callbacku `consume()` jako
+zprávu `null`. Klient na ni odpovídal holým `return`: žádný záznam, žádná změna
+stavu, žádné znovupřipojení. Značka konzumenta zůstala nastavená, a protože
+právě ona je jediný fakt, kterým `performHealthCheck()` odpovídá „je konzument
+TOHOTO klienta připojený", hlásil klient `healthy: true` o frontě, ze které už
+nic nečetl. Ticho je vada stejné závažnosti jako špatný výsledek
+(`automation-gates.md` §5).
+
+Nově v tomto pořadí: značka se zahodí (týž fakt, který d.386b zavedl pro
+odmítnutou re-registraci — od té chvíle je klient `unhealthy` a jmenuje frontu),
+ztráta se zapíše na úrovni **error** se jménem fronty i zrušené značky, a
+konzument se znovu připojí **kolejí, kterou už používá obnova kanálu**: tělo
+smyčky `_reRegisterConsumers()` dostalo jméno (`_reRegisterConsumer()`) a cancel
+volá tutéž funkci pro jednu frontu. Celá smyčka by znovu připojila i konzumenty,
+kteří o své místo nepřišli.
+
+Klasifikaci, deklaraci a prefetch tedy dělá `_prepareQueueForConsume()` —
+vlastněná business fronta se znovu deklaruje, nevlastněná infrastrukturní se jen
+`checkQueue` a její absence je odmítnutí se značkou `CONSUMER_QUEUE_MISSING`,
+nikdy tiché založení. Odmítnuté znovupřipojení nechá konzumenta sledovaného bez
+značky a důvod jede na události, kterou balíček už má —
+`consumer:re-registration:failed`.
+
+**Žádný nový veřejný kontrakt**: žádná nová metoda, žádná nová událost, žádná
+změna podpisu. Každý stav, do kterého se cesta může dostat, už balíček hlásí.
+
+Ticho zůstává tam, kde zrušení není vada: vlastní `cancelConsumer()` callback
+vůbec nevolá (amqplib odregistruje konzumenta na `basic.cancel-ok`; broker
+neposílá cancel), a cancel, který dorazí během `disconnect()`, je zapsán na
+úrovni debug — úmyslné zavření není porucha.
+
+Kdo z toho co má: každá služba, která konzumuje frontu, se po re-pinu na tuto
+verzi dozví, že o konzumenta přišla — dnes to nepozná ani z logu, ani ze
+zdravotní kontroly.
+
+### Fixed — „připojený konzument" má jednu definici, a čte ji i levný reportér (d.613)
+
+`getConsumerState()` vracelo jako `active` klíče `_activeConsumers`, tedy
+konzumenty, které klient **sleduje**. `_performHealthCheck()` odpovídá na tutéž
+otázku podle značky (`consumerInfo.consumerTag`), kterou d.386b a d.605 nechávají
+nastavenou jen po dobu skutečného připojení. Jeden soubor, dvě definice slova
+„aktivní" — a rozcházely se přesně tam, kde na tom záleží: konzument, jemuž
+někdo smazal frontu a jehož znovupřipojení broker odmítl (406), zůstává
+sledovaný bez značky, takže zdravotní kontrola hlásila 0 připojených, kdežto
+`getConsumerState()` frontu dál jmenovalo jako aktivní.
+
+To není kosmetika. `getConsumerState()` je ta **levná synchronní** odpověď, na
+kterou se čtenář dostane: `docs/standards/rabbitmq-channel-best-practices.md`
+§ „Consumers stop receiving after a reconnect" i
+`docs/operations/rabbitmq-connection-recovery-troubleshooting.md` posílají
+operátora právě sem pro tento případ — a dostal odpověď, že konzument je aktivní.
+
+Nově obě čtení volají jednu privátní funkci `_isConsumerAttached(consumerInfo)`;
+`active` jmenuje **připojené** fronty a `tracked` zůstává počtem sledovaných,
+takže `tracked > active.length` je celá věta „tento klient z některé fronty nic
+nebere". Tvar návratové hodnoty se nemění (žádný klíč nepřibyl ani nezmizel),
+mění se pravdivost hodnoty `active`; mimo tento balíček ji dnes nečte žádný kód
+(změřeno přes `api`, `api_biz/*`, `fe_adminui`), takže se nic dalšího
+nepřepisuje.
+
+Kdo z toho co má: `@onlineapps/conn-infra-mq` to po re-pinu pošle dál ve
+`getHealth().consumers` a `@onlineapps/service-wrapper` z toho odvodí
+`components.mq` — služba se ztraceným konzumentem přestane být v heartbeatu
+`healthy`.
+
 ## [4.0.0] — 2026-09-16
 
 ### Changed — značku odmítnutí nese i deklarační rail, jednou funkcí pro obě cesty (d.582)

package/README.md

@@ -187,7 +187,10 @@ Owner decision: `api/docs/governance/confirmations/connector-logger-contract.md`
   three channels, the consumers this client holds, and what is waiting in the
   publish buffer (`{ size, inMemory }` — there is one buffer). All five refuse
   before `connect()` has built a transport, rather than answering with an invented
-  zero.
+  zero. `getConsumerState()` answers `{ tracked, active }`: `tracked` counts the
+  consumers this client would restore, `active` names the ones ATTACHED right now
+  — the same question the health check asks — so `tracked > active.length` says
+  this client takes no message off some queue it registered.
 - `disconnectAll()` (static, on the class and on the package export) - Close every
   client this module holds; see § Shutdown.
 - `onError(callback)` - Register error handler
@@ -328,6 +331,39 @@ There is no third meaning. `requeueOnError: false` together with `maxAttempts`
 above 1 is a contradiction and is **refused where it was written**, rather than
 one of the two being silently ignored.
 
+#### A cancel from the BROKER — the consumer that was stopped without asking
+
+`basic.cancel` sent by the broker is how a consumer learns its attachment is gone
+while the channel and the connection stay up: the queue was deleted, or the broker
+moved it (`x-cancel-on-ha-failover`). amqplib delivers it to the consume callback
+as a `null` message, and it reaches nothing else in this client — the channel
+handlers listen for `error` and `close`, and both stay silent.
+
+It is **not** a silent event. In this order:
+
+- the consumer's tag is dropped, because it names an attachment the broker no
+  longer holds — so `performHealthCheck()` stops counting that consumer as
+  attached the moment the cancel arrives, rather than one recovery later;
+- the loss is logged at **error** level, naming the queue and the tag the broker
+  cancelled;
+- the consumer is re-attached on the rail a channel recreate uses, for that queue
+  alone: the queue is classified, declared or checked and the prefetch re-applied
+  exactly as `consume()` does it. So a business queue the service owns is
+  re-declared, and an infrastructure queue this client does not own is only
+  checked — a deleted one is refused with `CONSUMER_QUEUE_MISSING`, never
+  silently recreated.
+
+If that re-attachment is refused, the consumer stays **tracked with no tag** — the
+same state a refused re-registration leaves — so the client reports itself
+unhealthy and names the queue, `consumer:re-registration:failed` carries the
+broker's reason and code, and the next channel recreate tries again.
+
+Two cancels that are NOT this: `cancelConsumer()` on this client (the broker
+answers `basic.cancel-ok`, the callback is never invoked, and the consumer is
+dropped from the registry on purpose), and a cancel arriving while
+`disconnect()` is running — an intentional close is not a fault, and it is
+recorded at debug level.
+
 ### Connection loss — the contract
 
 When the broker goes away, the transport runs connection-level recovery with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "oa": {
     "category": "connector"

package/src/BaseClient.js

@@ -1125,9 +1125,14 @@ class BaseClient {
   }
 
   /**
-   * The consumers this client currently holds: how many, and on which queues.
+   * The consumers this client currently holds: how many it TRACKS, and which of
+   * them are ATTACHED right now. A consumer whose queue was deleted, or whose
+   * re-registration the broker refused, stays tracked without its tag — so
+   * `tracked > active.length` says this client takes no message off some queue
+   * it registered (d.613; one definition of "attached",
+   * `RabbitMQClient._isConsumerAttached()`).
    *
-   * @returns {Object} `{ tracked: <count>, active: [<queue names>] }`
+   * @returns {Object} `{ tracked: <count>, active: [<attached queue names>] }`
    * @throws {ConnectionError} Before `connect()` has built a transport.
    */
   getConsumerState() {

package/src/transports/rabbitmqClient.js

@@ -525,13 +525,52 @@ class RabbitMQClient extends EventEmitter {
   }
 
   /**
-   * Get current consumer state
-   * @returns {Object} Consumer state information
+   * THE definition of "this client's consumer is attached to that queue".
+   *
+   * The tag is the one fact that is about THIS client: the broker gives it to
+   * the attachment it created, and since d.386b / d.605 the entry carries it
+   * only while that attachment exists — a refused re-registration and a cancel
+   * sent by the broker both drop it while the consumer stays TRACKED, because
+   * the next recovery must find it on the list.
+   *
+   * It is a method rather than an expression repeated twice for the reason
+   * `change-discipline.md` § One rail per concern states: until d.613
+   * `getConsumerState()` answered from `_activeConsumers.keys()` and
+   * `_performHealthCheck()` from the tag, so one file held two definitions of
+   * "active" — and the cheap synchronous reader, the one a service and an
+   * operator actually read, was the one that answered about a consumer the
+   * broker had already cancelled.
+   *
+   * @param {Object|undefined} consumerInfo - The entry `_activeConsumers` holds
+   * @returns {boolean}
+   * @private
+   */
+  _isConsumerAttached(consumerInfo) {
+    return typeof consumerInfo?.consumerTag === 'string' && consumerInfo.consumerTag !== '';
+  }
+
+  /**
+   * Get current consumer state.
+   *
+   * `tracked` counts the consumers this client would restore; `active` names the
+   * ones that are ATTACHED right now (`_isConsumerAttached()`, the same question
+   * `_performHealthCheck()` asks). `tracked > active.length` is therefore the
+   * cheap, synchronous statement that this client takes no message off some
+   * queue it registered — the state
+   * `docs/operations/rabbitmq-connection-recovery-troubleshooting.md` sends an
+   * operator here to read, and which the queue-name list could not carry.
+   *
+   * @returns {{tracked: number, active: string[]}} Consumer state information
    */
   getConsumerState() {
+    const active = [];
+    for (const [queue, consumerInfo] of this._activeConsumers.entries()) {
+      if (this._isConsumerAttached(consumerInfo)) active.push(queue);
+    }
+
     return {
       tracked: this._activeConsumers.size,
-      active: Array.from(this._activeConsumers.keys())
+      active
     };
   }
 
@@ -1858,54 +1897,160 @@ class RabbitMQClient extends EventEmitter {
     if (this._activeConsumers.size > 0) {
       this._logger.info(`[RabbitMQClient] [mq-client-core] Re-registering ${this._activeConsumers.size} consumers...`);
       for (const [queue, consumerInfo] of this._activeConsumers.entries()) {
-        try {
-          await this._prepareQueueForConsume(queue, {
-            durable: consumerInfo.options.durable,
-            queueOptions: consumerInfo.options.queueOptions
-          });
-
-          // The consumer's prefetch is re-applied here for the same reason the
-          // queue step is: the channel is new, and QoS lives on the channel.
-          await this._applyConsumerPrefetch(queue, consumerInfo.options.prefetch);
-
-          const consumeResult = await this._consumerChannel.consume(
-            queue,
-            consumerInfo.handler,
-            { noAck: consumerInfo.options.noAck }
-          );
-          consumerInfo.consumerTag = consumeResult.consumerTag;
+        if (await this._reRegisterConsumer(queue, consumerInfo)) {
           reRegistered++;
-          this._logger.info(`[RabbitMQClient] [mq-client-core] \u2713 Re-registered consumer for queue: ${queue} (consumerTag: ${consumeResult.consumerTag})`);
-        } catch (err) {
+        } else {
           failed++;
-          this._logger.error(`[RabbitMQClient] [mq-client-core] Failed to re-register consumer for queue ${queue}:`, err.message);
-          // The consumer STAYS tracked. Whatever refused it — a 406 against the
-          // owner's declaration, a missing infrastructure queue, a channel that
-          // went away mid-flight — is a condition somebody fixes at its source,
-          // and the next recreate must find the consumer still on the list.
-          //
-          // Its TAG does not stay, and the two are not the same fact (d.386b). A
-          // consumer tag names an attachment on ONE channel; the channel that
-          // issued this one is gone and the new one refused to re-attach, so the
-          // string the entry carried names nothing on the broker. Two readers
-          // took it for an attachment that exists: `_performHealthCheck()` counts
-          // `active` by "is the tag set", so a client whose only consumer had
-          // just been refused reported `healthy: true` and `1/1 consumers active`
-          // — the false OK d.386 exists to end, one layer below where d.386 could
-          // reach it; and `cancelConsumer()` sent `basic.cancel` with it, asking
-          // the broker to stop a consumer it does not hold.
-          consumerInfo.consumerTag = null;
-          // The broker's own code is what a listener acts on (406 = the queue
-          // exists with different arguments), and the rail wraps it in a typed
-          // error, so it is read from the cause when the wrapper carries none.
-          const code = err.code !== undefined ? err.code : (err.cause ? err.cause.code : undefined);
-          this.emit('consumer:re-registration:failed', { queue, error: err.message, code });
         }
       }
     }
     return { reRegistered, failed };
   }
 
+  /**
+   * Re-attach ONE tracked consumer on the current consumer channel.
+   *
+   * This is the body of the loop above, given a name in d.605 because a second
+   * event needs exactly it: `basic.cancel` from the broker takes ONE consumer
+   * away while every other one stays attached, so re-running the whole loop
+   * would re-attach consumers that never lost their place — a second
+   * `basic.consume` for each of them on the broker. One rail, one set of
+   * consequences (`change-discipline.md` § One rail per concern).
+   *
+   * Everything a first `consume()` does is done here: the queue is classified,
+   * declared or checked by `_prepareQueueForConsume()` — so an owned business
+   * queue is re-declared and an unowned infrastructure queue is only checked,
+   * its absence answered with `CONSUMER_QUEUE_MISSING` rather than a silent
+   * creation — and the prefetch is re-applied, because QoS lives on the channel.
+   *
+   * @param {string} queue - Queue name
+   * @param {Object} consumerInfo - The entry `_activeConsumers` holds for it
+   * @returns {Promise<boolean>} `true` when the consumer is attached again
+   * @private
+   */
+  async _reRegisterConsumer(queue, consumerInfo) {
+    try {
+      await this._prepareQueueForConsume(queue, {
+        durable: consumerInfo.options.durable,
+        queueOptions: consumerInfo.options.queueOptions
+      });
+
+      // The consumer's prefetch is re-applied here for the same reason the
+      // queue step is: the channel is new, and QoS lives on the channel.
+      await this._applyConsumerPrefetch(queue, consumerInfo.options.prefetch);
+
+      const consumeResult = await this._consumerChannel.consume(
+        queue,
+        consumerInfo.handler,
+        { noAck: consumerInfo.options.noAck }
+      );
+      consumerInfo.consumerTag = consumeResult.consumerTag;
+      this._logger.info(`[RabbitMQClient] [mq-client-core] ✓ Re-registered consumer for queue: ${queue} (consumerTag: ${consumeResult.consumerTag})`);
+      return true;
+    } catch (err) {
+      this._logger.error(`[RabbitMQClient] [mq-client-core] Failed to re-register consumer for queue ${queue}:`, err.message);
+      // The consumer STAYS tracked. Whatever refused it — a 406 against the
+      // owner's declaration, a missing infrastructure queue, a channel that
+      // went away mid-flight — is a condition somebody fixes at its source,
+      // and the next recreate must find the consumer still on the list.
+      //
+      // Its TAG does not stay, and the two are not the same fact (d.386b). A
+      // consumer tag names an attachment on ONE channel; the channel that
+      // issued this one is gone and the new one refused to re-attach, so the
+      // string the entry carried names nothing on the broker. Two readers
+      // took it for an attachment that exists: `_performHealthCheck()` counts
+      // `active` by "is the tag set", so a client whose only consumer had
+      // just been refused reported `healthy: true` and `1/1 consumers active`
+      // — the false OK d.386 exists to end, one layer below where d.386 could
+      // reach it; and `cancelConsumer()` sent `basic.cancel` with it, asking
+      // the broker to stop a consumer it does not hold.
+      consumerInfo.consumerTag = null;
+      // The broker's own code is what a listener acts on (406 = the queue
+      // exists with different arguments), and the rail wraps it in a typed
+      // error, so it is read from the cause when the wrapper carries none.
+      const code = err.code !== undefined ? err.code : (err.cause ? err.cause.code : undefined);
+      this.emit('consumer:re-registration:failed', { queue, error: err.message, code });
+      return false;
+    }
+  }
+
+  /**
+   * The broker cancelled one of this client's consumers.
+   *
+   * `basic.cancel` sent BY THE BROKER is not an error frame and does not touch
+   * the channel or the connection: the queue was deleted, or the broker moved it
+   * (`x-cancel-on-ha-failover`). Nothing else in this client hears it — the
+   * channel handlers listen for `error` and `close`, and both stay silent — so
+   * this method is the whole of the client's answer, and until d.605 that answer
+   * was nothing at all.
+   *
+   * Three things happen, in this order:
+   *
+   *   1. the TAG is dropped, first, because it is the one fact
+   *      `_performHealthCheck()` reads to answer "is THIS client's consumer
+   *      attached" (d.386b). Dropping it before anything else leaves no window in
+   *      which the check reports an attachment the broker has already cancelled;
+   *   2. the loss is stated at ERROR level, naming the queue and the cancelled
+   *      tag. A consumer that stops reading a queue is not a debug-level event,
+   *      and the record is what tells an operator which queue went quiet;
+   *   3. the consumer is re-attached through `_reRegisterConsumer()`, the rail a
+   *      channel recreate already uses. A refusal there keeps the consumer
+   *      tracked with no tag and travels on `consumer:re-registration:failed` —
+   *      which is why this method introduces no event and no public method of its
+   *      own: every state it can reach is a state the package already reports.
+   *
+   * @param {string} queue - The queue whose consumer the broker cancelled
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _onBrokerCancel(queue) {
+    if (this._closedByCaller) {
+      // An intentional close is not a fault — the doctrine `disconnect()` states
+      // and both channel handlers already follow.
+      this._logger.debug(
+        `[RabbitMQClient] [mq-client-core] [CONSUMER] Broker cancelled the consumer for queue "${queue}" while the client was being closed by its caller - no alarm, no re-attachment`
+      );
+      return;
+    }
+
+    const consumerInfo = this._activeConsumers.get(queue);
+    const cancelledTag = consumerInfo ? consumerInfo.consumerTag : null;
+
+    if (consumerInfo) {
+      consumerInfo.consumerTag = null;
+    }
+
+    this._logger.error(
+      `[RabbitMQClient] Consumer cancelled by the broker - the consumer on queue "${queue}" `
+        + `(consumerTag: ${cancelledTag}) was stopped by the BROKER, not by this client: the queue `
+        + 'was deleted, or the broker moved it (x-cancel-on-ha-failover). '
+        + 'Expected: a consumer stays attached until cancelConsumer() or disconnect(). '
+        + 'Fix: none here - the client re-attaches it on the rail a channel recreate uses; if that '
+        + 'is refused, the consumer stays tracked with no tag, performHealthCheck() reports this '
+        + 'client unhealthy and names the queue, and consumer:re-registration:failed carries the '
+        + 'broker reason.',
+      { queue, consumerTag: cancelledTag }
+    );
+
+    if (!consumerInfo) {
+      // The client no longer holds this consumer, so there is nothing to
+      // re-attach and no state left to correct. The loss is still stated above.
+      return;
+    }
+
+    if (!this._isChannelAlive(this._consumerChannel)) {
+      // Re-attaching on a dead channel is not this method's job: the channel
+      // recovery re-registers every tracked consumer when it recreates the
+      // channel (d.262), and the consumer stays tracked for exactly that.
+      this._logger.warn(
+        `[RabbitMQClient] [mq-client-core] [CONSUMER] Consumer for queue "${queue}" stays tracked and unattached - the consumer channel is not alive, so the channel recovery re-registers it`
+      );
+      return;
+    }
+
+    await this._reRegisterConsumer(queue, consumerInfo);
+  }
+
   /**
    * Disconnects: closes channel and connection.
    * @returns {Promise<void>}
@@ -2061,8 +2206,10 @@ class RabbitMQClient extends EventEmitter {
             // this client's and everybody else's alike, so it cannot say whether
             // the one asking is among them. The tag can: it is the name the
             // broker gave THIS client's attachment, and since d.386b it is set
-            // only while that attachment exists.
-            if (consumerInfo.consumerTag) {
+            // only while that attachment exists. The question is asked through
+            // `_isConsumerAttached()` — the one definition `getConsumerState()`
+            // now reads too (d.613).
+            if (this._isConsumerAttached(consumerInfo)) {
               health.consumers.active++;
             } else {
               health.consumers.inactive.push(queue);
@@ -3532,7 +3679,21 @@ class RabbitMQClient extends EventEmitter {
       // Wrap handler to track message processing and prefetch utilization
       const messageHandler = async (msg) => {
         if (msg === null) {
-          return; // Consumer cancellation
+          // `null` is not a message. It is `basic.cancel` FROM THE BROKER,
+          // handed to this callback by amqplib (`handleCancel()` →
+          // `dispatchMessage(fields, null)`), and it is the only way a consumer
+          // learns that its attachment is gone while the channel and the
+          // connection stay up: the queue was deleted, or the broker moved it
+          // (`x-cancel-on-ha-failover`).
+          //
+          // Until d.605 the answer was this bare `return`. Nothing was logged,
+          // the tag stayed set — so `_performHealthCheck()` went on counting the
+          // consumer as attached — and nothing re-attached it. The service
+          // reported itself healthy while no message was taken off the queue,
+          // which is the failure `automation-gates.md` §5 calls a defect of the
+          // same severity as a wrong result.
+          await this._onBrokerCancel(queue);
+          return;
         }
 
         // IMPORTANT: