@zdavison/matador 2.0.2 → 2.0.4

package/src/topology/builder.ts

@@ -12,6 +12,15 @@ import type {
  */
 export type QueueOptions = Omit<QueueDefinition, 'name'>;
 
+/**
+ * Type guard to check if the argument is a QueueDefinition object.
+ */
+function isQueueDefinition(
+  arg: string | QueueDefinition,
+): arg is QueueDefinition {
+  return typeof arg === 'object' && arg !== null && 'name' in arg;
+}
+
 /**
  * Error thrown when topology validation fails.
  */
@@ -64,17 +73,46 @@ export class TopologyBuilder {
 
   /**
    * Adds a queue to the topology.
+   * @param definition - A complete QueueDefinition object
+   */
+  addQueue(definition: QueueDefinition): this;
+  /**
+   * Adds a queue to the topology.
+   * @param name - Queue name
+   * @param options - Queue options
    */
-  addQueue(name: string, options: QueueOptions = {}): this {
-    this.queues.push({ name, ...options });
+  addQueue(name: string, options?: QueueOptions): this;
+  addQueue(
+    nameOrDefinition: string | QueueDefinition,
+    options: QueueOptions = {},
+  ): this {
+    if (isQueueDefinition(nameOrDefinition)) {
+      this.queues.push(nameOrDefinition);
+    } else {
+      this.queues.push({ name: nameOrDefinition, ...options });
+    }
     return this;
   }
 
   /**
    * Alias for addQueue().
+   * @param definition - A complete QueueDefinition object
+   */
+  queue(definition: QueueDefinition): this;
+  /**
+   * Alias for addQueue().
+   * @param name - Queue name
+   * @param options - Queue options
    */
-  queue(name: string, options: QueueOptions = {}): this {
-    return this.addQueue(name, options);
+  queue(name: string, options?: QueueOptions): this;
+  queue(
+    nameOrDefinition: string | QueueDefinition,
+    options: QueueOptions = {},
+  ): this {
+    if (isQueueDefinition(nameOrDefinition)) {
+      return this.addQueue(nameOrDefinition);
+    }
+    return this.addQueue(nameOrDefinition, options);
   }
 
   /**
@@ -141,7 +179,8 @@ export class TopologyBuilder {
     for (const queue of this.queues) {
       if (!queue.name || queue.name.trim() === '') {
         issues.push('Queue name cannot be empty');
-      } else if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(queue.name)) {
+      } else if (!queue.exact && !/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(queue.name)) {
+        // Skip pattern validation for exact queues (allows names like 'matador.shared.id-platform')
         issues.push(
           `Queue name "${queue.name}" must start with a letter and contain only alphanumeric characters, underscores, and hyphens`,
         );

package/src/topology/index.ts

@@ -2,13 +2,17 @@ export type {
   DeadLetterConfig,
   DeadLetterQueueConfig,
   QueueDefinition,
+  RabbitMQQueueDefinition,
+  RabbitMQQueueOptions,
   RetryConfig,
   Topology,
+  TransportQueueOptions,
 } from './types.js';
 export {
   getDeadLetterQueueName,
   getQualifiedQueueName,
   getRetryQueueName,
+  resolveQueueName,
 } from './types.js';
 
 export type { QueueOptions } from './builder.js';

package/src/topology/types.ts

@@ -20,7 +20,7 @@ export interface Topology {
  * Individual queue definition.
  */
 export interface QueueDefinition {
-  /** Queue name (will be prefixed with namespace) */
+  /** Queue name (will be prefixed with namespace unless exact: true) */
   readonly name: string;
 
   /** Concurrency for this queue */
@@ -39,6 +39,66 @@ export interface QueueDefinition {
    * queues that are not managed by Matador.
    */
   readonly exact?: boolean | undefined;
+
+  /** Transport-specific queue options */
+  readonly transport?: TransportQueueOptions | undefined;
+}
+
+/**
+ * Transport-specific queue options.
+ * Each transport can define its own options under its transport name key.
+ */
+export interface TransportQueueOptions {
+  /** RabbitMQ-specific queue options */
+  readonly rabbitmq?: RabbitMQQueueDefinition | undefined;
+}
+
+/**
+ * RabbitMQ-specific queue definition options.
+ */
+export interface RabbitMQQueueDefinition {
+  /**
+   * Exact RabbitMQ queue assertion options.
+   * When provided, these options completely replace all auto-computed defaults
+   * (durable, x-queue-type, x-dead-letter-exchange, etc.).
+   */
+  readonly options?: RabbitMQQueueOptions | undefined;
+}
+
+/**
+ * RabbitMQ queue assertion options.
+ * Maps to amqplib's Options.AssertQueue.
+ */
+export interface RabbitMQQueueOptions {
+  /** Queue survives broker restart */
+  readonly durable?: boolean | undefined;
+
+  /** Queue is deleted when last consumer unsubscribes */
+  readonly autoDelete?: boolean | undefined;
+
+  /** Queue can only be used by the declaring connection */
+  readonly exclusive?: boolean | undefined;
+
+  /** Exchange to which dead-lettered messages are sent */
+  readonly deadLetterExchange?: string | undefined;
+
+  /** Routing key for dead-lettered messages */
+  readonly deadLetterRoutingKey?: string | undefined;
+
+  /** Message TTL in milliseconds */
+  readonly messageTtl?: number | undefined;
+
+  /** Queue expires after this many milliseconds of non-use */
+  readonly expires?: number | undefined;
+
+  /** Maximum number of messages in the queue */
+  readonly maxLength?: number | undefined;
+
+  /** Maximum priority level (0-255) */
+  readonly maxPriority?: number | undefined;
+
+  /** Additional x-* arguments for RabbitMQ */
+  readonly arguments?: Record<string, unknown> | undefined;
 }
 
 /**
@@ -107,3 +167,17 @@ export function getRetryQueueName(
 ): string {
   return `${namespace}.${queueName}.retry`;
 }
+
+/**
+ * Resolves the actual queue name for a given queue definition.
+ * When exact: true, returns name as-is. Otherwise, returns namespace.name.
+ */
+export function resolveQueueName(
+  namespace: string,
+  queueDef: QueueDefinition,
+): string {
+  if (queueDef.exact) {
+    return queueDef.name;
+  }
+  return `${namespace}.${queueDef.name}`;
+}

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

@@ -185,7 +185,10 @@ export class LocalTransport implements Transport {
         await sub.handler(message.envelope, receipt);
       } catch (error) {
         // Handler errors should be caught in the pipeline
-        this.logger.error('[Matador] 🔴 Handler error in message processing', error);
+        this.logger.error(
+          '[Matador] 🔴 Handler error in message processing',
+          error,
+        );
       }
     }
   }

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

@@ -0,0 +1,118 @@
+import { describe, expect, it, mock } from 'bun:test';
+import type { Logger } from '../../hooks/index.js';
+import { RabbitMQTransport, redactAmqpUrl } from './rabbitmq-transport.js';
+
+describe('redactAmqpUrl', () => {
+  it('should redact username and password with 4 asterisks', () => {
+    const url = 'amqp://myuser:mypassword@localhost:5672';
+    const redacted = redactAmqpUrl(url);
+    expect(redacted).toBe('amqp://****:****@localhost:5672');
+  });
+
+  it('should redact credentials in amqps URLs', () => {
+    const url = 'amqps://admin:secret123@rabbitmq.example.com:5671';
+    const redacted = redactAmqpUrl(url);
+    expect(redacted).toBe('amqps://****:****@rabbitmq.example.com:5671');
+  });
+
+  it('should redact long credentials to exactly 4 asterisks', () => {
+    const url =
+      'amqp://verylongusername:verylongpassword@rabbitmq-cluster.svc.local:5672';
+    const redacted = redactAmqpUrl(url);
+    expect(redacted).toBe('amqp://****:****@rabbitmq-cluster.svc.local:5672');
+  });
+
+  it('should redact short credentials to exactly 4 asterisks', () => {
+    const url = 'amqp://a:b@host:5672';
+    const redacted = redactAmqpUrl(url);
+    expect(redacted).toBe('amqp://****:****@host:5672');
+  });
+
+  it('should preserve vhost in URL', () => {
+    const url = 'amqp://user:pass@host:5672/myvhost';
+    const redacted = redactAmqpUrl(url);
+    expect(redacted).toBe('amqp://****:****@host:5672/myvhost');
+  });
+
+  it('should not modify URL without credentials', () => {
+    const url = 'amqp://localhost:5672';
+    const redacted = redactAmqpUrl(url);
+    expect(redacted).toBe('amqp://localhost:5672');
+  });
+
+  it('should not modify URL with only username (no password)', () => {
+    const url = 'amqp://guest@localhost:5672';
+    const redacted = redactAmqpUrl(url);
+    expect(redacted).toBe('amqp://guest@localhost:5672');
+  });
+
+  it('should handle URL-encoded credentials', () => {
+    // URL-encoded @ in password: p%40ssword
+    const url = 'amqp://user:p%40ssword@host:5672';
+    const redacted = redactAmqpUrl(url);
+    expect(redacted).toBe('amqp://****:****@host:5672');
+  });
+});
+
+describe('RabbitMQTransport', () => {
+  describe('connection logging', () => {
+    it('should log redacted connection URL when connecting', async () => {
+      const mockLogger: Logger = {
+        debug: mock(() => {}),
+        info: mock(() => {}),
+        warn: mock(() => {}),
+        error: mock(() => {}),
+      };
+
+      const transport = new RabbitMQTransport({
+        url: 'amqp://testuser:testpass@localhost:5672',
+        logger: mockLogger,
+        connection: {
+          maxReconnectAttempts: 1, // Only try once to avoid long retries
+          initialReconnectDelay: 10,
+        },
+      });
+
+      // Attempt to connect - it will fail since there's no RabbitMQ server
+      // but the log should still be emitted before the connection attempt
+      try {
+        await transport.connect();
+      } catch {
+        // Expected to fail - no RabbitMQ server running
+      }
+
+      // Verify the log was called with the redacted URL
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        "[Matador] \u23F3 Connecting to RabbitMQ at 'amqp://****:****@localhost:5672'.",
+      );
+    });
+
+    it('should log connection URL as-is when no credentials provided', async () => {
+      const mockLogger: Logger = {
+        debug: mock(() => {}),
+        info: mock(() => {}),
+        warn: mock(() => {}),
+        error: mock(() => {}),
+      };
+
+      const transport = new RabbitMQTransport({
+        url: 'amqp://localhost:5672',
+        logger: mockLogger,
+        connection: {
+          maxReconnectAttempts: 1,
+          initialReconnectDelay: 10,
+        },
+      });
+
+      try {
+        await transport.connect();
+      } catch {
+        // Expected to fail
+      }
+
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        "[Matador] \u23F3 Connecting to RabbitMQ at 'amqp://localhost:5672'.",
+      );
+    });
+  });
+});

package/src/transport/rabbitmq/rabbitmq-transport.ts

@@ -62,6 +62,18 @@ interface ActiveConsumer {
   active: boolean;
 }
 
+/**
+ * Redacts credentials from an AMQP URL.
+ * Replaces username and password with '****' regardless of their length.
+ *
+ * @example
+ * redactAmqpUrl('amqp://user:pass@host:5672') // 'amqp://****:****@host:5672'
+ */
+export function redactAmqpUrl(url: string): string {
+  const regex = /^(amqps?:\/\/)[^:]+:[^@]+@/;
+  return url.replace(regex, '$1****:****@');
+}
+
 /**
  * RabbitMQ transport implementation using amqplib.
  */
@@ -430,6 +442,9 @@ export class RabbitMQTransport implements Transport {
   }
 
   private async doConnect(): Promise<void> {
+    this.logger.info(
+      `[Matador] ⏳ Connecting to RabbitMQ at '${redactAmqpUrl(this.config.url)}'.`,
+    );
     const connection = await amqplib.connect(this.config.url);
     this.connection = connection;
 
@@ -589,36 +604,44 @@ export class RabbitMQTransport implements Transport {
       ? queueDef.name
       : `${topology.namespace}.${queueDef.name}`;
 
-    const queueOptions: Options.AssertQueue = {
-      durable: true,
-      arguments: {} as Record<string, unknown>,
-    };
+    const rabbitmqOptions = queueDef.transport?.rabbitmq?.options;
 
-    // Use quorum queues for durability
-    if (this.config.quorumQueues && !queueDef.exact) {
-      queueOptions.arguments['x-queue-type'] = 'quorum';
-    }
+    // If user provided exact RabbitMQ options, use them directly (replaces all defaults)
+    if (rabbitmqOptions) {
+      await channel.assertQueue(queueName, rabbitmqOptions);
+    } else {
+      // Use computed defaults
+      const queueOptions: Options.AssertQueue = {
+        durable: true,
+        arguments: {} as Record<string, unknown>,
+      };
 
-    // Set up dead-letter exchange routing
-    const dlxExchange = this.getDLXExchangeName(topology.namespace);
-    if (
-      topology.deadLetter.unhandled.enabled ||
-      topology.deadLetter.undeliverable.enabled
-    ) {
-      queueOptions.arguments['x-dead-letter-exchange'] = dlxExchange;
-    }
+      // Use quorum queues for durability
+      if (this.config.quorumQueues && !queueDef.exact) {
+        queueOptions.arguments['x-queue-type'] = 'quorum';
+      }
 
-    // Enable priority if requested
-    if (queueDef.priorities) {
-      queueOptions.arguments['x-max-priority'] = 10;
-    }
+      // Set up dead-letter exchange routing
+      const dlxExchange = this.getDLXExchangeName(topology.namespace);
+      if (
+        topology.deadLetter.unhandled.enabled ||
+        topology.deadLetter.undeliverable.enabled
+      ) {
+        queueOptions.arguments['x-dead-letter-exchange'] = dlxExchange;
+      }
 
-    // Set consumer timeout if specified
-    if (queueDef.consumerTimeout) {
-      queueOptions.arguments['x-consumer-timeout'] = queueDef.consumerTimeout;
-    }
+      // Enable priority if requested
+      if (queueDef.priorities) {
+        queueOptions.arguments['x-max-priority'] = 10;
+      }
 
-    await channel.assertQueue(queueName, queueOptions);
+      // Set consumer timeout if specified
+      if (queueDef.consumerTimeout) {
+        queueOptions.arguments['x-consumer-timeout'] = queueDef.consumerTimeout;
+      }
+
+      await channel.assertQueue(queueName, queueOptions);
+    }
 
     // Bind queue to main exchange
     const mainExchange = this.getMainExchangeName(topology.namespace);

package/src/types/dispatcher.ts

@@ -0,0 +1,18 @@
+import type { SendResult } from '../core/fanout.js';
+import type { Event, EventClass, EventOptions } from './event.js';
+
+/**
+ * Interface for dispatching events.
+ * Implemented by Matador to allow subscribers to send events.
+ */
+export interface Dispatcher {
+  /**
+   * Sends an event to all registered subscribers.
+   */
+  send<T>(
+    eventClass: EventClass<T>,
+    data: T,
+    options?: EventOptions,
+  ): Promise<SendResult>;
+  send<T>(event: Event<T>, options?: EventOptions): Promise<SendResult>;
+}

package/src/types/index.ts

@@ -7,6 +7,8 @@ export type {
 } from './common.js';
 export { invalidResult, validResult } from './common.js';
 
+export type { Dispatcher } from './dispatcher.js';
+
 export type { CreateEnvelopeOptions, Docket, Envelope } from './envelope.js';
 export { createEnvelope } from './envelope.js';
 
@@ -26,11 +28,13 @@ export { MatadorEvent } from './event.js';
 export type {
   AnySubscriber,
   BaseSubscriberOptions,
+  CallbackContext,
   CreateResumableSubscriberInput,
   CreateStandardSubscriberInput,
   CreateSubscriberInput,
   EnvelopeOf,
   ResumableCallback,
+  ResumableCallbackContext,
   ResumableSubscriber,
   ResumableSubscriberOptions,
   StandardCallback,

package/src/types/subscriber.ts

@@ -1,8 +1,18 @@
 import type { SubscriberContext } from '../checkpoint/index.js';
 import type { Idempotency, Importance } from './common.js';
+import type { Dispatcher } from './dispatcher.js';
 import type { Envelope } from './envelope.js';
 import type { MatadorEvent } from './event.js';
 
+/**
+ * Context passed to subscriber callbacks.
+ * Provides access to the Matador instance for sending additional events.
+ */
+export interface CallbackContext {
+  /** Matador dispatcher for sending additional events from within a subscriber */
+  readonly matador: Dispatcher;
+}
+
 /**
  * Helper type to get the envelope type for a subscriber callback.
  * Extracts the data type from a MatadorEvent and wraps it in an Envelope.
@@ -16,19 +26,28 @@ export type EnvelopeOf<T extends MatadorEvent> = Envelope<T['data']>;
 
 /**
  * Callback function executed when an event is received (standard subscribers).
- * Receives the full envelope containing id, data, and docket.
+ * Receives the full envelope containing id, data, and docket, plus a context
+ * with access to the matador instance for sending additional events.
  */
 export type StandardCallback<T = unknown> = (
   envelope: Envelope<T>,
+  context: CallbackContext,
 ) => Promise<void> | void;
 
+/**
+ * Context for resumable subscriber callbacks.
+ * Combines checkpoint operations (io, all) with matador access.
+ */
+export type ResumableCallbackContext = SubscriberContext & CallbackContext;
+
 /**
  * Callback function for resumable subscribers.
- * Receives the envelope and a SubscriberContext with io() for checkpointed operations.
+ * Receives the envelope and a context with io() for checkpointed operations
+ * and matador for sending additional events.
  */
 export type ResumableCallback<T = unknown> = (
   envelope: Envelope<T>,
-  context: SubscriberContext,
+  context: ResumableCallbackContext,
 ) => Promise<void> | void;
 
 /**