@zdavison/matador 2.0.1

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

@@ -0,0 +1,262 @@
+import { beforeEach, describe, expect, it } from 'bun:test';
+import type { Topology } from '../../topology/types.js';
+import { createEnvelope } from '../../types/index.js';
+import { LocalTransport } from './local-transport.js';
+
+describe('LocalTransport', () => {
+  let transport: LocalTransport;
+
+  beforeEach(() => {
+    transport = new LocalTransport();
+  });
+
+  describe('connection', () => {
+    it('should start disconnected', () => {
+      expect(transport.isConnected()).toBe(false);
+    });
+
+    it('should connect successfully', async () => {
+      await transport.connect();
+      expect(transport.isConnected()).toBe(true);
+    });
+
+    it('should disconnect successfully', async () => {
+      await transport.connect();
+      await transport.disconnect();
+      expect(transport.isConnected()).toBe(false);
+    });
+  });
+
+  describe('capabilities', () => {
+    it('should report correct capabilities', () => {
+      expect(transport.name).toBe('local');
+      expect(transport.capabilities.deliveryModes).toContain('at-least-once');
+      expect(transport.capabilities.delayedMessages).toBe(true);
+      expect(transport.capabilities.deadLetterRouting).toBe('manual');
+    });
+  });
+
+  describe('send and receive', () => {
+    beforeEach(async () => {
+      await transport.connect();
+    });
+
+    it('should throw when sending while disconnected', async () => {
+      await transport.disconnect();
+      const envelope = createTestEnvelope();
+
+      await expect(transport.send('test-queue', envelope)).rejects.toThrow(
+        'is not connected',
+      );
+    });
+
+    it('should send and receive a message', async () => {
+      const envelope = createTestEnvelope();
+      await transport.send('test-queue', envelope);
+
+      const received = await transport.receiveOne('test-queue');
+      expect(received).not.toBeNull();
+      expect(received?.envelope.id).toBe(envelope.id);
+      expect(received?.envelope.data).toEqual({ test: 'data' });
+    });
+
+    it('should track queue size correctly', async () => {
+      expect(transport.getQueueSize('test-queue')).toBe(0);
+
+      await transport.send('test-queue', createTestEnvelope());
+      expect(transport.getQueueSize('test-queue')).toBe(1);
+
+      await transport.send('test-queue', createTestEnvelope());
+      expect(transport.getQueueSize('test-queue')).toBe(2);
+    });
+
+    it('should complete messages and remove from queue', async () => {
+      const envelope = createTestEnvelope();
+      await transport.send('test-queue', envelope);
+
+      const received = await transport.receiveOne('test-queue');
+      expect(received).not.toBeNull();
+
+      await transport.complete(received!.receipt);
+
+      expect(transport.getQueueSize('test-queue')).toBe(0);
+      expect(transport.getCompleted()).toHaveLength(1);
+    });
+
+    it('should return null when queue is empty', async () => {
+      const received = await transport.receiveOne('empty-queue');
+      expect(received).toBeNull();
+    });
+  });
+
+  describe('subscriptions', () => {
+    beforeEach(async () => {
+      await transport.connect();
+    });
+
+    it('should throw when subscribing while disconnected', async () => {
+      await transport.disconnect();
+
+      await expect(
+        transport.subscribe('test-queue', async () => {}),
+      ).rejects.toThrow('is not connected');
+    });
+
+    it('should deliver messages to subscribers', async () => {
+      const receivedMessages: unknown[] = [];
+
+      await transport.subscribe('test-queue', async (envelope) => {
+        receivedMessages.push(envelope);
+      });
+
+      const envelope = createTestEnvelope();
+      await transport.send('test-queue', envelope);
+
+      expect(receivedMessages).toHaveLength(1);
+      expect((receivedMessages[0] as { id: string }).id).toBe(envelope.id);
+    });
+
+    it('should deliver pending messages when subscribing', async () => {
+      const envelope = createTestEnvelope();
+      await transport.send('test-queue', envelope);
+
+      const receivedMessages: unknown[] = [];
+      await transport.subscribe('test-queue', async (env) => {
+        receivedMessages.push(env);
+      });
+
+      expect(receivedMessages).toHaveLength(1);
+    });
+
+    it('should stop delivering after unsubscribe', async () => {
+      const receivedMessages: unknown[] = [];
+
+      const subscription = await transport.subscribe(
+        'test-queue',
+        async (envelope) => {
+          receivedMessages.push(envelope);
+        },
+      );
+
+      await transport.send('test-queue', createTestEnvelope());
+      expect(receivedMessages).toHaveLength(1);
+
+      await subscription.unsubscribe();
+      expect(subscription.isActive).toBe(false);
+    });
+  });
+
+  describe('dead letter queue', () => {
+    beforeEach(async () => {
+      await transport.connect();
+    });
+
+    it('should send messages to dead letter queue', async () => {
+      const envelope = createTestEnvelope();
+      await transport.send('test-queue', envelope);
+
+      const received = await transport.receiveOne('test-queue');
+      expect(received).not.toBeNull();
+
+      await transport.sendToDeadLetter(
+        received!.receipt,
+        'dlq',
+        envelope,
+        'test error',
+      );
+
+      expect(transport.getQueueSize('test-queue')).toBe(0);
+      expect(transport.getQueueSize('test-queue.dlq')).toBe(1);
+    });
+  });
+
+  describe('topology', () => {
+    it('should apply topology and create queues', async () => {
+      const topology: Topology = {
+        namespace: 'test',
+        queues: [{ name: 'events' }, { name: 'notifications' }],
+        deadLetter: {
+          unhandled: { enabled: true },
+          undeliverable: { enabled: true },
+        },
+        retry: {
+          enabled: true,
+          defaultDelayMs: 1000,
+          maxDelayMs: 30000,
+        },
+      };
+
+      await transport.connect();
+      await transport.applyTopology(topology);
+
+      // Queues should be created
+      expect(transport.getQueueSize('test.events')).toBe(0);
+      expect(transport.getQueueSize('test.notifications')).toBe(0);
+    });
+  });
+
+  describe('clear', () => {
+    it('should reset all state', async () => {
+      await transport.connect();
+      await transport.send('test-queue', createTestEnvelope());
+
+      const received = await transport.receiveOne('test-queue');
+      await transport.complete(received!.receipt);
+
+      transport.clear();
+
+      expect(transport.getQueueSize('test-queue')).toBe(0);
+      expect(transport.getCompleted()).toHaveLength(0);
+    });
+  });
+
+  describe('delayed messages', () => {
+    beforeEach(async () => {
+      await transport.connect();
+    });
+
+    it('should return immediately and delay message delivery', async () => {
+      const envelope = createTestEnvelope();
+
+      // Send returns immediately (non-blocking)
+      await transport.send('test-queue', envelope, {
+        delay: 100,
+      });
+
+      // Message should not be in queue immediately
+      expect(transport.getQueueSize('test-queue')).toBe(0);
+
+      // Wait for the delay to pass
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // Message should now be in queue
+      expect(transport.getQueueSize('test-queue')).toBe(1);
+    });
+
+    it('should cancel delayed messages on disconnect', async () => {
+      const envelope = createTestEnvelope();
+
+      await transport.send('test-queue', envelope, {
+        delay: 100,
+      });
+
+      // Disconnect before delay expires
+      await transport.disconnect();
+
+      // Wait past the original delay
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // Message should never have been delivered
+      expect(transport.getQueueSize('test-queue')).toBe(0);
+    });
+  });
+});
+
+function createTestEnvelope() {
+  return createEnvelope({
+    eventKey: 'test.event',
+    targetSubscriber: 'test-subscriber',
+    data: { test: 'data' },
+    importance: 'should-investigate',
+  });
+}

package/src/transport/local/local-transport.ts

@@ -0,0 +1,327 @@
+import { TransportNotConnectedError } from '../../errors/index.js';
+import { type Logger, consoleLogger } 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';
+
+/**
+ * Capabilities of the LocalTransport.
+ */
+const localCapabilities: TransportCapabilities = {
+  deliveryModes: ['at-least-once', 'at-most-once'],
+  delayedMessages: true, // Implemented with setTimeout
+  deadLetterRouting: 'manual',
+  attemptTracking: false,
+  concurrencyModel: 'none',
+  ordering: 'queue',
+  priorities: false,
+};
+
+/**
+ * Internal message structure for the local queue.
+ */
+interface QueuedMessage {
+  readonly envelope: Envelope;
+  readonly id: string;
+  completed: boolean;
+}
+
+/**
+ * Internal subscription structure.
+ */
+interface ActiveSubscription {
+  readonly handler: MessageHandler;
+  readonly options: SubscribeOptions;
+  active: boolean;
+}
+
+/**
+ * Local in-memory transport for testing and fallback.
+ * Messages are stored in memory and delivered synchronously.
+ */
+export class LocalTransport implements Transport {
+  readonly name = 'local';
+  readonly capabilities = localCapabilities;
+
+  private connected = false;
+  private readonly queues = new Map<string, QueuedMessage[]>();
+  private readonly subscriptions = new Map<string, ActiveSubscription[]>();
+  private readonly completedMessages: MessageReceipt[] = [];
+  private readonly delayedTimers = new Set<ReturnType<typeof setTimeout>>();
+  private messageIdCounter = 0;
+  private readonly logger: Logger;
+
+  constructor(logger?: Logger) {
+    this.logger = logger ?? consoleLogger;
+  }
+
+  async connect(): Promise<void> {
+    this.connected = true;
+  }
+
+  async disconnect(): Promise<void> {
+    // Cancel all delayed message timers
+    for (const timer of this.delayedTimers) {
+      clearTimeout(timer);
+    }
+    this.delayedTimers.clear();
+
+    // Deactivate all subscriptions
+    for (const subs of this.subscriptions.values()) {
+      for (const sub of subs) {
+        sub.active = false;
+      }
+    }
+
+    this.connected = false;
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  async applyTopology(topology: Topology): Promise<void> {
+    if (!this.connected) {
+      throw new TransportNotConnectedError(this.name, 'applyTopology');
+    }
+
+    // Initialize queues for the topology.
+    // Note: Retry queues are not pre-created here because LocalTransport handles
+    // retries by re-enqueueing messages with a delay to the original queue, matching
+    // how the pipeline schedules retries via transport.send() with a delay option.
+    for (const queueDef of topology.queues) {
+      const queueName = `${topology.namespace}.${queueDef.name}`;
+      if (!this.queues.has(queueName)) {
+        this.queues.set(queueName, []);
+      }
+    }
+  }
+
+  async send(
+    queue: string,
+    envelope: Envelope,
+    options?: SendOptions,
+  ): Promise<Transport['name']> {
+    if (!this.connected) {
+      throw new TransportNotConnectedError(this.name, 'send');
+    }
+
+    // Handle delayed messages (non-blocking, like real transports)
+    if (options?.delay !== undefined && options.delay > 0) {
+      this.scheduleDelayedMessage(queue, envelope, options.delay);
+      return this.name;
+    }
+
+    await this.enqueue(queue, envelope);
+    return this.name;
+  }
+
+  /**
+   * Schedules a message for delayed delivery.
+   * Returns immediately (non-blocking) to match real transport behavior.
+   */
+  private scheduleDelayedMessage(
+    queue: string,
+    envelope: Envelope,
+    delayMs: number,
+  ): void {
+    const timer = setTimeout(() => {
+      this.delayedTimers.delete(timer);
+      // Fire and forget - errors are logged in enqueue/deliverToSubscribers
+      this.enqueue(queue, envelope).catch((error) => {
+        this.logger.error(
+          '[Matador] 🔴 Failed to enqueue delayed message',
+          error,
+        );
+      });
+    }, delayMs);
+    this.delayedTimers.add(timer);
+  }
+
+  private async enqueue(queue: string, envelope: Envelope): Promise<void> {
+    const messages = this.getOrCreateQueue(queue);
+    const messageId = `${++this.messageIdCounter}`;
+
+    const queuedMessage: QueuedMessage = {
+      envelope,
+      id: messageId,
+      completed: false,
+    };
+
+    messages.push(queuedMessage);
+
+    // Deliver to any active subscriptions
+    await this.deliverToSubscribers(queue, queuedMessage);
+  }
+
+  private async deliverToSubscribers(
+    queue: string,
+    message: QueuedMessage,
+  ): Promise<void> {
+    const subs = this.subscriptions.get(queue);
+    if (!subs) return;
+
+    for (const sub of subs) {
+      if (!sub.active || message.completed) continue;
+
+      const receipt: MessageReceipt = {
+        handle: message,
+        redelivered: false,
+        attemptNumber: message.envelope.docket.attempts,
+        deliveryCount: message.envelope.docket.attempts,
+        sourceQueue: queue,
+        sourceTransport: this.name,
+      };
+
+      try {
+        await sub.handler(message.envelope, receipt);
+      } catch (error) {
+        // Handler errors should be caught in the pipeline
+        this.logger.error('🔴 Handler error in message processing', error);
+      }
+    }
+  }
+
+  async subscribe(
+    queue: string,
+    handler: MessageHandler,
+    options: SubscribeOptions = {},
+  ): Promise<Subscription> {
+    if (!this.connected) {
+      throw new TransportNotConnectedError(this.name, 'subscribe');
+    }
+
+    const subscription: ActiveSubscription = {
+      handler,
+      options,
+      active: true,
+    };
+
+    const subs = this.subscriptions.get(queue) ?? [];
+    subs.push(subscription);
+    this.subscriptions.set(queue, subs);
+
+    // Deliver any pending messages
+    const messages = this.queues.get(queue) ?? [];
+    for (const message of messages) {
+      if (message.completed) continue;
+      await this.deliverToSubscribers(queue, message);
+    }
+
+    return {
+      unsubscribe: async () => {
+        subscription.active = false;
+        const remaining = subs.filter((s) => s !== subscription);
+        if (remaining.length > 0) {
+          this.subscriptions.set(queue, remaining);
+        } else {
+          this.subscriptions.delete(queue);
+        }
+      },
+      get isActive() {
+        return subscription.active;
+      },
+    };
+  }
+
+  async complete(receipt: MessageReceipt): Promise<void> {
+    const message = receipt.handle as QueuedMessage;
+    message.completed = true;
+    this.completedMessages.push(receipt);
+  }
+
+  async sendToDeadLetter(
+    receipt: MessageReceipt,
+    dlqName: string,
+    envelope: Envelope,
+    _reason: string,
+  ): Promise<void> {
+    const dlqQueueName = `${receipt.sourceQueue}.${dlqName}`;
+    await this.enqueue(dlqQueueName, envelope);
+    await this.complete(receipt);
+  }
+
+  // Test helpers
+
+  /**
+   * Gets the current size of a queue.
+   */
+  getQueueSize(queue: string): number {
+    const messages = this.queues.get(queue);
+    if (!messages) return 0;
+    return messages.filter((m) => !m.completed).length;
+  }
+
+  /**
+   * Gets all completed message receipts.
+   */
+  getCompleted(): readonly MessageReceipt[] {
+    return this.completedMessages;
+  }
+
+  /**
+   * Gets pending (uncompleted) messages from a queue.
+   */
+  getPendingMessages(queue: string): readonly Envelope[] {
+    const messages = this.queues.get(queue);
+    if (!messages) return [];
+    return messages.filter((m) => !m.completed).map((m) => m.envelope);
+  }
+
+  /**
+   * Clears all state (for test isolation).
+   */
+  clear(): void {
+    this.queues.clear();
+    this.subscriptions.clear();
+    this.completedMessages.length = 0;
+    this.messageIdCounter = 0;
+
+    for (const timer of this.delayedTimers) {
+      clearTimeout(timer);
+    }
+    this.delayedTimers.clear();
+  }
+
+  /**
+   * Receives one message from the queue without a subscription.
+   * Useful for testing.
+   */
+  async receiveOne(
+    queue: string,
+  ): Promise<{ envelope: Envelope; receipt: MessageReceipt } | null> {
+    const messages = this.queues.get(queue);
+    if (!messages) return null;
+
+    const pending = messages.find((m) => !m.completed);
+    if (!pending) return null;
+
+    const receipt: MessageReceipt = {
+      handle: pending,
+      redelivered: false,
+      attemptNumber: pending.envelope.docket.attempts,
+      deliveryCount: pending.envelope.docket.attempts,
+      sourceQueue: queue,
+      sourceTransport: this.name,
+    };
+
+    return { envelope: pending.envelope, receipt };
+  }
+
+  private getOrCreateQueue(queue: string): QueuedMessage[] {
+    let messages = this.queues.get(queue);
+    if (!messages) {
+      messages = [];
+      this.queues.set(queue, messages);
+    }
+    return messages;
+  }
+}