@onlineapps/mq-client-core 2.0.1-rc.1 → 3.0.0

package/src/buffer/InMemoryBuffer.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { assertLogger } = require('@onlineapps/logger-contract');
+
 /**
  * Jednoduchý in-memory buffer pro zprávy, které čekají na bezpečné odeslání.
  * - Omezený počtem položek (maxSize)
@@ -10,15 +12,54 @@
 
 class InMemoryBuffer {
   /**
+   * Both numbers are REQUIRED and have no stand-in here.
+   *
+   * They are declared and defaulted one floor up — `publishBufferMaxSize` and
+   * `publishBufferTtlMs` in `config/defaultConfig.js`, composed before validation
+   * and handed down by the transport through `MessageBuffer`. Until d.311 this
+   * constructor wrote `options.maxSize || 100` and `options.ttlMs || 5 * 60 * 1000`,
+   * a second copy of two values that already had an owner — and `||` means "if
+   * falsy", so `publishBufferMaxSize: 0` ("hold nothing") arrived here as 100.
+   * That is the defect d.292 §5 removed from the transport and recorded as still
+   * open one floor down.
+   *
+   * Absence is therefore a defect of the caller, named as one
+   * (`architecture-principles.md` §3, §4, §5), not an invitation to invent a size.
+   *
    * @param {Object} options
-   * @param {number} [options.maxSize=100] - Max počet zpráv v bufferu
-   * @param {number} [options.ttlMs=300000] - TTL jedné zprávy v ms (default 5 minut)
-   * @param {Function} [options.logger] - Volitelný logger (console-like)
+   * @param {number} options.maxSize - Max messages held; 0 means hold none
+   * @param {number} options.ttlMs - How long one message may wait, in ms
+   * @param {Object} options.logger - Logger s info/warn/error/debug (povinný)
    */
   constructor(options = {}) {
-    this._maxSize = options.maxSize || 100;
-    this._ttlMs = options.ttlMs || 5 * 60 * 1000;
-    this._logger = options.logger || console;
+    // The logger first, so a caller who forgot it gets the contract message
+    // rather than a complaint about the next missing thing (same order as
+    // `BaseClient`).
+    this._logger = assertLogger(
+      'InMemoryBuffer',
+      options.logger,
+      'the buffer reports every message it drops when it is full or expired',
+      'pass options.logger (MessageBuffer forwards the one your service built)'
+    );
+
+    if (!Number.isFinite(options.maxSize)) {
+      throw new Error(
+        '[InMemoryBuffer] Missing required option - maxSize is required and has no default here. '
+          + 'Expected: the value the client resolved from publishBufferMaxSize (config/defaultConfig.js). '
+          + 'Fix: build this buffer through MessageBuffer, which is handed the resolved configuration, '
+          + 'or pass maxSize explicitly.'
+      );
+    }
+    if (!Number.isFinite(options.ttlMs)) {
+      throw new Error(
+        '[InMemoryBuffer] Missing required option - ttlMs is required and has no default here. '
+          + 'Expected: the value the client resolved from publishBufferTtlMs (config/defaultConfig.js). '
+          + 'Fix: build this buffer through MessageBuffer, which is handed the resolved configuration, '
+          + 'or pass ttlMs explicitly.'
+      );
+    }
+    this._maxSize = options.maxSize;
+    this._ttlMs = options.ttlMs;
 
     /** @type {Array<{queue:string, buffer:Buffer, options:Object, createdAt:number, priority:string}>} */
     this._items = [];
@@ -34,7 +75,7 @@ class InMemoryBuffer {
 
     if (this._items.length >= this._maxSize) {
       const dropped = this._items.shift();
-      this._logger?.warn?.(
+      this._logger.warn(
         `[InMemoryBuffer] Buffer full (${this._maxSize}), dropping oldest message for queue '${dropped.queue}'`
       );
     }
@@ -81,7 +122,7 @@ class InMemoryBuffer {
       } catch (err) {
         // Pokud flush selže, vrátíme zprávu zpět do bufferu (na konec fronty),
         // aby ji mohl zpracovat další pokus / worker.
-        this._logger?.warn?.(
+        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);
@@ -106,7 +147,7 @@ class InMemoryBuffer {
     );
     const removed = before - this._items.length;
     if (removed > 0) {
-      this._logger?.info?.(
+      this._logger.info(
         `[InMemoryBuffer] Removed ${removed} expired buffered messages`
       );
     }

package/src/buffer/MessageBuffer.js

@@ -1,25 +1,35 @@
 'use strict';
 
 const InMemoryBuffer = require('./InMemoryBuffer');
-const RedisBuffer = require('./RedisBuffer');
+const { assertLogger } = require('@onlineapps/logger-contract');
 
 /**
- * MessageBuffer – sjednocený interface nad in-memory a (potenciálně) persistentním bufferem.
+ * MessageBuffer – the buffer a failed publish is held in until the connection is
+ * back.
  *
- * - InMemoryBuffer: pro transient zprávy (např. health checky)
- * - RedisBuffer: pro kritické zprávy (workflow.completed apod.) – aktuálně jen připravený hook
+ * ONE buffer, `InMemoryBuffer`, bounded by `publishBufferMaxSize` and
+ * `publishBufferTtlMs`. Until d.343 this class also routed critical-priority
+ * messages to a `RedisBuffer` whose `add()` and `flush()` stored and returned
+ * nothing, so `persistentBufferEnabled: true` DROPPED exactly the messages it
+ * claimed to protect — a declaration with no mechanism
+ * (`automation-gates.md` §5). The stub, its two config keys and this branch went
+ * out together; the four questions of `change-discipline.md` § Removing are
+ * answered in the commit that removed them.
  */
 
 class MessageBuffer {
   /**
    * @param {Object} options
    * @param {Object} [options.inMemory] - In-memory buffer options
-   * @param {Object} [options.persistent] - Persistent buffer options (Redis)
-   * @param {boolean} [options.persistent.enabled=false] - Zapnutí persistentního bufferu
-   * @param {Object} [options.logger] - Logger (console-like)
+   * @param {Object} options.logger - Logger s info/warn/error/debug (povinny)
    */
   constructor(options = {}) {
-    this._logger = options.logger || console;
+    this._logger = assertLogger(
+      'MessageBuffer',
+      options.logger,
+      'the buffer reports every message it holds, drops or replays',
+      'pass options.logger (PublishLayer forwards the one your service built)'
+    );
 
     this._inMemory = new InMemoryBuffer({
       maxSize: options.inMemory?.maxSize,
@@ -27,19 +37,6 @@ class MessageBuffer {
       logger: this._logger,
     });
 
-    const persistentEnabled = !!options.persistent?.enabled;
-    this._persistent = persistentEnabled
-      ? new RedisBuffer({
-          redisClient: options.persistent?.redisClient,
-          logger: this._logger,
-        })
-      : null;
-
-    if (!persistentEnabled) {
-      this._logger?.info?.(
-        '[MessageBuffer] Persistent buffer is disabled (persistent.enabled=false)'
-      );
-    }
   }
 
   /**
@@ -49,22 +46,9 @@ class MessageBuffer {
    * @param {Object} options
    * @param {Object} [meta]
    * @param {string} [meta.priority='normal'] - 'normal' | 'critical'
-   * @param {boolean} [meta.persistent=false] - zda preferovat persistentní buffer
    */
   async add(queue, buffer, options = {}, meta = {}) {
     const priority = meta.priority || 'normal';
-    const wantPersistent = !!meta.persistent;
-
-    if (wantPersistent && this._persistent) {
-      try {
-        await this._persistent.add(queue, buffer, options, priority);
-        return;
-      } catch (err) {
-        this._logger?.warn?.(
-          `[MessageBuffer] Failed to add message to persistent buffer, falling back to in-memory: ${err.message}`
-        );
-      }
-    }
 
     await this._inMemory.add(queue, buffer, options, priority);
   }
@@ -72,26 +56,10 @@ class MessageBuffer {
   /**
    * Flushne všechny buffered zprávy přes poskytnutou publish funkci.
    * @param {Function} flushFn - async (queue, buffer, options) => void
-   * @returns {Promise<{inMemory:number,persistent:number}>}
+   * @returns {Promise<number>} how many messages were replayed
    */
   async flush(flushFn) {
-    let persistentFlushed = 0;
-    if (this._persistent) {
-      try {
-        persistentFlushed = await this._persistent.flush(flushFn);
-      } catch (err) {
-        this._logger?.error?.(
-          `[MessageBuffer] Failed to flush persistent buffer: ${err.message}`
-        );
-      }
-    }
-
-    const inMemoryFlushed = await this._inMemory.flush(flushFn);
-
-    return {
-      inMemory: inMemoryFlushed,
-      persistent: persistentFlushed,
-    };
+    return await this._inMemory.flush(flushFn);
   }
 
   /**

package/src/config/composeConfig.js

@@ -0,0 +1,60 @@
+'use strict';
+
+/**
+ * composeConfig.js
+ *
+ * How this client builds ONE configuration object out of several sources
+ * (module defaults, the caller's config, the overrides `connect()` was given).
+ *
+ * SHALLOW, AND THAT IS THE POINT. `BaseClient` used `lodash.merge`, which walks
+ * into every plain object it is handed and copies it key by key. A config here
+ * carries two different kinds of value, and deep-merging treats them the same:
+ *
+ *   - configuration keys — all 42 of them flat (`configSchema.js`), so there has
+ *     never been a nested branch for a deep merge to merge;
+ *   - INJECTED DEPENDENCIES — the `logger` every layer of this client writes
+ *     through, and the callbacks (`onFatal`, `healthReportCallback`,
+ *     `healthCriticalCallback`, …).
+ *
+ * Measured 2026-09-13: a dependency written as a plain object came out of that
+ * merge as a DIFFERENT object (`out.plainOne === plain` → false) while a class
+ * instance passed through by reference. So a dependency built as an object
+ * literal — a wrapper, a double, anything not built with `new` — reached the
+ * component that needs it as a copy: the same shape, none of the identity, and
+ * none of whatever the copy could not carry. It looked configured and was not.
+ * What the caller injects is what the mechanism must get
+ * (`architecture-principles.md` §1). (The example that measurement was written
+ * against was `persistentRedisClient`; the key went out with the stub it fed,
+ * d.343, and the rule it proved did not.)
+ *
+ * A key whose value is `undefined` is treated as NOT PROVIDED and never
+ * overwrites what an earlier source set. That is not a fallback, it is what
+ * "absent" means for an optional key in a config object literal: callers build
+ * their config with optional keys present and unset (`@onlineapps/service-wrapper`
+ * passes `onFatal` whether the service declared one or not), and `lodash.merge`
+ * skipped them the same way.
+ *
+ * The caller's own object is never written into: composition returns a new object
+ * and the sources are only read (`automation-gates.md` §1 requirement 3, the same
+ * idea applied to a library).
+ *
+ * @param {...(Object|null|undefined)} sources - Read left to right; a later
+ *   source wins over an earlier one, except where its value is `undefined`.
+ * @returns {Object} A new object carrying every provided key, values by reference.
+ */
+function composeConfig(...sources) {
+  const composed = {};
+
+  for (const source of sources) {
+    if (source === null || source === undefined) continue;
+
+    for (const key of Object.keys(source)) {
+      if (source[key] === undefined) continue;
+      composed[key] = source[key];
+    }
+  }
+
+  return composed;
+}
+
+module.exports = composeConfig;