@zdavison/matador 2.0.9 → 2.0.10

package/{src/pipeline/index.ts → dist/pipeline/index.d.ts}

@@ -1,2 +1,3 @@
 export type { PipelineConfig, ProcessResult } from './pipeline.js';
 export { ProcessingPipeline } from './pipeline.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/pipeline/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pipeline/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/pipeline/index.js

@@ -0,0 +1 @@
+export { ProcessingPipeline } from './pipeline.js';

package/dist/pipeline/pipeline.d.ts

@@ -0,0 +1,63 @@
+import type { CheckpointStore } from '../checkpoint/index.js';
+import type { Codec } from '../codec/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 { Dispatcher, Envelope, SubscriberDefinition } 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;
+    /** Dispatcher (matador) for sending events from subscriber callbacks */
+    readonly dispatcher: Dispatcher;
+}
+/**
+ * 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 declare class ProcessingPipeline {
+    private readonly transport;
+    private readonly schema;
+    private readonly codec;
+    private readonly retryPolicy;
+    private readonly hooks;
+    private readonly checkpointStore;
+    private readonly dispatcher;
+    constructor(config: PipelineConfig);
+    /**
+     * Processes a raw message from the transport.
+     */
+    process(rawMessage: Uint8Array, receipt: MessageReceipt): Promise<ProcessResult>;
+    private handleRetryDecision;
+    private sendToDeadLetter;
+    /**
+     * Gets retry decision for unhandled messages (subscriber not found).
+     * Uses same retry policy logic but sends to 'unhandled' DLQ after max attempts.
+     */
+    private getUnhandledRetryDecision;
+}
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/pipeline/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE1E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAM/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAEV,UAAU,EACV,QAAQ,EAER,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAG3B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACvD,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;gBAE5B,MAAM,EAAE,cAAc;IAUlC;;OAEG;IACG,OAAO,CACX,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC;YA4NX,mBAAmB;YAqCnB,gBAAgB;IAkB9B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;CA+BlC"}

package/dist/pipeline/pipeline.js

@@ -0,0 +1,273 @@
+import { NoOpCheckpointStore, ResumableContext } from '../checkpoint/index.js';
+import { CodecDecodeError } from '../codec/index.js';
+import { SubscriberIsStubError, SubscriberNotRegisteredError, } from '../errors/index.js';
+import { isResumableSubscriber } from '../types/index.js';
+/**
+ * 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 {
+    transport;
+    schema;
+    codec;
+    retryPolicy;
+    hooks;
+    checkpointStore;
+    dispatcher;
+    constructor(config) {
+        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();
+        this.dispatcher = config.dispatcher;
+    }
+    /**
+     * Processes a raw message from the transport.
+     */
+    async process(rawMessage, receipt) {
+        const startTime = performance.now();
+        // 1. Decode envelope
+        let 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;
+        let error;
+        let context;
+        // For resumable subscribers, load existing checkpoint and create context
+        const isResumable = isResumableSubscriber(subscriber);
+        let existingCheckpoint;
+        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),
+                },
+            });
+        }
+        // Create base callback context with matador dispatcher
+        const callbackContext = { matador: this.dispatcher };
+        await this.hooks.onWorkerWrap(envelope, subscriberDef, async () => {
+            await this.hooks.onWorkerBeforeProcess(envelope, subscriberDef);
+            try {
+                if (isResumable && context) {
+                    // Resumable subscriber: pass combined context (checkpoint + matador)
+                    // Cast needed because TypeScript can't narrow the union type based on isResumable
+                    const resumableCallback = subscriber.callback;
+                    // Create combined context by binding class methods and adding matador
+                    const fullContext = {
+                        io: context.io.bind(context),
+                        all: context.all.bind(context),
+                        attempt: context.attempt,
+                        isRetry: context.isRetry,
+                        matador: this.dispatcher,
+                    };
+                    result = await resumableCallback(envelope, fullContext);
+                }
+                else {
+                    // Standard subscriber: pass envelope and callback context
+                    const standardCallback = subscriber.callback;
+                    result = await standardCallback(envelope, callbackContext);
+                }
+            }
+            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,
+        };
+    }
+    async handleRetryDecision(receipt, envelope, decision) {
+        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;
+            }
+        }
+    }
+    async sendToDeadLetter(receipt, envelope, dlqName, reason) {
+        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.
+     */
+    getUnhandledRetryDecision(envelope, receipt, error) {
+        // Create a synthetic subscriber definition for retry policy
+        const syntheticSubscriber = {
+            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/dist/pipeline/pipeline.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pipeline.test.d.ts.map

package/dist/pipeline/pipeline.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.test.d.ts","sourceRoot":"","sources":["../../src/pipeline/pipeline.test.ts"],"names":[],"mappings":""}