@bsb/events-rabbitmq 0.0.1

package/README.md

@@ -0,0 +1,109 @@
+# @bsb/events-rabbitmq
+
+RabbitMQ events plugin for BSB that provides a distributed event bus using AMQP. It enables communication between multiple processes, containers, and microservices with reliable delivery and advanced routing.
+
+## Key Features
+
+- Distributed event bus across multiple processes and containers
+- Full support for all BSB event patterns (fire-and-forget, request-response, broadcast, streaming)
+- RabbitMQ cluster support with automatic reconnection
+- Reliable message delivery with acknowledgments
+- Configurable prefetch for load balancing
+- Platform isolation with multi-tenancy support
+- Unique client identification for routing
+
+## Installation
+
+```bash
+npm install @bsb/events-rabbitmq
+```
+
+## Configuration
+
+Add the plugin to your BSB configuration file:
+
+```yaml
+plugins:
+  events:
+    plugin: "@bsb/events-rabbitmq"
+    enabled: true
+    config:
+      endpoints:
+        - "amqp://localhost:5672"
+      credentials:
+        username: "guest"
+        password: "guest"
+      prefetch: 10
+      fatalOnDisconnect: true
+      platformKey: null
+      uniqueId: null
+```
+
+### Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `endpoints` | Array of RabbitMQ server URLs (cluster support) | `["amqp://localhost"]` |
+| `credentials.username` | RabbitMQ username | `guest` |
+| `credentials.password` | RabbitMQ password | `guest` |
+| `prefetch` | Messages to prefetch per consumer | `10` |
+| `fatalOnDisconnect` | Exit process on connection loss | `true` |
+| `platformKey` | Isolate multiple BSB platforms on same RabbitMQ | `null` |
+| `uniqueId` | Static client ID (uses hostname if not set) | `null` |
+
+## Usage
+
+Once configured, the plugin provides the same API as `events-default`, but distributed across RabbitMQ.
+
+### Fire-and-Forget
+
+```typescript
+await this.events.emitEvent("order.created", {
+  orderId: "12345",
+  items: [{ sku: "ABC", qty: 2 }]
+});
+```
+
+### Request-Response
+
+```typescript
+const result = await this.events.emitEventAndReturn(
+  "user.validate",
+  { email: "user@example.com" },
+  5000
+);
+```
+
+### Broadcast
+
+```typescript
+await this.events.emitBroadcast("cache.invalidate", { keys: ["a", "b"] });
+```
+
+### Streaming
+
+```typescript
+const streamId = await this.events.receiveStream("file.upload", handler, 30);
+await this.events.sendStream("file.upload", streamId, fileStream);
+```
+
+## RabbitMQ Setup
+
+For local development, the RabbitMQ management image is a quick start:
+
+```bash
+docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:management
+```
+
+## Documentation
+
+Detailed documentation (used by the BSB Registry): `https://github.com/BetterCorp/better-service-base/blob/master/plugins/nodejs/events-rabbitmq/docs/plugin.md`
+
+## Links
+
+- GitHub: `https://github.com/BetterCorp/better-service-base/tree/master/plugins/nodejs/events-rabbitmq`
+- BSB Registry (package): `https://io.bsbcode.dev/packages/nodejs/@bsb/events-rabbitmq`
+
+## License
+
+(AGPL-3.0-only OR Commercial)

package/lib/plugins/events-rabbitmq/events/broadcast.d.ts

@@ -0,0 +1,19 @@
+import { Plugin } from "../index.js";
+import { Observable } from "@bsb/base";
+export declare class broadcast {
+    private plugin;
+    private publishQueuesSetup;
+    private publishChannel;
+    private receiveChannel;
+    private readonly channelKey;
+    private readonly exchange;
+    private readonly exchangeOpts;
+    private readonly queueOpts;
+    constructor(plugin: Plugin);
+    init(obs: Observable): Promise<void>;
+    dispose(): void;
+    onBroadcast(obs: Observable, pluginName: string, event: string, listener: {
+        (obs: Observable, args: Array<any>): Promise<void>;
+    }): Promise<void>;
+    emitBroadcast(obs: Observable, pluginName: string, event: string, args: Array<any>): Promise<void>;
+}

package/lib/plugins/events-rabbitmq/events/broadcast.js

@@ -0,0 +1,105 @@
+import { LIB } from "./lib.js";
+import { randomUUID } from "crypto";
+import { SmartFunctionCallAsync, } from "@bsb/base";
+export class broadcast {
+    constructor(plugin) {
+        this.publishQueuesSetup = [];
+        this.channelKey = "91eb";
+        this.exchange = {
+            type: "fanout",
+            name: "better.service9.broadcast",
+        };
+        this.exchangeOpts = {
+            durable: false,
+            autoDelete: false,
+        };
+        this.queueOpts = {
+            durable: false,
+            autoDelete: false,
+            messageTtl: 60 * 60 * 1000,
+            expires: 60 * 60 * 1000,
+        };
+        this.plugin = plugin;
+    }
+    async init(obs) {
+        obs.log.debug("Open broadcast channel ({exchangeName})", {
+            exchangeName: this.exchange.name,
+        });
+        this.publishChannel = await LIB.setupChannel(this.plugin, obs, this.plugin.publishConnection, this.channelKey, this.exchange.name, this.exchange.type, this.exchangeOpts);
+        this.receiveChannel = await LIB.setupChannel(this.plugin, obs, this.plugin.receiveConnection, this.channelKey, this.exchange.name, this.exchange.type, this.exchangeOpts, 5);
+    }
+    dispose() {
+        this.publishChannel.channel.close();
+        this.receiveChannel.channel.close();
+    }
+    async onBroadcast(obs, pluginName, event, listener) {
+        const thisUUID = randomUUID();
+        const rawQueueKey = LIB.getQueueKey(this.plugin, this.channelKey, pluginName, event);
+        const thisQueueKey = LIB.getQueueKey(this.plugin, this.channelKey, pluginName, event, thisUUID);
+        obs.log.debug("LISTEN: [{thisQueueKey}]", {
+            thisQueueKey: rawQueueKey,
+        });
+        await this.receiveChannel.channel.addSetup(async (iChannel) => {
+            await iChannel.assertQueue(thisQueueKey, this.queueOpts);
+            await this.receiveChannel.channel.consume(thisQueueKey, async (msg) => {
+                const body = msg.content.toString();
+                const bodyObj = JSON.parse(body);
+                let listenerObs = null;
+                try {
+                    const rootObs = this.plugin.createObservableFromTrace(bodyObj.trace, {
+                        pluginName,
+                        event,
+                    });
+                    listenerObs = rootObs.startSpan("broadcast.listener", {
+                        pluginName,
+                        event,
+                    });
+                    await SmartFunctionCallAsync(this.plugin, listener, listenerObs, bodyObj.args ?? []);
+                    this.receiveChannel.channel.ack(msg);
+                }
+                catch (err) {
+                    const errorObj = err instanceof Error ? err : new Error(err?.message || String(err));
+                    if (listenerObs) {
+                        listenerObs.error(errorObj);
+                    }
+                    this.receiveChannel.channel.nack(msg, true);
+                    obs.log.error("broadcast listener error: {err}", { err: errorObj.message });
+                }
+                finally {
+                    if (listenerObs) {
+                        listenerObs.end();
+                    }
+                }
+            }, { noAck: false });
+            await iChannel.bindQueue(thisQueueKey, this.receiveChannel.exchangeName, rawQueueKey);
+            obs.log.debug("listen rabbit: [{thisQueueKey}]", {
+                thisQueueKey: rawQueueKey,
+            });
+        });
+    }
+    async emitBroadcast(obs, pluginName, event, args) {
+        const thisQueueKey = LIB.getQueueKey(this.plugin, this.channelKey, pluginName, event);
+        obs.log.debug("Emit: [{thisQueueKey}]", {
+            thisQueueKey,
+        });
+        if (!this.publishQueuesSetup.includes(thisQueueKey)) {
+            this.publishQueuesSetup.push(thisQueueKey);
+            await this.publishChannel.channel.addSetup(async (iChannel) => {
+                await iChannel.assertQueue(thisQueueKey, this.queueOpts);
+                obs.log.debug("emit rabbit: [{thisQueueKey}]", { thisQueueKey });
+            });
+        }
+        if (!await this.publishChannel.channel.publish(this.publishChannel.exchangeName, thisQueueKey, {
+            trace: obs.trace,
+            args,
+        }, {
+            expiration: this.queueOpts.messageTtl,
+            contentType: "string",
+            appId: this.plugin.myId,
+            timestamp: Date.now(),
+        })) {
+            throw `Cannot send msg to queue [${thisQueueKey}]`;
+        }
+        obs.log.debug(" - EMIT: [{thisQueueKey}] - EMITTED", { thisQueueKey });
+    }
+}

package/lib/plugins/events-rabbitmq/events/emit.d.ts

@@ -0,0 +1,17 @@
+import { Plugin } from "../index.js";
+import { Observable } from "@bsb/base";
+export declare class emit {
+    private plugin;
+    private publishQueuesSetup;
+    private publishChannel;
+    private receiveChannel;
+    private readonly channelKey;
+    private readonly queueOpts;
+    constructor(plugin: Plugin);
+    init(obs: Observable): Promise<void>;
+    dispose(): void;
+    onEvent(obs: Observable, pluginName: string, event: string, listener: {
+        (obs: Observable, args: Array<any>): Promise<void>;
+    }): Promise<void>;
+    emitEvent(obs: Observable, pluginName: string, event: string, args: Array<any>): Promise<void>;
+}

package/lib/plugins/events-rabbitmq/events/emit.js

@@ -0,0 +1,89 @@
+import { LIB } from "./lib.js";
+import { SmartFunctionCallAsync, } from "@bsb/base";
+export class emit {
+    constructor(plugin) {
+        this.publishQueuesSetup = [];
+        this.channelKey = "91eq";
+        this.queueOpts = {
+            durable: false,
+            autoDelete: false,
+            messageTtl: 60 * 60 * 1000,
+            expires: 60 * 60 * 1000,
+        };
+        this.plugin = plugin;
+    }
+    async init(obs) {
+        obs.log.debug("Open broadcast channel ({channelKey})", {
+            channelKey: this.channelKey,
+        });
+        this.publishChannel = await LIB.setupChannel(this.plugin, obs, this.plugin.publishConnection, this.channelKey, null);
+        this.receiveChannel = await LIB.setupChannel(this.plugin, obs, this.plugin.receiveConnection, this.channelKey, null, undefined, undefined, 5);
+    }
+    dispose() {
+        this.publishChannel.channel.close();
+        this.receiveChannel.channel.close();
+    }
+    async onEvent(obs, pluginName, event, listener) {
+        const thisQueueKey = LIB.getQueueKey(this.plugin, this.channelKey, pluginName, event);
+        obs.log.debug("LISTEN: [{thisQueueKey}]", { thisQueueKey });
+        await this.receiveChannel.channel.addSetup(async (iChannel) => {
+            await iChannel.assertQueue(thisQueueKey, this.queueOpts);
+            await this.receiveChannel.channel.consume(thisQueueKey, async (msg) => {
+                const body = msg.content.toString();
+                const bodyObj = JSON.parse(body);
+                let listenerObs = null;
+                try {
+                    const rootObs = this.plugin.createObservableFromTrace(bodyObj.trace, {
+                        pluginName,
+                        event,
+                    });
+                    listenerObs = rootObs.startSpan("event.listener", {
+                        pluginName,
+                        event,
+                    });
+                    await SmartFunctionCallAsync(this.plugin, listener, listenerObs, bodyObj.args ?? []);
+                    this.receiveChannel.channel.ack(msg);
+                }
+                catch (err) {
+                    const errorObj = err instanceof Error ? err : new Error(err?.message || String(err));
+                    if (listenerObs) {
+                        listenerObs.error(errorObj);
+                    }
+                    this.receiveChannel.channel.nack(msg, true);
+                    obs.log.error("event listener error: {err}", { err: errorObj.message });
+                }
+                finally {
+                    if (listenerObs) {
+                        listenerObs.end();
+                    }
+                }
+            }, { noAck: false });
+            obs.log.debug("listen rabbit: [{thisQueueKey}]", { thisQueueKey });
+        });
+    }
+    async emitEvent(obs, pluginName, event, args) {
+        const thisQueueKey = LIB.getQueueKey(this.plugin, this.channelKey, pluginName, event);
+        obs.log.debug("Emit: [{thisQueueKey}]", {
+            thisQueueKey,
+        });
+        if (!this.publishQueuesSetup.includes(thisQueueKey)) {
+            this.publishQueuesSetup.push(thisQueueKey);
+            await this.publishChannel.channel.addSetup(async (iChannel) => {
+                await iChannel.assertQueue(thisQueueKey, this.queueOpts);
+                obs.log.debug("emit rabbit: [{thisQueueKey}]", { thisQueueKey });
+            });
+        }
+        if (!await this.publishChannel.channel.sendToQueue(thisQueueKey, {
+            trace: obs.trace,
+            args,
+        }, {
+            expiration: this.queueOpts.messageTtl,
+            contentType: "string",
+            appId: this.plugin.myId,
+            timestamp: Date.now(),
+        })) {
+            throw new Error(`Cannot send msg to queue [${thisQueueKey}]`);
+        }
+        obs.log.debug(" - EMIT: [{thisQueueKey}] - EMITTED", { thisQueueKey });
+    }
+}

package/lib/plugins/events-rabbitmq/events/emitAndReturn.d.ts

@@ -0,0 +1,20 @@
+import { Plugin } from "../index.js";
+import { EventEmitter } from "events";
+import { Observable } from "@bsb/base";
+export declare class emitAndReturn extends EventEmitter {
+    private plugin;
+    private privateQueuesSetup;
+    private publishChannel;
+    private receiveChannel;
+    private readonly channelKey;
+    private readonly myChannelKey;
+    private readonly queueOpts;
+    private readonly myQueueOpts;
+    constructor(plugin: Plugin);
+    init(obs: Observable): Promise<void>;
+    dispose(): void;
+    onReturnableEvent(obs: Observable, pluginName: string, event: string, listener: {
+        (obs: Observable, args: Array<any>): Promise<any>;
+    }): Promise<void>;
+    emitEventAndReturn(obs: Observable, pluginName: string, event: string, timeoutSeconds: number, args: Array<any>): Promise<any>;
+}

package/lib/plugins/events-rabbitmq/events/emitAndReturn.js

@@ -0,0 +1,207 @@
+import { EventEmitter } from "events";
+import { randomUUID } from "crypto";
+import { LIB } from "./lib.js";
+import { BSBError, SmartFunctionCallAsync, } from "@bsb/base";
+export class emitAndReturn extends EventEmitter {
+    constructor(plugin) {
+        super();
+        this.privateQueuesSetup = [];
+        this.channelKey = "91ar";
+        this.myChannelKey = "91kr";
+        this.queueOpts = {
+            durable: false,
+            autoDelete: false,
+            messageTtl: 60 * 1000,
+            expires: 60 * 1000,
+        };
+        this.myQueueOpts = {
+            exclusive: true,
+            durable: false,
+            autoDelete: false,
+            messageTtl: 60 * 1000,
+            expires: 60 * 1000,
+        };
+        this.plugin = plugin;
+    }
+    async init(obs) {
+        const myEARQueueKey = LIB.getMyQueueKey(this.plugin, this.myChannelKey, this.plugin.myId);
+        obs.log.debug("Ready my events name: {myEARQueueKey}", {
+            myEARQueueKey,
+        });
+        this.publishChannel = await LIB.setupChannel(this.plugin, obs, this.plugin.publishConnection, this.myChannelKey, null);
+        this.receiveChannel = await LIB.setupChannel(this.plugin, obs, this.plugin.receiveConnection, this.myChannelKey, null, undefined, undefined, 2);
+        await this.receiveChannel.channel.addSetup(async (iChannel) => {
+            await iChannel.assertQueue(myEARQueueKey, this.myQueueOpts);
+            obs.log.debug("LISTEN: [{myEARQueueKey}]", { myEARQueueKey });
+            await iChannel.consume(myEARQueueKey, (msg) => {
+                if (msg === null) {
+                    obs.log.warn("[RECEIVED {myEARQueueKey}]... as null", {
+                        myEARQueueKey,
+                    });
+                    return;
+                }
+                try {
+                    const body = msg.content.toString();
+                    obs.log.debug("[RECEIVED {myEARQueueKey}]", {
+                        myEARQueueKey,
+                    });
+                    this.emit(msg.properties.correlationId, JSON.parse(body));
+                    iChannel.ack(msg);
+                }
+                catch (exc) {
+                    obs.log.error("AMQP Consumed exception: {eMsg}", {
+                        eMsg: exc.message || exc.toString(),
+                    });
+                    throw new Error(`AMQP consume exception: ${exc.message || exc}`);
+                }
+            }, { noAck: false });
+            obs.log.debug("LISTEN: [{myEARQueueKey}]", { myEARQueueKey });
+            obs.log.debug("Ready my events name: {myEARQueueKey} OKAY", {
+                myEARQueueKey,
+            });
+        });
+    }
+    dispose() {
+        this.publishChannel.channel.close();
+        this.receiveChannel.channel.close();
+    }
+    async onReturnableEvent(obs, pluginName, event, listener) {
+        const queueKey = LIB.getQueueKey(this.plugin, this.channelKey, pluginName, event);
+        obs.log.debug("EAR: listen {queueKey}", {
+            queueKey,
+        });
+        await this.receiveChannel.channel.addSetup(async (iChannel) => {
+            await iChannel.assertQueue(queueKey, this.queueOpts);
+            await iChannel.consume(queueKey, async (msg) => {
+                if (msg === null) {
+                    return obs.log.error("Message received on my EAR queue was null...");
+                }
+                const returnQueue = LIB.getMyQueueKey(this.plugin, this.myChannelKey, msg.properties.appId);
+                obs.log.debug("EAR: Received: {queueKey} from {returnQueue}", {
+                    queueKey,
+                    returnQueue,
+                });
+                const body = msg.content.toString();
+                const bodyObj = JSON.parse(body);
+                let handlerObs = null;
+                try {
+                    const rootObs = this.plugin.createObservableFromTrace(bodyObj.trace, {
+                        pluginName,
+                        event,
+                    });
+                    handlerObs = rootObs.startSpan("emitAndReturn.handler", {
+                        pluginName,
+                        event,
+                    });
+                    const response = await SmartFunctionCallAsync(this.plugin, listener, handlerObs, bodyObj.args ?? []);
+                    iChannel.ack(msg);
+                    obs.log.debug("EAR: OKAY: {queueKey} -> {returnQueue}", {
+                        queueKey,
+                        returnQueue,
+                    });
+                    if (!await this.publishChannel.channel.sendToQueue(returnQueue, {
+                        trace: handlerObs.trace,
+                        result: response,
+                    }, {
+                        expiration: 5000,
+                        correlationId: `${msg.properties.correlationId}-resolve`,
+                        contentType: "string",
+                        appId: this.plugin.myId,
+                        timestamp: Date.now(),
+                    })) {
+                        throw new BSBError(handlerObs.trace, "Cannot send msg to queue [{returnQueue}]", { returnQueue });
+                    }
+                }
+                catch (exc) {
+                    const errorObj = exc instanceof Error ? exc : new Error(String(exc));
+                    if (handlerObs) {
+                        handlerObs.error(errorObj);
+                    }
+                    obs.log.error("EAR: ERROR: {queueKey} -> {returnQueue}", {
+                        queueKey,
+                        returnQueue,
+                    });
+                    if (!await this.publishChannel.channel.sendToQueue(returnQueue, {
+                        trace: bodyObj.trace,
+                        error: errorObj.message,
+                    }, {
+                        expiration: 5000,
+                        correlationId: `${msg.properties.correlationId}-reject`,
+                        contentType: "string",
+                        appId: this.plugin.myId,
+                        timestamp: Date.now(),
+                    })) {
+                        throw new BSBError(obs.trace, "Cannot send msg to queue [{returnQueue}]", { returnQueue });
+                    }
+                    iChannel.ack(msg);
+                }
+                finally {
+                    if (handlerObs) {
+                        handlerObs.end();
+                    }
+                }
+            }, { noAck: false });
+            obs.log.debug("EAR: listening {queueKey}", {
+                queueKey,
+            });
+        });
+    }
+    async emitEventAndReturn(obs, pluginName, event, timeoutSeconds, args) {
+        const start = Date.now();
+        const resultKey = `${randomUUID()}-${start}${Math.random()}`;
+        const queueKey = LIB.getQueueKey(this.plugin, this.channelKey, pluginName, event);
+        const requestObs = obs.startSpan("emitAndReturn.request", {
+            pluginName,
+            event,
+            correlationId: resultKey,
+        });
+        requestObs.log.debug("EAR: emitting {queueKey} ({resultKey})", {
+            queueKey,
+            resultKey,
+        });
+        if (!this.privateQueuesSetup.includes(queueKey)) {
+            this.privateQueuesSetup.push(queueKey);
+            await this.publishChannel.channel.addSetup(async (iChannel) => {
+                await iChannel.assertQueue(queueKey, this.queueOpts);
+            });
+        }
+        return new Promise(async (resolve, reject) => {
+            const timeoutHandler = setTimeout(() => {
+                this.removeAllListeners(`${resultKey}-resolve`);
+                this.removeAllListeners(`${resultKey}-reject`);
+                const err = new Error("Timeout");
+                requestObs.error(err);
+                requestObs.end();
+                reject(err);
+            }, timeoutSeconds * 1000);
+            this.once(`${resultKey}-resolve`, async (rargs) => {
+                clearTimeout(timeoutHandler);
+                requestObs.end();
+                resolve(rargs?.result ?? rargs);
+            });
+            this.once(`${resultKey}-reject`, async (rargs) => {
+                clearTimeout(timeoutHandler);
+                const err = new Error(rargs?.error || "Unknown error");
+                requestObs.error(err);
+                requestObs.end();
+                reject(err);
+            });
+            if (!await this.publishChannel.channel.sendToQueue(queueKey, {
+                trace: requestObs.trace,
+                args,
+            }, {
+                expiration: timeoutSeconds * 1000 + 5000,
+                correlationId: resultKey,
+                contentType: "string",
+                appId: this.plugin.myId,
+                timestamp: Date.now(),
+            })) {
+                throw new BSBError(requestObs.trace, "Cannot send msg to queue [{queueKey}]", { queueKey });
+            }
+            requestObs.log.debug("EAR: emitted {queueKey} ({resultKey})", {
+                queueKey,
+                resultKey,
+            });
+        });
+    }
+}

package/lib/plugins/events-rabbitmq/events/emitStreamAndReceiveStream.d.ts

@@ -0,0 +1,24 @@
+import { EventEmitter } from "events";
+import { Readable } from "stream";
+import { Plugin } from "../index.js";
+import { Observable } from "@bsb/base";
+export declare class emitStreamAndReceiveStream extends EventEmitter {
+    private readonly staticCommsTimeout;
+    private plugin;
+    private eventsChannel;
+    private streamChannel;
+    private readonly eventsChannelKey;
+    private readonly streamChannelKey;
+    private readonly queueOpts;
+    private myEventsQueueKey;
+    private myStreamQueueKey;
+    private cleanupSelf;
+    constructor(plugin: Plugin);
+    dispose(): void;
+    setupChannel(obs: Observable, channel: any, channelKey: string, queueKeyMethod: Function, logMessage: string): Promise<void>;
+    setupChannelsIfNotSetup(obs: Observable): Promise<void>;
+    receiveStream(obs: Observable, pluginName: string, event: string, listener: {
+        (obs: Observable, error: Error | null, stream: Readable): Promise<void>;
+    }, timeoutSeconds?: number): Promise<string>;
+    sendStream(obs: Observable, pluginName: string, event: string, streamIdf: string, stream: Readable): Promise<void>;
+}