@zdavison/matador 2.0.1

package/src/transport/multi/multi-transport.test.ts

@@ -0,0 +1,320 @@
+import { beforeEach, describe, expect, it, mock } from 'bun:test';
+import type { TransportFallbackContext } from '../../hooks/index.js';
+import type { Topology } from '../../topology/types.js';
+import { createEnvelope } from '../../types/index.js';
+import { LocalTransport } from '../local/local-transport.js';
+import { MultiTransport } from './multi-transport.js';
+
+describe('MultiTransport', () => {
+  let primary: LocalTransport;
+  let secondary: LocalTransport;
+  let transport: MultiTransport;
+
+  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: 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: TransportFallbackContext[] = [];
+      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: unknown[] = [];
+
+      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: unknown[] = [];
+
+      // 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] as { id: string }).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/src/transport/multi/multi-transport.ts

@@ -0,0 +1,294 @@
+import { AllTransportsFailedError } from '../../errors/index.js';
+import type { TransportFallbackContext } 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 {
+  MessageHandler,
+  MessageReceipt,
+  SendOptions,
+  SubscribeOptions,
+  Subscription,
+  Transport,
+} from '../transport.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: MessageReceipt): Transport | undefined {
+  return (receipt as unknown as Record<symbol, Transport | undefined>)[
+    SOURCE_TRANSPORT
+  ];
+}
+
+/**
+ * Configuration for MultiTransport.
+ */
+export interface MultiTransportConfig {
+  /**
+   * Ordered list of transports.
+   * First transport is primary, rest are used as fallbacks when primary fails
+   * (if fallback is enabled), or can be explicitly selected via the getDesiredBackend hook.
+   */
+  readonly transports: readonly Transport[];
+
+  /**
+   * Whether to automatically try fallback transports when the primary/selected fails.
+   * When true (default), send() will try each transport in order until one succeeds.
+   * When false, send() will only use the selected transport and throw immediately on failure.
+   *
+   * @default true
+   */
+  readonly fallbackEnabled?: boolean;
+}
+
+/**
+ * Hooks for MultiTransport.
+ */
+export interface MultiTransportHooks {
+  /**
+   * Hook to dynamically select which backend to use.
+   * Return the transport name (e.g., 'local', 'rabbitmq') or undefined to use primary.
+   *
+   * @example
+   * ```typescript
+   * getDesiredBackend: async () => {
+   *   if (process.env.SANDBOX === 'true') return 'local';
+   *   const backend = await runtimeConfig.get('events.backend');
+   *   return backend || 'rabbitmq';
+   * }
+   * ```
+   */
+  readonly getDesiredBackend?: () =>
+    | string
+    | undefined
+    | Promise<string | undefined>;
+
+  /**
+   * Called when a fallback transport is used successfully after the selected one fails.
+   * Only called when fallbackEnabled is true.
+   */
+  readonly onEnqueueFallback?: (context: TransportFallbackContext) => void;
+}
+
+/**
+ * Computes merged capabilities from multiple transports.
+ * Uses the most restrictive/conservative interpretation.
+ */
+function mergeCapabilities(
+  transports: readonly Transport[],
+): TransportCapabilities {
+  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 implements Transport {
+  readonly name: string;
+  readonly capabilities: TransportCapabilities;
+  readonly primary: Transport;
+
+  /** All available transports, in order of preference (primary first). */
+  readonly transports: readonly Transport[];
+
+  /** Whether fallback to secondary transports is enabled. */
+  readonly fallbackEnabled: boolean;
+
+  private readonly hooks: MultiTransportHooks;
+  private connected = false;
+
+  constructor(config: MultiTransportConfig, hooks: MultiTransportHooks = {}) {
+    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(): Promise<void> {
+    // Connect all transports in parallel
+    await Promise.all(this.transports.map((t) => t.connect()));
+    this.connected = true;
+  }
+
+  async disconnect(): Promise<void> {
+    // Disconnect all transports in parallel
+    await Promise.all(this.transports.map((t) => t.disconnect()));
+    this.connected = false;
+  }
+
+  isConnected(): boolean {
+    // Consider connected if primary is connected
+    return this.connected && this.primary.isConnected();
+  }
+
+  async applyTopology(topology: Topology): Promise<void> {
+    // Apply topology to all transports so they're all ready
+    await Promise.all(this.transports.map((t) => t.applyTopology(topology)));
+  }
+
+  async send(
+    queue: string,
+    envelope: Envelope,
+    options?: SendOptions,
+  ): Promise<Transport['name']> {
+    // 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: Error[] = [];
+
+    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.
+   */
+  private async selectTransport(): Promise<Transport> {
+    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.
+   */
+  private getTransportOrder(selected: Transport): readonly Transport[] {
+    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: string,
+    handler: MessageHandler,
+    options?: SubscribeOptions,
+  ): Promise<Subscription> {
+    // 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: MessageHandler = (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: MessageReceipt): Promise<void> {
+    const transport = getSourceTransport(receipt) ?? this.primary;
+    return transport.complete(receipt);
+  }
+
+  async sendToDeadLetter(
+    receipt: MessageReceipt,
+    dlqName: string,
+    envelope: Envelope,
+    reason: string,
+  ): Promise<void> {
+    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');
+  }
+}