@onlineapps/conn-infra-mq 1.1.0

package/src/ConnectorMQClient.js

@@ -0,0 +1,446 @@
+'use strict';
+
+const BaseClient = require('./BaseClient');
+const WorkflowRouter = require('./layers/WorkflowRouter');
+const QueueManager = require('./layers/QueueManager');
+const ForkJoinHandler = require('./layers/ForkJoinHandler');
+const RPCHandler = require('./layers/RPCHandler');
+const RetryHandler = require('./layers/RetryHandler');
+
+/**
+ * Main MQ client orchestrating all messaging operations
+ *
+ * @class ConnectorMQClient
+ * @extends BaseClient
+ *
+ * @example <caption>Basic Usage</caption>
+ * const mqClient = new ConnectorMQClient({
+ *   url: 'amqp://localhost:5672',
+ *   serviceName: 'invoice-service'
+ * });
+ *
+ * await mqClient.connect();
+ * await mqClient.publish('invoice.created', { id: 123 });
+ *
+ * @example <caption>With Workflow</caption>
+ * const mqClient = new ConnectorMQClient({
+ *   url: 'amqp://localhost:5672',
+ *   serviceName: 'invoice-service',
+ *   enableRPC: true
+ * });
+ */
+class ConnectorMQClient extends BaseClient {
+  /**
+   * Creates a new ConnectorMQClient instance
+   *
+   * @constructor
+   * @param {Object} [config={}] - Configuration options
+   * @param {string} config.url - RabbitMQ connection URL
+   * @param {string} [config.serviceName='unknown'] - Service name
+   * @param {boolean} [config.enableRPC=true] - Enable RPC handler
+   * @param {number} [config.prefetchCount=10] - Message prefetch count
+   * @param {Object} [config.retry] - Retry configuration
+   *
+   * @example
+   * const mqClient = new ConnectorMQClient({
+   *   url: 'amqp://user:pass@localhost:5672',
+   *   serviceName: 'my-service',
+   *   prefetchCount: 20
+   * });
+   */
+  constructor(config = {}) {
+    super(config);
+
+    // Initialize layers
+    this.workflow = new WorkflowRouter(this, config);
+    this.queues = new QueueManager(this, config);
+    this.retry = new RetryHandler(this, config);
+    this.forkJoin = new ForkJoinHandler(this, this.queues, config);
+    this.rpc = new RPCHandler(this, this.queues, config);
+
+    // Service identification
+    this.serviceName = config.serviceName || 'unknown';
+
+    // Track initialization state
+    this._initialized = false;
+  }
+
+  /**
+   * Connect to RabbitMQ and initialize layers
+   *
+   * @async
+   * @method connect
+   * @returns {Promise<boolean>} Connection success
+   *
+   * @throws {Error} If connection fails
+   *
+   * @example
+   * try {
+   *   await mqClient.connect();
+   *   console.log('Connected to RabbitMQ');
+   * } catch (error) {
+   *   console.error('Connection failed:', error);
+   * }
+   */
+  async connect() {
+    // Base connection
+    await super.connect();
+
+    // Initialize RPC handler if needed
+    if (this._config.enableRPC !== false) {
+      await this.rpc.initialize();
+    }
+
+    // Setup service queues if service name provided
+    if (this.serviceName !== 'unknown') {
+      try {
+        await this.queues.setupServiceQueues(this.serviceName);
+      } catch (error) {
+        console.warn(`Failed to setup service queues: ${error.message}`);
+      }
+    }
+
+    this._initialized = true;
+    return true;
+  }
+
+  /**
+   * Disconnect from RabbitMQ with cleanup
+   *
+   * @async
+   * @method disconnect
+   * @returns {Promise<void>}
+   *
+   * @example
+   * await mqClient.disconnect();
+   */
+  async disconnect() {
+    if (this._initialized) {
+      // Cleanup layers
+      await this.forkJoin.cleanupAll();
+      await this.rpc.cleanup();
+      await this.queues.cleanup();
+    }
+
+    // Base disconnect
+    await super.disconnect();
+
+    this._initialized = false;
+  }
+
+  // ============================================
+  // Workflow Operations (via WorkflowRouter)
+  // ============================================
+
+  /**
+   * Publish workflow to initialization queue
+   *
+   * @async
+   * @method publishWorkflowInit
+   * @param {Object} workflow - Workflow definition
+   * @param {Object} [options] - Publishing options
+   * @returns {Promise<boolean>} Publish success
+   *
+   * @example
+   * await mqClient.publishWorkflowInit({
+   *   cookbook: cookbookDef,
+   *   context: { invoiceId: 123 }
+   * });
+   */
+  async publishWorkflowInit(workflow, options) {
+    return this.workflow.publishWorkflowInit(workflow, options);
+  }
+
+  /**
+   * Publish message to service workflow queue
+   *
+   * @async
+   * @method publishToServiceWorkflow
+   * @param {string} serviceName - Target service name
+   * @param {Object} message - Message to send
+   * @param {Object} [options] - Publishing options
+   * @returns {Promise<boolean>} Publish success
+   *
+   * @example
+   * await mqClient.publishToServiceWorkflow(
+   *   'invoice-service',
+   *   { action: 'process', data: {...} }
+   * );
+   */
+  async publishToServiceWorkflow(serviceName, message, options) {
+    return this.workflow.publishToServiceWorkflow(serviceName, message, options);
+  }
+
+  /**
+   * Publish message directly to service queue
+   *
+   * @async
+   * @method publishToService
+   * @param {string} serviceName - Target service name
+   * @param {Object} message - Message to send
+   * @param {Object} [options] - Publishing options
+   * @returns {Promise<boolean>} Publish success
+   *
+   * @example
+   * await mqClient.publishToService(
+   *   'email-service',
+   *   { template: 'invoice', data: {...} }
+   * );
+   */
+  async publishToService(serviceName, message, options) {
+    return this.workflow.publishToService(serviceName, message, options);
+  }
+
+  /**
+   * Publish workflow completed
+   */
+  async publishWorkflowCompleted(result, options) {
+    return this.workflow.publishWorkflowCompleted(result, options);
+  }
+
+  /**
+   * Route to next service in workflow
+   */
+  async routeToNextService(workflow, nextService, stepResult) {
+    return this.workflow.routeToNextService(workflow, nextService, stepResult);
+  }
+
+  /**
+   * Consume from workflow init queue
+   */
+  async consumeWorkflowInit(handler, options) {
+    return this.workflow.consumeWorkflowInit(handler, options);
+  }
+
+  /**
+   * Consume from service workflow queue
+   */
+  async consumeServiceWorkflow(serviceName, handler, options) {
+    return this.workflow.consumeServiceWorkflow(serviceName, handler, options);
+  }
+
+  // ============================================
+  // Queue Management (via QueueManager)
+  // ============================================
+
+  /**
+   * Ensure queue exists with configuration
+   */
+  async ensureQueue(queueName, options) {
+    return this.queues.ensureQueue(queueName, options);
+  }
+
+  /**
+   * Setup service queues
+   */
+  async setupServiceQueues(serviceName, options) {
+    return this.queues.setupServiceQueues(serviceName || this.serviceName, options);
+  }
+
+  /**
+   * Create temporary queue
+   */
+  async createTemporaryQueue(prefix, options) {
+    return this.queues.createTemporaryQueue(prefix, options);
+  }
+
+  /**
+   * Get queue statistics
+   */
+  async getQueueStats(queueName) {
+    return this.queues.getQueueStats(queueName);
+  }
+
+  // ============================================
+  // Fork-Join Operations (via ForkJoinHandler)
+  // ============================================
+
+  /**
+   * Execute fork-join pattern
+   */
+  async forkJoin(branches, joinStrategy, options) {
+    return this.forkJoin.forkJoin(branches, joinStrategy, options);
+  }
+
+  /**
+   * Fork work to multiple queues
+   */
+  async fork(branches, context) {
+    return this.forkJoin.fork(branches, context);
+  }
+
+  /**
+   * Create accumulator for collecting results
+   */
+  async createAccumulator(workflowId, stepId, expectedCount) {
+    return this.forkJoin.createAccumulator(workflowId, stepId, expectedCount);
+  }
+
+  /**
+   * Join results with strategy
+   */
+  async join(queueName, joinStrategy, options) {
+    return this.forkJoin.join(queueName, joinStrategy, options);
+  }
+
+  // ============================================
+  // RPC Operations (via RPCHandler)
+  // ============================================
+
+  /**
+   * Make RPC call
+   */
+  async rpcCall(targetQueue, request, options) {
+    return this.rpc.call(targetQueue, request, options);
+  }
+
+  /**
+   * Setup RPC server
+   */
+  async rpcServe(queue, handler, options) {
+    return this.rpc.serve(queue, handler, options);
+  }
+
+  /**
+   * Make multiple RPC calls
+   */
+  async rpcCallMany(requests) {
+    return this.rpc.callMany(requests);
+  }
+
+  /**
+   * RPC with retry
+   */
+  async rpcCallWithRetry(targetQueue, request, options) {
+    return this.rpc.callWithRetry(targetQueue, request, options);
+  }
+
+  // ============================================
+  // Retry Operations (via RetryHandler)
+  // ============================================
+
+  /**
+   * Consume with automatic retry
+   */
+  async consumeWithRetry(queue, handler, options) {
+    return this.retry.consumeWithRetry(queue, handler, options);
+  }
+
+  /**
+   * Process message with retry logic
+   */
+  async processWithRetry(handler, message, rawMsg, options) {
+    return this.retry.processWithRetry(handler, message, rawMsg, options);
+  }
+
+  /**
+   * Send message to DLQ
+   */
+  async publishToDLQ(originalQueue, message, error, options) {
+    return this.retry.sendToDLQ(message, originalQueue, error, options);
+  }
+
+  /**
+   * Process DLQ messages
+   */
+  async processDLQ(dlqName, handler, options) {
+    return this.retry.processDLQ(dlqName, handler, options);
+  }
+
+  /**
+   * Get retry statistics
+   */
+  getRetryStats() {
+    return this.retry.getStats();
+  }
+
+  // ============================================
+  // Convenience Methods
+  // ============================================
+
+  /**
+   * Publish with routing (decides between workflow/service/direct)
+   */
+  async publishWithRouting(message, options = {}) {
+    if (options.workflow) {
+      return this.publishWorkflowInit(message, options);
+    } else if (options.service) {
+      return this.publishToService(options.service, message, options);
+    } else if (options.rpc) {
+      return this.rpcCall(options.rpc, message, options);
+    } else {
+      return this.publish(message, options);
+    }
+  }
+
+  /**
+   * Smart consume (with retry and error handling)
+   */
+  async smartConsume(queue, handler, options = {}) {
+    const wrappedHandler = async (message, rawMsg) => {
+      // Add context
+      message._context = {
+        queue,
+        service: this.serviceName,
+        receivedAt: Date.now()
+      };
+
+      // Process with retry if enabled
+      if (options.retry !== false) {
+        return this.processWithRetry(handler, message, rawMsg, options);
+      } else {
+        return handler(message, rawMsg);
+      }
+    };
+
+    return this.consume(wrappedHandler, { queue, ...options });
+  }
+
+  /**
+   * Get overall health status
+   */
+  async getHealth() {
+    const health = {
+      connected: this.isConnected(),
+      initialized: this._initialized,
+      service: this.serviceName,
+      layers: {
+        workflow: true,
+        queues: true,
+        retry: true,
+        forkJoin: true,
+        rpc: this.rpc.getPendingCount() >= 0
+      },
+      stats: {
+        retry: this.retry.getStats(),
+        pendingRPC: this.rpc.getPendingCount(),
+        managedQueues: this.queues.getManagedQueues().length
+      }
+    };
+
+    // Try to get queue stats if connected
+    if (this.isConnected() && this.serviceName !== 'unknown') {
+      try {
+        health.queueStats = await this.getQueueStats(`${this.serviceName}.queue`);
+      } catch (error) {
+        health.queueStats = { error: error.message };
+      }
+    }
+
+    return health;
+  }
+
+  /**
+   * Static factory method for quick setup
+   */
+  static async create(config) {
+    const client = new ConnectorMQClient(config);
+    await client.connect();
+    return client;
+  }
+}
+
+// Export join strategies for convenience
+ConnectorMQClient.JoinStrategies = ForkJoinHandler.JoinStrategies;
+
+module.exports = ConnectorMQClient;

package/src/config/configSchema.js

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * configSchema.js
+ *
+ * JSON Schema used by Ajv to validate the user-supplied configuration object.
+ * Ensures required fields are present and correctly typed. Any unsupported
+ * or misspelled field will trigger a ValidationError.
+ */
+
+module.exports = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      enum: ['rabbitmq'],
+    },
+    host: {
+      type: 'string',
+      minLength: 1,
+    },
+    // For RabbitMQ: queue is required. 
+    queue: {
+      type: 'string',
+      minLength: 1,
+    },
+    exchange: {
+      type: 'string',
+    },
+    durable: {
+      type: 'boolean',
+    },
+    prefetch: {
+      type: 'integer',
+      minimum: 0,
+    },
+    noAck: {
+      type: 'boolean',
+    },
+    logger: {
+      type: 'object',
+      description: 'Custom logger with methods: info, warn, error, debug',
+    },
+    retryPolicy: {
+      type: 'object',
+      properties: {
+        retries: {
+          type: 'integer',
+          minimum: 0,
+        },
+        initialDelayMs: {
+          type: 'integer',
+          minimum: 0,
+        },
+        maxDelayMs: {
+          type: 'integer',
+          minimum: 0,
+        },
+        factor: {
+          type: 'number',
+          minimum: 1,
+        },
+      },
+      required: ['retries', 'initialDelayMs', 'maxDelayMs', 'factor'],
+      additionalProperties: false,
+    },
+  },
+  required: ['type', 'host', 'queue'],
+  additionalProperties: false,
+};

package/src/config/defaultConfig.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * defaultConfig.js
+ *
+ * Provides default configuration values for AgentMQClient.
+ * Users can override any of these by passing a custom config object
+ * or by supplying overrides to connect().
+ */
+
+module.exports = {
+  // Transport type: currently only 'rabbitmq' is fully supported.
+  type: 'rabbitmq',
+
+  // RabbitMQ connection URI or hostname (e.g., 'amqp://localhost:5672').
+  host: 'amqp://localhost:5672',
+
+  // Default queue name; can be overridden per call to publish/consume.
+  queue: '',
+
+  // Default exchange name (empty string → default direct exchange).
+  exchange: '',
+
+  // Declare queues/exchanges as durable by default.
+  durable: true,
+
+  // Default prefetch count for consumers.
+  prefetch: 1,
+
+  // Default auto-acknowledge setting for consumers.
+  noAck: false,
+
+  // Custom logger object (if not provided, console.* will be used).
+  // Expected interface: { info(), warn(), error(), debug() }.
+  logger: null,
+
+  // Retry policy for reconnect attempts (not fully implemented in current version).
+  // - retries: maximum number of reconnection attempts
+  // - initialDelayMs: starting backoff delay
+  // - maxDelayMs: maximum backoff delay
+  // - factor: exponential backoff multiplier
+  retryPolicy: {
+    retries: 5,
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+    factor: 2,
+  },
+};

package/src/index.js

@@ -0,0 +1,65 @@
+'use strict';
+
+/**
+ * @module @onlineapps/conn-infra-mq
+ * @description RabbitMQ connector with workflow routing, fork-join, RPC, and retry patterns for OA Drive.
+ * Provides layered architecture for complex messaging patterns.
+ *
+ * @see {@link https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-infra-mq|GitHub Repository}
+ * @author OA Drive Team
+ * @license MIT
+ * @since 1.0.0
+ */
+
+const ConnectorMQClient = require('./ConnectorMQClient');
+const BaseClient = require('./BaseClient');
+
+// Layers - exported for advanced usage
+const WorkflowRouter = require('./layers/WorkflowRouter');
+const QueueManager = require('./layers/QueueManager');
+const ForkJoinHandler = require('./layers/ForkJoinHandler');
+const RPCHandler = require('./layers/RPCHandler');
+const RetryHandler = require('./layers/RetryHandler');
+
+// Default export - the main client
+module.exports = ConnectorMQClient;
+
+// Named exports
+module.exports.ConnectorMQClient = ConnectorMQClient;
+module.exports.BaseClient = BaseClient;
+
+// Export layers for advanced usage
+module.exports.layers = {
+  WorkflowRouter,
+  QueueManager,
+  ForkJoinHandler,
+  RPCHandler,
+  RetryHandler
+};
+
+// Backwards compatibility - MQWrapper points to ConnectorMQClient
+module.exports.MQWrapper = ConnectorMQClient;
+
+// Export join strategies
+module.exports.JoinStrategies = ForkJoinHandler.JoinStrategies;
+
+/**
+ * Factory function to create MQ client instance
+ *
+ * @function create
+ * @param {Object} config - Configuration object
+ * @returns {ConnectorMQClient} New MQ client instance
+ *
+ * @example
+ * const mqClient = create({
+ *   url: 'amqp://localhost:5672',
+ *   serviceName: 'invoice-service'
+ * });
+ */
+module.exports.create = ConnectorMQClient.create;
+
+/**
+ * Current version
+ * @constant {string}
+ */
+module.exports.VERSION = '1.0.0';