@codefresh-io/eventbus 2.4.0 → 3.0.0-alpha.0

package/README.md

@@ -1,5 +1,6 @@
 ## cf eventbus
 
+```TS
 const eventbus = require('cf-eventbus');
 
 eventbus.init({
@@ -14,4 +15,41 @@ eventbus.init({
         password: 'postgres' // postgres password
     },
     microServiceName: 'service-name' // client name
-});
+});
+```
+
+## Graceful shutdown
+
+`quit()` method can be used to gracefully terminate the bus connection by cancelling all consumers, waiting for all consumers in progress to finish, and then closing the connection.
+If it's not desired, use `quit({ force: true })` to terminate the connection immediately.
+
+```TS
+const eventbus = require('cf-eventbus');
+
+process.on('SIGTERM', async () => {
+    try {
+        await eventbus.quit();
+        // ...
+    } catch (err) {
+        // ...
+    }
+});
+```
+
+It's may be required to perform some additional cleanup after all consumers are cancelled and before the connection is closed. In that case, use the following pattern:
+
+```TS
+const eventbus = require('cf-eventbus');
+
+process.on('SIGTERM', async () => {
+    try {
+        await eventbus.cancelAllConsumers();
+        await eventbus.waitForConsumersToFinish();
+        // perform additional cleanup here, such as waiting for HTTP requests to finish
+        await eventbus.quit();
+        // ...
+    } catch (err) {
+        // ...
+    }
+});
+```

package/lib/Bus.js

@@ -1,27 +1,49 @@
 "use strict";
 
-const _            = require('lodash');
-const EventEmitter = require('events');
-const Promise      = require('bluebird');
-const debug        = require('debug')('eventbus:bus');
+const EventEmitter = require('node:events');
+const timers       = require('node:timers/promises');
 const amqplib      = require('amqplib');
 const isFatalError = require('amqplib/lib/connection').isFatalError;
-const domain       = require('domain');
-const uuid         = require('uuid');
+const { logger }   = require('./logger');
 
-const RECONNET_INTERVAL_DEFAULT = 1; // in seconds
+
+/**
+ * @typedef {(...args: any[]) => Promise<void>} Handler
+ * 
+ * @typedef {object} Subscriber
+ * @property {string} eventName
+ * @property {Handler} handler
+ * @property {object} options
+ */
+
+const RECONNECT_INTERVAL_DEFAULT_SEC = 1;
 
 class Bus extends EventEmitter {
+    _logger = logger.child(this.constructor.name);
+    _consumersInProgressCount = 0;
+    _terminating = false;
+    _terminated = false;
 
+    /**
+     * @param {string} microServiceName
+     * @param {object} options
+     * @param {string} options.url RabbitMQ connection url
+     * @param {number} [options.reconnectInterval] Reconnect interval in seconds. Default is 1 second.
+     */
     constructor(microServiceName, options) {
         super();
-        this.url               = options.url;
-        this.microServiceName  = microServiceName;
-        this.reconnectInterval = (options.reconnectInterval || RECONNET_INTERVAL_DEFAULT) * 1000;
+        this.url = options.url;
+        this.microServiceName = microServiceName;
+        this.reconnectIntervalMs = (options.reconnectInterval || RECONNECT_INTERVAL_DEFAULT_SEC) * 1000;
+        /** @type {Record<string, Subscriber[]>} */
         this.subscribers = {};
         this.initializing = false;
+        /** @type {boolean} */
+        this._forbidNewConsumers = false;
         this._reSubscribe = this._reSubscribe.bind(this);
         this._reconnect = this._reconnect.bind(this);
+        /** @type {Map<amqplib.Channel, string[]>} */
+        this.consumerTagsByChannel = new Map();
     }
 
     _createErrorHandler() {
@@ -37,28 +59,94 @@ class Bus extends EventEmitter {
         });
     }
 
-    async quit() {
-        await this.connection.close();
+    /**
+     * Unsubscribes all consumers and forbids new consumers from being subscribed.
+     * This should be used when you want to gracefully terminate the connection and ensure that no new messages are consumed while terminating.
+     * @returns {Promise<void>}
+     */
+    async cancelAllConsumers() {
+        this._logger.info('Cancelling all consumers on all channels. New subscriptions will be forbidden from now on.');
+        this._forbidNewConsumers = true;
+
+        for (const ch of this.consumerTagsByChannel.keys()) {
+            const consumerTags = this.consumerTagsByChannel.get(ch) ?? [];
+            const results = await Promise.allSettled(
+                consumerTags.map((consumerTag) => ch.cancel(consumerTag))
+            );
+            for (let i = 0; i < results.length; i++) {
+                const result = results[i];
+                const consumerTag = consumerTags[i];
+                if (result.status === 'rejected') {
+                    this._logger.error(`Failed to cancel consumer with tag "${consumerTag}". Ignoring error`, { error: result.reason });
+                    continue;
+                }
+                this._logger.debug(`Consumer with tag "${consumerTag}" was cancelled successfully`);
+            }
+        }
+        this.consumerTagsByChannel.clear();
+        this._logger.info('All consumers were cancelled');
+    }
+
+    /**
+     * Waits for all consumers in progress to finish.
+     * This should be used before terminating the connection
+     * to ensure that all messages are processed before the connection is closed.
+     * @returns {Promise<void>}
+     */
+    async waitForConsumersToFinish() {
+        while (this._consumersInProgressCount > 0) {
+            this._logger.info(`Waiting for ${this._consumersInProgressCount} consumers in progress to finish...`);
+            await timers.setTimeout(1000);
+        }
+    }
+
+    /**
+     * Terminates the connection gracefully by cancelling all consumers, waiting for all consumers in progress to finish, and then closing the connection.
+     * @param {object} [options]
+     * @param {boolean} [options.force] If `true`, closes connection immediately.
+     */
+    async quit(options = {}) {
+        this._terminating = true;
+        if (options.force) {
+            this._logger.warn('Forcefully terminating eventbus connection. All consumers in progress will be interrupted and may not finish processing messages');
+            await this._closeConnection();
+            this._terminated = true;
+            return;
+        }
+        this._logger.info('Gracefully terminating eventbus connection');
+        await this.cancelAllConsumers();
+        await this.waitForConsumersToFinish();
+        await this._closeConnection();
+        this._terminated = true;
+    }
+
+    async _closeConnection() {
+        this._logger.info('Closing eventbus connection');
+        await this.connection?.close();
         this.subscribers = {};
-        debug('bus closed');
+        this._logger.info('Eventbus connection closed');
     }
 
+    /**
+     * @returns {void}
+     */
     init() {
         this.initializing = true;
         this._createErrorHandler();
 
+        this._logger.debug('Eventbus connecting...');
         this.openPromise = amqplib.connect(this.url);
         this.openPromise
             .then((newConnection) => {
-                debug('new connection created');
+                this._logger.debug('Eventbus connected');
                 if (this.reconnect && this.connection) {
                     this.publishChannel = undefined;
-                    debug('reconnected');
+                    this._logger.debug('Eventbus reconnected');
                 }
                 this.reconnect  = false;
                 this.connection = newConnection;
 
-                debug(`ready`);
+                this._logger.debug('Eventbus ready');
                 this.emit('ready');
 
                 this.connection.on('error', (err) => {
@@ -66,17 +154,17 @@ class Bus extends EventEmitter {
                 });
 
                 this.connection.on('close', () => {
-                    debug(`connection close event`);
+                    this._logger.debug('Eventbus connection closed');
                     this.emit('close');
                     this._reconnect();
                 });
 
                 this.connection.on('blocked', () => {
-                    debug('connection blocked');
+                    this._logger.debug('Eventbus connection blocked');
                 });
 
                 this.connection.on('unblocked', () => {
-                    debug('connection unblocked');
+                    this._logger.debug('Eventbus connection unblocked');
                 });
 
                 return this._reSubscribe();
@@ -90,165 +178,198 @@ class Bus extends EventEmitter {
     }
 
     _reconnect() {
-        if (this.initializing) {
-            debug('not reconnecting because initialization is still in process');
+        if (this.initializing || this._terminating || this._terminated) {
+            this._logger.debug('Skipping eventbus reconnect because eventbus is initializing or terminating');
             return;
         }
 
-        debug(`reconnecting in: ${this.reconnectInterval / 1000} seconds because of fatal error`);
+        this._logger.debug(`Eventbus reconnecting in ${this.reconnectIntervalMs / 1000} seconds`);
         this.reconnect = true;
         setTimeout(() => {
-            debug(`reconnecting`);
+            this._logger.debug('Eventbus reconnecting...');
             this.init();
-        }, this.reconnectInterval);
+        }, this.reconnectIntervalMs);
     }
 
-    _reSubscribe() {
-        return Promise.map(_.values(this.subscribers), (eventSubscribers) => {
-            // `Promise.each` for guarantee of order for subscribers
-            return Promise.each(eventSubscribers, ({eventName, handler, options}) => {
-                return this.subscribe(eventName, handler, options, true);
-            });
-        });
+    async _reSubscribe() {
+        for (const [eventName, subscribers] of Object.entries(this.subscribers)) {
+            this._logger.debug(`Re-subscribing ${subscribers.length} subscribers to event "${eventName}"`);
+            for (const { eventName, handler, options } of subscribers) {
+                this.subscribe(eventName, handler, options, true);
+            }
+            this._logger.debug(`Finished re-subscribing ${subscribers.length} subscribers to event "${eventName}"`);
+        }
     }
 
-    publish(eventName, msg) {
-        return Promise.resolve()
-            .then(() => {
-                if (!this.publishChannel) {
-                    return this._createPublishChannel();
-                }
-            })
-            .then(() => {
-                return this.publishChannel.assertExchange(eventName, 'fanout', { durable: true });
-            })
-            .then(() => {
-                return this.publishChannel.publish(eventName, 'my-routing-key', new Buffer(this._serialize(msg)));
-            });
+    /**
+     * 
+     * @param {string} eventName
+     * @param {any} msg
+     * @param {string} [routingKey]
+     * @returns {Promise<boolean>} Returns true if the message was published successfully, false otherwise.
+     */
+    async publish(eventName, msg, routingKey = 'default') {
+        if (!this.publishChannel) {
+            await this._createPublishChannel();
+        }
+        await this.publishChannel?.assertExchange(eventName, 'fanout', { durable: true });
+        return !!(this.publishChannel?.publish(
+            eventName,
+            routingKey,
+            Buffer.from(this._serialize(msg)),
+        ));
     }
 
+    /**
+     * @param {string} eventName
+     * @param {Handler} handler
+     * @param {object} [options]
+     * @param {boolean} [options.pubSub]
+     * @param {boolean} [options.waitForAck]
+     * @param {number} [options.concurrencyLimit]
+     * @param {number} [options.ttl]
+     * @param {number} [options.timeout]
+     * @param {boolean} [options.ackOnTimeout]
+     * @param {string} [options.serviceRole]
+     * @param {string} [options.additionalIdentifier]
+     * @param {boolean} [restarting]
+     * @returns {EventEmitter} An EventEmitter that emits 'error' event when an error occurs in the handler or during subscription process.
+     */
     subscribe(eventName, handler, options = {}, restarting) {
-        if (!restarting) {
-            this.subscribers[eventName] = this.subscribers[eventName] || [];
-            this.subscribers[eventName].push({eventName, handler, options});
-        }
+        this._logger.debug(`Subscribing to event "${eventName}", options:`, options);
         const subscriberEmitter = new EventEmitter();
         subscriberEmitter.on('error', () => {});
+
+        if (this._forbidNewConsumers || this._terminating || this._terminated) {
+            this._logger.warn(`Skipping new consumer subscription to "${eventName}" because eventbus is terminating or terminated or new consumers are forbidden`);
+            return subscriberEmitter;
+        }
+
+        if (!restarting) {
+            this.subscribers[eventName] ??= [];
+            this.subscribers[eventName].push({ eventName, handler, options });
+        }
+
         const pubSub = options.pubSub || false;
         const waitForAck = options.waitForAck || false;
-        const concurrencyLimit =  options.concurrencyLimit || false;
+        const concurrencyLimit = options.concurrencyLimit || 0; // 0 means no limit
         const messageTtl = options.ttl || false;
         const timeout = options.timeout;
         const ackOnTimeout = options.ackOnTimeout;
 
-        const serviceRole = options.serviceRole ? `${options.serviceRole}_` : '';
-        const additionalIdentifier = options.additionalIdentifier ? `${options.additionalIdentifier}_` : '';
-        const pubSubIdentifier = options.pubSub ? `${uuid()}_` : '';
+        const serviceRole = options.serviceRole
+            ? `${options.serviceRole}_`
+            : '';
+        const additionalIdentifier = options.additionalIdentifier
+            ? `${options.additionalIdentifier}_`
+            : '';
+        const pubSubIdentifier = options.pubSub
+            ? `${globalThis.crypto.randomUUID()}_`
+            : '';
         const queueName = `${this.microServiceName}_${serviceRole}${additionalIdentifier}${pubSubIdentifier}${eventName}`;
         Promise.resolve()
-            .then(() => {
-                return this._getSubscribeChannel();
+            .then(() => this._getSubscribeChannel())
+            .then(async (ch) => {
+                if (!ch) {
+                    throw new Error('Channel was not created. Perhaps initial connection failed or not established yet');
+                }
+                await ch.assertExchange(eventName, 'fanout', { durable: true });
+                this._logger.debug(`Durable exchange "${eventName}" of type "fanout" asserted`);
+                return ch;
+            })
+            .then(async (ch) => {
+                const queueOptions = {
+                    ...(!pubSub && { durable: true }),
+                    ...(pubSub && { exclusive: true }),
+                    ...(messageTtl && { messageTtl }),
+                };
+                await ch.assertQueue(queueName, queueOptions);
+                this._logger.debug(`Queue "${queueName}" asserted`, { queueOptions });
+                return ch;
             })
-            .then((ch) => {
-                return ch.assertExchange(eventName, 'fanout', { durable: true })
-                    .then(() => {
-                        const queueOptions = {
-                            ...(!pubSub && { durable: true }),
-                            ...(pubSub && { exclusive: true })
-                        };
-                        if (messageTtl) {
-                            queueOptions.messageTtl = messageTtl;
+            .then(async (ch) => {
+                await ch.bindQueue(queueName, eventName, '');
+                this._logger.debug(`Queue "${queueName}" bound to exchange "${eventName}", pattern ""`);
+                return ch;
+            })
+            .then(async (ch) => {
+                this._logger.debug(`Setting concurrency limit "${concurrencyLimit}" for queue "${queueName}"`);
+                await ch.prefetch(concurrencyLimit);
+                return ch;
+            })
+            .then(async (ch) => {
+                const { consumerTag } = await ch.consume(queueName, async (msg) => {
+                    let finished = false;
+                    try {
+                        if (waitForAck && timeout) {
+                            setTimeout(() => {
+                                if (finished) return;
+                                finished = true;
+                                subscriberEmitter.emit('error', new Error('Handler timedout'));
+                                if (ackOnTimeout) {
+                                    ch.ack(msg);
+                                } else {
+                                    ch.nack(msg);
+                                }
+                            }, timeout);
+                        } else {
+                            ch.ack(msg);
+                        }
+                        const content = this._deserialize(msg.content.toString());
+                        this._consumersInProgressCount++;
+                        await handler(content).finally(() => this._consumersInProgressCount--);
+                    } catch (error) {
+                        subscriberEmitter.emit('error', error);
+                        if (!finished && waitForAck) {
+                            finished = true;
+                            ch.nack(msg);
+                        } else {
+                            finished = true;
                         }
-                        return ch.assertQueue(queueName, queueOptions)
-                            .then(() => {
-                                debug(`queue: ${queueName} asserted`);
-                                return ch.bindQueue(queueName, eventName);
-                            })
-                            .then(() => {
-                                return ch.prefetch(concurrencyLimit);
-                            })
-                            .then(() => {
-                                debug(`queue: ${queueName} concurrencyLimit: ${concurrencyLimit} was set`);
-                                return ch.consume(queueName, (msg) => {
-                                    const d = domain.create();
-                                    d.on('error', (err) => {
-                                        subscriberEmitter.emit('error', err);
-                                    });
-                                    d.run(() => {
-                                        let finished = false;
-                                        if (waitForAck) {
-                                            if (timeout) {
-                                                setTimeout(() => {
-                                                    if (!finished) {
-                                                        finished = true;
-                                                        subscriberEmitter.emit('error', new Error('Handler timedout'));
-                                                        if (ackOnTimeout) {
-                                                            ch.ack(msg);
-                                                        } else {
-                                                            ch.nack(msg);
-                                                        }
-                                                    }
-                                                }, timeout);
-                                            }
-                                        } else {
-                                            ch.ack(msg);
-                                        }
-                                        handler(this._deserialize(msg.content.toString()))
-                                            .then(() => {
-                                                if (!finished && waitForAck) {
-                                                    finished = true;
-                                                    ch.ack(msg);
-                                                } else {
-                                                    finished = true;
-                                                }
-                                            }, (err) => {
-                                                subscriberEmitter.emit('error', err);
-                                                if (!finished && waitForAck) {
-                                                    finished = true;
-                                                    ch.nack(msg);
-                                                } else {
-                                                    finished = true;
-                                                }
-                                            });
-                                    });
-                                });
-                            });
-                    });
+                    }
+                });
+                const consumerTags = this.consumerTagsByChannel.get(ch) ?? [];
+                consumerTags.push(consumerTag);
+                this.consumerTagsByChannel.set(ch, consumerTags);
             })
             .catch((err) => {
                 subscriberEmitter.emit('error', { connection: err });
-            })
-            .done();
+            });
 
         return subscriberEmitter;
     }
 
-    _createPublishChannel() {
-        return this.openPromise
-            .then((conn) => {
-                return conn.createChannel();
-            })
-            .then((ch) => {
-                this.publishChannel = ch;
-            });
+    /**
+     * @returns {Promise<void>}
+     */
+    async _createPublishChannel() {
+        const model = await this.openPromise;
+        this.publishChannel = await model?.createChannel();
     }
 
-    _getSubscribeChannel() {
-        return this.openPromise
-            .then((conn) => {
-                return conn.createChannel();
-            });
+    /**
+     * @returns {Promise<amqplib.Channel | undefined>}
+     */
+    async _getSubscribeChannel() {
+        const model = await this.openPromise;
+        return model?.createChannel();
     }
 
+    /**
+     * @param {unknown} body 
+     * @returns {string}
+     */
     _serialize(body) {
         return JSON.stringify(body);
     }
 
+    /**
+     * @param {string} content 
+     * @returns {unknown}
+     */
     _deserialize(content) {
         return JSON.parse(content);
     }
-
-
 }