@zdavison/matador 4.0.3 → 4.1.0

package/dist/core/matador.d.ts.map

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

package/dist/core/matador.js

@@ -141,6 +141,10 @@ export class Matador {
         else {
             this.hooks.logger.info('[Matador] 🟡 Worker not subscribing to any queues (consumeFrom is empty).');
         }
+        // Mark as started
+        // Needed for the subscribe calls below, as we might start getting messages
+        // that could send events before the code here finishes subscribing to all the queues
+        this.started = true;
         for (const queueName of this.consumeFrom) {
             const qualifiedName = resolveTargetQueueName(this.topology, queueName);
             const queueDef = findQueueDefinition(this.topology, queueName);
@@ -158,7 +162,6 @@ export class Matador {
                 : undefined);
             this.subscriptions.push(subscription);
         }
-        this.started = true;
     }
     async send(eventOrClass, dataOrOptions, maybeOptions) {
         if (!this.started) {

package/dist/core/matador.test.js

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
 import { SomeSendError, TransportSendError } from '../errors/index.js';
 import { TopologyBuilder } from '../topology/builder.js';
 import { LocalTransport, MultiTransport } from '../transport/index.js';
-import { MatadorEvent, createSubscriber } from '../types/index.js';
+import { MatadorEvent, createDummyEnvelope, createSubscriber, } from '../types/index.js';
 import { Matador } from './matador.js';
 class UserCreatedEvent extends MatadorEvent {
     data;
@@ -623,6 +623,99 @@ describe('Matador', () => {
             expect(matador.isConnected()).toBe(true);
         });
     });
+    describe('start() race between subscribing and marking started', () => {
+        it('should allow send() from a subscriber callback fired while start() is still subscribing later queues', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .addQueue('notifications')
+                .build();
+            let sendError;
+            const userSub = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async (_envelope, context) => {
+                    try {
+                        await context.matador.send(OrderPlacedEvent, {
+                            orderId: 'order-1',
+                            amount: 100,
+                        });
+                    }
+                    catch (err) {
+                        sendError = err;
+                    }
+                },
+            });
+            const orderSub = createSubscriber({
+                name: 'handle-order',
+                description: 'Handles order events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [userSub]],
+                [OrderPlacedEvent.key]: [OrderPlacedEvent, [orderSub]],
+            };
+            // Simulates a broker delivering a message on the first subscribed
+            // queue before subscribe() has resolved for a later queue - the
+            // exact window in which `started` used to still be false.
+            let capturedHandler;
+            let releaseSecondSubscribe;
+            const secondSubscribeGate = new Promise((resolve) => {
+                releaseSecondSubscribe = resolve;
+            });
+            const raceTransport = {
+                name: 'race-transport',
+                capabilities: {
+                    deliveryModes: ['at-least-once'],
+                    delayedMessages: false,
+                    deadLetterRouting: 'native',
+                    attemptTracking: true,
+                    concurrencyModel: 'prefetch',
+                    ordering: 'none',
+                    priorities: false,
+                },
+                isConnected: () => true,
+                connect: mock(async () => { }),
+                disconnect: mock(async () => { }),
+                send: mock(async () => 'race-transport'),
+                subscribe: mock(async (queueName, handler) => {
+                    if (queueName === 'matador.test.notifications') {
+                        await secondSubscribeGate;
+                    }
+                    else {
+                        capturedHandler = handler;
+                    }
+                    return { unsubscribe: mock(async () => { }), isActive: true };
+                }),
+                applyTopology: mock(async () => { }),
+                complete: mock(async () => { }),
+            };
+            matador = new Matador({
+                transport: raceTransport,
+                topology,
+                schema,
+                consumeFrom: ['events', 'notifications'],
+            });
+            const startPromise = matador.start();
+            // Wait for the first queue's subscribe() to resolve and capture its
+            // handler, while the second queue's subscribe() is still pending.
+            while (!capturedHandler) {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            }
+            const envelope = createDummyEnvelope(new UserCreatedEvent({ userId: '123', email: 'test@example.com' }), { targetSubscriber: 'handle-user' });
+            await capturedHandler?.(envelope, {
+                handle: 'msg-1',
+                redelivered: false,
+                attemptNumber: 1,
+                deliveryCount: 1,
+                sourceQueue: 'matador.test.events',
+                sourceTransport: 'race-transport',
+            });
+            expect(sendError).toBeUndefined();
+            releaseSecondSubscribe?.();
+            await startPromise;
+        });
+    });
     describe('self-dispatch during graceful shutdown (stopReceiving)', () => {
         it('LOCAL transport only: a self-dispatched follow-up should still be delivered after stopReceiving()', async () => {
             const topology = TopologyBuilder.create()

package/dist/index.cjs

@@ -1893,10 +1893,20 @@ var ProcessingPipeline = class {
         durationMs: performance.now() - startTime
       };
     }
+    const isResumable = isResumableSubscriber(subscriber);
+    const shouldProcessResult = await this.handleShouldProcess(
+      envelope,
+      subscriberDef,
+      isResumable,
+      receipt,
+      startTime
+    );
+    if (!shouldProcessResult.success) {
+      return shouldProcessResult;
+    }
     let result;
     let error;
     let context;
-    const isResumable = isResumableSubscriber(subscriber);
     let existingCheckpoint;
     if (isResumable) {
       existingCheckpoint = await this.checkpointStore.get(envelope.id);
@@ -1972,10 +1982,65 @@ var ProcessingPipeline = class {
       subscriber: subscriberDef,
       receipt
     });
+    return await this.handleFailure(
+      error,
+      decision,
+      envelope,
+      subscriberDef,
+      isResumable,
+      receipt,
+      durationMs
+    );
+  }
+  /**
+   * Runs the retry policy's pre-processing check.
+   *
+   * This returns a terminal `ProcessResult` if the message should be skipped (dead-lettered/discarded) without ever invoking the callback,
+   * or a success result if shouldProcess passes and we should continue processing the message.
+   * @param envelope - The message envelope
+   * @param subscriberDef - The subscriber definition
+   * @param isResumable - Whether the subscriber is resumable
+   * @param receipt - The message receipt
+   * @param startTime - The start time of the processing
+   * @returns A `ProcessResult` indicating if we should continue with processing the message, or fail it preemptively
+   */
+  async handleShouldProcess(envelope, subscriberDef, isResumable, receipt, startTime) {
+    const decision = this.retryPolicy.shouldProcess({ envelope, receipt });
+    if (decision.action === "process") {
+      return {
+        success: true,
+        durationMs: 0
+      };
+    }
+    const durationMs = performance.now() - startTime;
+    const error = new Error(decision.reason);
+    return await this.handleFailure(
+      error,
+      decision,
+      envelope,
+      subscriberDef,
+      isResumable,
+      receipt,
+      durationMs
+    );
+  }
+  /**
+   * Performs failure handling and cleanup based on retry decision (e.g. dead-letter).
+   *
+   * @param error - The error from the processing attempt
+   * @param decision - The decision from executing the appropriate retry policy check
+   * @param envelope - The message envelope
+   * @param subscriberDef - The subscriber definition
+   * @param isResumable - Whether the subscriber is resumable
+   * @param receipt - The message receipt
+   * @param durationMs - The duration of processing
+   * @returns A `ProcessResult` indicating failure
+   */
+  async handleFailure(error, decision, envelope, subscriberDef, isResumable, receipt, durationMs) {
     envelope.docket.lastError = error.message;
     envelope.docket.firstError ??= error.message;
-    if (decision.action === "dead-letter" && context) {
-      await context.clear();
+    if (decision.action === "dead-letter" && isResumable) {
+      await this.checkpointStore.delete(envelope.id);
       await this.hooks.onCheckpointCleared?.({
         envelope,
         subscriber: subscriberDef,
@@ -2081,15 +2146,31 @@ var StandardRetryPolicy = class {
   constructor(config = {}) {
     this.config = { ...defaultRetryConfig, ...config };
   }
+  /**
+   * Check if the message should be dead-lettered before the subscriber callback is invoked
+   *
+   * Uses the same delivery-count threshold as `shouldRetry` poison check, so an
+   * already-poisoned message is dead-lettered without ever running the callback again.
+   *
+   * @param context - The shouldProcess context.
+   * @returns A 'process' decision if the message is not poisoned; a dead-letter decision otherwise.
+   */
+  shouldProcess(context) {
+    const poisonError = this.checkPoisoned(context.envelope, context.receipt);
+    if (poisonError) {
+      return {
+        action: "dead-letter",
+        queue: "undeliverable",
+        reason: poisonError.message
+      };
+    }
+    return { action: "process" };
+  }
   shouldRetry(context) {
     const { envelope, error, subscriber, receipt } = context;
     const errorMessage = error.message;
-    if (receipt.deliveryCount >= this.config.maxDeliveries) {
-      const poisonError = new MessageMaybePoisonedError(
-        envelope.id,
-        receipt.deliveryCount,
-        this.config.maxDeliveries
-      );
+    const poisonError = this.checkPoisoned(envelope, receipt);
+    if (poisonError) {
       return {
         action: "dead-letter",
         queue: "undeliverable",
@@ -2151,6 +2232,23 @@ var StandardRetryPolicy = class {
     const delay = this.config.baseDelay * this.config.backoffMultiplier ** (attempt - 1);
     return Math.min(delay, this.config.maxDelay);
   }
+  /**
+   * Checks the native delivery count against the poison threshold
+   *
+   * @param envelope - The message envelope.
+   * @param receipt - The message receipt.
+   * @returns A MessageMaybePoisonedError if the message is poisoned; null otherwise
+   */
+  checkPoisoned(envelope, receipt) {
+    if (receipt.deliveryCount >= this.config.maxDeliveries) {
+      return new MessageMaybePoisonedError(
+        envelope.id,
+        receipt.deliveryCount,
+        this.config.maxDeliveries
+      );
+    }
+    return null;
+  }
 };
 
 // src/schema/types.ts
@@ -2461,6 +2559,7 @@ var Matador = class {
         "[Matador] \u{1F7E1} Worker not subscribing to any queues (consumeFrom is empty)."
       );
     }
+    this.started = true;
     for (const queueName of this.consumeFrom) {
       const qualifiedName = resolveTargetQueueName(this.topology, queueName);
       const queueDef = findQueueDefinition(this.topology, queueName);
@@ -2479,7 +2578,6 @@ var Matador = class {
       );
       this.subscriptions.push(subscription);
     }
-    this.started = true;
   }
   async send(eventOrClass, dataOrOptions, maybeOptions) {
     if (!this.started) {
@@ -3626,6 +3724,9 @@ var RabbitMQTransport = class {
     if (queueDef.consumerTimeout) {
       queueOptions.arguments["x-consumer-timeout"] = queueDef.consumerTimeout;
     }
+    if (queueDef.singleActiveConsumer) {
+      queueOptions.arguments["x-single-active-consumer"] = true;
+    }
     return queueOptions;
   }
   async assertWorkQueue(channel, topology, queueDef) {