@onlineapps/mq-client-core 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -4,6 +4,151 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [5.1.0] — 2026-10-03
+
+### Added
+
+- `publish(queue, message, { bufferOnFailure: false })` — volba pro jedno volání: zpráva, jejíž
+  publikace selhala přechodně (vyčerpané pokusy, `publishRetryEnabled: false`, selhaný reconnect,
+  na který retry čekal), se NEuloží do bufferu, takže ji žádný reconnect znovu neodešle. Výchozí
+  `true` = chování beze změny. Pro volajícího, který zprávu drží trvale jinde (orchestrátor,
+  `publish_pending`, conf `step-publish-failure` 001; d.1122). Hodnota jiná než boolean se
+  odmítne `ValidationError` před prvním pokusem.
+- Chyba ze tří přechodných cest nese `buffered` (boolean) — na chybě `PublishLayer` i na obalu
+  `PublishError` z `BaseClient.publish()`: `true` jen když buffer zprávu opravdu drží. Trvalé
+  odmítnutí `buffered` nenese. Věta `Fix:` chyby už neslibuje „is buffered“ tam, kde zpráva
+  v bufferu není (volba `false`, nebo buffer zprávu nepřijal).
+- Chyba publishe nese `sent` (boolean) — zda rámec zprávy OPUSTIL klienta (`sendToQueue()` /
+  `publish()` kanálu vrátil bez výjimky), vedle `buffered` z d.1122: na obalu `PublishError`
+  z `BaseClient.publish()` i na chybě `PublishLayer` (`true`, když ho odeslal KTERÝKOLI pokus
+  volání); chyba jednoho pokusu transportu (`_publishOnce()`) nese `sent` toho pokusu. Záznam
+  bufferu nese totéž. Neříká nic o tom, zda broker zprávu uložil: při memory alarmu broker
+  odeslané rámce doručí sám po jeho zrušení (d.1143: 3 kopie publishe na exchange, 1 kopie
+  prvního publishe do fronty, 0 u neodeslaného). Rozhodnutí vlastníka
+  `docs/governance/confirmations/mq-publish-buffer.md` 001 (D); orchestrátor ho kopíruje do
+  záznamu `publish_pending` (`step-publish-failure` 003). Chyba transportu bez booleovského
+  `sent` je vada souseda: `PublishLayer` ji odmítne jménem a zprávu nebufferuje (d.1145).
+
+### Changed
+
+- Každé čekání na odpověď brokera má limit `brokerAnswerTimeout` — jedna kolej, žádný nový klíč
+  (rozhodnutí vlastníka, `docs/governance/confirmations/mq-broker-answer-budget.md` 001, verdikt A;
+  d.1135). Dosud ho mělo jen potvrzení publishe a `close-ok` při `disconnect()`; `assertQueue`,
+  `checkQueue` (veřejné i kontrola před publishem do fronty), `bindQueue`, `assertExchange`,
+  `purgeQueue`, `deleteQueue`, `consume`, `cancelConsumer`, prefetch a otevření kanálu
+  (`createChannel` / `createConfirmChannel`, při `connect()`, obnově i reconnectu) čekaly bez
+  limitu. Změřeno d.1126 na izolovaném brokeru platformního obrazu: při alarmu paměti (spojení
+  žije, heartbeat teče) visela po 300 s, u zmrazeného brokeru je ukončil až heartbeat po ~90 s.
+  Co se mění pro volajícího — hodnotami:
+  - volání, na které broker v limitu neodpoví, skončí po `brokerAnswerTimeout` chybou
+    `ConnectionError` s větou `The broker did not answer <operace> <cíl> within
+    brokerAnswerTimeout (<N>ms)`; kanál, který požadavek nesl, se vyřadí a příští operace otevře
+    nový (kanál, který broker otevře až po limitu, se hned zavře);
+  - publish do fronty, jehož kontrola `checkQueue` (nebo obnova kanálu) nedostala odpověď, je
+    přechodné selhání: `TransientPublishError` → retry → buffer, s `bufferOnFailure: false`
+    `PublishError(cause=TransientPublishError)` a `buffered: false` (D2, conf
+    `step-publish-failure` 001);
+  - holé `Channel ended, no reply will be forthcoming` z amqplibu (kanál nebo spojení skončilo
+    dřív, než broker odpověděl) se na těchto voláních vrací jako `ConnectionError` s původní
+    chybou v `cause`; číslované odmítnutí brokera (404, 406, …) zůstává beze změny;
+  - `connect()`, jemuž broker neodpoví na otevření kanálu, skončí do limitu a zavře spojení
+    v témže limitu (neodpovězené zavření zahodí socket jako `disconnect()`).
+  Heartbeat, potvrzení publishe a teardown beze změny.
+- Klient poslouchá `blocked`/`unblocked` svého spojení (broker v memory/disk alarmu blokuje
+  spojení, které publikuje; d.1143 změřil na obrazu platformy). `blocked` = `warn` s důvodem
+  brokera; `unblocked` = `warn` a flush bufferu jednou kolejí `PublishLayer.flushBuffered('unblocked')`:
+  znovu se pošle JEN záznam, jehož rámec nikdy neopustil klienta; záznam s `sent: true` se vyřadí
+  s `warn` (fronta/exchange, stáří v bufferu), protože broker podržené rámce po alarmu doručí sám.
+  Flush po reconnectu beze změny — `flushBuffered('reconnected')` pošle všechno. Změřeno na
+  izolovaném brokeru d1145-rmq: po uvolnění alarmu u brokera 3 kopie odeslaného publishe na
+  exchange (beze změny, žádná navíc), 1 kopie odeslaného prvního publishe do fronty (beze změny)
+  a nově 1 kopie publishe, který se neodeslal (dřív 0 a tichá expirace); buffer po uvolnění
+  prázdný (dřív 2 a 1). Rozhodnutí vlastníka `docs/governance/confirmations/mq-publish-buffer.md`
+  001 (D), d.1145.
+- `PublishLayer.flushBuffered(trigger)` — jediný argument je nově POVINNÝ spouštěč
+  `'reconnected'` | `'unblocked'` (rozhoduje, co se stane se záznamem, jehož rámec už odešel);
+  jiná hodnota se odmítne jménem. `InMemoryBuffer.flush(flushFn, { sentEntries })` totéž
+  (`'resend'` | `'drop'`). Uvnitř balíčku jediný volající je transport (d.1145).
+  Druhý argument `flushOptions` (slučoval se do voleb každé znovu poslané zprávy) je PRYČ:
+  nikdo ho nepředával (0 volajících v `shared/**`, `infra/**`, `api_biz/*/src`); znovu poslaná
+  zpráva nese přesně volby, se kterými ji buffer držel (d.1145).
+- Vypršení zprávy v bufferu je `error`, ne `info`: jeden řádek na cíl (fronta nebo exchange)
+  a hodnotu `sent`, s počtem, stářím nejstarší a TTL; `sent=false` = zpráva je ZTRACENÁ,
+  `sent=true` = broker ji mohl doručit sám. Dřív „Removed N expired buffered messages“ bez
+  fronty i stáří. Rozhodnutí vlastníka `docs/governance/confirmations/mq-publish-buffer.md`
+  001 (D), d.1145.
+- Publish, jehož potvrzení ještě čekalo, když broker zavřel spojení nebo kanál (`320
+  CONNECTION_FORCED`, restart či stop brokeru, výpadek spojení), končil `PermanentPublishError`
+  bez bufferu a bez retry — zpráva byla ztracena, ač o ní broker nic neřekl (měřeno d.1126).
+  Příčina: amqplib odpovídá nepotvrzeným publishům `Error('channel closed')` ze svého `close`
+  posluchače registrovaného v konstruktoru kanálu, tedy DŘÍV, než klient kanál označil za
+  mrtvý; callback pak četl živý kanál. Klientův `close` posluchač send kanálu se nyní
+  registruje `prependListener` a běží první, takže tahle cesta je přechodná
+  (`TransientPublishError`) a jde dnešní cestou retry/buffer, včetně `bufferOnFailure: false`
+  (`buffered: false`). `nack` brokeru a číslovaný close frame této zprávy zůstávají trvalé
+  (d.1134).
+- Hláška `PublishError` větve fronty při zavření kanálu s čekajícím potvrzením tvrdila „and not
+  reconnecting“ — v S3 nepravda: spojení v tu chvíli ještě neohlásilo `close` a reconnect
+  následuje. Nově: „Channel closed during publish to queue "<q>" before the broker confirmed the
+  message …“, bez tvrzení o reconnectu, `Fix:` odkazuje na `error.buffered` (d.1134).
+- Re-registrace konzumentů po obnově kanálu se ptá na živost konzumentského kanálu před KAŽDÝM
+  konzumentem (a znovu po kroku fronty), ne jednou před smyčkou. Kanál, který zemřel uprostřed
+  smyčky (zavřel ho broker, nebo ho vyřadil `brokerAnswerTimeout`, d.1135), dřív vedl
+  u dalšího konzumenta na `TypeError: Cannot read properties of null (reading 'consume')`
+  a na zbytečnou deklaraci jeho fronty. Nově `ConnectionError` „Cannot re-register the consumer
+  of <q>: consumer channel is not available …“ v `consumer:re-registration:failed`; konzument
+  zůstává sledovaný bez tagu a obnoví ho příští obnova, jako dosud (d.1138).
+- Hláška `_waitForReconnection()` po vypršení jmenovala env `RABBITMQ_RECONNECT_WAIT_TIMEOUT`,
+  který nic nečte. Nově jmenuje, co se čte: klíč konfigurace `reconnectWaitTimeout` („set in the
+  client configuration“), nebo odvození `max(60000, maxReconnectAttempts × reconnectMaxDelay)`,
+  když klíč zadaný není; `Fix:` odkazuje na tentýž klíč. Chování beze změny (d.1138).
+- Přechodná chyba cesty publishe (`_publishPathTransient()`) tvrdila „queue channel is not
+  available (connection may be closed)“ i při ŽIVÉM spojení blokovaném memory alarmem (d.1143,
+  nález 3; od d.1135 končí touto chybou i neodpovězená kontrola `checkQueue`). Věta se nově
+  volí ze stavu klienta: zavřené spojení → „the connection is closed“; blokované → „the broker
+  has blocked this connection (reason: …)“; jinak „the queue channel is not available on a
+  live, unblocked connection“ s příčinou v `error.cause`. Třída beze změny (d.1145).
+
+### Fixed
+
+- Spojení, které obnova navázala až po `disconnect()` volajícího, se zavírá v rozpočtu
+  `brokerAnswerTimeout` (`_closeWithinTeardownBudget()`, jedna kolej, conf
+  `mq-broker-answer-budget` 001). Dřív `await revived.close()` bez limitu: broker, který v tu
+  chvíli neodpovídal, držel kolo obnovy (`_reconnecting: true`) a socket otevřené navždy.
+  Neodpovězené zavření nově zahodí socket jako teardown (d.1138).
+
+### Documentation — JSDoc a popis klíče na pravdu, docblock jedné koleje `workflow_initiated` bez smazané cesty (d.1134, d.1138, d.1176)
+
+- JSDoc `workflowIdOf()` tvrdil, že alias `workflowId` dosud píše webhook submit gatewaye.
+  Nepravda: žádný producent v `shared/**` ani `infra/**` alias nepíše (hlavičky gatewaye nesou
+  jen `workflow_id`, `infra/api_gateway/shared/workflowMessageHeaders.js`); čtení aliasu
+  v transportu neexistuje od d.416, chování beze změny (d.1134).
+- Popis klíče `heartbeat` v `configSchema.js` na pravdu: hodnota se navrhuje brokeru v URL
+  spojení (ne „předává se amqplibu“) a `0` heartbeat NEVYPNE — vyjednávání amqplibu vezme
+  stranu, která limit stanoví, tedy hodnotu brokera (změřeno d.1126: pauza zjištěna po 179 s).
+  Chování beze změny (d.1138).
+- Docblock `src/monitoring-initiated.js` popisuje rozhodnutí o jedné koleji události
+  `workflow_initiated` (conf `scheduler` 009 a 024) bez cesty na smazaný soubor gatewaye
+  a bez vyprávění o kopiích, které to rozhodnutí rušilo; chování beze změny (d.1176).
+
+### Tests — sady bez nástěnného času a s pravdivým popisem bloku (d.1174, d.1138)
+
+- Test, ne chování: sada `connect-timeout-closes-late-handshake.test.js` čekala nástěnný čas
+  (`connectTimeout` 20 ms, pak `setTimeout` 80 ms na druhý pokus reconnectu) a pod zátěží runneru
+  `oa-staging` (pipeline 2904670335) četla `amqp.connect` 2× místo 3×, proto hodiny teď řídí
+  test (`jest.useFakeTimers()` + `advanceTimersByTimeAsync`) a výsledek nezávisí na zátěži
+  stroje (d.1174).
+- Popis bloku testu `connection-parameters-reach-the-broker.test.js` („…one name for its two
+  consumers“) srovnán s d.1135: budget `brokerAnswerTimeout` platí pro každé čekání na odpověď
+  brokera, ne pro dva konzumenty (d.1138).
+- Test, ne chování: akceptační sada čekací koleje `waiting-helper.test.js` měřila vzorkování
+  `waitForValue`/`waitForEvent` na nástěnných hodinách a pod loadem 17–30 (pre-K sweep
+  `release/w4`) vzorek rastru 20 ms zpožděný o víc než 40 ms minul okno 150–190 ms, takže
+  „s `pollMs: 20` tentýž stav VIDÍ" četl `true`; hodiny teď řídí test (`jest.useFakeTimers()`
+  + `advanceTimersByTimeAsync`, čas čte `jest.now()`); hodnoty a počty v tvrzeních beze změny,
+  podlahy pauzy přesně podle pravidla, bez rezervy na plánovač; kolej `tests/waiting.js`
+  nedotčena (d.1192).
+
 ## [5.0.0] — 2026-09-27
 
 ### Removed — BREAKING — fronta `workflow.control` (d.1061)

package/README.md

@@ -86,11 +86,18 @@ says" — and every connection on the platform ran on the broker's number rather
 the configured one (measured on the dev broker: 39 live connections, `timeout: 60`
 on all of them).
 
-`brokerAnswerTimeout` bounds **both** things this client waits for the broker to
-answer: the confirm of one publish attempt, and the `close-ok` of each handle
-`disconnect()` closes. It was called `publishConfirmationTimeout` until
-2026-09-14 — the name of one of its two consumers — and writing that name now is
-refused, with the new one named.
+`brokerAnswerTimeout` bounds **every** wait on the broker's answer — the confirm of
+one publish attempt, the `close-ok` of each handle `disconnect()` closes, and every
+request a channel sends and waits on: `assertQueue`, `checkQueue` (also the check before a
+queue publish), `bindQueue`, `assertExchange`, `purgeQueue`, `deleteQueue`, `consume`,
+`cancelConsumer`, the prefetch, and every channel open (conf `mq-broker-answer-budget` 001).
+A request left unanswered for that long discards the channel that carried it (the next
+operation opens a fresh one) and ends in `ConnectionError` naming the operation, its target
+and the budget; on the publish path it is `TransientPublishError`, so retry, the buffer and
+`bufferOnFailure: false` apply as to any transient failure. This is what ends the wait on a
+broker in a memory alarm, which keeps the connection and its heartbeats alive while it
+answers nothing. It was called `publishConfirmationTimeout` until 2026-09-14 — the name of
+one of its consumers — and writing that name now is refused, with the new one named.
 
 `maxReconnectAttempts` and `maxReconnectCycles` resolve the usual way — explicit
 config → env (`RABBITMQ_MAX_RECONNECT_ATTEMPTS`, `RABBITMQ_MAX_RECONNECT_CYCLES`)
@@ -134,7 +141,10 @@ Owner decision: `api/docs/governance/confirmations/connector-logger-contract.md`
 
 - `connect(options?)` - Connect to RabbitMQ
 - `disconnect()` - Disconnect from RabbitMQ
-- `publish(queue, message, options?)` - Publish message to queue
+- `publish(queue, message, options?)` - Publish message to queue. `options.bufferOnFailure`
+  (boolean, default `true`): `false` leaves the publish buffer for this one call — a
+  transiently failed message is NOT held and no reconnect replays it; the thrown
+  `PublishError` then carries `buffered: false` (see § The publish buffer).
 - `publishTelemetry(queue, message, options?)` - Publish the client's OWN event (the
   monitoring helpers below use it) on a confirm channel of its own, opened with the
   first such publish. A refusal there closes that channel only, never the one a
@@ -570,8 +580,40 @@ buffered, because no retry and no reconnect declares the exchange (d.693).
 A publish that fails transiently (the connection is closing, a channel is being
 recreated, the broker did not confirm in time) is held in memory — bounded by
 `publishBufferMaxSize` messages and `publishBufferTtlMs` each — and replayed after
-the reconnect, critical priority first. `getBufferState()` reports it and
-`publish:buffered` / `buffer:flush:failed` announce it.
+the reconnect or after the broker unblocks the connection (below), critical priority first. `getBufferState()` reports it and
+`publish:buffered` / `buffer:flush:failed` announce it. That includes a publish whose
+confirm was still pending when the channel or the connection died under it (the broker
+closed it, restarted or stopped): the broker said nothing about that message, so it is
+transient, never a refusal — only a `nack` or a numbered close frame naming this send
+is permanent (d.1134).
+
+**One call can leave the buffer: `publish(queue, message, { bufferOnFailure: false })`.**
+It is for a caller that keeps the message durably elsewhere and must not have a second
+copy replayed behind its back — the orchestrator writing a `publish_pending` record
+(`docs/governance/confirmations/step-publish-failure.md` 001). On each of the three
+transient paths (retries exhausted, `publishRetryEnabled: false`, the reconnect a retry
+waited for failed) the error `publish()` throws carries `buffered` (boolean): `true` only
+when the buffer holds the message for the next reconnect, `false` when nothing will
+replay it. A permanent refusal never reaches the buffer and carries no `buffered`. A
+value that is not a boolean is refused before any attempt (`ValidationError`). Retry
+stays the library's either way — the option decides only what happens after it.
+
+**Every failed publish says whether its frame left the client: `error.sent`** (boolean, on
+the `PublishError` from `publish()` and on its cause; conf
+`docs/governance/confirmations/mq-publish-buffer.md` 001). `true` when any attempt wrote the
+frame to the channel — the broker may hold it, and after a memory alarm deliver it, although
+the call failed; `false` when no attempt got that far. It says nothing about whether the
+broker stored the message. The buffer entry records the same fact, and it decides what
+happens when the outage ends:
+
+| The outage ends with | A held message whose frame was never sent | … whose frame was sent |
+|---|---|---|
+| a reconnect (`reconnected`) | re-sent | re-sent — the old socket and what the broker had not read are gone |
+| the broker unblocking the connection (`connection.unblocked`, end of a memory or disk alarm) | re-sent | dropped with a `warn` — the broker delivers the frames it held by itself |
+
+`connection.blocked` is logged as a `warn` with the broker's reason. A held message that
+outlives `publishBufferTtlMs` is logged as an `error` naming its queue or exchange, the
+count, the age and `sent` — `sent=false` is a message lost for good.
 
 **There is no persistent buffer, and `persistentBufferEnabled` /
 `persistentRedisClient` are refused by name.** They declared one until

package/package.json

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

package/src/BaseClient.js

@@ -494,9 +494,14 @@ class BaseClient {
    *   infrastructure or business queue is created by its owner before anything
    *   publishes to it, and an ownerless name is declared with the arguments the
    *   central `queueConfig` resolves (`transports/rabbitmqClient.js`, the 404 branch).
+   * @param {boolean} [options.bufferOnFailure=true] - `false` = a transiently failed message
+   *   is NOT held in the library's buffer, so no reconnect replays it; for a caller that keeps
+   *   the message durably elsewhere. Owned by `layers/PublishLayer.js`; a non-boolean is refused.
    * @returns {Promise<void>}
    * @throws {ConnectionError} If not connected.
-   * @throws {PublishError} If publish fails.
+   * @throws {PublishError} If publish fails. After a transient failure (retries exhausted,
+   *   retry disabled, the awaited reconnect failed) it carries `buffered` (boolean): `true`
+   *   only when the buffer holds the message for the next reconnect.
    */
   async publish(queue, message, options = {}) {
     if (!this._connected || !this._transport) {
@@ -539,7 +544,7 @@ class BaseClient {
       // answer as d.297 one call over (`_consumerRefusal()`): name no likeliest
       // cause, carry the one actually caught. `cause` is unchanged, so a caller
       // deciding on the class still reads the object.
-      throw new PublishError(
+      const failure = new PublishError(
         `[BaseClient] Failed to publish to queue "${queue}": ${describeThrown(err)} - `
           + 'Expected: publish() to hand the message to the broker. '
           + 'Fix: act on the reason above — this layer does not know which failure it was, and naming the '
@@ -548,6 +553,20 @@ class BaseClient {
         queue,
         err
       );
+      // Whether the library's buffer holds the message is decided and written by
+      // `PublishLayer` (options.bufferOnFailure, d.1122); it is carried up here unchanged so
+      // the caller reads it on the error it catches. Absent when the failure never reached
+      // the buffer decision — "not asked" is not "false".
+      if (err && typeof err.buffered === 'boolean') {
+        failure.buffered = err.buffered;
+      }
+      // Whether any attempt wrote the frame (d.1145, conf `mq-publish-buffer` 001): carried
+      // like `buffered`, so the caller — the orchestrator's `publish_pending` record
+      // (`step-publish-failure` 003) — reads it on the error it catches.
+      if (err && typeof err.sent === 'boolean') {
+        failure.sent = err.sent;
+      }
+      throw failure;
     }
   }
 

package/src/buffer/InMemoryBuffer.js

@@ -10,6 +10,19 @@ const { assertLogger } = require('@onlineapps/logger-contract');
  * Primárně určený pro transient scénáře (health checky apod.).
  */
 
+/**
+ * How a log line names where a buffered message was going: its exchange when it was published
+ * to one, its queue otherwise.
+ *
+ * @param {{queue: string, options: Object}} item
+ * @returns {string}
+ */
+function describeTarget(item) {
+  return item.options && typeof item.options.exchange === 'string' && item.options.exchange !== ''
+    ? `exchange "${item.options.exchange}"`
+    : `queue "${item.queue}"`;
+}
+
 class InMemoryBuffer {
   /**
    * Both numbers are REQUIRED and have no stand-in here.
@@ -61,7 +74,7 @@ class InMemoryBuffer {
     this._maxSize = options.maxSize;
     this._ttlMs = options.ttlMs;
 
-    /** @type {Array<{queue:string, buffer:Buffer, options:Object, createdAt:number, priority:string}>} */
+    /** @type {Array<{queue:string, buffer:Buffer, options:Object, createdAt:number, priority:string, sent:boolean}>} */
     this._items = [];
   }
 
@@ -69,7 +82,18 @@ class InMemoryBuffer {
    * Přidá zprávu do bufferu.
    * Staré/expirující zprávy jsou průběžně čištěny, při překročení kapacity odhazujeme nejstarší.
    */
-  async add(queue, buffer, options = {}, priority = 'normal') {
+  async add(queue, buffer, options = {}, priority = 'normal', sent) {
+    // Whether the frame of this message already LEFT the client (d.1145, conf
+    // `mq-publish-buffer` 001): the flush after `unblocked` re-sends only the entries that
+    // never did, because the broker delivers the frames it was holding by itself. Required —
+    // an entry that cannot say would be re-sent or dropped by a guess.
+    if (typeof sent !== 'boolean') {
+      throw new Error(
+        `[InMemoryBuffer] Cannot hold a message for queue '${queue}' without knowing whether its frame was sent - `
+          + `got sent=${JSON.stringify(sent)}. Expected: a boolean from the failed publish (error.sent). `
+          + 'Fix: pass it from PublishLayer, which reads it off the transport\'s error.'
+      );
+    }
     const now = Date.now();
     this._cleanupExpired(now);
 
@@ -86,6 +110,7 @@ class InMemoryBuffer {
       options,
       createdAt: now,
       priority,
+      sent,
     });
   }
 
@@ -94,7 +119,20 @@ class InMemoryBuffer {
    * @param {Function} flushFn - async (queue, buffer, options) => void
    * @returns {Promise<number>} - počet úspěšně flushnutých zpráv
    */
-  async flush(flushFn) {
+  async flush(flushFn, { sentEntries } = {}) {
+    // What happens to an entry whose frame already LEFT the client (d.1145, conf
+    // `mq-publish-buffer` 001): 'resend' after a reconnect — the old socket and whatever the
+    // broker had not read from it are gone; 'drop' after the broker unblocked the connection —
+    // it reads what was waiting in the socket and delivers those frames by itself, so a
+    // re-send would be one more copy. Required: a flush that guessed would do one or the other
+    // wrong.
+    if (sentEntries !== 'resend' && sentEntries !== 'drop') {
+      throw new Error(
+        `[InMemoryBuffer] flush() needs to know what to do with a sent entry - got sentEntries=${JSON.stringify(sentEntries)}. `
+          + "Expected: 'resend' (after a reconnect) or 'drop' (after the broker unblocked the connection). "
+          + 'Fix: flush through PublishLayer.flushBuffered(trigger), which maps its trigger to one of them.'
+      );
+    }
     const now = Date.now();
     this._cleanupExpired(now);
 
@@ -103,9 +141,23 @@ class InMemoryBuffer {
     }
 
     // Zkopírujeme a vyprázdníme interní pole, abychom se vyhnuli reentrancy problémům
-    const items = this._items.slice();
+    let items = this._items.slice();
     this._items = [];
 
+    if (sentEntries === 'drop') {
+      for (const item of items.filter((entry) => entry.sent)) {
+        this._logger.warn(
+          `[InMemoryBuffer] A buffered message for ${describeTarget(item)} is not re-sent after the broker unblocked `
+            + `the connection: its frame had been sent, and it was buffered ${now - item.createdAt} ms ago - Expected: the broker delivers `
+            + 'the frames it held during the alarm by itself once it reads the socket again, so a re-send would '
+            + 'be one more copy. Fix: nothing to do here; a consumer that must not see a message twice '
+            + 'deduplicates it (conf mq-consumer-contract 009), and a message the broker did NOT keep is '
+            + 'a broker-side loss this client cannot see.'
+        );
+      }
+      items = items.filter((entry) => !entry.sent);
+    }
+
     // Kritické zprávy (priority === 'critical') házíme dopředu
     items.sort((a, b) => {
       if (a.priority === b.priority) return a.createdAt - b.createdAt;
@@ -125,7 +177,9 @@ class InMemoryBuffer {
         this._logger.warn(
           `[InMemoryBuffer] Failed to flush message for queue '${item.queue}': ${err.message}`
         );
-        await this.add(item.queue, item.buffer, item.options, item.priority);
+        // The replay is one more attempt: if IT wrote the frame, the entry says so from now on.
+        const sent = item.sent || (err !== null && typeof err === 'object' && err.sent === true);
+        await this.add(item.queue, item.buffer, item.options, item.priority, sent);
       }
     }
 
@@ -140,15 +194,46 @@ class InMemoryBuffer {
     return this._items.length;
   }
 
+  /**
+   * Drop the entries older than the TTL — and say, as an ERROR, what was dropped (d.1145, conf
+   * `mq-publish-buffer` 001).
+   *
+   * Until d.1145 this was one `info` line with a count and nothing else, the only trace of a
+   * message nobody would ever deliver (a memory alarm keeps the connection alive, so no
+   * reconnect flush comes — d.1143). One error per destination and `sent` value, with the
+   * count and the age of the oldest: a message whose frame never left is LOST, one whose frame
+   * had been sent may have been delivered by the broker on its own, and the two are never
+   * folded into one sentence.
+   *
+   * @param {number} now - the clock reading the caller took
+   * @private
+   */
   _cleanupExpired(now) {
-    const before = this._items.length;
-    this._items = this._items.filter(
-      (item) => now - item.createdAt <= this._ttlMs
-    );
-    const removed = before - this._items.length;
-    if (removed > 0) {
-      this._logger.info(
-        `[InMemoryBuffer] Removed ${removed} expired buffered messages`
+    const expired = this._items.filter((item) => now - item.createdAt > this._ttlMs);
+    if (expired.length === 0) {
+      return;
+    }
+    this._items = this._items.filter((item) => now - item.createdAt <= this._ttlMs);
+
+    const groups = new Map();
+    for (const item of expired) {
+      const key = `${describeTarget(item)}|${item.sent}`;
+      const group = groups.get(key) || { target: describeTarget(item), sent: item.sent, count: 0, oldestMs: 0 };
+      group.count += 1;
+      group.oldestMs = Math.max(group.oldestMs, now - item.createdAt);
+      groups.set(key, group);
+    }
+    for (const { target, sent, count, oldestMs } of groups.values()) {
+      this._logger.error(
+        `[InMemoryBuffer] ${count} buffered message(s) for ${target} expired after the buffer TTL `
+          + `(${this._ttlMs} ms; oldest ${oldestMs} ms), sent=${sent} - `
+          + (sent
+            ? 'the frame had been sent, so the broker may have delivered it on its own; nothing re-sends it now. '
+            : 'the frame never left this client, so the message is LOST; nothing re-sends it now. ')
+          + 'Expected: a reconnect, or the broker unblocking the connection, within publishBufferTtlMs. '
+          + 'Fix: find why the broker stayed away that long (an alarm: management API /api/health/checks/alarms; '
+          + 'an outage: the connection log); a message that must survive longer belongs to a caller that keeps '
+          + 'it durably and publishes with bufferOnFailure: false.'
       );
     }
   }

package/src/buffer/MessageBuffer.js

@@ -50,7 +50,9 @@ class MessageBuffer {
   async add(queue, buffer, options = {}, meta = {}) {
     const priority = meta.priority || 'normal';
 
-    await this._inMemory.add(queue, buffer, options, priority);
+    // `sent` is passed through unread: the in-memory buffer owns the rule that it is required
+    // (d.1145, conf `mq-publish-buffer` 001).
+    await this._inMemory.add(queue, buffer, options, priority, meta.sent);
   }
 
   /**
@@ -58,8 +60,8 @@ class MessageBuffer {
    * @param {Function} flushFn - async (queue, buffer, options) => void
    * @returns {Promise<number>} how many messages were replayed
    */
-  async flush(flushFn) {
-    return await this._inMemory.flush(flushFn);
+  async flush(flushFn, flushPolicy) {
+    return await this._inMemory.flush(flushFn, flushPolicy);
   }
 
   /**

package/src/config/configSchema.js

@@ -136,8 +136,12 @@ module.exports = {
       type: 'integer',
       minimum: 0,
       description:
-        'AMQP heartbeat in SECONDS, handed to amqplib at connect. Explicit value, else ENV '
-        + 'RABBITMQ_HEARTBEAT, else the module default (../defaults.js heartbeatSeconds).',
+        'AMQP heartbeat in SECONDS, proposed to the broker in the connection URL (?heartbeat=) at '
+        + 'connect. Explicit value, else ENV RABBITMQ_HEARTBEAT, else the module default '
+        + '(../defaults.js heartbeatSeconds). 0 does NOT switch the heartbeat off: amqplib\'s '
+        + 'negotiation takes whichever side sets a limit, so the broker\'s own value applies '
+        + '(RabbitMQ 60 s unless its configuration says otherwise; measured d.1126: a paused broker '
+        + 'detected after 179 s). Only a broker that also offers 0 disables it.',
     },
     serviceName: {
       type: 'string',
@@ -287,10 +291,12 @@ module.exports = {
       type: 'integer',
       minimum: 0,
       description:
-        'How long this client waits for an ANSWER from the broker, in milliseconds: the confirm of '
-        + 'one publish attempt, and the close-ok of each handle disconnect() closes. One number, two '
-        + 'consumers — it was named publishConfirmationTimeout until d.299, after the teardown had '
-        + 'been spending it since d.283.',
+        'How long this client waits for an ANSWER from the broker, in milliseconds — every wait: the '
+        + 'confirm of one publish attempt, the close-ok of each handle disconnect() closes, and every '
+        + 'request a channel sends and waits on (queue/exchange declarations, checkQueue, bindQueue, '
+        + 'purge, delete, consume, cancel, prefetch, channel open; conf mq-broker-answer-budget 001, '
+        + 'd.1135). One number for one question — it was named publishConfirmationTimeout until d.299, '
+        + 'after the teardown had been spending it since d.283.',
     },
     connectTimeout: {
       type: 'integer',

package/src/config/defaultConfig.js

@@ -120,12 +120,13 @@ module.exports = {
   publishRetryMaxDelay: 5000,
   publishRetryBackoffMultiplier: 2,
 
-  // How long this client waits for an ANSWER from the broker, in ms: the confirm
-  // of one publish attempt, and the `close-ok` of each handle `disconnect()`
-  // closes — one number for two consumers, which is why it carries the name of
-  // neither. It was `publishConfirmationTimeout` until d.299, a name that was
-  // true of the publish path and false of the teardown that had used it since
-  // d.283.
+  // How long this client waits for an ANSWER from the broker, in ms — every wait:
+  // the confirm of one publish attempt, the `close-ok` of each handle
+  // `disconnect()` closes, and every request a channel sends and waits on
+  // (conf `mq-broker-answer-budget` 001, d.1135) — one number for all of them,
+  // which is why it carries the name of none. It was `publishConfirmationTimeout`
+  // until d.299, a name that was true of the publish path and false of the
+  // teardown that had used it since d.283.
   brokerAnswerTimeout: 5000,
 
   // How long the connect handshake may take before the attempt is abandoned, in