poly-bus-rabbitmq 0.4.1

package/README.md

@@ -0,0 +1,209 @@
+# poly-bus-rabbitmq
+
+The RabbitMQ transport for PolyBus.
+
+## Prerequisites
+
+- Node.js 18+
+- npm 9+
+- RabbitMQ server (for runtime/integration scenarios)
+
+## Installation
+
+```bash
+npm install poly-bus-rabbitmq poly-bus@0.3.11
+```
+
+## Quick Start
+
+### Setting Up Development Environment
+
+```bash
+# Navigate to the typescript directory
+cd src/typescript
+
+# Install dependencies
+npm install
+```
+
+## Usage
+
+```ts
+import { PolyBusBuilder } from "poly-bus";
+import { RabbitMqConfig } from "poly-bus-rabbitmq";
+
+const builder = new PolyBusBuilder("my-service");
+
+const rabbitMq = new RabbitMqConfig();
+rabbitMq.connectionString = "amqp://guest:guest@localhost:5672";
+rabbitMq.queueName = "my-service";
+
+builder.withTransport(async (b, bus) => rabbitMq.create(b, bus));
+```
+
+## Behavior
+
+The transport mirrors the .NET implementation in this repository:
+
+- Command, event, and direct exchanges.
+- Dead-letter queue setup.
+- Delayed delivery queues using binary routing segments and TTL dead-letter chaining.
+- Routing key format:
+  - Publish: `MessageType.Endpoint.Name.Major.Minor.Patch`
+  - Subscribe: `MessageType.Endpoint.Name.Major.#`
+
+## Exports
+
+- `RabbitMqConfig`
+- `RabbitMqTransport`
+
+## Development
+
+```bash
+cd src/typescript
+npm install
+npm run build
+npm test
+```
+
+## Building The Project
+
+```bash
+cd src/typescript
+npm run build
+```
+
+## Running Tests
+
+```bash
+# Run all tests once
+npm test
+
+# Run a specific test file
+npx jest src/__tests__/transport/rabbitmq/rabbitmq-transport.test.ts
+
+# Run tests matching a test name pattern
+npx jest -t "formats publish routing keys"
+
+# Run RabbitMQ integration tests (creates and deletes its own RabbitMQ virtual host)
+# Optional: set RABBITMQ_MANAGEMENT_URL if management API is not on http://localhost:15672
+RABBITMQ_CONNECTION_STRING=amqp://guest:guest@localhost:5672 \
+npx jest src/__tests__/transport/rabbitmq/rabbitmq-transport.integration.test.ts --runInBand
+```
+
+## Development Workflow
+
+### Code Quality
+
+Current package scripts include:
+
+- `npm run build` for TypeScript compilation
+- `npm test` for Jest test execution
+
+If you want stricter checks, common additions are:
+
+- `npm run typecheck` using `tsc --noEmit`
+- linting with ESLint
+- formatting with Prettier
+
+## Configuration
+
+### RabbitMqConfig
+
+Common options:
+
+- `connectionString` (required): AMQP connection URI.
+- `queueName`: endpoint queue name.
+- `deadLetterQueueName`: dead-letter queue endpoint.
+- `commandExchangeName`, `eventExchangeName`, `directExchangeName`: exchange naming overrides.
+- `delayDelivery`: delayed message exchange prefix.
+- `networkRecoveryIntervalMs`: reconnect interval.
+
+### Routing Behavior
+
+Routing keys mirror the .NET implementation:
+
+- Publish format: `MessageType.Endpoint.Name.Major.Minor.Patch`
+- Subscribe format: `MessageType.Endpoint.Name.Major.#`
+
+## Dependencies
+
+### Runtime Dependencies
+
+- `amqplib`
+- `poly-bus@0.3.11`
+
+### Development Dependencies
+
+- `typescript`
+- `jest`
+- `@types/node`
+- `@types/amqplib`
+- `rimraf`
+
+## Common Commands
+
+```bash
+cd src/typescript
+
+# Install, build, and test
+npm install
+npm run build
+npm test
+
+# Clean output
+npm run clean
+
+# Inspect generated package files
+npm pack --dry-run
+```
+
+## Troubleshooting
+
+### Environment Issues
+
+1. Verify Node.js version:
+
+```bash
+node --version
+npm --version
+```
+
+2. Ensure RabbitMQ is reachable via your connection string.
+
+### Build Issues
+
+1. Clean and rebuild:
+
+```bash
+npm run clean
+npm run build
+```
+
+2. If type declaration or module resolution errors appear, delete `node_modules` and reinstall:
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Test Issues
+
+1. Run one file directly to isolate failures:
+
+```bash
+npx jest src/__tests__/transport/rabbitmq/rabbitmq-transport.test.ts
+```
+
+2. Use test name filtering to narrow down behavioral regressions.
+
+## Contributing
+
+1. Run `npm run build` and `npm test` before committing.
+2. Add tests for new transport behavior.
+3. Keep behavior aligned with the .NET and Python transport implementations.
+4. Update README examples and configuration docs when APIs change.
+
+## License
+
+See the repository LICENSE file for licensing details.

package/dist/__tests__/mocks/poly-bus.d.ts

@@ -0,0 +1,60 @@
+export declare enum MessageType {
+    Event = 0,
+    Command = 1
+}
+export declare const Headers: {
+    readonly MessageType: "MessageType";
+};
+export declare class MessageInfo {
+    readonly type: MessageType;
+    readonly endpoint: string;
+    readonly name: string;
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    constructor(type: MessageType, endpoint: string, name: string, major: number, minor: number, patch: number);
+    static getAttributeFromHeader(_header: string): MessageInfo | null;
+}
+export declare class IncomingMessage {
+    headers: Map<string, string>;
+    constructor(_bus: IPolyBus, _body: string, _messageInfo: MessageInfo);
+}
+export interface OutgoingMessage {
+    messageInfo: MessageInfo;
+    headers: Map<string, string>;
+    endpoint?: string;
+    body: string;
+    deliverAt?: Date;
+}
+export interface Transaction {
+    outgoingMessages: OutgoingMessage[];
+}
+export interface IncomingTransaction {
+    commit(): Promise<void>;
+}
+export interface OutgoingTransaction extends Transaction {
+}
+export interface IPolyBus {
+    name: string;
+    properties: Map<string, object>;
+    transport: unknown;
+    incomingPipeline: unknown[];
+    outgoingPipeline: unknown[];
+    messages: {
+        getHeaderByMessageInfo(messageInfo: MessageInfo): string;
+        getTypeByMessageInfo(messageInfo: MessageInfo): new () => unknown;
+        getMessageInfo(type: new () => unknown): MessageInfo;
+        add(type: new () => unknown): MessageInfo;
+    };
+    createIncomingTransaction(message: IncomingMessage): Promise<IncomingTransaction>;
+    createOutgoingTransaction(): Promise<OutgoingTransaction>;
+    send(transaction: Transaction): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface ITransport {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    subscribe(messageInfo: MessageInfo): Promise<void>;
+    handle(transaction: Transaction): Promise<void>;
+}

package/dist/__tests__/mocks/poly-bus.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IncomingMessage = exports.MessageInfo = exports.Headers = exports.MessageType = void 0;
+var MessageType;
+(function (MessageType) {
+    MessageType[MessageType["Event"] = 0] = "Event";
+    MessageType[MessageType["Command"] = 1] = "Command";
+})(MessageType || (exports.MessageType = MessageType = {}));
+exports.Headers = {
+    MessageType: "MessageType"
+};
+class MessageInfo {
+    constructor(type, endpoint, name, major, minor, patch) {
+        this.type = type;
+        this.endpoint = endpoint;
+        this.name = name;
+        this.major = major;
+        this.minor = minor;
+        this.patch = patch;
+    }
+    static getAttributeFromHeader(_header) {
+        return null;
+    }
+}
+exports.MessageInfo = MessageInfo;
+class IncomingMessage {
+    constructor(_bus, _body, _messageInfo) {
+        this.headers = new Map();
+    }
+}
+exports.IncomingMessage = IncomingMessage;

package/dist/__tests__/transport/rabbitmq/rabbitmq-transport.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/transport/rabbitmq/rabbitmq-transport.integration.test.js

@@ -0,0 +1,230 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_crypto_1 = require("node:crypto");
+const globals_1 = require("@jest/globals");
+const amqplib_1 = __importDefault(require("amqplib"));
+const poly_bus_1 = require("poly-bus");
+const rabbitmq_config_1 = require("../../../transport/rabbitmq/rabbitmq-config");
+const rabbitmq_transport_1 = require("../../../transport/rabbitmq/rabbitmq-transport");
+const baseConnectionString = process.env.RABBITMQ_CONNECTION_STRING ?? 'amqp://guest:guest@localhost:5672';
+function encodePathSegment(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function getManagementBaseUrl(connectionString) {
+    if (process.env.RABBITMQ_MANAGEMENT_URL) {
+        return process.env.RABBITMQ_MANAGEMENT_URL;
+    }
+    const connection = new URL(connectionString);
+    const protocol = connection.protocol === 'amqps:' ? 'https:' : 'http:';
+    const port = connection.port === '5671' ? '15671' : '15672';
+    return `${protocol}//${connection.hostname}:${port}`;
+}
+async function callManagementApi(managementBaseUrl, username, password, path, method, body) {
+    const authToken = Buffer.from(`${username}:${password}`, 'utf8').toString('base64');
+    const response = await fetch(`${managementBaseUrl}${path}`, {
+        method,
+        headers: {
+            Authorization: `Basic ${authToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: body ? JSON.stringify(body) : undefined
+    });
+    if (!response.ok) {
+        const responseText = await response.text();
+        throw new Error(`RabbitMQ management API ${method} ${path} failed with ${response.status}: ${responseText}`);
+    }
+}
+async function createTestVirtualHost(connectionString, vhost) {
+    const connection = new URL(connectionString);
+    const username = decodeURIComponent(connection.username || 'guest');
+    const password = decodeURIComponent(connection.password || 'guest');
+    const managementBaseUrl = getManagementBaseUrl(connectionString);
+    const encodedVhost = encodePathSegment(vhost);
+    const encodedUser = encodePathSegment(username);
+    await callManagementApi(managementBaseUrl, username, password, `/api/vhosts/${encodedVhost}`, 'PUT');
+    await callManagementApi(managementBaseUrl, username, password, `/api/permissions/${encodedVhost}/${encodedUser}`, 'PUT', {
+        configure: '.*',
+        write: '.*',
+        read: '.*'
+    });
+    connection.pathname = `/${vhost}`;
+    connection.search = '';
+    connection.hash = '';
+    return connection.toString();
+}
+async function deleteTestVirtualHost(connectionString, vhost) {
+    const connection = new URL(connectionString);
+    const username = decodeURIComponent(connection.username || 'guest');
+    const password = decodeURIComponent(connection.password || 'guest');
+    const managementBaseUrl = getManagementBaseUrl(connectionString);
+    const encodedVhost = encodePathSegment(vhost);
+    await callManagementApi(managementBaseUrl, username, password, `/api/vhosts/${encodedVhost}`, 'DELETE');
+}
+function createHeader(messageInfo) {
+    return `${messageInfo.type}.${messageInfo.endpoint}.${messageInfo.name}.${messageInfo.major}.${messageInfo.minor}.${messageInfo.patch}`;
+}
+function createBusStub(name, onIncomingMessage) {
+    return {
+        name,
+        properties: new Map(),
+        transport: {},
+        incomingPipeline: [],
+        outgoingPipeline: [],
+        messages: {
+            getHeaderByMessageInfo: (messageInfo) => createHeader(messageInfo),
+            getTypeByMessageInfo: () => class TestMessage {
+            },
+            getMessageInfo: () => new poly_bus_1.MessageInfo(poly_bus_1.MessageType.Command, name, 'created', 1, 0, 0),
+            add: () => new poly_bus_1.MessageInfo(poly_bus_1.MessageType.Command, name, 'created', 1, 0, 0)
+        },
+        createIncomingTransaction: async (message) => {
+            onIncomingMessage(message);
+            return {
+                commit: async () => undefined
+            };
+        },
+        createOutgoingTransaction: async () => ({
+            outgoingMessages: []
+        }),
+        send: async (_transaction) => undefined,
+        start: async () => undefined,
+        stop: async () => undefined
+    };
+}
+function withTimeout(promise, timeoutMs = 20000) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            reject(new Error(`Timed out after ${timeoutMs}ms waiting for RabbitMQ message`));
+        }, timeoutMs);
+        promise
+            .then((value) => {
+            clearTimeout(timeout);
+            resolve(value);
+        })
+            .catch((error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+    });
+}
+(0, globals_1.describe)('RabbitMqTransport integration', () => {
+    let connectionString;
+    let testVirtualHostName;
+    let transport;
+    let queueName;
+    let receivedResolve;
+    let receivedReject;
+    let receivedMessagePromise;
+    let parserSpy;
+    let publisherConnection;
+    let publisherChannel;
+    (0, globals_1.beforeAll)(async () => {
+        testVirtualHostName = `ts-rabbitmq-integration-${(0, node_crypto_1.randomUUID)()}`;
+        connectionString = await createTestVirtualHost(baseConnectionString, testVirtualHostName);
+    });
+    (0, globals_1.afterAll)(async () => {
+        await deleteTestVirtualHost(baseConnectionString, testVirtualHostName);
+    });
+    (0, globals_1.beforeEach)(() => {
+        queueName = `ts-rabbitmq-integration-${(0, node_crypto_1.randomUUID)()}`;
+        receivedMessagePromise = new Promise((resolve, reject) => {
+            receivedResolve = resolve;
+            receivedReject = reject;
+        });
+        const bus = createBusStub(queueName, (message) => {
+            receivedResolve?.(message);
+        });
+        const config = new rabbitmq_config_1.RabbitMqConfig();
+        config.connectionString = connectionString;
+        config.queueName = queueName;
+        config.deadLetterQueueName = `${queueName}.dead.letters`;
+        config.log = {
+            info: globals_1.jest.fn(),
+            error: (message, ...meta) => {
+                receivedReject?.(new Error([message, ...meta.map((entry) => String(entry))].join(' ')));
+            }
+        };
+        parserSpy = globals_1.jest.spyOn(poly_bus_1.MessageInfo, 'getAttributeFromHeader').mockImplementation((header) => {
+            const parts = header.split('.');
+            if (parts.length !== 6) {
+                return null;
+            }
+            const [typeText, endpoint, name, major, minor, patch] = parts;
+            const parsedType = Number.parseInt(typeText, 10);
+            if (Number.isNaN(parsedType)) {
+                return null;
+            }
+            return new poly_bus_1.MessageInfo(parsedType, endpoint, name, Number.parseInt(major, 10), Number.parseInt(minor, 10), Number.parseInt(patch, 10));
+        });
+        transport = new rabbitmq_transport_1.RabbitMqTransport(config, bus);
+        publisherConnection = null;
+        publisherChannel = null;
+    });
+    (0, globals_1.afterEach)(async () => {
+        parserSpy.mockRestore();
+        if (publisherChannel) {
+            try {
+                await publisherChannel.close();
+            }
+            catch {
+                // Ignore shutdown failures in cleanup.
+            }
+            publisherChannel = null;
+        }
+        if (publisherConnection) {
+            try {
+                await publisherConnection.close();
+            }
+            catch {
+                // Ignore shutdown failures in cleanup.
+            }
+            publisherConnection = null;
+        }
+        await transport.stop();
+    });
+    (0, globals_1.it)('creates a real RabbitMQ channel and connection on start', async () => {
+        await transport.start();
+        (0, globals_1.expect)(transport.connection).not.toBeNull();
+        (0, globals_1.expect)(transport.channel).not.toBeNull();
+    });
+    (0, globals_1.it)('publishes and receives command messages through RabbitMQ', async () => {
+        await transport.start();
+        const messageInfo = new poly_bus_1.MessageInfo(poly_bus_1.MessageType.Command, queueName, 'created', 1, 0, 0);
+        const transaction = {
+            outgoingMessages: [
+                {
+                    messageInfo,
+                    headers: new Map(),
+                    endpoint: undefined,
+                    body: JSON.stringify({ id: 'integration-command' }),
+                    deliverAt: undefined
+                }
+            ]
+        };
+        await transport.handle(transaction);
+        const incoming = await withTimeout(receivedMessagePromise);
+        (0, globals_1.expect)(incoming).toBeInstanceOf(poly_bus_1.IncomingMessage);
+        (0, globals_1.expect)(incoming.headers.get(poly_bus_1.Headers.MessageType)).toBe(createHeader(messageInfo));
+    });
+    (0, globals_1.it)('receives subscribed events published by a RabbitMQ producer', async () => {
+        await transport.start();
+        const eventInfo = new poly_bus_1.MessageInfo(poly_bus_1.MessageType.Event, 'billing', 'paid', 1, 0, 0);
+        await transport.subscribe(eventInfo);
+        publisherConnection = await amqplib_1.default.connect(connectionString);
+        publisherChannel = await publisherConnection.createChannel();
+        await publisherChannel.assertExchange(transport.config.eventExchangeName, 'topic', { durable: true });
+        const routingKey = transport.getRoutingKey(false, eventInfo);
+        const options = {
+            headers: {
+                [poly_bus_1.Headers.MessageType]: createHeader(eventInfo)
+            }
+        };
+        publisherChannel.publish(transport.config.eventExchangeName, routingKey, Buffer.from(JSON.stringify({ id: 'integration-event' }), 'utf8'), options);
+        const incoming = await withTimeout(receivedMessagePromise);
+        (0, globals_1.expect)(incoming).toBeInstanceOf(poly_bus_1.IncomingMessage);
+        (0, globals_1.expect)(incoming.headers.get(poly_bus_1.Headers.MessageType)).toBe(createHeader(eventInfo));
+    });
+});

package/dist/__tests__/transport/rabbitmq/rabbitmq-transport.test.d.ts

@@ -0,0 +1 @@
+export {};