@zdavison/matador 2.0.1

package/dist/transport/multi/multi-transport.js

@@ -0,0 +1,184 @@
+import { AllTransportsFailedError } from '../../errors/index.js';
+/**
+ * Symbol key used to store the source transport on wrapped receipts.
+ */
+const SOURCE_TRANSPORT = Symbol('sourceTransport');
+/**
+ * Extracts the source transport from a tagged receipt.
+ */
+function getSourceTransport(receipt) {
+    return receipt[SOURCE_TRANSPORT];
+}
+/**
+ * Computes merged capabilities from multiple transports.
+ * Uses the most restrictive/conservative interpretation.
+ */
+function mergeCapabilities(transports) {
+    const primary = transports[0];
+    if (!primary) {
+        throw new Error('At least one transport is required');
+    }
+    // For multi-transport scenarios, we use primary's capabilities since that's
+    // what we'll use for subscriptions and most operations
+    return primary.capabilities;
+}
+/**
+ * A transport wrapper that manages multiple transports.
+ *
+ * Features:
+ * - All transports are connected upfront
+ * - send() tries transports in order until one succeeds (fallback behavior)
+ * - Specific transport can be selected via getDesiredBackend hook
+ * - Subscriptions are created on ALL transports
+ *
+ * @example
+ * ```typescript
+ * const transport = new MultiTransport(
+ *   { transports: [rabbitMQTransport, localTransport] },
+ *   { onEnqueueFallback: (ctx) => console.warn(`Fallback to ${ctx.nextTransport}`) },
+ * );
+ * ```
+ */
+export class MultiTransport {
+    name;
+    capabilities;
+    primary;
+    /** All available transports, in order of preference (primary first). */
+    transports;
+    /** Whether fallback to secondary transports is enabled. */
+    fallbackEnabled;
+    hooks;
+    connected = false;
+    constructor(config, hooks = {}) {
+        const primary = config.transports[0];
+        if (!primary) {
+            throw new Error('At least one transport is required');
+        }
+        this.primary = primary;
+        this.transports = config.transports;
+        this.fallbackEnabled = config.fallbackEnabled ?? true;
+        this.hooks = hooks;
+        this.name = `multi(${this.transports.map((t) => t.name).join(',')})`;
+        this.capabilities = mergeCapabilities(this.transports);
+    }
+    async connect() {
+        // Connect all transports in parallel
+        await Promise.all(this.transports.map((t) => t.connect()));
+        this.connected = true;
+    }
+    async disconnect() {
+        // Disconnect all transports in parallel
+        await Promise.all(this.transports.map((t) => t.disconnect()));
+        this.connected = false;
+    }
+    isConnected() {
+        // Consider connected if primary is connected
+        return this.connected && this.primary.isConnected();
+    }
+    async applyTopology(topology) {
+        // Apply topology to all transports so they're all ready
+        await Promise.all(this.transports.map((t) => t.applyTopology(topology)));
+    }
+    async send(queue, envelope, options) {
+        // Determine which transport to use
+        const selectedTransport = await this.selectTransport();
+        // If fallback is disabled, only use selected transport
+        if (!this.fallbackEnabled) {
+            return selectedTransport.send(queue, envelope, options);
+        }
+        // Build transport order: selected first, then others
+        const transportOrder = this.getTransportOrder(selectedTransport);
+        const errors = [];
+        for (let i = 0; i < transportOrder.length; i++) {
+            const transport = transportOrder[i];
+            try {
+                return await transport.send(queue, envelope, options);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                errors.push(err);
+                // Notify about fallback before trying next transport
+                const nextTransport = transportOrder[i + 1];
+                if (nextTransport && this.hooks.onEnqueueFallback) {
+                    this.hooks.onEnqueueFallback({
+                        envelope,
+                        queue,
+                        failedTransport: transport.name,
+                        nextTransport: nextTransport.name,
+                        error: err,
+                    });
+                }
+                // Continue to next transport
+            }
+        }
+        // All transports failed
+        throw new AllTransportsFailedError(queue, errors);
+    }
+    /**
+     * Selects the transport to use based on the getDesiredBackend hook.
+     */
+    async selectTransport() {
+        if (!this.hooks.getDesiredBackend) {
+            return this.primary;
+        }
+        try {
+            const desiredBackend = await this.hooks.getDesiredBackend();
+            if (!desiredBackend) {
+                return this.primary;
+            }
+            const selected = this.transports.find((t) => t.name === desiredBackend);
+            if (selected) {
+                return selected;
+            }
+            // Desired backend not found, use primary
+            return this.primary;
+        }
+        catch {
+            // Hook threw, use primary
+            return this.primary;
+        }
+    }
+    /**
+     * Returns transports in order, with the selected transport first.
+     */
+    getTransportOrder(selected) {
+        if (selected === this.primary) {
+            return this.transports;
+        }
+        // Put selected first, then the rest (excluding selected)
+        return [selected, ...this.transports.filter((t) => t !== selected)];
+    }
+    async subscribe(queue, handler, options) {
+        // Subscribe on ALL transports so messages are processed regardless of
+        // which transport they were enqueued to
+        const subscriptions = await Promise.all(this.transports.map((transport) => {
+            // Wrap handler to tag receipts with source transport
+            const wrappedHandler = (envelope, receipt) => {
+                const taggedReceipt = Object.assign(receipt, {
+                    [SOURCE_TRANSPORT]: transport,
+                });
+                return handler(envelope, taggedReceipt);
+            };
+            return transport.subscribe(queue, wrappedHandler, options);
+        }));
+        return {
+            unsubscribe: async () => {
+                await Promise.all(subscriptions.map((s) => s.unsubscribe()));
+            },
+            get isActive() {
+                return subscriptions.some((s) => s.isActive);
+            },
+        };
+    }
+    async complete(receipt) {
+        const transport = getSourceTransport(receipt) ?? this.primary;
+        return transport.complete(receipt);
+    }
+    async sendToDeadLetter(receipt, dlqName, envelope, reason) {
+        const transport = getSourceTransport(receipt) ?? this.primary;
+        if (transport.sendToDeadLetter) {
+            return transport.sendToDeadLetter(receipt, dlqName, envelope, reason);
+        }
+        throw new Error('Transport does not support dead letter routing');
+    }
+}

package/dist/transport/multi/multi-transport.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=multi-transport.test.d.ts.map

package/dist/transport/multi/multi-transport.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-transport.test.d.ts","sourceRoot":"","sources":["../../../src/transport/multi/multi-transport.test.ts"],"names":[],"mappings":""}

package/dist/transport/multi/multi-transport.test.js

@@ -0,0 +1,236 @@
+import { beforeEach, describe, expect, it, mock } from 'bun:test';
+import { createEnvelope } from '../../types/index.js';
+import { LocalTransport } from '../local/local-transport.js';
+import { MultiTransport } from './multi-transport.js';
+describe('MultiTransport', () => {
+    let primary;
+    let secondary;
+    let transport;
+    beforeEach(() => {
+        primary = new LocalTransport();
+        secondary = new LocalTransport();
+        transport = new MultiTransport({
+            transports: [primary, secondary],
+        });
+    });
+    describe('constructor', () => {
+        it('should throw if no transports provided', () => {
+            expect(() => new MultiTransport({ transports: [] })).toThrow('At least one transport is required');
+        });
+        it('should set name based on transport names', () => {
+            expect(transport.name).toBe('multi(local,local)');
+        });
+        it('should use primary transport capabilities', () => {
+            expect(transport.capabilities).toBe(primary.capabilities);
+        });
+        it('should expose primary transport', () => {
+            expect(transport.primary).toBe(primary);
+        });
+        it('should expose all transports', () => {
+            expect(transport.transports).toEqual([primary, secondary]);
+        });
+        it('should default fallbackEnabled to true', () => {
+            expect(transport.fallbackEnabled).toBe(true);
+        });
+        it('should allow disabling fallback', () => {
+            const noFallback = new MultiTransport({
+                transports: [primary, secondary],
+                fallbackEnabled: false,
+            });
+            expect(noFallback.fallbackEnabled).toBe(false);
+        });
+    });
+    describe('connection', () => {
+        it('should start disconnected', () => {
+            expect(transport.isConnected()).toBe(false);
+        });
+        it('should connect all transports', async () => {
+            await transport.connect();
+            expect(transport.isConnected()).toBe(true);
+            expect(primary.isConnected()).toBe(true);
+            expect(secondary.isConnected()).toBe(true);
+        });
+        it('should disconnect all transports', async () => {
+            await transport.connect();
+            await transport.disconnect();
+            expect(transport.isConnected()).toBe(false);
+            expect(primary.isConnected()).toBe(false);
+            expect(secondary.isConnected()).toBe(false);
+        });
+    });
+    describe('topology', () => {
+        it('should apply topology to all transports', async () => {
+            const topology = {
+                namespace: 'test',
+                queues: [{ name: 'events' }],
+                deadLetter: {
+                    unhandled: { enabled: true },
+                    undeliverable: { enabled: true },
+                },
+                retry: {
+                    enabled: true,
+                    defaultDelayMs: 1000,
+                    maxDelayMs: 30000,
+                },
+            };
+            await transport.connect();
+            await transport.applyTopology(topology);
+            // Both transports should have the queue
+            expect(primary.getQueueSize('test.events')).toBe(0);
+            expect(secondary.getQueueSize('test.events')).toBe(0);
+        });
+    });
+    describe('send - primary success', () => {
+        beforeEach(async () => {
+            await transport.connect();
+        });
+        it('should send to primary transport when it succeeds', async () => {
+            const envelope = createTestEnvelope();
+            await transport.send('test-queue', envelope);
+            expect(primary.getQueueSize('test-queue')).toBe(1);
+            expect(secondary.getQueueSize('test-queue')).toBe(0);
+        });
+        it('should not call onEnqueueFallback when primary succeeds', async () => {
+            const onEnqueueFallback = mock(() => { });
+            const transportWithCallback = new MultiTransport({ transports: [primary, secondary] }, { onEnqueueFallback });
+            await transportWithCallback.connect();
+            const envelope = createTestEnvelope();
+            await transportWithCallback.send('test-queue', envelope);
+            expect(onEnqueueFallback).not.toHaveBeenCalled();
+        });
+    });
+    describe('send - fallback', () => {
+        beforeEach(async () => {
+            await transport.connect();
+        });
+        it('should fallback when primary fails', async () => {
+            // Make primary fail
+            await primary.disconnect();
+            const envelope = createTestEnvelope();
+            await transport.send('test-queue', envelope);
+            expect(secondary.getQueueSize('test-queue')).toBe(1);
+        });
+        it('should call onEnqueueFallback when fallback is used', async () => {
+            const fallbackContexts = [];
+            const transportWithCallback = new MultiTransport({ transports: [primary, secondary] }, { onEnqueueFallback: (ctx) => fallbackContexts.push(ctx) });
+            await transportWithCallback.connect();
+            // Make primary fail
+            await primary.disconnect();
+            const envelope = createTestEnvelope();
+            await transportWithCallback.send('test-queue', envelope);
+            expect(fallbackContexts).toHaveLength(1);
+            const ctx = fallbackContexts[0];
+            expect(ctx.failedTransport).toBe('local');
+            expect(ctx.nextTransport).toBe('local');
+            expect(ctx.queue).toBe('test-queue');
+            expect(ctx.envelope).toBe(envelope);
+            expect(ctx.error.message).toContain('is not connected');
+        });
+        it('should throw when all transports fail', async () => {
+            await primary.disconnect();
+            await secondary.disconnect();
+            const envelope = createTestEnvelope();
+            await expect(transport.send('test-queue', envelope)).rejects.toThrow('All transports failed');
+        });
+        it('should try transports in order', async () => {
+            const third = new LocalTransport();
+            const multiTransport = new MultiTransport({
+                transports: [primary, secondary, third],
+            });
+            await multiTransport.connect();
+            // Make primary and secondary fail
+            await primary.disconnect();
+            await secondary.disconnect();
+            const envelope = createTestEnvelope();
+            await multiTransport.send('test-queue', envelope);
+            expect(third.getQueueSize('test-queue')).toBe(1);
+        });
+        it('should not fallback when fallbackEnabled is false', async () => {
+            const noFallback = new MultiTransport({
+                transports: [primary, secondary],
+                fallbackEnabled: false,
+            });
+            await noFallback.connect();
+            // Make primary fail
+            await primary.disconnect();
+            const envelope = createTestEnvelope();
+            await expect(noFallback.send('test-queue', envelope)).rejects.toThrow('is not connected');
+            // Secondary should not have received the message
+            expect(secondary.getQueueSize('test-queue')).toBe(0);
+        });
+        it('should send to primary when fallbackEnabled is false and primary succeeds', async () => {
+            const noFallback = new MultiTransport({
+                transports: [primary, secondary],
+                fallbackEnabled: false,
+            });
+            await noFallback.connect();
+            const envelope = createTestEnvelope();
+            await noFallback.send('test-queue', envelope);
+            expect(primary.getQueueSize('test-queue')).toBe(1);
+            expect(secondary.getQueueSize('test-queue')).toBe(0);
+        });
+    });
+    describe('subscribe', () => {
+        beforeEach(async () => {
+            await transport.connect();
+        });
+        it('should receive messages from primary transport', async () => {
+            const receivedMessages = [];
+            await transport.subscribe('test-queue', async (envelope) => {
+                receivedMessages.push(envelope);
+            });
+            // Send directly to primary (simulating normal operation)
+            await primary.send('test-queue', createTestEnvelope());
+            expect(receivedMessages).toHaveLength(1);
+        });
+        it('should receive messages that fell back to secondary transport', async () => {
+            const receivedMessages = [];
+            // Subscribe through MultiTransport
+            await transport.subscribe('test-queue', async (envelope) => {
+                receivedMessages.push(envelope);
+            });
+            // Make primary fail for sends
+            await primary.disconnect();
+            // Send through MultiTransport - should fall back to secondary
+            const envelope = createTestEnvelope();
+            await transport.send('test-queue', envelope);
+            // Message went to secondary transport, subscriber should still receive it
+            expect(receivedMessages).toHaveLength(1);
+            expect(receivedMessages[0].id).toBe(envelope.id);
+        });
+    });
+    describe('complete', () => {
+        beforeEach(async () => {
+            await transport.connect();
+        });
+        it('should complete using primary transport', async () => {
+            await primary.send('test-queue', createTestEnvelope());
+            const received = await primary.receiveOne('test-queue');
+            expect(received).not.toBeNull();
+            await transport.complete(received.receipt);
+            expect(primary.getCompleted()).toHaveLength(1);
+        });
+    });
+    describe('sendToDeadLetter', () => {
+        beforeEach(async () => {
+            await transport.connect();
+        });
+        it('should send to dead letter using primary transport', async () => {
+            const envelope = createTestEnvelope();
+            await primary.send('test-queue', envelope);
+            const received = await primary.receiveOne('test-queue');
+            expect(received).not.toBeNull();
+            await transport.sendToDeadLetter(received.receipt, 'dlq', envelope, 'test error');
+            expect(primary.getQueueSize('test-queue')).toBe(0);
+            expect(primary.getQueueSize('test-queue.dlq')).toBe(1);
+        });
+    });
+});
+function createTestEnvelope() {
+    return createEnvelope({
+        eventKey: 'test.event',
+        targetSubscriber: 'test-subscriber',
+        data: { test: 'data' },
+        importance: 'should-investigate',
+    });
+}

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

@@ -0,0 +1,73 @@
+import { type Logger } from '../../hooks/index.js';
+import type { Topology } from '../../topology/types.js';
+import type { Envelope } from '../../types/index.js';
+import type { TransportCapabilities } from '../capabilities.js';
+import { type ConnectionManagerConfig } from '../connection-manager.js';
+import type { MessageHandler, MessageReceipt, SendOptions, SubscribeOptions, Subscription, Transport } from '../transport.js';
+/**
+ * Configuration options for the RabbitMQ transport.
+ */
+export interface RabbitMQTransportConfig {
+    /** RabbitMQ connection URL */
+    readonly url: string;
+    /** Connection manager configuration */
+    readonly connection?: Partial<ConnectionManagerConfig> | undefined;
+    /** Use quorum queues for durability (default: true) */
+    readonly quorumQueues?: boolean | undefined;
+    /** Default prefetch count per consumer (default: 10) */
+    readonly defaultPrefetch?: number | undefined;
+    /** Enable the delayed message exchange plugin if available (default: true) */
+    readonly enableDelayedMessages?: boolean | undefined;
+    /** Logger for transport events (defaults to console) */
+    readonly logger?: Logger | undefined;
+}
+/**
+ * RabbitMQ transport implementation using amqplib.
+ */
+export declare class RabbitMQTransport implements Transport {
+    readonly name = "rabbitmq";
+    private _capabilities;
+    get capabilities(): TransportCapabilities;
+    private connection;
+    private publishChannel;
+    private readonly connectionManager;
+    private readonly queueChannels;
+    private topology;
+    private readonly codec;
+    private readonly config;
+    private readonly logger;
+    private delayedExchangeAvailable;
+    constructor(config: RabbitMQTransportConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    applyTopology(topology: Topology): Promise<void>;
+    send(queue: string, envelope: Envelope, options?: SendOptions): Promise<Transport['name']>;
+    subscribe(queue: string, handler: MessageHandler, options?: SubscribeOptions): Promise<Subscription>;
+    complete(receipt: MessageReceipt): Promise<void>;
+    sendToDeadLetter(receipt: MessageReceipt, dlqName: string, envelope: Envelope, reason: string): Promise<void>;
+    /**
+     * Gets or creates a dedicated channel for a queue subscription.
+     *
+     * We create separate channels per subscribed queue to enable independent
+     * prefetch/concurrency control.
+     */
+    private getOrCreateQueueChannel;
+    private doConnect;
+    private doDisconnect;
+    private setupDelayedExchange;
+    private assertWorkQueue;
+    private assertRetryQueue;
+    private assertDeadLetterQueues;
+    private getMainExchangeName;
+    private getDLXExchangeName;
+    private getDelayedExchangeName;
+    private getAttemptNumber;
+    /**
+     * Gets the native delivery count for poison message detection.
+     * This tracks how many times the message was delivered without acknowledgment,
+     * which helps detect crash loops.
+     */
+    private getDeliveryCount;
+}
+//# sourceMappingURL=rabbitmq-transport.d.ts.map

package/dist/transport/rabbitmq/rabbitmq-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rabbitmq-transport.d.ts","sourceRoot":"","sources":["../../../src/transport/rabbitmq/rabbitmq-transport.ts"],"names":[],"mappings":"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"}