@zdavison/matador 2.0.1

package/src/topology/types.ts

@@ -0,0 +1,109 @@
+/**
+ * Transport-agnostic topology definition.
+ * Matador owns the topology; transports translate and apply it.
+ */
+export interface Topology {
+  /** Namespace prefix for all queues */
+  readonly namespace: string;
+
+  /** Work queues for processing events */
+  readonly queues: readonly QueueDefinition[];
+
+  /** Dead-letter queue configuration */
+  readonly deadLetter: DeadLetterConfig;
+
+  /** Retry queue configuration */
+  readonly retry: RetryConfig;
+}
+
+/**
+ * Individual queue definition.
+ */
+export interface QueueDefinition {
+  /** Queue name (will be prefixed with namespace) */
+  readonly name: string;
+
+  /** Concurrency for this queue */
+  readonly concurrency?: number | undefined;
+
+  /** Consumer timeout in milliseconds */
+  readonly consumerTimeout?: number | undefined;
+
+  /** Enable priority support if transport allows */
+  readonly priorities?: boolean | undefined;
+
+  /**
+   * When true, the queue name is used exactly as provided without any
+   * modification. The namespace prefix will NOT be added, and no other
+   * transformations will be applied. Use this for referencing external
+   * queues that are not managed by Matador.
+   */
+  readonly exact?: boolean | undefined;
+}
+
+/**
+ * Dead-letter queue configuration.
+ */
+export interface DeadLetterConfig {
+  /** Unhandled events (schema mismatch) queue */
+  readonly unhandled: DeadLetterQueueConfig;
+
+  /** Undeliverable events (permanent failures) queue */
+  readonly undeliverable: DeadLetterQueueConfig;
+}
+
+/**
+ * Configuration for a specific dead-letter queue.
+ */
+export interface DeadLetterQueueConfig {
+  /** Whether this DLQ is enabled */
+  readonly enabled: boolean;
+
+  /** Maximum number of messages in the DLQ */
+  readonly maxLength?: number | undefined;
+}
+
+/**
+ * Retry queue configuration.
+ */
+export interface RetryConfig {
+  /** Enable retry queue with delay */
+  readonly enabled: boolean;
+
+  /** Default retry delay in milliseconds */
+  readonly defaultDelayMs: number;
+
+  /** Maximum retry delay in milliseconds */
+  readonly maxDelayMs: number;
+}
+
+/**
+ * Gets the fully qualified queue name with namespace prefix.
+ */
+export function getQualifiedQueueName(
+  namespace: string,
+  queueName: string,
+): string {
+  return `${namespace}.${queueName}`;
+}
+
+/**
+ * Gets the dead-letter queue name for a given queue.
+ */
+export function getDeadLetterQueueName(
+  namespace: string,
+  queueName: string,
+  dlqType: 'unhandled' | 'undeliverable',
+): string {
+  return `${namespace}.${queueName}.${dlqType}`;
+}
+
+/**
+ * Gets the retry queue name for a given queue.
+ */
+export function getRetryQueueName(
+  namespace: string,
+  queueName: string,
+): string {
+  return `${namespace}.${queueName}.retry`;
+}

package/src/transport/capabilities.ts

@@ -0,0 +1,88 @@
+import type { DeliveryMode } from '../types/index.js';
+
+/**
+ * Describes the native capabilities of a transport.
+ * Matador adapts its behavior based on these capabilities.
+ */
+export interface TransportCapabilities {
+  /**
+   * Delivery semantics the transport supports.
+   * - 'at-least-once': Ack after processing (may redeliver on failure)
+   * - 'at-most-once': Ack before processing (no redelivery, may lose messages)
+   */
+  readonly deliveryModes: readonly DeliveryMode[];
+
+  /**
+   * Transport can delay message delivery natively.
+   * - true: Use transport's native delay (BullMQ, RabbitMQ with plugin)
+   * - false: Matador handles via retry queue with TTL or external scheduler
+   */
+  readonly delayedMessages: boolean;
+
+  /**
+   * Transport can route failed messages to dead-letter queue natively.
+   * - 'native': Transport handles DL routing (RabbitMQ DLX)
+   * - 'manual': Matador must send() to DLQ then complete() original
+   * - 'none': No DL support, Matador logs and discards
+   */
+  readonly deadLetterRouting: 'native' | 'manual' | 'none';
+
+  /**
+   * Transport tracks delivery/attempt count natively.
+   * - true: Receipt includes accurate attemptNumber from transport
+   * - false: Matador tracks attempts in envelope.docket.attempts field
+   */
+  readonly attemptTracking: boolean;
+
+  /**
+   * How transport handles concurrency.
+   * - 'prefetch': Channel-based prefetch (RabbitMQ)
+   * - 'worker': Worker concurrency setting (BullMQ)
+   * - 'partition': Partition-based parallelism (Kafka)
+   * - 'none': No concurrency control (Memory)
+   */
+  readonly concurrencyModel: 'prefetch' | 'worker' | 'partition' | 'none';
+
+  /**
+   * Message ordering guarantees.
+   * - 'none': No ordering guarantee (most transports with multiple consumers)
+   * - 'queue': Ordered within queue (single consumer scenarios)
+   * - 'partition': Ordered within partition/key (Kafka)
+   */
+  readonly ordering: 'none' | 'queue' | 'partition';
+
+  /**
+   * Transport supports message priority.
+   * - true: Higher priority messages processed first
+   * - false: FIFO only
+   */
+  readonly priorities: boolean;
+}
+
+/**
+ * Checks if the transport supports a specific delivery mode.
+ */
+export function supportsDeliveryMode(
+  capabilities: TransportCapabilities,
+  mode: DeliveryMode,
+): boolean {
+  return capabilities.deliveryModes.includes(mode);
+}
+
+/**
+ * Checks if the transport supports native delayed messages.
+ */
+export function supportsDelayedMessages(
+  capabilities: TransportCapabilities,
+): boolean {
+  return capabilities.delayedMessages;
+}
+
+/**
+ * Checks if the transport has native dead-letter routing.
+ */
+export function hasNativeDeadLetter(
+  capabilities: TransportCapabilities,
+): boolean {
+  return capabilities.deadLetterRouting === 'native';
+}

package/src/transport/connection-manager.ts

@@ -0,0 +1,218 @@
+/**
+ * Connection state machine states.
+ */
+export type ConnectionState =
+  | { readonly status: 'disconnected' }
+  | { readonly status: 'connecting'; readonly attempt: number }
+  | { readonly status: 'connected' }
+  | {
+      readonly status: 'reconnecting';
+      readonly attempt: number;
+      readonly lastError: Error;
+    }
+  | { readonly status: 'failed'; readonly error: Error };
+
+/**
+ * Configuration for the connection manager.
+ */
+export interface ConnectionManagerConfig {
+  /** Maximum reconnection attempts before giving up (0 = infinite) */
+  readonly maxReconnectAttempts: number;
+
+  /** Initial delay between reconnection attempts (ms) */
+  readonly initialReconnectDelay: number;
+
+  /** Maximum delay between reconnection attempts (ms) */
+  readonly maxReconnectDelay: number;
+
+  /** Backoff multiplier for reconnection delay */
+  readonly backoffMultiplier: number;
+
+  /** Heartbeat interval for connection health (ms), optional */
+  readonly heartbeatInterval?: number;
+}
+
+/**
+ * Default configuration values.
+ */
+export const defaultConnectionConfig: ConnectionManagerConfig = {
+  maxReconnectAttempts: 0, // Infinite
+  initialReconnectDelay: 1000,
+  maxReconnectDelay: 30000,
+  backoffMultiplier: 2,
+};
+
+/**
+ * Callback for state change notifications.
+ */
+export type StateChangeCallback = (state: ConnectionState) => void;
+
+/**
+ * Function that performs the actual connection.
+ */
+export type ConnectFn = () => Promise<void>;
+
+/**
+ * Function that performs disconnection.
+ */
+export type DisconnectFn = () => Promise<void>;
+
+/**
+ * Manages connection lifecycle with automatic reconnection.
+ */
+export class ConnectionManager {
+  private _state: ConnectionState = { status: 'disconnected' };
+  private readonly listeners: Set<StateChangeCallback> = new Set();
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private readonly config: ConnectionManagerConfig;
+
+  constructor(
+    private readonly connectFn: ConnectFn,
+    private readonly disconnectFn: DisconnectFn,
+    config: Partial<ConnectionManagerConfig> = {},
+  ) {
+    this.config = { ...defaultConnectionConfig, ...config };
+  }
+
+  /**
+   * Current connection state.
+   */
+  get state(): ConnectionState {
+    return this._state;
+  }
+
+  /**
+   * Whether currently connected.
+   */
+  isConnected(): boolean {
+    return this._state.status === 'connected';
+  }
+
+  /**
+   * Register a callback for connection state changes.
+   */
+  onStateChange(callback: StateChangeCallback): () => void {
+    this.listeners.add(callback);
+    return () => this.listeners.delete(callback);
+  }
+
+  /**
+   * Attempt to establish connection.
+   */
+  async connect(): Promise<void> {
+    if (this._state.status === 'connected') {
+      return;
+    }
+
+    this.setState({ status: 'connecting', attempt: 1 });
+
+    try {
+      await this.connectFn();
+      this.setState({ status: 'connected' });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      await this.handleConnectionFailure(err, 1);
+    }
+  }
+
+  /**
+   * Gracefully disconnect.
+   */
+  async disconnect(): Promise<void> {
+    this.clearReconnectTimer();
+
+    if (this._state.status === 'disconnected') {
+      return;
+    }
+
+    try {
+      await this.disconnectFn();
+    } finally {
+      this.setState({ status: 'disconnected' });
+    }
+  }
+
+  /**
+   * Called by transport when connection is lost unexpectedly.
+   */
+  async handleConnectionLost(error: Error): Promise<void> {
+    if (this._state.status === 'disconnected') {
+      return;
+    }
+
+    this.setState({ status: 'reconnecting', attempt: 1, lastError: error });
+    await this.attemptReconnect(1);
+  }
+
+  /**
+   * Calculate delay for a given attempt using exponential backoff.
+   */
+  calculateDelay(attempt: number): number {
+    const delay =
+      this.config.initialReconnectDelay *
+      Math.pow(this.config.backoffMultiplier, attempt - 1);
+    return Math.min(delay, this.config.maxReconnectDelay);
+  }
+
+  private setState(state: ConnectionState): void {
+    this._state = state;
+    for (const listener of this.listeners) {
+      try {
+        listener(state);
+      } catch {
+        // Ignore listener errors
+      }
+    }
+  }
+
+  private async handleConnectionFailure(
+    error: Error,
+    attempt: number,
+  ): Promise<void> {
+    if (this.shouldGiveUp(attempt)) {
+      this.setState({ status: 'failed', error });
+      throw error;
+    }
+
+    this.setState({
+      status: 'reconnecting',
+      attempt: attempt + 1,
+      lastError: error,
+    });
+    await this.attemptReconnect(attempt + 1);
+  }
+
+  private shouldGiveUp(attempt: number): boolean {
+    return (
+      this.config.maxReconnectAttempts > 0 &&
+      attempt >= this.config.maxReconnectAttempts
+    );
+  }
+
+  private async attemptReconnect(attempt: number): Promise<void> {
+    const delay = this.calculateDelay(attempt);
+
+    await new Promise<void>((resolve) => {
+      this.reconnectTimer = setTimeout(resolve, delay);
+    });
+
+    if (this._state.status === 'disconnected') {
+      return;
+    }
+
+    try {
+      await this.connectFn();
+      this.setState({ status: 'connected' });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      await this.handleConnectionFailure(err, attempt);
+    }
+  }
+
+  private clearReconnectTimer(): void {
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+}

package/src/transport/index.ts

@@ -0,0 +1,42 @@
+export type { TransportCapabilities } from './capabilities.js';
+export {
+  hasNativeDeadLetter,
+  supportsDeliveryMode,
+  supportsDelayedMessages,
+} from './capabilities.js';
+
+export type {
+  MessageHandler,
+  MessageReceipt,
+  RabbitMQSendOptions,
+  RabbitMQSubscribeOptions,
+  SendOptions,
+  SubscribeOptions,
+  Subscription,
+  Transport,
+  TransportSendOptions,
+  TransportSubscribeOptions,
+} from './transport.js';
+
+export type {
+  ConnectFn,
+  ConnectionManagerConfig,
+  ConnectionState,
+  DisconnectFn,
+  StateChangeCallback,
+} from './connection-manager.js';
+export {
+  ConnectionManager,
+  defaultConnectionConfig,
+} from './connection-manager.js';
+
+export { LocalTransport } from './local/local-transport.js';
+
+export type {
+  MultiTransportConfig,
+  MultiTransportHooks,
+} from './multi/multi-transport.js';
+export { MultiTransport } from './multi/multi-transport.js';
+
+export type { RabbitMQTransportConfig } from './rabbitmq/rabbitmq-transport.js';
+export { RabbitMQTransport } from './rabbitmq/rabbitmq-transport.js';