@onlineapps/conn-infra-mq 1.1.10 → 1.1.12

package/README.md

@@ -38,7 +38,7 @@ yarn add @onlineapps/conn-infra-mq
 ## 🏗️ Architecture
 
 ```
-ConnectorMQClient (main orchestrator)
+ConnectorMQClient (main orchestrator - for business services only)
     ├── BaseClient (core AMQP operations)
     ├── WorkflowRouter (workflow orchestration)
     ├── QueueManager (queue lifecycle management)
@@ -47,6 +47,25 @@ ConnectorMQClient (main orchestrator)
     └── RetryHandler (error recovery & DLQ)
 ```
 
+### WorkflowRouter - How It Works
+
+**Purpose**: Handles workflow routing between services in a decentralized architecture.
+
+**Key Methods**:
+- `publishWorkflowInit(workflow, options)` - Publishes workflow to `workflow.init` queue (entry point)
+- `publishToServiceWorkflow(serviceName, message, options)` - Routes to specific service's workflow queue
+- `publishWorkflowCompleted(result, options)` - Publishes completed workflow to `workflow.completed` queue
+- `consumeWorkflowInit(handler, options)` - Consumes from `workflow.init` (competing consumers pattern)
+- `consumeServiceWorkflow(serviceName, handler, options)` - Consumes from service-specific workflow queue
+
+**How It Works**:
+1. **Gateway** publishes to `workflow.init` via `publishWorkflowInit()`
+2. **Business services** (competing consumers) consume from `workflow.init` via `consumeWorkflowInit()`
+3. **Services** route to next service via `publishToServiceWorkflow()`
+4. **Final service** publishes completion via `publishWorkflowCompleted()`
+
+**Note**: WorkflowRouter is part of `conn-infra-mq` connector (for business services). Infrastructure services (gateway) should use the underlying MQ client library directly, not the connector.
+
 ## 🔧 Quick Start
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@onlineapps/conn-infra-mq",
-    "version": "1.1.10",
+    "version": "1.1.12",
     "description": "A promise-based, broker-agnostic client for sending and receiving messages via RabbitMQ",
     "main": "src/index.js",
     "repository": {
@@ -42,6 +42,7 @@
     },
     "homepage": "https://github.com/onlineapps/connector-mq-client#readme",
     "dependencies": {
+        "@onlineapps/mq-client-core": "^1.0.0",
         "ajv": "^8.11.0",
         "amqplib": "^0.10.3",
         "lodash.merge": "^4.6.2"

package/src/ConnectorMQClient.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const BaseClient = require('./BaseClient');
+const BaseClient = require('@onlineapps/mq-client-core');
 const WorkflowRouter = require('./layers/WorkflowRouter');
 const QueueManager = require('./layers/QueueManager');
 const ForkJoinHandler = require('./layers/ForkJoinHandler');

package/src/config/configSchema.js

@@ -72,6 +72,6 @@ module.exports = {
       additionalProperties: false,
     },
   },
-  required: ['type', 'host', 'queue'],
+  required: ['type', 'host', 'queue', 'serviceName'],
   additionalProperties: false,
 };

package/src/index.js

@@ -12,7 +12,7 @@
  */
 
 const ConnectorMQClient = require('./ConnectorMQClient');
-const BaseClient = require('./BaseClient');
+const BaseClient = require('@onlineapps/mq-client-core');
 
 // Layers - exported for advanced usage
 const WorkflowRouter = require('./layers/WorkflowRouter');

package/src/layers/QueueManager.js

@@ -80,8 +80,23 @@ class QueueManager {
     // Track managed queue
     this.managedQueues.add(queueName);
 
-    // Assert the queue
-    return channel.assertQueue(queueName, queueOptions);
+    // Use checkQueue first to avoid 406 PRECONDITION-FAILED closing the channel
+    // If queue doesn't exist (404), then assertQueue to create it
+    try {
+      await channel.checkQueue(queueName);
+      // Queue exists - return queue info
+      return channel.checkQueue(queueName);
+    } catch (checkErr) {
+      // If queue doesn't exist (404), create it with provided options
+      if (checkErr.code === 404) {
+        return channel.assertQueue(queueName, queueOptions);
+      } else {
+        // Other error (including 406) - queue exists with different args
+        // Log warning and return queue info without asserting
+        console.warn(`[QueueManager] Queue ${queueName} exists with different arguments, using as-is:`, checkErr.message);
+        return channel.checkQueue(queueName);
+      }
+    }
   }
 
   /**
@@ -154,30 +169,60 @@ class QueueManager {
     const queues = {};
 
     // Create main processing queue
-    await this.ensureQueue(`${serviceName}.queue`, {
-      ttl: options.ttl || this.config.defaultTTL,
-      dlq: true,
-      durable: true,
-      maxRetries: this.config.maxRetries
-    });
+    // Handle PRECONDITION-FAILED gracefully - queue may exist with different args
+    try {
+      await this.ensureQueue(`${serviceName}.queue`, {
+        ttl: options.ttl || this.config.defaultTTL,
+        dlq: true,
+        durable: true,
+        maxRetries: this.config.maxRetries
+      });
+    } catch (error) {
+      if (error.code === 406) {
+        // Queue exists with different arguments - use it as-is
+        console.warn(`[QueueManager] Queue ${serviceName}.queue exists with different arguments, using as-is`);
+        // Verify queue exists
+        await channel.checkQueue(`${serviceName}.queue`);
+      } else {
+        throw error;
+      }
+    }
     queues.main = `${serviceName}.queue`;
 
     // Create dead letter queue
-    await this.ensureQueue(`${serviceName}.dlq`, {
-      ttl: null, // No TTL for DLQ
-      dlq: false,
-      durable: true,
-      autoDelete: false
-    });
+    try {
+      await this.ensureQueue(`${serviceName}.dlq`, {
+        ttl: null, // No TTL for DLQ
+        dlq: false,
+        durable: true,
+        autoDelete: false
+      });
+    } catch (error) {
+      if (error.code === 406) {
+        console.warn(`[QueueManager] Queue ${serviceName}.dlq exists with different arguments, using as-is`);
+        await channel.checkQueue(`${serviceName}.dlq`);
+      } else {
+        throw error;
+      }
+    }
     queues.dlq = `${serviceName}.dlq`;
 
     // Create workflow queue if requested
     if (options.includeWorkflow !== false) {
-      await this.ensureQueue(`${serviceName}.workflow`, {
-        ttl: options.workflowTTL || this.config.defaultTTL,
-        dlq: true,
-        durable: true
-      });
+      try {
+        await this.ensureQueue(`${serviceName}.workflow`, {
+          ttl: options.workflowTTL || this.config.defaultTTL,
+          dlq: true,
+          durable: true
+        });
+      } catch (error) {
+        if (error.code === 406) {
+          console.warn(`[QueueManager] Queue ${serviceName}.workflow exists with different arguments, using as-is`);
+          await channel.checkQueue(`${serviceName}.workflow`);
+        } else {
+          throw error;
+        }
+      }
       queues.workflow = `${serviceName}.workflow`;
     }
 

package/src/layers/WorkflowRouter.js

@@ -21,10 +21,8 @@ class WorkflowRouter {
    * @param {Object} options - Additional publish options
    */
   async publishWorkflowInit(workflow, options = {}) {
-    return this.client.publish(workflow, {
-      queue: this.config.workflowInitQueue,
-      ...options
-    });
+    // BaseClient.publish expects: publish(queue, message, options)
+    return this.client.publish(this.config.workflowInitQueue, workflow, options);
   }
 
   /**
@@ -34,10 +32,8 @@ class WorkflowRouter {
    * @param {Object} options - Additional publish options
    */
   async publishToServiceWorkflow(serviceName, message, options = {}) {
-    return this.client.publish(message, {
-      queue: `${serviceName}.workflow`,
-      ...options
-    });
+    // BaseClient.publish expects: publish(queue, message, options)
+    return this.client.publish(`${serviceName}.workflow`, message, options);
   }
 
   /**
@@ -47,10 +43,8 @@ class WorkflowRouter {
    * @param {Object} options - Additional publish options
    */
   async publishToService(serviceName, message, options = {}) {
-    return this.client.publish(message, {
-      queue: `${serviceName}.queue`,
-      ...options
-    });
+    // BaseClient.publish expects: publish(queue, message, options)
+    return this.client.publish(`${serviceName}.queue`, message, options);
   }
 
   /**
@@ -59,10 +53,8 @@ class WorkflowRouter {
    * @param {Object} options - Additional publish options
    */
   async publishWorkflowCompleted(result, options = {}) {
-    return this.client.publish(result, {
-      queue: this.config.workflowCompletedQueue,
-      ...options
-    });
+    // BaseClient.publish expects: publish(queue, message, options)
+    return this.client.publish(this.config.workflowCompletedQueue, result, options);
   }
 
   /**
@@ -95,10 +87,8 @@ class WorkflowRouter {
    * @param {Object} options - Consume options
    */
   async consumeWorkflowInit(handler, options = {}) {
-    return this.client.consume(handler, {
-      queue: this.config.workflowInitQueue,
-      ...options
-    });
+    // BaseClient.consume expects: consume(queue, handler, options)
+    return this.client.consume(this.config.workflowInitQueue, handler, options);
   }
 
   /**
@@ -114,10 +104,8 @@ class WorkflowRouter {
       serviceName = this.config.serviceName;
     }
 
-    return this.client.consume(handler, {
-      queue: `${serviceName}.workflow`,
-      ...options
-    });
+    // BaseClient.consume expects: consume(queue, handler, options)
+    return this.client.consume(`${serviceName}.workflow`, handler, options);
   }
 
   /**
@@ -126,10 +114,8 @@ class WorkflowRouter {
    * @param {Object} options - Consume options
    */
   async consumeWorkflowCompleted(handler, options = {}) {
-    return this.client.consume(handler, {
-      queue: this.config.workflowCompletedQueue,
-      ...options
-    });
+    // BaseClient.consume expects: consume(queue, handler, options)
+    return this.client.consume(this.config.workflowCompletedQueue, handler, options);
   }
 }
 

package/src/BaseClient.js

@@ -1,219 +0,0 @@
-'use strict';
-
-/**
- * ConnectorMQClient: a promise-based, broker-agnostic client for RabbitMQ
- * Uses transportFactory to select the appropriate transport implementation.
- */
-
-const Ajv = require('ajv');
-const merge = require('lodash.merge');
-
-const configSchema = require('./config/configSchema');
-const defaultConfig = require('./config/defaultConfig');
-const transportFactory = require('./transports/transportFactory');
-const serializer = require('./utils/serializer');
-const {
-  ConnectionError,
-  PublishError,
-  ConsumeError,
-  ValidationError,
-  SerializationError,
-} = require('./utils/errorHandler');
-
-class ConnectorMQClient {
-  /**
-   * @param {Object} config - User-supplied configuration.
-   * @throws {ValidationError} If required fields are missing or invalid.
-   */
-  constructor(config) {
-    const ajv = new Ajv({ allErrors: true, useDefaults: true });
-    const validate = ajv.compile(configSchema);
-
-    // Merge user config with defaults
-    this._config = merge({}, defaultConfig, config || {});
-
-    // Validate merged config
-    const valid = validate(this._config);
-    if (!valid) {
-      const details = validate.errors.map((err) => ({
-        path: err.instancePath,
-        message: err.message,
-      }));
-      throw new ValidationError('Invalid configuration', details);
-    }
-
-    this._transport = null;
-    this._connected = false;
-    this._errorHandlers = [];
-  }
-
-  /**
-   * Connects to the message broker using merged configuration.
-   * @param {Object} [options] - Optional overrides for host, queue, etc.
-   * @returns {Promise<void>}
-   * @throws {ConnectionError} If connecting fails.
-   */
-  async connect(options = {}) {
-    if (this._connected) return;
-
-    // Merge overrides into existing config
-    this._config = merge({}, this._config, options);
-
-    try {
-      // Instantiate appropriate transport: RabbitMQClient 
-      this._transport = transportFactory.create(this._config);
-
-      // Register internal error propagation
-      this._transport.on('error', (err) => this._handleError(err));
-
-      await this._transport.connect(this._config);
-      this._connected = true;
-    } catch (err) {
-      throw new ConnectionError('Failed to connect to broker', err);
-    }
-  }
-
-  /**
-   * Disconnects from the message broker.
-   * @returns {Promise<void>}
-   * @throws {Error} If disconnecting fails unexpectedly.
-   */
-  async disconnect() {
-    if (!this._connected || !this._transport) return;
-    try {
-      await this._transport.disconnect();
-      this._connected = false;
-      this._transport = null;
-    } catch (err) {
-      throw new Error(`Error during disconnect: ${err.message}`);
-    }
-  }
-
-  /**
-   * Publishes a message to the specified queue.
-   * @param {string} queue - Target queue name.
-   * @param {Object|Buffer|string} message - Payload to send.
-   * @param {Object} [options] - RabbitMQ-specific overrides (routingKey, persistent, headers).
-   * @returns {Promise<void>}
-   * @throws {ConnectionError} If not connected.
-   * @throws {PublishError} If publish fails.
-   */
-  async publish(queue, message, options = {}) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot publish: client is not connected');
-    }
-
-    let buffer;
-    try {
-      if (Buffer.isBuffer(message)) {
-        buffer = message;
-      } else if (typeof message === 'string') {
-        buffer = Buffer.from(message, 'utf8');
-      } else {
-        const json = serializer.serialize(message);
-        buffer = Buffer.from(json, 'utf8');
-      }
-    } catch (err) {
-      throw new SerializationError('Failed to serialize message', message, err);
-    }
-
-    try {
-      await this._transport.publish(queue, buffer, options);
-    } catch (err) {
-      throw new PublishError(`Failed to publish to queue "${queue}"`, queue, err);
-    }
-  }
-
-  /**
-   * Begins consuming messages from the specified queue.
-   * @param {string} queue - Name of the queue to consume from.
-   * @param {function(Object): Promise<void>} messageHandler - Async function to process each message.
-   * @param {Object} [options] - RabbitMQ-specific overrides (prefetch, noAck).
-   * @returns {Promise<void>}
-   * @throws {ConnectionError} If not connected.
-   * @throws {ConsumeError} If consumer setup fails.
-   */
-  async consume(queue, messageHandler, options = {}) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot consume: client is not connected');
-    }
-
-    // Apply prefetch and noAck overrides if provided
-    const { prefetch, noAck } = options;
-    const consumeOptions = {};
-    if (typeof prefetch === 'number') consumeOptions.prefetch = prefetch;
-    if (typeof noAck === 'boolean') consumeOptions.noAck = noAck;
-
-    try {
-      await this._transport.consume(
-        queue,
-        async (msg) => {
-          try {
-            await messageHandler(msg);
-            if (consumeOptions.noAck === false) {
-              await this.ack(msg);
-            }
-          } catch (handlerErr) {
-            // On handler error, nack with requeue: true
-            await this.nack(msg, { requeue: true });
-          }
-        },
-        consumeOptions
-      );
-    } catch (err) {
-      throw new ConsumeError(`Failed to start consumer for queue "${queue}"`, queue, err);
-    }
-  }
-
-  /**
-   * Acknowledges a RabbitMQ message.
-   * @param {Object} msg - RabbitMQ message object.
-   * @returns {Promise<void>}
-   */
-  async ack(msg) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot ack: client is not connected');
-    }
-    return this._transport.ack(msg);
-  }
-
-  /**
-   * Negative-acknowledges a RabbitMQ message.
-   * @param {Object} msg - RabbitMQ message object.
-   * @param {Object} [options] - Options such as { requeue: boolean }.
-   * @returns {Promise<void>}
-   */
-  async nack(msg, options = {}) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot nack: client is not connected');
-    }
-    return this._transport.nack(msg, options);
-  }
-
-  /**
-   * Registers a global error handler. Internal or transport-level errors will be forwarded here.
-   * @param {function(Error): void} callback
-   */
-  onError(callback) {
-    if (typeof callback === 'function') {
-      this._errorHandlers.push(callback);
-    }
-  }
-
-  /**
-   * Internal helper to invoke all registered error handlers.
-   * @param {Error} error
-   * @private
-   */
-  _handleError(error) {
-    this._errorHandlers.forEach((cb) => {
-      try {
-        cb(error);
-      } catch (_) {
-        // Ignore errors in user-provided error handlers
-      }
-    });
-  }
-}
-
-module.exports = ConnectorMQClient;