@zdavison/matador 2.0.8 → 2.0.10

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

@@ -1,290 +0,0 @@
-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 envelope = createEnvelope({
-        eventKey: 'test.event',
-        targetSubscriber: 'test-subscriber',
-        data: { test: 'data' },
-        importance: 'should-investigate',
-      });
-      const context = createContext(
-        new EventAssertionError(envelope, '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,
-  };
-}

package/src/retry/standard-policy.ts

@@ -1,156 +0,0 @@
-import {
-  IdempotentMessageCannotRetryError,
-  MessageMaybePoisonedError,
-  isAssertionError,
-  isDoRetry,
-  isDontRetry,
-} from '../errors/index.js';
-import type { RetryContext, RetryDecision, RetryPolicy } from './policy.js';
-
-/**
- * Configuration for the standard retry policy.
- */
-export interface StandardRetryPolicyConfig {
-  /** Maximum number of attempts before dead-lettering */
-  readonly maxAttempts: number;
-
-  /** Base delay between retries in milliseconds */
-  readonly baseDelay: number;
-
-  /** Maximum delay between retries in milliseconds */
-  readonly maxDelay: number;
-
-  /** Multiplier for exponential backoff */
-  readonly backoffMultiplier: number;
-
-  /**
-   * Maximum native delivery count before considering message poisoned.
-   * This prevents crash loops from messages that crash the worker.
-   * Poison messages are sent directly to the dead-letter queue.
-   * Default: 5
-   */
-  readonly maxDeliveries: number;
-}
-
-/**
- * Default configuration values.
- */
-export const defaultRetryConfig: StandardRetryPolicyConfig = {
-  maxAttempts: 3,
-  baseDelay: 1000,
-  maxDelay: 300000, // 5 minutes
-  backoffMultiplier: 2,
-  maxDeliveries: 5,
-};
-
-/**
- * Standard retry policy implementing Matador v1 behavior.
- *
- * Decision logic (in priority order):
- * 1. Poison message → dead-letter (prevent crash loops)
- * 2. EventAssertionError → dead-letter (never retry)
- * 3. DontRetry → dead-letter (explicit no-retry)
- * 4. DoRetry → retry if under max attempts
- * 5. Max attempts exceeded → dead-letter
- * 6. Non-idempotent subscriber on redelivery → dead-letter
- * 7. Default → retry with exponential backoff
- */
-export class StandardRetryPolicy implements RetryPolicy {
-  private readonly config: StandardRetryPolicyConfig;
-
-  constructor(config: Partial<StandardRetryPolicyConfig> = {}) {
-    this.config = { ...defaultRetryConfig, ...config };
-  }
-
-  shouldRetry(context: RetryContext): RetryDecision {
-    const { envelope, error, subscriber, receipt } = context;
-    const errorMessage = error.message;
-
-    // 1. Poison message detection - prevent crash loops
-    if (receipt.deliveryCount >= this.config.maxDeliveries) {
-      const poisonError = new MessageMaybePoisonedError(
-        envelope.id,
-        receipt.deliveryCount,
-        this.config.maxDeliveries,
-      );
-      return {
-        action: 'dead-letter',
-        queue: 'undeliverable',
-        reason: poisonError.message,
-      };
-    }
-
-    // 2. Assertion errors never retry
-    if (isAssertionError(error)) {
-      return {
-        action: 'dead-letter',
-        queue: 'undeliverable',
-        reason: `assertion error: ${errorMessage}`,
-      };
-    }
-
-    // 3. Explicit no-retry
-    if (isDontRetry(error)) {
-      return {
-        action: 'dead-letter',
-        queue: 'undeliverable',
-        reason: errorMessage,
-      };
-    }
-
-    // 4. Explicit retry request
-    if (isDoRetry(error)) {
-      if (receipt.attemptNumber >= this.config.maxAttempts) {
-        return {
-          action: 'dead-letter',
-          queue: 'undeliverable',
-          reason: `max attempts exceeded (${this.config.maxAttempts}) with forced retry`,
-        };
-      }
-      return {
-        action: 'retry',
-        delay: this.getDelay(context),
-      };
-    }
-
-    // 5. Max attempts exceeded
-    if (receipt.attemptNumber >= this.config.maxAttempts) {
-      return {
-        action: 'dead-letter',
-        queue: 'undeliverable',
-        reason: `max attempts exceeded (${this.config.maxAttempts})`,
-      };
-    }
-
-    // 6. Non-idempotent subscriber on redelivery
-    // 'no' and 'unknown' are treated the same (safer default)
-    if (
-      receipt.redelivered &&
-      (subscriber.idempotent === 'no' || subscriber.idempotent === 'unknown')
-    ) {
-      const idempotentError = new IdempotentMessageCannotRetryError(
-        envelope.id,
-        subscriber.name,
-      );
-      return {
-        action: 'dead-letter',
-        queue: 'undeliverable',
-        reason: idempotentError.message,
-      };
-    }
-
-    // 7. Default: retry with backoff
-    return {
-      action: 'retry',
-      delay: this.getDelay(context),
-    };
-  }
-
-  getDelay(context: RetryContext): number {
-    const attempt = context.receipt.attemptNumber;
-    const delay =
-      this.config.baseDelay *
-      Math.pow(this.config.backoffMultiplier, attempt - 1);
-    return Math.min(delay, this.config.maxDelay);
-  }
-}

package/src/schema/index.ts

@@ -1,16 +0,0 @@
-export type {
-  AnyEventClass,
-  MatadorSchema,
-  RegisterOptions,
-  RuntimeSchemaEntry,
-  RuntimeSchemaEntryTuple,
-  SchemaEntry,
-  SchemaEntryTuple,
-  SchemaIssue,
-  SchemaPlugin,
-  SchemaValidationResult,
-} from './types.js';
-
-export { bind, installPlugins, isSchemaEntryTuple } from './types.js';
-
-export { SchemaError, SchemaRegistry } from './registry.js';