@zdavison/matador 2.0.1

package/src/core/shutdown.ts

@@ -0,0 +1,165 @@
+import { type Logger, consoleLogger } from '../hooks/index.js';
+
+/**
+ * Shutdown state.
+ */
+export type ShutdownState =
+  | 'running'
+  | 'stopping-receive'
+  | 'waiting-handlers'
+  | 'stopping-enqueue'
+  | 'disconnecting'
+  | 'stopped';
+
+/**
+ * Configuration for shutdown manager.
+ */
+export interface ShutdownConfig {
+  /** Timeout for graceful shutdown in milliseconds */
+  readonly gracefulShutdownTimeout: number;
+
+  /** Polling interval when waiting for handlers to idle */
+  readonly idlePollingInterval: number;
+
+  /** Logger for shutdown events (defaults to console) */
+  readonly logger: Logger;
+}
+
+/**
+ * Default shutdown configuration.
+ */
+export const defaultShutdownConfig: ShutdownConfig = {
+  gracefulShutdownTimeout: 30000,
+  idlePollingInterval: 1000,
+  logger: consoleLogger,
+};
+
+/**
+ * Handler state tracking.
+ */
+export interface HandlersState {
+  readonly eventsBeingProcessed: number;
+  readonly eventsBeingEnqueued: number;
+  readonly isIdle: boolean;
+}
+
+/**
+ * Manages graceful shutdown of Matador.
+ *
+ * Shutdown sequence:
+ * 1. Stop receiving new messages
+ * 2. Wait for in-flight processing to complete
+ * 3. Stop accepting new enqueue requests
+ * 4. Disconnect transport
+ */
+export class ShutdownManager {
+  private _state: ShutdownState = 'running';
+  private readonly config: ShutdownConfig;
+  private eventsBeingProcessed = 0;
+  private acceptingEnqueue = true;
+
+  constructor(
+    private readonly getEnqueueCount: () => number,
+    private readonly stopReceiving: () => Promise<void>,
+    private readonly disconnectTransport: () => Promise<void>,
+    config: Partial<ShutdownConfig> = {},
+  ) {
+    this.config = { ...defaultShutdownConfig, ...config };
+  }
+
+  /**
+   * Current shutdown state.
+   */
+  get state(): ShutdownState {
+    return this._state;
+  }
+
+  /**
+   * Whether enqueue is currently allowed.
+   */
+  get isEnqueueAllowed(): boolean {
+    return this.acceptingEnqueue;
+  }
+
+  /**
+   * Gets current handler state.
+   */
+  getHandlersState(): HandlersState {
+    const eventsBeingEnqueued = this.getEnqueueCount();
+    return {
+      eventsBeingProcessed: this.eventsBeingProcessed,
+      eventsBeingEnqueued,
+      isIdle: this.eventsBeingProcessed === 0 && eventsBeingEnqueued === 0,
+    };
+  }
+
+  /**
+   * Increment processing counter.
+   */
+  incrementProcessing(): void {
+    this.eventsBeingProcessed++;
+  }
+
+  /**
+   * Decrement processing counter.
+   */
+  decrementProcessing(): void {
+    this.eventsBeingProcessed--;
+  }
+
+  /**
+   * Performs graceful shutdown.
+   */
+  async shutdown(): Promise<void> {
+    if (this._state !== 'running') {
+      return;
+    }
+
+    // 1. Stop receiving new messages
+    this._state = 'stopping-receive';
+    await this.stopReceiving();
+
+    // 2. Wait for handlers to idle
+    this._state = 'waiting-handlers';
+    await this.waitForIdle();
+
+    // 3. Stop accepting new enqueue requests
+    this._state = 'stopping-enqueue';
+    this.acceptingEnqueue = false;
+
+    // 4. Disconnect transport
+    this._state = 'disconnecting';
+    await this.disconnectTransport();
+
+    this._state = 'stopped';
+  }
+
+  /**
+   * Forcefully stops without waiting.
+   */
+  async forceStop(): Promise<void> {
+    this.acceptingEnqueue = false;
+    await this.stopReceiving();
+    await this.disconnectTransport();
+    this._state = 'stopped';
+  }
+
+  private async waitForIdle(): Promise<void> {
+    const deadline = Date.now() + this.config.gracefulShutdownTimeout;
+
+    while (!this.getHandlersState().isIdle) {
+      if (Date.now() > deadline) {
+        this.config.logger.warn(
+          `[Matador] ⚠️ Shutdown timeout reached with ${this.eventsBeingProcessed} events still processing`,
+        );
+        break;
+      }
+
+      await this.sleep(this.config.idlePollingInterval);
+    }
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/errors/checkpoint-errors.ts

@@ -0,0 +1,62 @@
+import { MatadorError } from './matador-errors.js';
+
+/**
+ * Thrown when a duplicate io() key is used within a single subscriber execution.
+ * Each io() call must have a unique key to prevent cache collisions.
+ */
+export class DuplicateIoKeyError extends MatadorError {
+  readonly description =
+    'The same io() key was used multiple times in a single subscriber execution. ' +
+    'Each io() call must have a unique key to ensure correct checkpoint behavior. ' +
+    'ACTION: Ensure all io() keys are unique within the subscriber. ' +
+    'For dynamic operations (e.g., loops), include a unique identifier in the key ' +
+    '(e.g., `process-item-${item.id}`).';
+
+  constructor(
+    public readonly key: string,
+    public readonly subscriberName: string,
+  ) {
+    super(
+      `Duplicate io key "${key}" in subscriber "${subscriberName}". ` +
+        `Each io() call must have a unique key.`,
+    );
+  }
+}
+
+/**
+ * Thrown when checkpoint store operations fail.
+ */
+export class CheckpointStoreError extends MatadorError {
+  readonly description =
+    'A checkpoint store operation failed. This may cause issues with resumable subscribers. ' +
+    'ACTION: Check the underlying storage system (Redis, etc.) for connectivity issues. ' +
+    'The subscriber may re-execute operations that were already completed.';
+
+  constructor(
+    public readonly operation: 'get' | 'set' | 'delete',
+    public readonly envelopeId: string,
+    public readonly cause: Error,
+  ) {
+    super(
+      `Checkpoint store ${operation} failed for envelope "${envelopeId}": ${cause.message}`,
+    );
+  }
+}
+
+/**
+ * Type guard for DuplicateIoKeyError.
+ */
+export function isDuplicateIoKeyError(
+  error: unknown,
+): error is DuplicateIoKeyError {
+  return error instanceof DuplicateIoKeyError;
+}
+
+/**
+ * Type guard for CheckpointStoreError.
+ */
+export function isCheckpointStoreError(
+  error: unknown,
+): error is CheckpointStoreError {
+  return error instanceof CheckpointStoreError;
+}

package/src/errors/has-description.ts

@@ -0,0 +1,25 @@
+/**
+ * Interface for errors that provide a human-readable description.
+ * The description explains what the error means and what actions
+ * users should take when encountering it in logs/observability.
+ */
+export interface HasDescription {
+  /**
+   * Human-readable description of the error type.
+   * Intended for logging and observability to help users understand
+   * the error and determine appropriate remediation steps.
+   */
+  readonly description: string;
+}
+
+/**
+ * Type guard to check if an error implements HasDescription.
+ */
+export function hasDescription(error: unknown): error is HasDescription {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'description' in error &&
+    typeof (error as HasDescription).description === 'string'
+  );
+}

package/src/errors/index.ts

@@ -0,0 +1,57 @@
+export type { HasDescription } from './has-description.js';
+export { hasDescription } from './has-description.js';
+
+export {
+  DontRetry,
+  DoRetry,
+  EventAssertionError,
+  isAssertionError,
+  isDontRetry,
+  isDoRetry,
+  RetryControlError,
+} from './retry-errors.js';
+
+export {
+  // Base class
+  MatadorError,
+  isMatadorError,
+  // Lifecycle errors
+  NotStartedError,
+  isNotStartedError,
+  ShutdownInProgressError,
+  // Transport errors
+  TransportNotConnectedError,
+  isTransportNotConnectedError,
+  TransportClosedError,
+  TransportSendError,
+  AllTransportsFailedError,
+  DelayedMessagesNotSupportedError,
+  // Schema & configuration errors
+  EventNotRegisteredError,
+  isEventNotRegisteredError,
+  SubscriberNotRegisteredError,
+  isSubscriberNotRegisteredError,
+  NoSubscribersExistError,
+  InvalidSchemaError,
+  SubscriberIsStubError,
+  LocalTransportCannotProcessStubError,
+  // Queue errors
+  QueueNotFoundError,
+  // Event validation errors
+  InvalidEventError,
+  // Message processing errors
+  MessageMaybePoisonedError,
+  isMessageMaybePoisonedError,
+  IdempotentMessageCannotRetryError,
+  isIdempotentMessageCannotRetryError,
+  // Timeout errors
+  TimeoutError,
+} from './matador-errors.js';
+
+export {
+  // Checkpoint errors
+  CheckpointStoreError,
+  DuplicateIoKeyError,
+  isCheckpointStoreError,
+  isDuplicateIoKeyError,
+} from './checkpoint-errors.js';