@onlineapps/conn-infra-mq 1.1.0

package/src/layers/WorkflowRouter.js

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * WorkflowRouter - Handles workflow routing between services
+ * Manages workflow.init, service routing, and workflow.completed patterns
+ */
+class WorkflowRouter {
+  constructor(mqClient, config = {}) {
+    this.client = mqClient;
+    this.config = {
+      workflowInitQueue: config.workflowInitQueue || 'workflow.init',
+      workflowCompletedQueue: config.workflowCompletedQueue || 'workflow.completed',
+      serviceName: config.serviceName || 'unknown',
+      ...config
+    };
+  }
+
+  /**
+   * Publish workflow to init queue (entry point for all workflows)
+   * @param {Object} workflow - Workflow message with cookbook
+   * @param {Object} options - Additional publish options
+   */
+  async publishWorkflowInit(workflow, options = {}) {
+    return this.client.publish(workflow, {
+      queue: this.config.workflowInitQueue,
+      ...options
+    });
+  }
+
+  /**
+   * Publish to specific service workflow queue
+   * @param {string} serviceName - Target service name
+   * @param {Object} message - Workflow message
+   * @param {Object} options - Additional publish options
+   */
+  async publishToServiceWorkflow(serviceName, message, options = {}) {
+    return this.client.publish(message, {
+      queue: `${serviceName}.workflow`,
+      ...options
+    });
+  }
+
+  /**
+   * Publish directly to service queue (non-workflow)
+   * @param {string} serviceName - Target service name
+   * @param {Object} message - Message to send
+   * @param {Object} options - Additional publish options
+   */
+  async publishToService(serviceName, message, options = {}) {
+    return this.client.publish(message, {
+      queue: `${serviceName}.queue`,
+      ...options
+    });
+  }
+
+  /**
+   * Publish completed workflow result
+   * @param {Object} result - Workflow completion result
+   * @param {Object} options - Additional publish options
+   */
+  async publishWorkflowCompleted(result, options = {}) {
+    return this.client.publish(result, {
+      queue: this.config.workflowCompletedQueue,
+      ...options
+    });
+  }
+
+  /**
+   * Route to next service based on workflow step
+   * @param {Object} workflow - Current workflow state
+   * @param {string} nextService - Next service to route to
+   * @param {Object} stepResult - Result from current step
+   */
+  async routeToNextService(workflow, nextService, stepResult) {
+    const updatedWorkflow = {
+      ...workflow,
+      current_step: (workflow.current_step || 0) + 1,
+      results: [...(workflow.results || []), stepResult],
+      last_service: this.config.serviceName,
+      routed_at: new Date().toISOString()
+    };
+
+    if (nextService) {
+      return this.publishToServiceWorkflow(nextService, updatedWorkflow);
+    } else {
+      // No next service, workflow is complete
+      updatedWorkflow.status = 'completed';
+      return this.publishWorkflowCompleted(updatedWorkflow);
+    }
+  }
+
+  /**
+   * Consume from workflow init queue (competing consumers pattern)
+   * @param {Function} handler - Message handler function
+   * @param {Object} options - Consume options
+   */
+  async consumeWorkflowInit(handler, options = {}) {
+    return this.client.consume(handler, {
+      queue: this.config.workflowInitQueue,
+      ...options
+    });
+  }
+
+  /**
+   * Consume from service workflow queue
+   * @param {string} serviceName - Service name (defaults to configured)
+   * @param {Function} handler - Message handler function
+   * @param {Object} options - Consume options
+   */
+  async consumeServiceWorkflow(serviceName, handler, options = {}) {
+    if (typeof serviceName === 'function') {
+      // If serviceName is actually the handler
+      handler = serviceName;
+      serviceName = this.config.serviceName;
+    }
+
+    return this.client.consume(handler, {
+      queue: `${serviceName}.workflow`,
+      ...options
+    });
+  }
+
+  /**
+   * Consume completed workflows
+   * @param {Function} handler - Message handler function
+   * @param {Object} options - Consume options
+   */
+  async consumeWorkflowCompleted(handler, options = {}) {
+    return this.client.consume(handler, {
+      queue: this.config.workflowCompletedQueue,
+      ...options
+    });
+  }
+}
+
+module.exports = WorkflowRouter;

package/src/transports/rabbitmqClient.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/**
+ * RabbitMQClient: transport implementation for RabbitMQ using amqplib.
+ * Implements connect, disconnect, publish, consume, ack, nack, and error propagation.
+ */
+
+const amqp = require('amqplib');
+const EventEmitter = require('events');
+
+class RabbitMQClient extends EventEmitter {
+  /**
+   * @param {Object} config
+   * @param {string} config.host         - AMQP URI or hostname (e.g., 'amqp://localhost:5672')
+   * @param {string} [config.queue]      - Default queue name (optional; can be overridden per call)
+   * @param {string} [config.exchange]   - Default exchange (default: '')
+   * @param {boolean} [config.durable]   - Declare queues/exchanges as durable (default: true)
+   * @param {number} [config.prefetch]   - Default prefetch count for consumers (default: 1)
+   * @param {boolean} [config.noAck]     - Default auto-acknowledge setting (default: false)
+   * @param {Object} [config.retryPolicy] - { retries, initialDelayMs, maxDelayMs, factor } (not implemented here)
+   */
+  constructor(config) {
+    super();
+    this._config = Object.assign(
+      {
+        exchange: '',
+        durable: true,
+        prefetch: 1,
+        noAck: false,
+      },
+      config
+    );
+
+    this._connection = null;
+    this._channel = null;
+  }
+
+  /**
+   * Connects to RabbitMQ server and creates a confirm channel.
+   * @returns {Promise<void>}
+   * @throws {Error} If connection or channel creation fails.
+   */
+  async connect() {
+    try {
+      this._connection = await amqp.connect(this._config.host);
+      this._connection.on('error', (err) => this.emit('error', err));
+      this._connection.on('close', () => {
+        // Emit a connection close error to notify listeners
+        this.emit('error', new Error('RabbitMQ connection closed unexpectedly'));
+      });
+
+      // Use ConfirmChannel to enable publisher confirms
+      this._channel = await this._connection.createConfirmChannel();
+      this._channel.on('error', (err) => this.emit('error', err));
+      this._channel.on('close', () => {
+        // Emit a channel close error
+        this.emit('error', new Error('RabbitMQ channel closed unexpectedly'));
+      });
+    } catch (err) {
+      // Cleanup partially created resources
+      if (this._connection) {
+        try {
+          await this._connection.close();
+        } catch (_) {
+          /* ignore */
+        }
+        this._connection = null;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Disconnects: closes channel and connection.
+   * @returns {Promise<void>}
+   */
+  async disconnect() {
+    try {
+      if (this._channel) {
+        await this._channel.close();
+        this._channel = null;
+      }
+    } catch (err) {
+      this.emit('error', err);
+    }
+    try {
+      if (this._connection) {
+        await this._connection.close();
+        this._connection = null;
+      }
+    } catch (err) {
+      this.emit('error', err);
+    }
+  }
+
+  /**
+   * Publishes a message buffer to the specified queue (or default queue) or exchange.
+   * @param {string} queue           - Target queue name.
+   * @param {Buffer} buffer          - Message payload as Buffer.
+   * @param {Object} [options]       - Overrides: routingKey, persistent, headers.
+   * @returns {Promise<void>}
+   * @throws {Error} If publish fails or channel is not available.
+   */
+  async publish(queue, buffer, options = {}) {
+    if (!this._channel) {
+      throw new Error('Cannot publish: channel is not initialized');
+    }
+
+    const exchange = this._config.exchange || '';
+    const routingKey = options.routingKey || queue;
+    const persistent = options.persistent !== undefined ? options.persistent : this._config.durable;
+    const headers = options.headers || {};
+
+    try {
+      // Ensure queue exists if publishing directly to queue and using default exchange
+      if (!exchange) {
+        await this._channel.assertQueue(queue, { durable: this._config.durable });
+        this._channel.sendToQueue(queue, buffer, { persistent, headers, routingKey });
+      } else {
+        // If exchange is specified, assert exchange and publish to it
+        await this._channel.assertExchange(exchange, 'direct', { durable: this._config.durable });
+        this._channel.publish(exchange, routingKey, buffer, { persistent, headers });
+      }
+      // Wait for confirmation
+      await this._channel.waitForConfirms();
+    } catch (err) {
+      this.emit('error', err);
+      throw err;
+    }
+  }
+
+  /**
+   * Starts consuming messages from the specified queue.
+   * @param {string} queue                         - Queue name to consume from.
+   * @param {function(Object): Promise<void>} onMessage - Async handler receiving raw msg.
+   * @param {Object} [options]                     - Overrides: prefetch, noAck.
+   * @returns {Promise<void>}
+   * @throws {Error} If consume setup fails or channel is not available.
+   */
+  async consume(queue, onMessage, options = {}) {
+    if (!this._channel) {
+      throw new Error('Cannot consume: channel is not initialized');
+    }
+
+    const durable = this._config.durable;
+    const prefetch = options.prefetch !== undefined ? options.prefetch : this._config.prefetch;
+    const noAck = options.noAck !== undefined ? options.noAck : this._config.noAck;
+
+    try {
+      // Ensure queue exists
+      await this._channel.assertQueue(queue, { durable });
+      // Set prefetch if provided
+      if (typeof prefetch === 'number') {
+        this._channel.prefetch(prefetch);
+      }
+
+      await this._channel.consume(
+        queue,
+        async (msg) => {
+          if (msg === null) {
+            return;
+          }
+          try {
+            await onMessage(msg);
+            if (!noAck) {
+              this._channel.ack(msg);
+            }
+          } catch (handlerErr) {
+            // Negative acknowledge and requeue by default
+            this._channel.nack(msg, false, true);
+          }
+        },
+        { noAck }
+      );
+    } catch (err) {
+      this.emit('error', err);
+      throw err;
+    }
+  }
+
+  /**
+   * Acknowledges a message.
+   * @param {Object} msg - RabbitMQ message object.
+   */
+  async ack(msg) {
+    if (!this._channel) {
+      throw new Error('Cannot ack: channel is not initialized');
+    }
+    try {
+      this._channel.ack(msg);
+    } catch (err) {
+      this.emit('error', err);
+      throw err;
+    }
+  }
+
+  /**
+   * Negative-acknowledges a message.
+   * @param {Object} msg - RabbitMQ message object.
+   * @param {Object} [options] - { requeue: boolean }.
+   */
+  async nack(msg, options = {}) {
+    if (!this._channel) {
+      throw new Error('Cannot nack: channel is not initialized');
+    }
+    const requeue = options.requeue !== undefined ? options.requeue : true;
+    try {
+      this._channel.nack(msg, false, requeue);
+    } catch (err) {
+      this.emit('error', err);
+      throw err;
+    }
+  }
+}
+
+module.exports = RabbitMQClient;

package/src/transports/transportFactory.js

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * transportFactory: selects and instantiates the appropriate transport
+ * based on configuration. Currently supports RabbitMQ; 
+ */
+
+const RabbitMQClient = require('./rabbitmqClient');
+
+/**
+ * Factory method: returns a transport instance based on config.type.
+ * @param {Object} config
+ * @param {'rabbitmq'} config.type - Transport type ('rabbitmq' for now)
+ * @returns {Object} Instance of transport (RabbitMQClient, etc.)
+ * @throws {Error} If the configured type is unsupported or missing
+ */
+function create(config) {
+  if (!config || !config.type) {
+    throw new Error('Transport type is required in configuration');
+  }
+
+  switch (config.type.toLowerCase()) {
+    case 'rabbitmq':
+      return new RabbitMQClient(config);
+
+    default:
+      throw new Error(`Unsupported transport type: ${config.type}`);
+  }
+}
+
+module.exports = {
+  create,
+};

package/src/utils/errorHandler.js

@@ -0,0 +1,120 @@
+'use strict';
+
+/**
+ * errorHandler.js
+ *
+ * Defines all custom error types used by AgentMQClient and RabbitMQClient.
+ * Each extends the built-in Error class and carries additional contextual fields.
+ */
+
+/**
+ * ValidationError
+ * Thrown when user-supplied configuration does not match schema.
+ * - message: human-readable description
+ * - details: array of { path, message } describing each invalid field
+ */
+class ValidationError extends Error {
+  /**
+   * @param {string} message
+   * @param {Array<{path: string, message: string}>} details
+   */
+  constructor(message, details) {
+    super(message);
+    this.name = 'ValidationError';
+    this.details = Array.isArray(details) ? details : [];
+    Error.captureStackTrace(this, ValidationError);
+  }
+}
+
+/**
+ * ConnectionError
+ * Thrown when client cannot connect to broker.
+ * - message: description of what went wrong
+ * - cause: original error object
+ */
+class ConnectionError extends Error {
+  /**
+   * @param {string} message
+   * @param {Error} cause
+   */
+  constructor(message, cause) {
+    super(message);
+    this.name = 'ConnectionError';
+    this.cause = cause;
+    Error.captureStackTrace(this, ConnectionError);
+  }
+}
+
+/**
+ * PublishError
+ * Thrown when publishing a message fails.
+ * - message: description
+ * - queue: target queue name
+ * - cause: original error
+ */
+class PublishError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} queue
+   * @param {Error} cause
+   */
+  constructor(message, queue, cause) {
+    super(message);
+    this.name = 'PublishError';
+    this.queue = queue;
+    this.cause = cause;
+    Error.captureStackTrace(this, PublishError);
+  }
+}
+
+/**
+ * ConsumeError
+ * Thrown when setting up a consumer fails.
+ * - message: description
+ * - queue: queue name associated with the consumer
+ * - cause: original error
+ */
+class ConsumeError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} queue
+   * @param {Error} cause
+   */
+  constructor(message, queue, cause) {
+    super(message);
+    this.name = 'ConsumeError';
+    this.queue = queue;
+    this.cause = cause;
+    Error.captureStackTrace(this, ConsumeError);
+  }
+}
+
+/**
+ * SerializationError
+ * Thrown when JSON serialization or deserialization fails.
+ * - message: description
+ * - payload: original object or buffer that caused the error
+ * - cause: native exception (e.g., TypeError for circular references)
+ */
+class SerializationError extends Error {
+  /**
+   * @param {string} message
+   * @param {*} payload
+   * @param {Error} cause
+   */
+  constructor(message, payload, cause) {
+    super(message);
+    this.name = 'SerializationError';
+    this.payload = payload;
+    this.cause = cause;
+    Error.captureStackTrace(this, SerializationError);
+  }
+}
+
+module.exports = {
+  ValidationError,
+  ConnectionError,
+  PublishError,
+  ConsumeError,
+  SerializationError,
+};

package/src/utils/logger.js

@@ -0,0 +1,38 @@
+'use strict';
+
+/**
+ * logger.js
+ *
+ * Provides a simple abstraction over console or a custom logger.
+ * If the user passes a custom logger object with methods { info, warn, error, debug },
+ * these are used; otherwise console.* se použije jako fallback.
+ */
+
+function createLogger(customLogger) {
+  const methods = ['info', 'warn', 'error', 'debug'];
+  if (
+    customLogger &&
+    typeof customLogger === 'object' &&
+    methods.every((fn) => typeof customLogger[fn] === 'function')
+  ) {
+    // Wrap custom logger to ensure consistent signature
+    return {
+      info: (...args) => customLogger.info(...args),
+      warn: (...args) => customLogger.warn(...args),
+      error: (...args) => customLogger.error(...args),
+      debug: (...args) => customLogger.debug(...args),
+    };
+  }
+
+  // Fallback to console
+  return {
+    info: (...args) => console.log('[INFO]', ...args),
+    warn: (...args) => console.warn('[WARN]', ...args),
+    error: (...args) => console.error('[ERROR]', ...args),
+    debug: (...args) => console.debug('[DEBUG]', ...args),
+  };
+}
+
+module.exports = {
+  createLogger,
+};

package/src/utils/serializer.js

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * serializer.js
+ *
+ * Contains helper functions for serializing and deserializing payloads.
+ * On failure, throws a SerializationError (defined in errorHandler.js).
+ */
+
+const { SerializationError } = require('./errorHandler');
+
+/**
+ * Serializes a JavaScript object to JSON string.
+ * @param {Object} obj
+ * @returns {string}
+ * @throws {SerializationError} If JSON.stringify fails (e.g., circular reference).
+ */
+function serialize(obj) {
+  try {
+    return JSON.stringify(obj);
+  } catch (err) {
+    throw new SerializationError('Failed to serialize object', obj, err);
+  }
+}
+
+/**
+ * Deserializes a Buffer or string into a JavaScript object via JSON.parse.
+ * @param {Buffer|string} buffer
+ * @returns {Object}
+ * @throws {SerializationError} If JSON.parse fails or buffer cannot be converted.
+ */
+function deserialize(buffer) {
+  try {
+    const str = Buffer.isBuffer(buffer) ? buffer.toString('utf8') : buffer;
+    return JSON.parse(str);
+  } catch (err) {
+    throw new SerializationError('Failed to deserialize payload', buffer, err);
+  }
+}
+
+module.exports = {
+  serialize,
+  deserialize,
+};