@zdavison/matador 2.0.1

package/src/pipeline/pipeline.ts

@@ -0,0 +1,371 @@
+import type { Checkpoint, CheckpointStore } from '../checkpoint/index.js';
+import { NoOpCheckpointStore, ResumableContext } from '../checkpoint/index.js';
+import type { Codec } from '../codec/index.js';
+import { CodecDecodeError } from '../codec/index.js';
+import {
+  SubscriberIsStubError,
+  SubscriberNotRegisteredError,
+} from '../errors/index.js';
+import type { SafeHooks } from '../hooks/index.js';
+import type { RetryDecision, RetryPolicy } from '../retry/index.js';
+import type { SchemaRegistry } from '../schema/index.js';
+import type { MessageReceipt, Transport } from '../transport/index.js';
+import type { Envelope, SubscriberDefinition } from '../types/index.js';
+import { isResumableSubscriber } from '../types/index.js';
+
+/**
+ * Configuration for the processing pipeline.
+ */
+export interface PipelineConfig {
+  readonly transport: Transport;
+  readonly schema: SchemaRegistry;
+  readonly codec: Codec;
+  readonly retryPolicy: RetryPolicy;
+  readonly hooks: SafeHooks;
+  /** Optional checkpoint store for resumable subscribers */
+  readonly checkpointStore?: CheckpointStore | undefined;
+}
+
+/**
+ * Result of pipeline processing.
+ */
+export interface ProcessResult {
+  readonly success: boolean;
+  readonly envelope?: Envelope | undefined;
+  readonly subscriber?: SubscriberDefinition | undefined;
+  readonly error?: Error | undefined;
+  readonly decision?: RetryDecision | undefined;
+  readonly durationMs: number;
+}
+
+/**
+ * Processing pipeline for incoming messages.
+ *
+ * Handles the complete message lifecycle:
+ * 1. Decode envelope from raw bytes
+ * 2. Lookup subscriber from schema
+ * 3. Execute subscriber callback with hooks
+ * 4. Handle success/failure with retry policy
+ */
+export class ProcessingPipeline {
+  private readonly transport: Transport;
+  private readonly schema: SchemaRegistry;
+  private readonly codec: Codec;
+  private readonly retryPolicy: RetryPolicy;
+  private readonly hooks: SafeHooks;
+  private readonly checkpointStore: CheckpointStore;
+
+  constructor(config: PipelineConfig) {
+    this.transport = config.transport;
+    this.schema = config.schema;
+    this.codec = config.codec;
+    this.retryPolicy = config.retryPolicy;
+    this.hooks = config.hooks;
+    this.checkpointStore = config.checkpointStore ?? new NoOpCheckpointStore();
+  }
+
+  /**
+   * Processes a raw message from the transport.
+   */
+  async process(
+    rawMessage: Uint8Array,
+    receipt: MessageReceipt,
+  ): Promise<ProcessResult> {
+    const startTime = performance.now();
+
+    // 1. Decode envelope
+    let envelope: Envelope;
+    try {
+      envelope = this.codec.decode(rawMessage);
+    } catch (error) {
+      const decodeError =
+        error instanceof CodecDecodeError
+          ? error
+          : new CodecDecodeError('Unknown decode error', error);
+
+      await this.transport.complete(receipt);
+      await this.hooks.onDecodeError({
+        error: decodeError,
+        rawMessage,
+        sourceQueue: receipt.sourceQueue,
+        transport: receipt.sourceTransport,
+      });
+
+      return {
+        success: false,
+        error: decodeError,
+        durationMs: performance.now() - startTime,
+      };
+    }
+
+    // 2. Lookup subscriber from schema
+    const subscriberDef = this.schema.getSubscriberDefinition(
+      envelope.docket.eventKey,
+      envelope.docket.targetSubscriber,
+    );
+
+    if (!subscriberDef) {
+      const error = new SubscriberNotRegisteredError(
+        envelope.docket.targetSubscriber,
+        envelope.docket.eventKey,
+      );
+
+      // Retry unhandled messages (likely deployment timing issue)
+      const decision = this.getUnhandledRetryDecision(envelope, receipt, error);
+      await this.handleRetryDecision(receipt, envelope, decision);
+
+      return {
+        success: false,
+        envelope,
+        error,
+        decision,
+        durationMs: performance.now() - startTime,
+      };
+    }
+
+    // Get executable subscriber
+    const subscriber = this.schema.getExecutableSubscriber(
+      envelope.docket.eventKey,
+      envelope.docket.targetSubscriber,
+    );
+
+    if (!subscriber) {
+      // Subscriber is a stub (remote implementation)
+      const error = new SubscriberIsStubError(envelope.docket.targetSubscriber);
+
+      // Retry stub messages (likely deployment timing issue)
+      const decision = this.getUnhandledRetryDecision(envelope, receipt, error);
+      await this.handleRetryDecision(receipt, envelope, decision);
+
+      return {
+        success: false,
+        envelope,
+        subscriber: subscriberDef,
+        error,
+        decision,
+        durationMs: performance.now() - startTime,
+      };
+    }
+
+    // 3. Execute subscriber callback with hooks
+    let result: unknown;
+    let error: Error | undefined;
+    let context: ResumableContext | undefined;
+
+    // For resumable subscribers, load existing checkpoint and create context
+    const isResumable = isResumableSubscriber(subscriber);
+    let existingCheckpoint: Checkpoint | undefined;
+
+    if (isResumable) {
+      existingCheckpoint = await this.checkpointStore.get(envelope.id);
+
+      if (existingCheckpoint) {
+        await this.hooks.onCheckpointLoaded?.({
+          envelope,
+          subscriber: subscriberDef,
+          checkpoint: existingCheckpoint,
+          cachedSteps: Object.keys(existingCheckpoint.completedSteps).length,
+        });
+      }
+
+      context = new ResumableContext({
+        store: this.checkpointStore,
+        envelope,
+        subscriber: subscriberDef,
+        existingCheckpoint,
+        hooks: {
+          onCheckpointHit: (ctx) => this.hooks.onCheckpointHit?.(ctx),
+          onCheckpointMiss: (ctx) => this.hooks.onCheckpointMiss?.(ctx),
+        },
+      });
+    }
+
+    await this.hooks.onWorkerWrap(envelope, subscriberDef, async () => {
+      await this.hooks.onWorkerBeforeProcess(envelope, subscriberDef);
+
+      try {
+        if (isResumable && context) {
+          // Resumable subscriber: pass context as second argument
+          // Cast needed because TypeScript can't narrow the union type based on isResumable
+          const resumableCallback = subscriber.callback as (
+            envelope: Envelope,
+            context: ResumableContext,
+          ) => Promise<void> | void;
+          result = await resumableCallback(envelope, context);
+        } else {
+          // Standard subscriber: just pass envelope
+          const standardCallback = subscriber.callback as (
+            envelope: Envelope,
+          ) => Promise<void> | void;
+          result = await standardCallback(envelope);
+        }
+      } catch (e) {
+        error = e instanceof Error ? e : new Error(String(e));
+      }
+    });
+
+    const durationMs = performance.now() - startTime;
+
+    // 4. Handle success
+    if (!error) {
+      // Clear checkpoint on success for resumable subscribers
+      if (context) {
+        await context.clear();
+        await this.hooks.onCheckpointCleared?.({
+          envelope,
+          subscriber: subscriberDef,
+          reason: 'success',
+        });
+      }
+
+      await this.transport.complete(receipt);
+      await this.hooks.onWorkerSuccess({
+        envelope,
+        subscriber: subscriberDef,
+        result,
+        durationMs,
+        transport: receipt.sourceTransport,
+      });
+
+      return {
+        success: true,
+        envelope,
+        subscriber: subscriberDef,
+        durationMs,
+      };
+    }
+
+    // 5. Handle failure - consult retry policy
+    const decision = this.retryPolicy.shouldRetry({
+      envelope,
+      error,
+      subscriber: subscriberDef,
+      receipt,
+    });
+
+    // Update envelope with error info
+    envelope.docket.lastError = error.message;
+    envelope.docket.firstError ??= error.message;
+
+    // Clear checkpoint on dead-letter (terminal state)
+    if (decision.action === 'dead-letter' && context) {
+      await context.clear();
+      await this.hooks.onCheckpointCleared?.({
+        envelope,
+        subscriber: subscriberDef,
+        reason: 'dead-letter',
+      });
+    }
+
+    await this.handleRetryDecision(receipt, envelope, decision);
+
+    await this.hooks.onWorkerError({
+      envelope,
+      subscriber: subscriberDef,
+      error,
+      durationMs,
+      decision,
+      transport: receipt.sourceTransport,
+    });
+
+    return {
+      success: false,
+      envelope,
+      subscriber: subscriberDef,
+      error,
+      decision,
+      durationMs,
+    };
+  }
+
+  private async handleRetryDecision(
+    receipt: MessageReceipt,
+    envelope: Envelope,
+    decision: RetryDecision,
+  ): Promise<void> {
+    switch (decision.action) {
+      case 'retry': {
+        // Increment attempts and schedule retry
+        envelope.docket.attempts++;
+        envelope.docket.scheduledFor = new Date(
+          Date.now() + decision.delay,
+        ).toISOString();
+
+        await this.transport.send(receipt.sourceQueue, envelope, {
+          delay: decision.delay,
+        });
+        await this.transport.complete(receipt);
+        break;
+      }
+
+      case 'dead-letter': {
+        await this.sendToDeadLetter(
+          receipt,
+          envelope,
+          decision.queue,
+          decision.reason,
+        );
+        break;
+      }
+
+      case 'discard': {
+        await this.transport.complete(receipt);
+        break;
+      }
+    }
+  }
+
+  private async sendToDeadLetter(
+    receipt: MessageReceipt,
+    envelope: Envelope,
+    dlqName: string,
+    reason: string,
+  ): Promise<void> {
+    envelope.docket.originalQueue ??= receipt.sourceQueue;
+
+    if (this.transport.sendToDeadLetter) {
+      await this.transport.sendToDeadLetter(receipt, dlqName, envelope, reason);
+    } else {
+      // Manual: send to DLQ then complete original
+      const fullDlqName = `${receipt.sourceQueue}.${dlqName}`;
+      await this.transport.send(fullDlqName, envelope);
+      await this.transport.complete(receipt);
+    }
+  }
+
+  /**
+   * Gets retry decision for unhandled messages (subscriber not found).
+   * Uses same retry policy logic but sends to 'unhandled' DLQ after max attempts.
+   */
+  private getUnhandledRetryDecision(
+    envelope: Envelope,
+    receipt: MessageReceipt,
+    error: Error,
+  ): RetryDecision {
+    // Create a synthetic subscriber definition for retry policy
+    const syntheticSubscriber: SubscriberDefinition = {
+      name: envelope.docket.targetSubscriber,
+      description: 'Synthetic subscriber for unhandled message retry',
+      idempotent: 'yes', // Safe to retry unhandled messages
+      importance: envelope.docket.importance ?? 'should-investigate',
+    };
+
+    const decision = this.retryPolicy.shouldRetry({
+      envelope,
+      error,
+      subscriber: syntheticSubscriber,
+      receipt,
+    });
+
+    // Override dead-letter queue to 'unhandled' instead of 'undeliverable'
+    if (decision.action === 'dead-letter') {
+      return {
+        action: 'dead-letter',
+        queue: 'unhandled',
+        reason: decision.reason,
+      };
+    }
+
+    return decision;
+  }
+}

package/src/retry/index.ts

@@ -0,0 +1,4 @@
+export type { RetryContext, RetryDecision, RetryPolicy } from './policy.js';
+
+export type { StandardRetryPolicyConfig } from './standard-policy.js';
+export { defaultRetryConfig, StandardRetryPolicy } from './standard-policy.js';

package/src/retry/policy.ts

@@ -0,0 +1,46 @@
+import type { MessageReceipt } from '../transport/index.js';
+import type { Envelope, SubscriberDefinition } from '../types/index.js';
+
+/**
+ * Context provided to retry policy for decision making.
+ */
+export interface RetryContext {
+  /** The message envelope */
+  readonly envelope: Envelope;
+
+  /** The error that caused the failure */
+  readonly error: Error;
+
+  /** The subscriber definition */
+  readonly subscriber: SubscriberDefinition;
+
+  /** Message receipt with delivery information */
+  readonly receipt: MessageReceipt;
+}
+
+/**
+ * Decision returned by retry policy.
+ */
+export type RetryDecision =
+  | { readonly action: 'retry'; readonly delay: number }
+  | {
+      readonly action: 'dead-letter';
+      readonly queue: string;
+      readonly reason: string;
+    }
+  | { readonly action: 'discard'; readonly reason: string };
+
+/**
+ * Interface for retry policies.
+ */
+export interface RetryPolicy {
+  /**
+   * Determines what to do with a failed message.
+   */
+  shouldRetry(context: RetryContext): RetryDecision;
+
+  /**
+   * Calculates the delay for a retry attempt.
+   */
+  getDelay(context: RetryContext): number;
+}

package/src/retry/standard-policy.test.ts

@@ -0,0 +1,282 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  DoRetry,
+  DontRetry,
+  EventAssertionError,
+} from '../errors/retry-errors.js';
+import type { MessageReceipt } from '../transport/transport.js';
+import { createEnvelope } from '../types/envelope.js';
+import type { SubscriberDefinition } from '../types/subscriber.js';
+import type { RetryContext, RetryDecision } from './policy.js';
+import { StandardRetryPolicy } from './standard-policy.js';
+
+describe('StandardRetryPolicy', () => {
+  describe('shouldRetry', () => {
+    it('should dead-letter on EventAssertionError', () => {
+      const policy = new StandardRetryPolicy();
+      const context = createContext(new EventAssertionError('Invalid event'));
+
+      const decision = policy.shouldRetry(context);
+
+      expect(decision.action).toBe('dead-letter');
+      assertDeadLetter(decision);
+      expect(decision.queue).toBe('undeliverable');
+      expect(decision.reason).toContain('assertion error');
+    });
+
+    it('should dead-letter on DontRetry error', () => {
+      const policy = new StandardRetryPolicy();
+      const context = createContext(new DontRetry('Business rule violation'));
+
+      const decision = policy.shouldRetry(context);
+
+      expect(decision.action).toBe('dead-letter');
+      assertDeadLetter(decision);
+      expect(decision.queue).toBe('undeliverable');
+      expect(decision.reason).toContain('Business rule violation');
+    });
+
+    it('should retry on DoRetry error if under max attempts', () => {
+      const policy = new StandardRetryPolicy({ maxAttempts: 3 });
+      const context = createContext(new DoRetry('Temporary failure'), {
+        attemptNumber: 1,
+      });
+
+      const decision = policy.shouldRetry(context);
+
+      expect(decision.action).toBe('retry');
+      assertRetry(decision);
+      expect(decision.delay).toBeGreaterThan(0);
+    });
+
+    it('should dead-letter on DoRetry error if max attempts exceeded', () => {
+      const policy = new StandardRetryPolicy({ maxAttempts: 3 });
+      const context = createContext(new DoRetry('Temporary failure'), {
+        attemptNumber: 3,
+      });
+
+      const decision = policy.shouldRetry(context);
+
+      expect(decision.action).toBe('dead-letter');
+      assertDeadLetter(decision);
+      expect(decision.reason).toContain('max attempts exceeded');
+    });
+
+    it('should dead-letter when max attempts exceeded', () => {
+      const policy = new StandardRetryPolicy({ maxAttempts: 3 });
+      const context = createContext(new Error('Generic error'), {
+        attemptNumber: 3,
+      });
+
+      const decision = policy.shouldRetry(context);
+
+      expect(decision.action).toBe('dead-letter');
+      assertDeadLetter(decision);
+      expect(decision.queue).toBe('undeliverable');
+      expect(decision.reason).toContain('max attempts exceeded (3)');
+    });
+
+    it('should dead-letter non-idempotent subscriber on redelivery', () => {
+      const policy = new StandardRetryPolicy();
+      const context = createContext(
+        new Error('Some error'),
+        { attemptNumber: 1, redelivered: true },
+        { idempotent: 'no' },
+      );
+
+      const decision = policy.shouldRetry(context);
+
+      expect(decision.action).toBe('dead-letter');
+      assertDeadLetter(decision);
+      expect(decision.reason).toContain('Non-idempotent subscriber');
+    });
+
+    it('should retry idempotent subscriber on redelivery', () => {
+      const policy = new StandardRetryPolicy();
+      const context = createContext(
+        new Error('Some error'),
+        { attemptNumber: 1, redelivered: true },
+        { idempotent: 'yes' },
+      );
+
+      const decision = policy.shouldRetry(context);
+
+      expect(decision.action).toBe('retry');
+    });
+
+    it('should dead-letter unknown idempotency subscriber on redelivery (unknown == no)', () => {
+      const policy = new StandardRetryPolicy();
+      const context = createContext(
+        new Error('Some error'),
+        { attemptNumber: 1, redelivered: true },
+        { idempotent: 'unknown' },
+      );
+
+      const decision = policy.shouldRetry(context);
+
+      expect(decision.action).toBe('dead-letter');
+      assertDeadLetter(decision);
+      expect(decision.reason).toContain('Non-idempotent subscriber');
+    });
+
+    it('should retry resumable subscriber on redelivery', () => {
+      const policy = new StandardRetryPolicy();
+      const context = createContext(
+        new Error('Some error'),
+        { attemptNumber: 1, redelivered: true },
+        { idempotent: 'resumable' },
+      );
+
+      const decision = policy.shouldRetry(context);
+
+      expect(decision.action).toBe('retry');
+    });
+
+    it('should retry generic errors with backoff', () => {
+      const policy = new StandardRetryPolicy({ maxAttempts: 5 });
+      const context = createContext(new Error('Generic error'), {
+        attemptNumber: 1,
+      });
+
+      const decision = policy.shouldRetry(context);
+
+      expect(decision.action).toBe('retry');
+      assertRetry(decision);
+      expect(decision.delay).toBeDefined();
+    });
+  });
+
+  describe('getDelay', () => {
+    it('should calculate exponential backoff', () => {
+      const policy = new StandardRetryPolicy({
+        baseDelay: 1000,
+        backoffMultiplier: 2,
+      });
+
+      const delay1 = policy.getDelay(
+        createContext(new Error(), { attemptNumber: 1 }),
+      );
+      const delay2 = policy.getDelay(
+        createContext(new Error(), { attemptNumber: 2 }),
+      );
+      const delay3 = policy.getDelay(
+        createContext(new Error(), { attemptNumber: 3 }),
+      );
+
+      expect(delay1).toBe(1000); // 1000 * 2^0
+      expect(delay2).toBe(2000); // 1000 * 2^1
+      expect(delay3).toBe(4000); // 1000 * 2^2
+    });
+
+    it('should cap delay at maxDelay', () => {
+      const policy = new StandardRetryPolicy({
+        baseDelay: 1000,
+        backoffMultiplier: 10,
+        maxDelay: 5000,
+      });
+
+      const delay = policy.getDelay(
+        createContext(new Error(), { attemptNumber: 5 }),
+      );
+
+      expect(delay).toBe(5000);
+    });
+  });
+
+  describe('configuration', () => {
+    it('should use default configuration', () => {
+      const policy = new StandardRetryPolicy();
+      const context = createContext(new Error(), { attemptNumber: 1 });
+
+      const decision = policy.shouldRetry(context);
+
+      // Default maxAttempts is 3, so should retry on attempt 1
+      expect(decision.action).toBe('retry');
+    });
+
+    it('should accept custom configuration', () => {
+      const policy = new StandardRetryPolicy({
+        maxAttempts: 1,
+        baseDelay: 500,
+        maxDelay: 1000,
+        backoffMultiplier: 1.5,
+      });
+
+      // With maxAttempts: 1, first attempt should dead-letter
+      const context = createContext(new Error(), { attemptNumber: 1 });
+      const decision = policy.shouldRetry(context);
+
+      expect(decision.action).toBe('dead-letter');
+    });
+
+    it('should merge partial configuration with defaults', () => {
+      const policy = new StandardRetryPolicy({ maxAttempts: 10 });
+      // Use attemptNumber: 5 but deliveryCount: 3 to avoid poison detection
+      const context = createContext(new Error(), {
+        attemptNumber: 5,
+        deliveryCount: 3,
+      });
+
+      // Should still retry because we increased maxAttempts
+      const decision = policy.shouldRetry(context);
+      expect(decision.action).toBe('retry');
+    });
+  });
+});
+
+function assertDeadLetter(decision: RetryDecision): asserts decision is {
+  action: 'dead-letter';
+  queue: string;
+  reason: string;
+} {
+  if (decision.action !== 'dead-letter') {
+    throw new Error(`Expected dead-letter action, got ${decision.action}`);
+  }
+}
+
+function assertRetry(
+  decision: RetryDecision,
+): asserts decision is { action: 'retry'; delay: number } {
+  if (decision.action !== 'retry') {
+    throw new Error(`Expected retry action, got ${decision.action}`);
+  }
+}
+
+function createContext(
+  error: Error,
+  receiptOverrides: Partial<MessageReceipt> = {},
+  subscriberOverrides: Partial<SubscriberDefinition> = {},
+): RetryContext {
+  const receipt: MessageReceipt = {
+    handle: {},
+    redelivered: false,
+    attemptNumber: 1,
+    deliveryCount:
+      receiptOverrides.deliveryCount ?? receiptOverrides.attemptNumber ?? 1,
+    sourceQueue: 'test-queue',
+    sourceTransport: 'mock',
+    ...receiptOverrides,
+  };
+
+  const subscriber: SubscriberDefinition = {
+    name: 'test-subscriber',
+    description: 'Test subscriber',
+    idempotent: 'yes',
+    importance: 'should-investigate',
+    ...subscriberOverrides,
+  };
+
+  const envelope = createEnvelope({
+    eventKey: 'test.event',
+    targetSubscriber: 'test-subscriber',
+    data: { test: 'data' },
+    importance: 'should-investigate',
+  });
+
+  return {
+    envelope,
+    error,
+    receipt,
+    subscriber,
+  };
+}