@onlineapps/conn-infra-mq 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ONLINE APPS s.r.o.; info@onlineapps.cz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# @onlineapps/connector-mq-client
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/onlineapps/connector-mq-client/nodejs.yml?branch=main)](https://github.com/onlineapps/connector-mq-client/actions)
+[![Coverage Status](https://codecov.io/gh/onlineapps/connector-mq-client/branch/main/graph/badge.svg)](https://codecov.io/gh/onlineapps/connector-mq-client)
+[![npm version](https://img.shields.io/npm/v/@onlineapps/connector-mq-client)](https://www.npmjs.com/package/@onlineapps/connector-mq-client)
+
+> Message queue connector with **layered architecture** for workflow orchestration, RPC, fork-join, and retry patterns. Built on top of RabbitMQ with clean separation of concerns.
+
+---
+
+## 🚀 Features
+
+- **Layered Architecture**: Clean separation into specialized layers (WorkflowRouter, QueueManager, ForkJoinHandler, RPCHandler, RetryHandler)
+- **Workflow Orchestration**: Decentralized workflow routing without central orchestrator
+- **Fork-Join Pattern**: Parallel processing with result aggregation and built-in join strategies
+- **RPC Support**: Request-response communication with correlation IDs and timeouts
+- **Automatic Retry**: Exponential backoff, dead letter queue management, configurable retry policies
+- **Queue Management**: TTL, DLQ, auto-delete, temporary queues, exchange bindings
+- **Promise-based API**: All operations return promises for clean async/await usage
+- **Built-in Serialization**: JSON with custom error handling
+- **Config Validation**: Strict schema validation via Ajv
+- **Extensible Transport**: Clear separation between core logic and transport layer
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @onlineapps/connector-mq-client
+# or
+yarn add @onlineapps/connector-mq-client
+````
+
+> Requires Node.js ≥12. For RabbitMQ usage, ensure an accessible AMQP server.
+
+---
+
+## 🏗️ Architecture
+
+```
+ConnectorMQClient (main orchestrator)
+    ├── BaseClient (core AMQP operations)
+    ├── WorkflowRouter (workflow orchestration)
+    ├── QueueManager (queue lifecycle management)
+    ├── ForkJoinHandler (parallel processing)
+    ├── RPCHandler (request-response patterns)
+    └── RetryHandler (error recovery & DLQ)
+```
+
+## 🔧 Quick Start
+
+```js
+'use strict';
+
+const ConnectorMQClient = require('@onlineapps/connector-mq-client');
+
+(async () => {
+  // 1. Create client with configuration
+  const client = new ConnectorMQClient({
+    host: 'amqp://localhost:5672',
+    serviceName: 'my-service',
+    queue: 'default-queue',
+    durable: true,
+    prefetch: 5,                        // Default prefetch count for consumers
+    noAck: false,                       // Default auto-acknowledge = false
+    retryPolicy: {                      // Optional reconnection policy (not enforced in v1.0.0)
+      retries: 5,
+      initialDelayMs: 1000,
+      maxDelayMs: 30000,
+      factor: 2
+    }
+  });
+
+  // 2. Register a global error handler
+  client.onError(err => {
+    console.error('[AgentMQClient] Error:', err);
+  });
+
+  // 3. Connect to RabbitMQ
+  try {
+    await client.connect();
+    console.log('Connected to broker');
+  } catch (err) {
+    console.error('Connection failed:', err);
+    process.exit(1);
+  }
+
+  // 4. Publish a sample message
+  const samplePayload = { taskId: 'abc123', action: 'processData', timestamp: Date.now() };
+  try {
+    await client.publish('job_queue', samplePayload, {
+      persistent: true,
+      headers: { origin: 'quickStart' }
+    });
+    console.log('Message published:', samplePayload);
+  } catch (err) {
+    console.error('Publish error:', err);
+  }
+
+  // 5. Consume messages
+  try {
+    await client.consume(
+      'job_queue',
+      async (msg) => {
+        const data = JSON.parse(msg.content.toString('utf8'));
+        console.log('Received:', data);
+        // Process message...
+        await client.ack(msg);
+      },
+      { prefetch: 5, noAck: false }
+    );
+    console.log('Consuming from "job_queue"...');
+  } catch (err) {
+    console.error('Consume error:', err);
+  }
+
+  // 6. Graceful shutdown on SIGINT
+  process.on('SIGINT', async () => {
+    console.log('Shutting down...');
+    try {
+      await client.disconnect();
+      console.log('Disconnected, exiting.');
+      process.exit(0);
+    } catch (discErr) {
+      console.error('Error during disconnect:', discErr);
+      process.exit(1);
+    }
+  });
+})();
+```
+
+---
+
+## 📄 Configuration
+
+Configuration can be provided to the `AgentMQClient` constructor or as overrides to `connect()`. Below is a summary of supported fields (see `docs/api.md` for full details):
+
+| Field         | Type      | Description                                                                                                                                                        | Default                                                              |
+| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| `type`        | `string`  | Transport type: `'rabbitmq'`                                                                                     | `'rabbitmq'`                                                         |
+| `host`        | `string`  | Connection URI or hostname. For RabbitMQ: e.g. `'amqp://user:pass@localhost:5672'`.                                                                                | *Required*                                                           |
+| `queue`       | `string`  | Default queue name for publish/consume if not overridden per call.                                                                                                 | `''`                                                                 |
+| `exchange`    | `string`  | Default exchange name. Empty string uses the default direct exchange.                                                                                              | `''`                                                                 |
+| `durable`     | `boolean` | Declare queues/exchanges as durable.                                                                                                                               | `true`                                                               |
+| `prefetch`    | `integer` | Default prefetch count for consumers.                                                                                                                              | `1`                                                                  |
+| `noAck`       | `boolean` | Default auto-acknowledge setting for consumers. If `true`, messages will be auto-acked.                                                                            | `false`                                                              |
+| `logger`      | `object`  | Custom logger with methods: `info()`, `warn()`, `error()`, `debug()`. If omitted, `console` is used.                                                               | `null`                                                               |
+| `retryPolicy` | `object`  | Reconnection policy with properties:<br>‒ `retries` (number)<br>‒ `initialDelayMs` (ms)<br>‒ `maxDelayMs` (ms)<br>‒ `factor` (multiplier). Not enforced in v1.0.0. | `{ retries: 5, initialDelayMs: 1000, maxDelayMs: 30000, factor: 2 }` |
+
+---
+
+## 🛠️ API Reference
+
+For full class and method documentation, including parameter descriptions, return values, and error details, see [docs/api.md](https://github.com/onlineapps/agent-mq-client/blob/main/docs/api.md).
+
+---
+
+## ✅ Testing
+
+```bash
+npm test                  # All tests
+npm run test:unit         # Unit tests only
+npm run test:component    # Component tests
+npm run test:integration  # Integration tests
+```
+
+### Test Coverage Status
+- **Overall Coverage**: 24.52% (improving after refactoring)
+- **Passing Tests**: 75/104 (72%)
+- **Test Suites**: 10/14 passing
+- **Well Tested**: Config, Transports, Error handling (100%)
+- **Needs Testing**: New layers (1-5%)
+
+See [Test Report](docs/TEST_REPORT.md) for detailed coverage analysis.
+
+---
+
+## 🎨 Coding Standards
+
+* **Linting**: ESLint (`eslint:recommended` + Prettier).
+* **Formatting**: Prettier — check with `npm run prettier:check`, fix with `npm run prettier:fix`.
+* **Testing**: Jest, aiming for ≥90% coverage.
+
+---
+
+## 🎯 Refactoring Benefits
+
+### ✅ What Was Achieved
+1. **Clean Layered Architecture** - Separated into specialized layers
+2. **Removed Technical Debt** - Replaced MQWrapper with cleaner design
+3. **Improved Extensibility** - Easy to add new patterns
+4. **Better Developer Experience** - Cleaner API and documentation
+
+### 📊 Quality Improvements
+- **Separation of Concerns** - Each layer has single responsibility
+- **Modular Design** - Use individual layers independently
+- **Testability** - Each layer can be tested in isolation
+- **Maintainability** - Easier to understand and modify
+- **Backwards Compatibility** - MQWrapper alias maintained
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! Please see [CONTRIBUTING.md](https://github.com/onlineapps/agent-mq-client/blob/main/CONTRIBUTING.md) for guidelines:
+
+1. Fork the repo.
+2. Create a feature branch: `git checkout -b feature/your-feature`.
+3. Run tests locally and ensure linting passes.
+4. Commit your changes and push to your branch.
+5. Open a Pull Request against `main`.
+
+---
+
+## 📜 License
+
+This project is licensed under the MIT License. See [LICENSE](https://github.com/onlineapps/agent-mq-client/blob/main/LICENSE) for details.
+
+## 📚 Documentation
+
+- [Complete Connectors Documentation](../../../docs/modules/connector.md)
+- [Testing Standards](../../../docs/modules/connector.md#testing-standards)
+

package/package.json

@@ -0,0 +1,96 @@
+{
+    "name": "@onlineapps/conn-infra-mq",
+    "version": "1.1.0",
+    "description": "A promise-based, broker-agnostic client for sending and receiving messages via RabbitMQ",
+    "main": "src/index.js",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/onlineapps/connector-mq-client.git"
+    },
+    "files": [
+        "src/",
+        "README.md",
+        "LICENSE",
+        "CHANGELOG.md"
+    ],
+    "scripts": {
+        "test": "jest --coverage",
+        "test:unit": "jest --testPathPattern=unit --coverage",
+        "test:component": "jest --testPathPattern=component --coverage",
+        "test:integration": "jest --config=jest.integration.config.js",
+        "test:integration:required": "REQUIRE_SERVICES=true jest --config=jest.integration.config.js",
+        "test:watch": "jest --watch",
+        "test:coverage": "jest --coverage --coverageReporters=text-lcov html",
+        "lint": "eslint \"src/**/*.js\" \"test/**/*.js\"",
+        "prettier:check": "prettier --check \"src/**/*.js\" \"test/**/*.js\"",
+        "prettier:fix": "prettier --write \"src/**/*.js\" \"test/**/*.js\""
+    },
+    "keywords": [
+        "connector",
+        "mq",
+        "rabbitmq",
+        "kafka",
+        "message-queue",
+        "microservice",
+        "client",
+        "async"
+    ],
+    "author": "OnlineApps Team <dev@onlineapps.io>",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/onlineapps/connector-mq-client/issues"
+    },
+    "homepage": "https://github.com/onlineapps/connector-mq-client#readme",
+    "dependencies": {
+        "ajv": "^8.11.0",
+        "amqplib": "^0.10.3",
+        "lodash.merge": "^4.6.2"
+    },
+    "devDependencies": {
+        "@semantic-release/changelog": "^6.0.3",
+        "@semantic-release/commit-analyzer": "^11.1.0",
+        "@semantic-release/git": "^10.0.1",
+        "@semantic-release/github": "^9.2.6",
+        "@semantic-release/npm": "^11.0.3",
+        "@semantic-release/release-notes-generator": "^12.1.0",
+        "dotenv": "^17.2.2",
+        "eslint": "^8.30.0",
+        "eslint-config-prettier": "^8.5.0",
+        "jest": "^29.5.0",
+        "prettier": "^2.8.0",
+        "sinon": "^15.0.0",
+        "uuid": "^13.0.0"
+    },
+    "engines": {
+        "node": ">=12"
+    },
+    "eslintConfig": {
+        "env": {
+            "node": true,
+            "jest": true,
+            "es2021": true
+        },
+        "extends": [
+            "eslint:recommended",
+            "prettier"
+        ],
+        "parserOptions": {
+            "ecmaVersion": 12,
+            "sourceType": "script"
+        },
+        "rules": {
+            "no-console": "off",
+            "strict": [
+                "error",
+                "global"
+            ]
+        }
+    },
+    "prettier": {
+        "printWidth": 100,
+        "singleQuote": true,
+        "trailingComma": "es5",
+        "tabWidth": 2,
+        "endOfLine": "lf"
+    }
+}

package/src/BaseClient.js

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