@onlineapps/conn-orch-registry 3.0.0 → 4.0.0

package/src/queueManager.js

@@ -1,25 +1,41 @@
 /**
  * queueManager.js
  *
- * Responsible for connecting to RabbitMQ and asserting/confirming the existence of queues
- * used by the microservice connector.
+ * The one MQ connection of the registry connector, and the only surface through
+ * which this package talks to the broker.
  *
  * Overview:
- *   - Queues managed by the microservice: 'workflow' and '<serviceName>.registry'
- *   - On startup: assertQueue for all required queues
- *   - Provides access to the channel for further operations (send, consume)
+ *   - Owns a single `@onlineapps/mq-client-core` client: connect, declare,
+ *     publish, consume, close.
+ *   - Queues managed by the microservice: `<serviceName>.registry` and
+ *     `<serviceName>.registry.events`. Their names are business-queue names and
+ *     their DECLARATION (durability, TTL, dead-letter route) belongs to
+ *     `queueConfig` in the core — never to an options object written here.
+ *   - Infrastructure queues (`registry.register`, …) are CHECKED, never
+ *     asserted: they are created by the infrastructure service that owns them
+ *     (`api/docs/standards/queue-ownership.md`).
+ *
+ * Why there is no `channel` on this object any more (d.198b-3): until 2026-09-14
+ * this class handed out a raw amqplib channel, and both consumers of the package
+ * settled every delivery on it by hand — `channel.ack(msg)` / `channel.nack(msg,
+ * false, false)`. That is a second implementation of the delivery contract
+ * (`.claude/rules/change-discipline.md` § One rail per concern) and the half that
+ * cannot count: a hand-written nack knows nothing about the attempt budget, the
+ * `x-oa-delivery-attempts` header or the `message_dlq` event the core publishes.
+ * `consume()` below forwards to the core's, which owns all three.
  *
  * Usage:
- *   const qm = new QueueManager(amqpUrl, serviceName);
+ *   const qm = new QueueManager(amqpUrl, serviceName, logger);
  *   await qm.init();
- *   await qm.ensureQueues();
- *   const { channel } = qm;
+ *   await qm.consume(`${serviceName}.registry`, handler, { requeueOnError: false });
  *
- * @module @onlineapps/connector-registry-client/src/queueManager
+ * @see node_modules/@onlineapps/mq-client-core/README.md § `consume()` — the delivery contract
+ * @module @onlineapps/conn-orch-registry/src/queueManager
  */
 
-const amqp = require('amqplib');
-const queueConfig = require('@onlineapps/mq-client-core/src/config/queueConfig');
+const BaseClient = require('@onlineapps/mq-client-core');
+const { queueConfig, redactUrl } = require('@onlineapps/mq-client-core');
+const { assertLogger } = require('@onlineapps/logger-contract');
 
 /**
  * Queue manager for the microservice connector.
@@ -28,148 +44,177 @@ class QueueManager {
   /**
    * @param {string} amqpUrl - RabbitMQ server URL (AMQP URI)
    * @param {string} serviceName - Name of the microservice (e.g. 'invoicing')
+   * @param {Object} logger - Logger with info/warn/error/debug; required, validated here
+   *   (docs/governance/confirmations/connector-logger-contract.md 001)
    */
-  constructor(amqpUrl, serviceName) {
-    if (!amqpUrl) throw new Error('amqpUrl is required');
-    if (!serviceName) throw new Error('serviceName is required');
+  constructor(amqpUrl, serviceName, logger) {
+    if (!amqpUrl) {
+      throw new Error(
+        '[QueueManager] Missing constructor argument - amqpUrl is required. '
+        + 'Fix: pass the AMQP URI as the first argument, e.g. new QueueManager(process.env.RABBITMQ_URL, serviceName, logger).'
+      );
+    }
+    if (!serviceName) {
+      throw new Error(
+        '[QueueManager] Missing constructor argument - serviceName is required. '
+        + 'Fix: pass the registering service name as the second argument.'
+      );
+    }
+    this.logger = assertLogger('QueueManager', logger, 'queue lifecycle events reach the service log');
     this.amqpUrl = amqpUrl;
+    // The URL carries the broker credential, so nothing that reaches a message or
+    // a log line uses `this.amqpUrl` — only this redacted form. The redactor is
+    // the platform's one (`@onlineapps/mq-client-core`, d.448); a local copy stood
+    // here until d.446b, from the days when that package masked the password alone.
+    this.safeAmqpUrl = redactUrl(amqpUrl);
     this.serviceName = serviceName;
-    this.conn = null;
-    this.channel = null;
+    this.client = new BaseClient({
+      type: 'rabbitmq',
+      host: amqpUrl,
+      serviceName,
+      logger: this.logger
+    });
   }
 
   /**
-   * Initializes the connection and channel to RabbitMQ.
-   * @returns {Promise<void>} 
-   * @throws {Error} If connection or channel creation fails or times out
+   * Opens the connection to RabbitMQ.
+   * @returns {Promise<void>}
+   * @throws {Error} If connecting fails; the message names the broker without its credential.
    */
   async init() {
-    const CONNECT_TIMEOUT = 10000; // 10 seconds
-    let connectTimeout;
-    const connectPromise = amqp.connect(this.amqpUrl);
-    const connectTimeoutPromise = new Promise((_, reject) => {
-      connectTimeout = setTimeout(() => {
-        reject(new Error(`RabbitMQ connection timeout after ${CONNECT_TIMEOUT}ms. RabbitMQ may be unavailable at ${this.amqpUrl}`));
-      }, CONNECT_TIMEOUT);
-    });
-
     try {
-      this.conn = await Promise.race([connectPromise, connectTimeoutPromise]);
+      await this.client.connect();
     } catch (error) {
-      throw new Error(`[QueueManager] Failed to connect to RabbitMQ: ${error.message}`);
-    } finally {
-      if (connectTimeout) clearTimeout(connectTimeout);
+      // The core's refusal says "the configured host" without naming it — which
+      // host is exactly what a reader of a boot failure needs, so it is added
+      // here, redacted, with the core's error as the cause.
+      throw new Error(
+        `[QueueManager] Failed to connect to RabbitMQ at ${this.safeAmqpUrl} - ${error.message}. `
+        + 'Fix: check broker health and the credentials in the AMQP URI.',
+        { cause: error }
+      );
     }
+  }
 
-    // Use regular channel instead of ConfirmChannel to avoid RPC reply queue issues
-    // ConfirmChannel uses RPC pattern which requires reply queues that may not exist
-    const CHANNEL_TIMEOUT = 5000; // 5 seconds
-    let channelTimeout;
-    const channelPromise = this.conn.createChannel();
-    const channelTimeoutPromise = new Promise((_, reject) => {
-      channelTimeout = setTimeout(() => {
-        reject(new Error(`Channel creation timeout after ${CHANNEL_TIMEOUT}ms`));
-      }, CHANNEL_TIMEOUT);
-    });
+  /**
+   * Is the broker connection open? The one question `register()` asks before it
+   * publishes; a closed client is not reusable.
+   * @returns {boolean}
+   */
+  isConnected() {
+    return this.client.isConnected();
+  }
 
-    try {
-      this.channel = await Promise.race([channelPromise, channelTimeoutPromise]);
-    } catch (error) {
-      // Clean up connection on channel creation failure
+  /**
+   * Declares the business queues this service owns.
+   *
+   * The declaration — durability, TTL, cap, dead-letter route — comes from
+   * `queueConfig` inside the core and is never written here: a name the central
+   * config declares carries no caller options, and asserting one with arguments
+   * of our own is how a queue ends up declared two different ways and the broker
+   * answers the second declarer `406 PRECONDITION-FAILED`.
+   *
+   * @param {Array<string>} [queues=[]] - Business queue names owned by this service
+   * @returns {Promise<void>}
+   * @throws {Error} If a name is an infrastructure queue, or the broker refuses the declaration.
+   */
+  async ensureQueues(queues = []) {
+    for (const q of queues) {
+      if (queueConfig.isInfrastructureQueue(q)) {
+        // Not logged before throwing: the thrown error carries the queue name and the
+        // reason, and whoever handles it decides whether that is worth a log line.
+        throw new Error(
+          `[QueueManager] [REGISTRY] Refusing to assert infrastructure queue '${q}' - `
+          + 'these queues are owned by infrastructure services and must exist before a business service starts. '
+          + 'Fix: let the owning infrastructure service create it, or pass a business queue name.'
+        );
+      }
+
+      const assertStartTime = Date.now();
       try {
-        await this.conn.close();
-      } catch (closeErr) {
-        // Ignore close errors
+        await this.client.assertQueue(q);
+      } catch (assertErr) {
+        const errorMsg = assertErr.message || String(assertErr);
+        throw new Error(
+          `[QueueManager] Failed to assert queue ${q} - ${errorMsg} (code ${assertErr.code || 'N/A'}). `
+          + 'Fix: a 406 PRECONDITION-FAILED means the queue exists with different arguments; '
+          + 'align them or let its owner declare it.',
+          { cause: assertErr }
+        );
       }
-      throw new Error(`[QueueManager] Failed to create channel: ${error.message}`);
-    } finally {
-      if (channelTimeout) clearTimeout(channelTimeout);
+      this.logger.debug('[QueueManager] Queue asserted', {
+        serviceName: this.serviceName,
+        queue: q,
+        durationMs: Date.now() - assertStartTime
+      });
     }
   }
 
   /**
-   * Ensures all required queues exist. Creates them if they don't.
-   * @param {Array<string>} [additionalQueues=[]] - Any additional custom queues
-   * @returns {Promise<void>}
+   * Confirms an infrastructure queue exists without creating it.
+   * @param {string} queue - Queue name
+   * @returns {Promise<Object>} The broker's `queue.declare-ok`
    */
-  async ensureQueues(additionalQueues = []) {
-    if (!this.channel) {
-      throw new Error('Channel is not initialized. Call init() first.');
-    }
+  async checkQueue(queue) {
+    return this.client.checkQueue(queue);
+  }
 
-    // Default queues for the registry client
-    const baseQueues = [];
+  /**
+   * Declares an exchange this package binds to.
+   * @param {string} exchange - Exchange name
+   * @param {string} type - Exchange type; required, never guessed
+   * @param {Object} [options] - Exchange options
+   * @returns {Promise<Object>}
+   */
+  async assertExchange(exchange, type, options = {}) {
+    return this.client.assertExchange(exchange, type, options);
+  }
 
-    const queuesToCreate = baseQueues.concat(additionalQueues);
+  /**
+   * Binds one of this service's queues to an exchange.
+   * @param {string} queue
+   * @param {string} exchange
+   * @param {string} pattern - Routing pattern; `''` is legal for a fanout
+   * @returns {Promise<Object>}
+   */
+  async bindQueue(queue, exchange, pattern) {
+    return this.client.bindQueue(queue, exchange, pattern);
+  }
 
-    for (const q of queuesToCreate) {
-      console.log(`[QueueManager] [REGISTRY] [QUEUE] Ensuring queue: ${q} at ${new Date().toISOString()}`);
-      
-      // CRITICAL: Use queueConfig.js to get correct parameters (TTL, max-length, etc.)
-      // This prevents 406 PRECONDITION-FAILED errors from TTL mismatches
-      let queueOptions = { durable: true };
-      const isInfrastructureQueue = queueConfig?.isInfrastructureQueue
-        ? queueConfig.isInfrastructureQueue(q)
-        : ['workflow.', 'registry.', 'infrastructure.', 'validation.', 'monitoring.', 'delivery.'].some(prefix => q.startsWith(prefix));
+  /**
+   * Publishes one message.
+   * @param {string} queue - Target queue (or the exchange's name when `options.exchange` is set)
+   * @param {Object} message - Payload; serialized by the core
+   * @param {Object} [options] - `persistent`, `exchange`, `routingKey`, `headers`
+   * @returns {Promise<void>} Resolves when published; THROWS on failure — there is no falsy return
+   */
+  async publish(queue, message, options = {}) {
+    return this.client.publish(queue, message, options);
+  }
 
-      if (isInfrastructureQueue) {
-        const message = `[QueueManager] [REGISTRY] Refusing to assert infrastructure queue '${q}'. ` +
-          'These queues are owned by infrastructure services and must be created before business services start.';
-        console.error(message);
-        throw new Error(message);
-      }
-      
-      if (queueConfig) {
-        try {
-          console.warn(`[QueueManager] [REGISTRY] [QUEUE] Queue ${q} is not an infrastructure queue, using default options`);
-        } catch (configErr) {
-          console.warn(`[QueueManager] [REGISTRY] [QUEUE] Failed to get config for ${q}, using defaults:`, configErr.message);
-        }
-      } else {
-        console.warn(`[QueueManager] [REGISTRY] [QUEUE] queueConfig not available, using default options for ${q}`);
-      }
-      
-      // Directly assert queue with canonical configuration (idempotent)
-      try {
-        const assertStartTime = Date.now();
-        const ASSERT_TIMEOUT = 5000; // 5 seconds
-        let assertTimeout;
-        const assertPromise = this.channel.assertQueue(q, queueOptions);
-        const assertTimeoutPromise = new Promise((_, reject) => {
-          assertTimeout = setTimeout(() => {
-            reject(new Error(`assertQueue timeout after ${ASSERT_TIMEOUT}ms`));
-          }, ASSERT_TIMEOUT);
-        });
-        
-        try {
-          await Promise.race([assertPromise, assertTimeoutPromise]);
-        } finally {
-          if (assertTimeout) clearTimeout(assertTimeout);
-        }
-        const assertEndTime = Date.now();
-        console.log(`[QueueManager] [REGISTRY] [QUEUE] ✓ Queue ${q} asserted (took ${assertEndTime - assertStartTime}ms)`);
-      } catch (assertErr) {
-        const errorMsg = assertErr.message || String(assertErr);
-        console.error(`[QueueManager] [REGISTRY] [QUEUE] ✗ Failed to assert queue ${q}: ${errorMsg}`);
-        console.error(`[QueueManager] [REGISTRY] [QUEUE] Error code: ${assertErr.code || 'N/A'}`);
-        throw new Error(`[QueueManager] Failed to assert queue ${q}: ${errorMsg}`);
-      }
-    }
+  /**
+   * Attaches a consumer on the core's delivery rail.
+   *
+   * The handler reports failure by THROWING. Settling is the core's: a handler
+   * that returns is acked once, a handler that throws is counted against the
+   * delivery budget and, when the budget is spent, rejected into `<service>.dlq`
+   * with a `message_dlq` event.
+   *
+   * @param {string} queue
+   * @param {function(Object, Object): Promise<void>} handler
+   * @param {Object} [options] - `requeueOnError`, `maxAttempts`, `classify`, `prefetch`
+   * @returns {Promise<string>} The broker's consumer tag
+   */
+  async consume(queue, handler, options = {}) {
+    return this.client.consume(queue, handler, options);
   }
 
   /**
-   * Closes the channel and connection.
+   * Closes the connection.
    * @returns {Promise<void>}
    */
   async close() {
-    if (this.channel) {
-      await this.channel.close();
-      this.channel = null;
-    }
-    if (this.conn) {
-      await this.conn.close();
-      this.conn = null;
-    }
+    await this.client.disconnect();
   }
 }