@onlineapps/mq-client-core 1.0.36 → 1.0.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "1.0.36",
+  "version": "1.0.38",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "main": "src/index.js",
   "scripts": {

package/src/buffer/InMemoryBuffer.js

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * Jednoduchý in-memory buffer pro zprávy, které čekají na bezpečné odeslání.
+ * - Omezený počtem položek (maxSize)
+ * - TTL pro jednotlivé položky (ttlMs)
+ *
+ * Primárně určený pro transient scénáře (health checky apod.).
+ */
+
+class InMemoryBuffer {
+  /**
+   * @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)
+   */
+  constructor(options = {}) {
+    this._maxSize = options.maxSize || 100;
+    this._ttlMs = options.ttlMs || 5 * 60 * 1000;
+    this._logger = options.logger || console;
+
+    /** @type {Array<{queue:string, buffer:Buffer, options:Object, createdAt:number, priority:string}>} */
+    this._items = [];
+  }
+
+  /**
+   * 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') {
+    const now = Date.now();
+    this._cleanupExpired(now);
+
+    if (this._items.length >= this._maxSize) {
+      const dropped = this._items.shift();
+      this._logger?.warn?.(
+        `[InMemoryBuffer] Buffer full (${this._maxSize}), dropping oldest message for queue '${dropped.queue}'`
+      );
+    }
+
+    this._items.push({
+      queue,
+      buffer,
+      options,
+      createdAt: now,
+      priority,
+    });
+  }
+
+  /**
+   * Flushne všechny aktuálně platné zprávy do poskytnuté publish funkce (FIFO, priority-aware).
+   * @param {Function} flushFn - async (queue, buffer, options) => void
+   * @returns {Promise<number>} - počet úspěšně flushnutých zpráv
+   */
+  async flush(flushFn) {
+    const now = Date.now();
+    this._cleanupExpired(now);
+
+    if (this._items.length === 0) {
+      return 0;
+    }
+
+    // Zkopírujeme a vyprázdníme interní pole, abychom se vyhnuli reentrancy problémům
+    const items = this._items.slice();
+    this._items = [];
+
+    // Kritické zprávy (priority === 'critical') házíme dopředu
+    items.sort((a, b) => {
+      if (a.priority === b.priority) return a.createdAt - b.createdAt;
+      if (a.priority === 'critical') return -1;
+      if (b.priority === 'critical') return 1;
+      return a.createdAt - b.createdAt;
+    });
+
+    let flushed = 0;
+    for (const item of items) {
+      try {
+        await flushFn(item.queue, item.buffer, item.options || {});
+        flushed++;
+      } 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?.(
+          `[InMemoryBuffer] Failed to flush message for queue '${item.queue}': ${err.message}`
+        );
+        await this.add(item.queue, item.buffer, item.options, item.priority);
+      }
+    }
+
+    return flushed;
+  }
+
+  /**
+   * Aktuální velikost bufferu.
+   */
+  size() {
+    this._cleanupExpired(Date.now());
+    return this._items.length;
+  }
+
+  _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`
+      );
+    }
+  }
+}
+
+module.exports = InMemoryBuffer;
+
+

package/src/buffer/MessageBuffer.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const InMemoryBuffer = require('./InMemoryBuffer');
+const RedisBuffer = require('./RedisBuffer');
+
+/**
+ * MessageBuffer – sjednocený interface nad in-memory a (potenciálně) persistentním bufferem.
+ *
+ * - InMemoryBuffer: pro transient zprávy (např. health checky)
+ * - RedisBuffer: pro kritické zprávy (workflow.completed apod.) – aktuálně jen připravený hook
+ */
+
+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)
+   */
+  constructor(options = {}) {
+    this._logger = options.logger || console;
+
+    this._inMemory = new InMemoryBuffer({
+      maxSize: options.inMemory?.maxSize,
+      ttlMs: options.inMemory?.ttlMs,
+      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)'
+      );
+    }
+  }
+
+  /**
+   * Přidá zprávu do bufferu.
+   * @param {string} queue
+   * @param {Buffer} buffer
+   * @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);
+  }
+
+  /**
+   * 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}>}
+   */
+  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,
+    };
+  }
+
+  /**
+   * Aktuální velikost in-memory bufferu.
+   */
+  size() {
+    return this._inMemory.size();
+  }
+}
+
+module.exports = MessageBuffer;
+
+

package/src/buffer/RedisBuffer.js

@@ -0,0 +1,57 @@
+'use strict';
+
+/**
+ * Placeholder Redis buffer.
+ *
+ * Záměrně JE minimalistický: v tomto projektu zatím nemáme přímou Redis závislost v mq-client-core.
+ * Třída je připravená na budoucí rozšíření – aktuálně pouze no-op / deleguje na in-memory fallback.
+ */
+
+class RedisBuffer {
+  /**
+   * @param {Object} options
+   * @param {Object} [options.redisClient] - Volitelný Redis klient (s metodami set/get/lpush/brpop atd.)
+   * @param {Function} [options.logger]    - Logger (console-like)
+   */
+  constructor(options = {}) {
+    this._redis = options.redisClient || null;
+    this._logger = options.logger || console;
+
+    if (!this._redis) {
+      this._logger?.info?.(
+        '[RedisBuffer] No redisClient provided - RedisBuffer is effectively disabled (will not persist messages)'
+      );
+    }
+  }
+
+  /**
+   * Přidá zprávu do persistentního bufferu.
+   * Aktuální implementace je no-op, pokud není k dispozici redisClient.
+   */
+  async add(/* queue, buffer, options, priority */) {
+    if (!this._redis) {
+      // No-op; fallback na InMemoryBuffer zajišťuje MessageBuffer
+      return;
+    }
+    // Budoucí rozšíření: implementace zápisu do Redis seznamu/streamu.
+  }
+
+  /**
+   * Flushne všechny zprávy z Redis bufferu přes poskytnutý flushFn.
+   * Aktuální implementace je no-op, pokud není k dispozici redisClient.
+   *
+   * @param {Function} flushFn - async (queue, buffer, options) => void
+   * @returns {Promise<number>} - počet flushnutých zpráv
+   */
+  async flush(flushFn) {
+    if (!this._redis) {
+      return 0;
+    }
+    // Budoucí rozšíření: čtení z Redis (např. list/stream) a volání flushFn.
+    return 0;
+  }
+}
+
+module.exports = RedisBuffer;
+
+

package/src/index.js

@@ -19,6 +19,12 @@ const {
   ConsumeError,
   SerializationError,
 } = require('./utils/errorHandler');
+const {
+  TransientPublishError,
+  PermanentPublishError,
+  QueueNotFoundError,
+  classifyPublishError,
+} = require('./utils/publishErrors');
 
 // Export BaseClient as default (constructor), with additional named exports
 // NOTE: When destructuring, use: const { BaseClient } = require('@onlineapps/mq-client-core');
@@ -34,4 +40,10 @@ module.exports.errors = {
   ConsumeError,
   SerializationError,
 };
+module.exports.publishErrors = {
+  TransientPublishError,
+  PermanentPublishError,
+  QueueNotFoundError,
+  classifyPublishError,
+};
 

package/src/layers/PublishLayer.js

@@ -0,0 +1,242 @@
+'use strict';
+
+const {
+  TransientPublishError,
+  PermanentPublishError,
+  QueueNotFoundError,
+} = require('../utils/publishErrors');
+const MessageBuffer = require('../buffer/MessageBuffer');
+
+/**
+ * PublishLayer - čistá vrstva pro publish s retry + buffer
+ * 
+ * Odděluje:
+ * - Retry logiku (exponential backoff)
+ * - Bufferování při transient chybách
+ * - Delegaci na RabbitMQClient._publishOnce() (čisté publish bez retry)
+ */
+class PublishLayer {
+  /**
+   * @param {Object} options
+   * @param {Object} options.client - Instance RabbitMQClient
+   * @param {Object} [options.logger] - Logger
+   * @param {Object} [options.bufferConfig] - Konfigurace pro MessageBuffer
+   * @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
+   * @param {number} [options.retryMaxDelay=5000] - Max delay v ms
+   * @param {number} [options.retryBackoffMultiplier=2] - Backoff multiplikátor
+   */
+  constructor(options = {}) {
+    if (!options.client) {
+      throw new Error('PublishLayer requires a client instance');
+    }
+
+    this._client = options.client;
+    this._logger = options.logger || console;
+
+    // Retry konfigurace - bere z client config nebo options
+    this._retryEnabled = options.retryEnabled !== undefined 
+      ? options.retryEnabled 
+      : (this._client._publishRetryEnabled !== false);
+    this._maxRetries = options.maxRetries || this._client._publishMaxRetries || 3;
+    this._retryBaseDelay = options.retryBaseDelay || this._client._publishRetryBaseDelay || 100;
+    this._retryMaxDelay = options.retryMaxDelay || this._client._publishRetryMaxDelay || 5000;
+    this._retryBackoffMultiplier = options.retryBackoffMultiplier || this._client._publishRetryBackoffMultiplier || 2;
+
+    // Buffer
+    this._buffer = new MessageBuffer({
+      inMemory: options.bufferConfig?.inMemory,
+      persistent: options.bufferConfig?.persistent,
+      logger: this._logger,
+    });
+  }
+
+  /**
+   * Publish s retry + buffer logikou
+   * @param {string} queue
+   * @param {Buffer} buffer
+   * @param {Object} [options]
+   */
+  async publish(queue, buffer, options = {}) {
+    const priority = options.priority || 'normal';
+    const usePersistentBuffer =
+      priority === 'critical' && !!this._client._config?.persistentBufferEnabled;
+
+    if (this._retryEnabled) {
+      return await this._publishWithRetry(queue, buffer, options, priority, usePersistentBuffer);
+    } else {
+      return await this._publishOnce(queue, buffer, options, priority, usePersistentBuffer);
+    }
+  }
+
+  /**
+   * Single publish attempt - deleguje na RabbitMQClient._publishOnce()
+   * @private
+   */
+  async _publishOnce(queue, buffer, options, priority, usePersistentBuffer) {
+    try {
+      await this._client._publishOnce(queue, buffer, options);
+    } catch (err) {
+      return await this._handlePublishError(err, queue, buffer, options, priority, usePersistentBuffer);
+    }
+  }
+
+  /**
+   * Publish s retry logikou
+   * @private
+   */
+  async _publishWithRetry(queue, buffer, options, priority, usePersistentBuffer) {
+    let lastError = null;
+    let attempt = 0;
+
+    while (attempt < this._maxRetries) {
+      attempt++;
+
+      try {
+        // Track attempt (i při prvním pokusu pro monitoring)
+        this._client.emit('publish:retry', {
+          queue,
+          attempt,
+          maxRetries: this._maxRetries,
+          lastError: lastError?.message
+        });
+        if (attempt > 1) {
+          this._logger?.log?.(`[PublishLayer] Retry attempt ${attempt}/${this._maxRetries} for queue "${queue}"`);
+        }
+
+        await this._client._publishOnce(queue, buffer, options);
+
+        // Track success (always emit, even for first attempt)
+        this._client.emit('publish:success', {
+          queue,
+          attempt,
+          totalAttempts: attempt
+        });
+        if (attempt > 1) {
+          this._logger?.log?.(`[PublishLayer] ✓ Published successfully after ${attempt} attempts for queue "${queue}"`);
+        }
+
+        return; // Success
+
+      } catch (err) {
+        lastError = err;
+
+        // Non-retryable errors - fail immediately
+        if (err instanceof PermanentPublishError || err instanceof QueueNotFoundError) {
+          this._client.emit('publish:failed', {
+            queue,
+            attempt,
+            error: err.message,
+            retryable: false
+          });
+          throw err;
+        }
+
+        // Transient errors - check if we should retry or buffer
+        if (err instanceof TransientPublishError) {
+          // If we have more attempts, retry
+          if (attempt < this._maxRetries) {
+            // Wait for reconnection if in progress
+            if (this._client._reconnecting) {
+              this._logger?.log?.(`[PublishLayer] Connection reconnecting, waiting before retry ${attempt + 1}/${this._maxRetries}...`);
+              try {
+                await this._client._waitForReconnection();
+                this._logger?.log?.(`[PublishLayer] ✓ Reconnection completed, proceeding with retry ${attempt + 1}/${this._maxRetries}`);
+                continue; // Retry immediately after reconnect
+              } catch (reconnectErr) {
+                // Reconnection failed - buffer and fail
+                await this._bufferMessage(queue, buffer, options, priority, usePersistentBuffer, err);
+                this._client.emit('publish:failed', {
+                  queue,
+                  attempt,
+                  error: `Reconnection failed: ${reconnectErr.message}`,
+                  retryable: false,
+                  reconnectFailed: true
+                });
+                throw new Error(`Publish failed: reconnection failed after ${attempt} attempts for queue "${queue}": ${reconnectErr.message}`);
+              }
+            }
+
+            // Exponential backoff
+            const delay = Math.min(
+              this._retryBaseDelay * Math.pow(this._retryBackoffMultiplier, attempt - 1),
+              this._retryMaxDelay
+            );
+            this._logger?.warn?.(`[PublishLayer] Retryable error for queue "${queue}" (attempt ${attempt}/${this._maxRetries}), waiting ${delay}ms before retry: ${err.message}`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+            continue;
+          }
+
+          // Max retries exceeded - buffer and fail
+          await this._bufferMessage(queue, buffer, options, priority, usePersistentBuffer, err);
+          this._client.emit('publish:failed', {
+            queue,
+            attempt,
+            error: err.message,
+            retryable: true,
+            maxRetriesExceeded: true
+          });
+          throw new Error(`Publish failed after ${attempt} attempts for queue "${queue}": ${err.message}`);
+        }
+
+        // Unknown error - fail immediately
+        throw err;
+      }
+    }
+
+    throw lastError || new Error(`Publish failed for queue "${queue}" after ${attempt} attempts`);
+  }
+
+  /**
+   * Handle publish error - buffer transient errors
+   * @private
+   */
+  async _handlePublishError(err, queue, buffer, options, priority, usePersistentBuffer) {
+    if (err instanceof QueueNotFoundError) {
+      this._logger?.error?.(`[PublishLayer] QueueNotFoundError for '${queue}' (infra=${err.isInfrastructure}): ${err.message}`);
+      throw err;
+    }
+
+    if (err instanceof TransientPublishError) {
+      await this._bufferMessage(queue, buffer, options, priority, usePersistentBuffer, err);
+      throw err;
+    }
+
+    throw err;
+  }
+
+  /**
+   * Buffer message při transient error
+   * @private
+   */
+  async _bufferMessage(queue, buffer, options, priority, usePersistentBuffer, err) {
+    try {
+      await this._buffer.add(queue, buffer, options, {
+        priority,
+        persistent: usePersistentBuffer,
+      });
+      this._logger?.warn?.(`[PublishLayer] Buffered message for queue '${queue}' due to transient error: ${err.message}`);
+      this._client.emit('publish:buffered', { queue });
+    } catch (bufferErr) {
+      this._logger?.error?.(`[PublishLayer] Failed to buffer message for queue '${queue}': ${bufferErr.message}`);
+    }
+  }
+
+  /**
+   * Flush buffered messages po reconnectu
+   */
+  async flushBuffered(flushOptions = {}) {
+    const result = await this._buffer.flush(async (queue, buf, opts) => {
+      const mergedOptions = Object.assign({}, opts, flushOptions);
+      await this._client._publishOnce(queue, buf, mergedOptions);
+    });
+
+    this._logger?.info?.(`[PublishLayer] Flushed buffered messages (inMemory=${result.inMemory}, persistent=${result.persistent})`);
+    return result;
+  }
+}
+
+module.exports = PublishLayer;
+
+

package/src/monitoring/PublishMonitor.js

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * PublishMonitor - tracking a metriky pro publish operace
+ */
+class PublishMonitor {
+  /**
+   * @param {Object} options
+   * @param {Object} [options.logger] - Logger
+   */
+  constructor(options = {}) {
+    this._logger = options.logger || console;
+    
+    // Metrics
+    this._metrics = {
+      attempts: 0,
+      successes: 0,
+      failures: 0,
+      retries: 0,
+      buffered: 0,
+      flushed: 0,
+    };
+
+    // Per-queue metrics
+    this._queueMetrics = new Map(); // queue -> { attempts, successes, failures, retries }
+  }
+
+  /**
+   * Track publish attempt
+   */
+  trackAttempt(queue) {
+    this._metrics.attempts++;
+    this._updateQueueMetrics(queue, 'attempts');
+  }
+
+  /**
+   * Track publish success
+   */
+  trackSuccess(queue, attempt = 1) {
+    this._metrics.successes++;
+    if (attempt > 1) {
+      this._metrics.retries += (attempt - 1);
+    }
+    this._updateQueueMetrics(queue, 'successes', attempt);
+  }
+
+  /**
+   * Track publish failure
+   */
+  trackFailure(queue, retryable = false) {
+    this._metrics.failures++;
+    this._updateQueueMetrics(queue, 'failures', 0, retryable);
+  }
+
+  /**
+   * Track buffered message
+   */
+  trackBuffered(queue) {
+    this._metrics.buffered++;
+  }
+
+  /**
+   * Track flushed messages
+   */
+  trackFlushed(count) {
+    this._metrics.flushed += count;
+  }
+
+  /**
+   * Get metrics
+   */
+  getMetrics() {
+    return {
+      ...this._metrics,
+      queues: Array.from(this._queueMetrics.entries()).map(([queue, metrics]) => ({
+        queue,
+        ...metrics
+      }))
+    };
+  }
+
+  /**
+   * Get Prometheus metrics format
+   */
+  getPrometheusMetrics() {
+    const lines = [];
+    lines.push(`# HELP mq_publish_attempts Total publish attempts`);
+    lines.push(`# TYPE mq_publish_attempts counter`);
+    lines.push(`mq_publish_attempts ${this._metrics.attempts}`);
+    
+    lines.push(`# HELP mq_publish_successes Total successful publishes`);
+    lines.push(`# TYPE mq_publish_successes counter`);
+    lines.push(`mq_publish_successes ${this._metrics.successes}`);
+    
+    lines.push(`# HELP mq_publish_failures Total failed publishes`);
+    lines.push(`# TYPE mq_publish_failures counter`);
+    lines.push(`mq_publish_failures ${this._metrics.failures}`);
+    
+    lines.push(`# HELP mq_publish_retries Total retry attempts`);
+    lines.push(`# TYPE mq_publish_retries counter`);
+    lines.push(`mq_publish_retries ${this._metrics.retries}`);
+    
+    lines.push(`# HELP mq_publish_buffered Total buffered messages`);
+    lines.push(`# TYPE mq_publish_buffered counter`);
+    lines.push(`mq_publish_buffered ${this._metrics.buffered}`);
+    
+    lines.push(`# HELP mq_publish_flushed Total flushed messages`);
+    lines.push(`# TYPE mq_publish_flushed counter`);
+    lines.push(`mq_publish_flushed ${this._metrics.flushed}`);
+    
+    return lines.join('\n');
+  }
+
+  /**
+   * Update queue metrics
+   * @private
+   */
+  _updateQueueMetrics(queue, type, attempt = 1, retryable = false) {
+    if (!this._queueMetrics.has(queue)) {
+      this._queueMetrics.set(queue, {
+        attempts: 0,
+        successes: 0,
+        failures: 0,
+        retries: 0,
+      });
+    }
+
+    const metrics = this._queueMetrics.get(queue);
+    metrics[type]++;
+
+    if (type === 'successes' && attempt > 1) {
+      metrics.retries += (attempt - 1);
+    }
+  }
+}
+
+module.exports = PublishMonitor;
+