@onlineapps/mq-client-core 2.0.1 → 3.0.0

package/src/workers/RecoveryWorker.js

@@ -1,49 +1,57 @@
 'use strict';
 
 const { QueueNotFoundError } = require('../utils/publishErrors');
+const { ValidationError } = require('../utils/errorHandler');
+const { assertLogger } = require('@onlineapps/logger-contract');
 
 /**
- * RecoveryWorker - řeší problémy s publish (connection recovery, queue creation)
- * 
- * Scope:
- * - infrastructure: connection recovery, channel recreation, consumer re-registration (NENÍ queue creation)
- * - business: totéž + zakládání front, ale POUZE těch, které nemají vlastníka
- *   (viz Queue Creation níže). Scope říká, ČÍ ten klient je — ne co smí založit.
+ * RecoveryWorker — odpovídá na problémy publish cesty (connection recovery,
+ * hlášení chybějící fronty).
  *
- * Queue Creation — vlastnictví fronty rozhoduje, ne scope:
- * - infrastrukturní fronty (`queueConfig.isInfrastructureQueue`) zakládá vlastnící
- *   infra služba předem → tento worker je nikdy nezaloží, chybu propustí dál;
- * - business fronty (`queueConfig.isBusinessQueue`, tj. `{service}.{workflow|queue|dlq}`)
- *   zakládá vlastnící služba přes `setupServiceQueues()` po registraci, s argumenty
- *   z queueConfig (TTL, DLQ) → tento worker je nikdy nezaloží, chybu propustí dál;
- * - ostatní jména (ani infra, ani business vzor) smí založit, pokud to scope
- *   a `queueCreationFilter` dovolují — buď přes `queueCreationCallback`
- *   (deleguje na QueueManager), nebo přímo.
+ * Zakládání front — NEZAKLÁDÁ ŽÁDNOU. Fronta vzniká výhradně z deklarace:
+ * infrastrukturní ji zakládá vlastnící infra služba při bootu, business ji
+ * zakládá vlastnící služba přes `setupServiceQueues()` nad šablonou z
+ * `queueConfig` po registraci, a jméno, které `queueConfig` neklasifikuje ani
+ * jako jedno, nezakládá nikdo. Rozhodnutí vlastníka
+ * (`docs/governance/confirmations/mq-consumer-contract.md` 006) říká obojí
+ * větou: *„queues come into being only from declarations"* a *„A future family
+ * of queues that a service must create ad hoc gets a `queueConfig` template
+ * first, never a generic create-anything method."*
+ *
+ * Do d.419 tady byly DRUHÉ dveře k těm, které publish cesta v témže kroku
+ * zavírala: `createQueue()` a delegující `queueCreationCallback` zakládaly
+ * frontu bez vlastníka s `durable=true, arguments={}` — bez TTL a bez cesty pro
+ * nedoručitelné zprávy. Taková fronta je od d.259 nekonzumovatelná
+ * (`consume()` odmítne frontu, které konfigurace žádnou cestu nedeklaruje), takže
+ * ty dveře vyráběly fronty, do kterých lze publikovat a nelze z nich číst.
+ * Čtyři otázky (`change-discipline.md` § Removing something removes its
+ * declaration) jsou zodpovězené v CHANGELOGu dávky.
+ *
+ * `scope` tedy už o zakládání front nerozhoduje; říká jen, čí ten klient je.
  */
 class RecoveryWorker {
   /**
    * @param {Object} options
    * @param {Object} options.client - RabbitMQClient instance
    * @param {string} [options.scope='infrastructure'] - 'infrastructure' nebo 'business'
-   * @param {Function} [options.queueCreationCallback] - Callback for queue creation: async (queueName, options) => void
-   *   Should delegate to QueueManager (e.g., setupServiceQueues or ensureQueue)
-   * @param {Object} [options.logger] - Logger
+   * @param {Object} options.logger - Logger s info/warn/error/debug (povinny)
    */
   constructor(options = {}) {
     if (!options.client) {
-      throw new Error('RecoveryWorker requires a client instance');
+      throw new ValidationError(
+        '[RecoveryWorker] options.client is required - Expected: the RabbitMQClient whose publish failures the worker answers. '
+          + 'Fix: construct it as new RecoveryWorker({ client, logger }).'
+      );
     }
 
     this._client = options.client;
     this._scope = options.scope || 'infrastructure';
-    this._logger = options.logger || console;
-
-    // Scope configuration
-    this._queueCreationEnabled = this._scope === 'business';
-    this._queueCreationFilter = options.queueCreationFilter || null;
-    
-    // Queue creation callback - delegates to QueueManager if provided
-    this._queueCreationCallback = options.queueCreationCallback || null;
+    this._logger = assertLogger(
+      'RecoveryWorker',
+      options.logger,
+      'the worker reports every recovery decision it makes about a queue that does not exist',
+      'pass options.logger (the transport forwards the one your service built)'
+    );
   }
 
   /**
@@ -54,11 +62,16 @@ class RecoveryWorker {
   async handleTransientError(error, context) {
     // Transient errors jsou už bufferované v PublishLayer
     // Recovery worker jen loguje a může triggerovat další akce
-    this._logger?.warn?.(`[RecoveryWorker] Transient error handled (buffered): ${error.message}`, context);
+    this._logger.warn(`[RecoveryWorker] Transient error handled (buffered): ${error.message}`, context);
   }
 
   /**
-   * Handle QueueNotFoundError
+   * Report a queue that does not exist, and rethrow.
+   *
+   * Every class of name ends the same way — the worker creates nothing — and the
+   * three branches differ only in which rule the reader has to act on: who owns
+   * the queue, and how it is meant to come into being.
+   *
    * @param {QueueNotFoundError} error
    * @param {Object} context - { queue, buffer, options }
    */
@@ -69,7 +82,7 @@ class RecoveryWorker {
 
     // Infrastructure queues must exist - cannot create
     if (error.isInfrastructure) {
-      this._logger?.error?.(`[RecoveryWorker] Cannot create infrastructure queue '${error.queueName}' - must exist before publishing`);
+      this._logger.error(`[RecoveryWorker] Cannot create infrastructure queue '${error.queueName}' - must exist before publishing`);
       throw error;
     }
 
@@ -89,61 +102,25 @@ class RecoveryWorker {
     // never meant "may create business queues", and ConnectorMQClient.js:74 sets
     // it for every biz service, so that reading made the rule vacuous.
     if (error.kind === 'business') {
-      this._logger?.error?.(`[RecoveryWorker] Cannot create business queue '${error.queueName}' - it is created by its owning service via setupServiceQueues() after registration`);
-      throw error;
-    }
-
-    // Everything else - create if scope allows
-    if (this._queueCreationEnabled) {
-      // Check filter if provided
-      if (this._queueCreationFilter && !this._queueCreationFilter(error.queueName)) {
-        this._logger?.warn?.(`[RecoveryWorker] Queue creation filtered out for '${error.queueName}'`);
-        throw error;
-      }
-
-      try {
-        // Use queue creation callback if provided (delegates to QueueManager)
-        // Otherwise fall back to direct queue creation (backward compatibility)
-        if (this._queueCreationCallback) {
-          this._logger?.info?.(`[RecoveryWorker] Delegating queue creation to callback for '${error.queueName}'`);
-          await this._queueCreationCallback(error.queueName, context.options);
-          this._logger?.info?.(`[RecoveryWorker] ✓ Queue '${error.queueName}' created via callback`);
-        } else {
-          // Fallback: direct queue creation (for backward compatibility)
-          await this.createQueue(error.queueName, context.options);
-          this._logger?.info?.(`[RecoveryWorker] ✓ Created queue '${error.queueName}' (direct)`);
-        }
-      } catch (createErr) {
-        this._logger?.error?.(`[RecoveryWorker] Failed to create queue '${error.queueName}': ${createErr.message}`);
-        throw error;
-      }
-    } else {
-      this._logger?.error?.(`[RecoveryWorker] Cannot create queue '${error.queueName}' - scope is '${this._scope}' (queue creation disabled)`);
+      this._logger.error(`[RecoveryWorker] Cannot create business queue '${error.queueName}' - it is created by its owning service via setupServiceQueues() after registration`);
       throw error;
     }
-  }
 
-  /**
-   * Create queue (business services only)
-   * @private
-   */
-  async createQueue(queueName, options = {}) {
-    if (!this._queueCreationEnabled) {
-      throw new Error(`Queue creation not enabled for scope '${this._scope}'`);
-    }
-
-    // Use queue channel to create queue
-    await this._client._ensureQueueChannel();
-    
-    // Guard: ensure queue channel is available after ensure
-    if (!this._client._queueChannel || this._client._queueChannel.closed) {
-      throw new Error(`Cannot create queue ${queueName}: queue channel is not available (connection may be closed)`);
-    }
-    
-    const queueOptions = options.queueOptions || { durable: this._client._config.durable };
-    await this._client._queueChannel.assertQueue(queueName, queueOptions);
+    // Everything else — a name `queueConfig` classifies as neither. Until d.419
+    // this was the one branch that DID create, and it is the same "one door
+    // refuses while the other opens" the business branch above records, one class
+    // of name further out: the publish path refused the name and this handler,
+    // answering the very error that refusal raised, declared it anyway. There is
+    // no owner to start and no template to call, so the report names the only
+    // thing the reader can act on — the missing declaration.
+    this._logger.error(
+      `[RecoveryWorker] Cannot create queue '${error.queueName}' - no section of queueConfig declares it, `
+        + 'and a queue is only ever brought into being from a declaration. Fix: add a template for this '
+        + 'name to queueConfig and let its owner declare it (confirmation mq-consumer-contract 003), or '
+        + 'publish to a queue that already has one.'
+    );
+    throw error;
   }
 }
 
 module.exports = RecoveryWorker;
-

package/src/buffer/RedisBuffer.js

@@ -1,57 +0,0 @@
-'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;
-
-