@flusys/nestjs-shared 6.4.0 → 7.0.0-beta.1

package/cjs/classes/event-transports/rabbitmq-transport.optional.js

@@ -0,0 +1,184 @@
+/**
+ * Optional RabbitMQ event transport
+ * Requires: npm install amqplib
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "RabbitMqTransport", {
+    enumerable: true,
+    get: function() {
+        return RabbitMqTransport;
+    }
+});
+const _common = require("@nestjs/common");
+const _constants = require("../../constants");
+const _eventpatternutil = require("../../utils/event-pattern.util");
+const _optionalmoduleutil = require("../../utils/optional-module.util");
+const _eventtransportregistry = require("./event-transport.registry");
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+const DEFAULT_URL = 'amqp://localhost:5672';
+const DEFAULT_RECONNECT_DELAY = 5000;
+let RabbitMqTransport = class RabbitMqTransport {
+    async connect() {
+        let amqp;
+        try {
+            amqp = await (0, _optionalmoduleutil.loadOptionalModule)('amqplib');
+        } catch  {
+            throw new _common.InternalServerErrorException({
+                message: 'amqplib not found',
+                messageKey: _constants.SYSTEM_MESSAGES.SDK_NOT_INSTALLED,
+                messageVariables: {
+                    sdk: 'amqplib'
+                }
+            });
+        }
+        this.connection = await (amqp.connect ?? amqp.default.connect)(this.config.url ?? DEFAULT_URL);
+        this.channel = await this.connection.createChannel();
+        await this.channel.assertExchange(this.exchange, 'topic', {
+            durable: this.durable
+        });
+        await this.channel.assertQueue(this.queue, {
+            durable: this.durable
+        });
+        await this.channel.prefetch(this.config.prefetch ?? 10);
+        // A channel dies on its own for any protocol error - a mismatched assert, a
+        // deleted exchange, an unknown delivery tag - while the connection stays up.
+        // Watching only the connection would leave the transport holding a dead
+        // channel: publishing throws into the void and nothing ever reconnects.
+        this.connection.on('close', ()=>this.scheduleReconnect());
+        this.connection.on('error', (error)=>this.logger.warn(error.message));
+        this.channel.on('close', ()=>this.scheduleReconnect());
+        this.channel.on('error', (error)=>this.logger.warn(error.message));
+        for (const pattern of this.boundPatterns){
+            await this.channel.bindQueue(this.queue, this.exchange, this.toRoutingKey(pattern));
+        }
+        if (this.boundPatterns.size) await this.startConsuming();
+    }
+    async publish(event) {
+        if (!this.channel) return;
+        this.channel.publish(this.exchange, event.name, Buffer.from(JSON.stringify(event)), {
+            persistent: this.durable,
+            messageId: event.id,
+            appId: this.config.queue ?? _constants.DEFAULT_EVENT_SERVICE_NAME,
+            contentType: 'application/json'
+        });
+    }
+    async bind(pattern) {
+        if (this.boundPatterns.has(pattern)) return;
+        this.boundPatterns.add(pattern);
+        if (!this.channel) return;
+        await this.channel.bindQueue(this.queue, this.exchange, this.toRoutingKey(pattern));
+        await this.startConsuming();
+    }
+    onMessage(handler) {
+        this.handlers.push(handler);
+    }
+    async close() {
+        this.closed = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        await this.teardown();
+    }
+    isReady() {
+        return Boolean(this.channel);
+    }
+    get exchange() {
+        return this.config.exchange ?? _constants.DEFAULT_EVENT_EXCHANGE;
+    }
+    get queue() {
+        return this.config.queue ?? `${_constants.DEFAULT_EVENT_SERVICE_NAME}.events`;
+    }
+    get durable() {
+        return this.config.durable ?? true;
+    }
+    /** `**` is the FLUSYS alias for the AMQP multi word wildcard */ toRoutingKey(pattern) {
+        return pattern.split('.').map((segment)=>(0, _eventpatternutil.isMultiWildcard)(segment) ? '#' : segment).join('.');
+    }
+    async startConsuming() {
+        // Captured, because a reconnect swaps `this.channel` while deliveries are in
+        // flight - a delivery tag means nothing on the new channel, and acking it
+        // there is a protocol error that kills that channel too.
+        const channel = this.channel;
+        if (this.consuming || !channel) return;
+        this.consuming = true;
+        try {
+            await channel.consume(this.queue, async (message)=>{
+                if (!message) return;
+                try {
+                    const event = JSON.parse(message.content.toString());
+                    await Promise.all(this.handlers.map((handler)=>handler(event)));
+                    channel.ack(message);
+                } catch (error) {
+                    this.logger.error(error instanceof Error ? error.message : 'Failed to handle event');
+                    channel.nack(message, false, false);
+                }
+            });
+        } catch (error) {
+            // A latch left set would keep the queue unconsumed for the process lifetime
+            this.consuming = false;
+            throw error;
+        }
+    }
+    /** A dropped connection reports itself twice - once per channel, once per connection */ scheduleReconnect() {
+        if (this.closed || this.reconnectTimer) return;
+        // Not awaited: the fields are cleared before its first await, so publishing
+        // stops using the dead channel now rather than after the sockets close.
+        void this.teardown();
+        this.reconnectTimer = setTimeout(()=>{
+            this.reconnectTimer = undefined;
+            this.connect().catch((error)=>{
+                this.logger.warn(`RabbitMQ reconnect failed: ${error.message}`);
+                this.scheduleReconnect();
+            });
+        }, this.config.reconnectDelay ?? DEFAULT_RECONNECT_DELAY);
+    }
+    /**
+   * Drops the current channel and connection. The connection is closed even when
+   * it was only the channel that died, otherwise every channel level failure
+   * would leave one more live connection behind on the broker.
+   */ async teardown() {
+        const { channel, connection } = this;
+        this.channel = undefined;
+        this.connection = undefined;
+        this.consuming = false;
+        channel?.removeAllListeners?.();
+        connection?.removeAllListeners?.();
+        await channel?.close().catch(()=>{});
+        await connection?.close().catch(()=>{});
+    }
+    constructor(config = {}){
+        _define_property(this, "config", void 0);
+        _define_property(this, "name", void 0);
+        _define_property(this, "logger", void 0);
+        _define_property(this, "handlers", void 0);
+        _define_property(this, "boundPatterns", void 0);
+        _define_property(this, "connection", void 0);
+        _define_property(this, "channel", void 0);
+        _define_property(this, "consuming", void 0);
+        _define_property(this, "closed", void 0);
+        _define_property(this, "reconnectTimer", void 0);
+        this.config = config;
+        this.name = 'rabbitmq';
+        this.logger = new _common.Logger(RabbitMqTransport.name);
+        this.handlers = [];
+        this.boundPatterns = new Set();
+        this.consuming = false;
+        this.closed = false;
+    }
+};
+_eventtransportregistry.EventTransportRegistry.register('rabbitmq', (config)=>new RabbitMqTransport(config));

package/cjs/classes/event-transports/rabbitmq-transport.optional.spec.js

@@ -0,0 +1,256 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _common = require("@nestjs/common");
+const _eventactionenum = require("../../enums/event-action.enum");
+const _rabbitmqtransportoptional = require("./rabbitmq-transport.optional");
+const mockLoadOptionalModule = jest.fn();
+jest.mock('../../utils/optional-module.util', ()=>({
+        loadOptionalModule: (...args)=>mockLoadOptionalModule(...args)
+    }));
+function buildEvent() {
+    return {
+        id: 'event-1',
+        name: 'storage.folder.created',
+        module: 'storage',
+        entity: 'folder',
+        action: _eventactionenum.EventAction.CREATED,
+        payload: {
+            ids: [
+                '1'
+            ]
+        },
+        actor: {},
+        occurredAt: '2026-01-01T00:00:00.000Z',
+        version: 1
+    };
+}
+function createChannelMock() {
+    return {
+        assertExchange: jest.fn().mockResolvedValue(undefined),
+        assertQueue: jest.fn().mockResolvedValue(undefined),
+        prefetch: jest.fn().mockResolvedValue(undefined),
+        bindQueue: jest.fn().mockResolvedValue(undefined),
+        consume: jest.fn().mockResolvedValue(undefined),
+        publish: jest.fn(),
+        ack: jest.fn(),
+        nack: jest.fn(),
+        on: jest.fn(),
+        removeAllListeners: jest.fn(),
+        close: jest.fn().mockResolvedValue(undefined)
+    };
+}
+/** A reconnect must land on a fresh channel, so every createChannel yields one */ function createAmqpMock() {
+    const channels = [];
+    const connection = {
+        createChannel: jest.fn(async ()=>{
+            const channel = createChannelMock();
+            channels.push(channel);
+            return channel;
+        }),
+        on: jest.fn(),
+        removeAllListeners: jest.fn(),
+        close: jest.fn().mockResolvedValue(undefined)
+    };
+    return {
+        channels,
+        connection,
+        connect: jest.fn().mockResolvedValue(connection),
+        get channel () {
+            return channels[channels.length - 1];
+        }
+    };
+}
+function listenerFor(target, event) {
+    const registered = target.on.mock.calls.find(([name])=>name === event);
+    if (!registered) throw new Error(`No '${event}' listener was registered`);
+    return registered[1];
+}
+describe('RabbitMqTransport', ()=>{
+    let amqp;
+    let warnSpy;
+    let errorSpy;
+    beforeEach(()=>{
+        amqp = createAmqpMock();
+        mockLoadOptionalModule.mockResolvedValue({
+            connect: amqp.connect
+        });
+        warnSpy = jest.spyOn(_common.Logger.prototype, 'warn').mockImplementation(()=>undefined);
+        errorSpy = jest.spyOn(_common.Logger.prototype, 'error').mockImplementation(()=>undefined);
+    });
+    afterEach(()=>{
+        warnSpy.mockRestore();
+        errorSpy.mockRestore();
+        jest.clearAllMocks();
+    });
+    it('should throw a descriptive error when amqplib is not installed', async ()=>{
+        mockLoadOptionalModule.mockRejectedValue(new Error('Cannot find module'));
+        await expect(new _rabbitmqtransportoptional.RabbitMqTransport().connect()).rejects.toThrow(_common.InternalServerErrorException);
+    });
+    it('should assert a topic exchange and a durable queue on connect', async ()=>{
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport({
+            exchange: 'ex',
+            queue: 'svc.events'
+        });
+        await transport.connect();
+        expect(amqp.channel.assertExchange).toHaveBeenCalledWith('ex', 'topic', {
+            durable: true
+        });
+        expect(amqp.channel.assertQueue).toHaveBeenCalledWith('svc.events', {
+            durable: true
+        });
+        expect(transport.isReady()).toBe(true);
+    });
+    it('should publish with the event name as the routing key', async ()=>{
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport({
+            exchange: 'ex'
+        });
+        await transport.connect();
+        const event = buildEvent();
+        await transport.publish(event);
+        expect(amqp.channel.publish).toHaveBeenCalledWith('ex', 'storage.folder.created', expect.any(Buffer), expect.objectContaining({
+            messageId: 'event-1',
+            contentType: 'application/json'
+        }));
+    });
+    it('should ignore publish before connect instead of throwing', async ()=>{
+        await expect(new _rabbitmqtransportoptional.RabbitMqTransport().publish(buildEvent())).resolves.toBeUndefined();
+    });
+    it('should translate the ** wildcard to the AMQP # wildcard when binding', async ()=>{
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport({
+            exchange: 'ex',
+            queue: 'q'
+        });
+        await transport.connect();
+        await transport.bind('storage.**');
+        expect(amqp.channel.bindQueue).toHaveBeenCalledWith('q', 'ex', 'storage.#');
+    });
+    it('should start consuming only once across several binds', async ()=>{
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport();
+        await transport.connect();
+        await transport.bind('storage.#');
+        await transport.bind('auth.#');
+        expect(amqp.channel.consume).toHaveBeenCalledTimes(1);
+    });
+    it('should hand a consumed message to its handlers and ack it', async ()=>{
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport();
+        const handler = jest.fn();
+        transport.onMessage(handler);
+        await transport.connect();
+        await transport.bind('storage.#');
+        const event = buildEvent();
+        const message = {
+            content: Buffer.from(JSON.stringify(event))
+        };
+        await amqp.channel.consume.mock.calls[0][1](message);
+        expect(handler).toHaveBeenCalledWith(event);
+        expect(amqp.channel.ack).toHaveBeenCalledWith(message);
+    });
+    it('should nack a message it cannot parse', async ()=>{
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport();
+        await transport.connect();
+        await transport.bind('storage.#');
+        const message = {
+            content: Buffer.from('not json')
+        };
+        await amqp.channel.consume.mock.calls[0][1](message);
+        expect(amqp.channel.nack).toHaveBeenCalledWith(message, false, false);
+    });
+    it('should close the channel and the connection', async ()=>{
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport();
+        await transport.connect();
+        await transport.close();
+        expect(amqp.channel.close).toHaveBeenCalled();
+        expect(amqp.connection.close).toHaveBeenCalled();
+        expect(transport.isReady()).toBe(false);
+    });
+    it('should reconnect when the channel dies while the connection is still up', async ()=>{
+        jest.useFakeTimers();
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport({
+            reconnectDelay: 10
+        });
+        await transport.connect();
+        listenerFor(amqp.channels[0], 'close')();
+        expect(transport.isReady()).toBe(false);
+        await jest.advanceTimersByTimeAsync(10);
+        expect(amqp.connect).toHaveBeenCalledTimes(2);
+        expect(transport.isReady()).toBe(true);
+        jest.useRealTimers();
+    });
+    it('should close the surviving connection rather than leak it on a channel failure', async ()=>{
+        jest.useFakeTimers();
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport({
+            reconnectDelay: 10
+        });
+        await transport.connect();
+        listenerFor(amqp.channels[0], 'close')();
+        await jest.advanceTimersByTimeAsync(10);
+        expect(amqp.connection.close).toHaveBeenCalledTimes(1);
+        jest.useRealTimers();
+    });
+    it('should schedule a single reconnect when the channel and the connection both close', async ()=>{
+        jest.useFakeTimers();
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport({
+            reconnectDelay: 10
+        });
+        await transport.connect();
+        listenerFor(amqp.channels[0], 'close')();
+        listenerFor(amqp.connection, 'close')();
+        await jest.advanceTimersByTimeAsync(10);
+        expect(amqp.connect).toHaveBeenCalledTimes(2);
+        jest.useRealTimers();
+    });
+    it('should re-bind every pattern onto the new channel after a reconnect', async ()=>{
+        jest.useFakeTimers();
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport({
+            exchange: 'ex',
+            queue: 'q',
+            reconnectDelay: 10
+        });
+        await transport.connect();
+        await transport.bind('storage.**');
+        listenerFor(amqp.channels[0], 'close')();
+        await jest.advanceTimersByTimeAsync(10);
+        expect(amqp.channels[1].bindQueue).toHaveBeenCalledWith('q', 'ex', 'storage.#');
+        expect(amqp.channels[1].consume).toHaveBeenCalledTimes(1);
+        jest.useRealTimers();
+    });
+    it('should ack an in-flight delivery on the channel it arrived on', async ()=>{
+        jest.useFakeTimers();
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport({
+            reconnectDelay: 10
+        });
+        await transport.connect();
+        await transport.bind('storage.#');
+        const deliver = amqp.channels[0].consume.mock.calls[0][1];
+        listenerFor(amqp.channels[0], 'close')();
+        await jest.advanceTimersByTimeAsync(10);
+        await deliver({
+            content: Buffer.from(JSON.stringify(buildEvent()))
+        });
+        expect(amqp.channels[0].ack).toHaveBeenCalled();
+        expect(amqp.channels[1].ack).not.toHaveBeenCalled();
+        jest.useRealTimers();
+    });
+    it('should let a later bind retry consuming after the broker rejects consume', async ()=>{
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport();
+        await transport.connect();
+        amqp.channel.consume.mockRejectedValueOnce(new Error('CHANNEL_ERROR'));
+        await expect(transport.bind('storage.#')).rejects.toThrow('CHANNEL_ERROR');
+        await transport.bind('auth.#');
+        expect(amqp.channel.consume).toHaveBeenCalledTimes(2);
+    });
+    it('should stop reconnecting once it has been closed', async ()=>{
+        jest.useFakeTimers();
+        const transport = new _rabbitmqtransportoptional.RabbitMqTransport({
+            reconnectDelay: 10
+        });
+        await transport.connect();
+        await transport.close();
+        listenerFor(amqp.channels[0], 'close')();
+        await jest.advanceTimersByTimeAsync(50);
+        expect(amqp.connect).toHaveBeenCalledTimes(1);
+        jest.useRealTimers();
+    });
+});