@vytches/ddd-messaging 0.27.0 → 0.29.1

package/dist/outbox/outbox-processor.d.ts

@@ -1,6 +1,15 @@
 import { IEventBus } from '../../../contracts/src/index.ts';
 import { IOutboxMessage, IOutboxMessageHandler, OutboxMiddleware, MessagePriority } from './outbox-interfaces';
 import { IOutboxRepository } from './outbox-repository.interface';
+import { OutboxProcessorHooks } from './outbox-hooks';
+export interface RetryBackoffConfig {
+    /** Initial delay in milliseconds before first retry (default: 1000) */
+    initial: number;
+    /** Multiplier applied per subsequent attempt (default: 2) */
+    multiplier: number;
+    /** Maximum delay cap in milliseconds (default: 300_000 — 5 min) */
+    maxDelay: number;
+}
 export interface OutboxProcessorOptions {
     /** Maximum number of messages to process in one batch */
     batchSize?: number;
@@ -14,6 +23,63 @@ export interface OutboxProcessorOptions {
     messageTimeout?: number;
     /** Enable logging */
     enableLogging?: boolean;
+    /**
+     * Exponential backoff for retries.
+     * When set, failed messages are scheduled for future retry via
+     * `IOutboxRepository.scheduleRetry()` instead of immediately re-queued.
+     * If the repository's `scheduleRetry` is a no-op, messages fall back to
+     * immediate PENDING reset (legacy behavior).
+     * If omitted, immediate retry is used for all messages.
+     */
+    retryBackoff?: RetryBackoffConfig;
+    /**
+     * Optional allow-list of message types to process. When set, only messages
+     * of these types are fetched from the repository (passed through to
+     * `getUnprocessedMessages`). Lets multiple processors partition the outbox
+     * by type. Omit to process all types.
+     */
+    messageTypes?: string[];
+    /**
+     * When set, the processor periodically calls
+     * `IOutboxRepository.resetStaleProcessing()` every N ms to recover messages
+     * orphaned in `PROCESSING` by a crashed worker. Omit to disable crash recovery.
+     */
+    crashRecoveryIntervalMs?: number;
+    /**
+     * How old (in ms) a `PROCESSING` message must be before crash recovery resets
+     * it to `PENDING`. Must be `>= messageTimeout` so legitimately in-flight
+     * messages are never reset. Defaults to `max(300_000, messageTimeout)`.
+     * Setting this below `messageTimeout` throws a `RangeError` from the constructor.
+     */
+    crashRecoveryThresholdMs?: number;
+    /**
+     * When `true`, after a **full** batch (every fetched slot used) the processor
+     * re-polls immediately instead of waiting `processingInterval`, draining a
+     * backlog faster. Defaults to `false` (opt-in — no behavior change).
+     */
+    adaptiveRepoll?: boolean;
+    /**
+     * Livelock guard for `adaptiveRepoll`: after this many consecutive full
+     * batches the processor inserts an `adaptiveRepollPauseMs` pause instead of
+     * re-polling immediately, yielding the event loop. Defaults to `5`.
+     */
+    adaptiveRepollMaxConsecutive?: number;
+    /**
+     * Pause (ms) inserted once the `adaptiveRepollMaxConsecutive` guard trips.
+     * Defaults to `50`.
+     */
+    adaptiveRepollPauseMs?: number;
+    /**
+     * Random delay (0..N ms) added before the first poll on `start()`, to
+     * de-synchronize many processors that boot simultaneously. Defaults to `0`.
+     */
+    startupJitterMs?: number;
+    /**
+     * Observability callbacks (batch completion, message failure, permanent
+     * failure). Each invocation is isolated in a try/catch — a throwing hook is
+     * logged and never breaks the processing loop. Omit to disable.
+     */
+    hooks?: OutboxProcessorHooks;
 }
 export declare class OutboxProcessor {
     private readonly repository;
@@ -22,8 +88,14 @@ export declare class OutboxProcessor {
     private readonly middlewares;
     private isRunning;
     private processingTimer?;
+    private crashRecoveryTimer?;
     private readonly logger;
     constructor(repository: IOutboxRepository, options?: OutboxProcessorOptions);
+    /**
+     * Invokes an observability hook in isolation. A throwing hook is logged and
+     * swallowed so it can never break the processing loop (mitigation T3).
+     */
+    private safelyInvokeHook;
     /**
      * Registers a message handler for a specific message type
      */
@@ -61,13 +133,21 @@ export declare class OutboxProcessor {
      * **Quiescence:** if there are no pending messages, returns immediately
      * without invoking handlers.
      *
+     * @returns `{ processed, batchSize }` — `processed` is how many messages were
+     *   dispatched this batch, `batchSize` the configured limit. A full batch
+     *   (`processed >= batchSize`) signals a likely backlog. Callers that ignore
+     *   the return value are unaffected (the value was previously `void`).
      * @public
      * @stable
      * @since 0.1.0
      */
-    processBatch(): Promise<void>;
+    processBatch(): Promise<{
+        processed: number;
+        batchSize: number;
+    }>;
     /**
-     * Processes a single message through the middleware pipeline
+     * Processes a single message through the middleware pipeline.
+     * @returns `true` if the message was processed successfully, `false` if it failed.
      */
     private processMessage;
     /**
@@ -79,9 +159,29 @@ export declare class OutboxProcessor {
      */
     private handleMessageError;
     /**
-     * Schedules the next processing cycle
+     * Schedules the next processing cycle.
+     *
+     * With `adaptiveRepoll` enabled, a full batch re-polls immediately (`delay 0`)
+     * to drain a backlog — until `adaptiveRepollMaxConsecutive` consecutive full
+     * batches trip the livelock guard, after which an `adaptiveRepollPauseMs`
+     * pause is inserted. Any non-full batch resets the cadence to
+     * `processingInterval`.
+     *
+     * @param consecutiveFullBatches running count of back-to-back full batches
+     * @param delay milliseconds to wait before the next batch
      */
     private scheduleProcessing;
+    /**
+     * Schedules the next crash-recovery cycle. No-op unless
+     * `crashRecoveryIntervalMs` was configured.
+     */
+    private scheduleCrashRecovery;
+    /**
+     * Resets messages orphaned in `PROCESSING` (older than
+     * `crashRecoveryThresholdMs`) back to `PENDING` via the repository. Errors are
+     * logged, never thrown — crash recovery must not crash the processor.
+     */
+    private runCrashRecovery;
     /**
      * Logs messages if logging is enabled
      */

package/dist/outbox/outbox-repository.interface.d.ts

@@ -16,9 +16,13 @@ export declare abstract class IOutboxRepository {
      * Gets unprocessed messages from the outbox
      * @param limit Maximum number of messages to retrieve
      * @param priorityOrder Order of priority for processing (default: [CRITICAL, HIGH, NORMAL, LOW])
+     * @param messageTypes Optional allow-list of message types to fetch. When
+     *   provided, only messages whose `messageType` is in this list are returned
+     *   (e.g. `WHERE message_type IN (...)`). Omitting it fetches all types —
+     *   this parameter is optional and backward-compatible.
      * @returns Unprocessed messages
      */
-    abstract getUnprocessedMessages(limit?: number, priorityOrder?: MessagePriority[]): Promise<IOutboxMessage[]>;
+    abstract getUnprocessedMessages(limit?: number, priorityOrder?: MessagePriority[], messageTypes?: string[]): Promise<IOutboxMessage[]>;
     /**
      * Gets specific message by ID
      * @param id Message ID
@@ -58,4 +62,40 @@ export declare abstract class IOutboxRepository {
      * @returns ID of the saved message
      */
     abstract scheduleMessage<T = unknown>(message: IOutboxMessage<T>, processAfter: Date): Promise<string>;
+    /**
+     * Schedules a retry for a failed message at a specific future time.
+     *
+     * Default implementation is a no-op — repositories that do not support
+     * delayed processing will fall back to immediate retry (PENDING reset).
+     * Override this in concrete repositories to enable exponential backoff.
+     *
+     * **Multi-worker note:** `OutboxProcessor` calls `updateStatus(PENDING)` immediately
+     * before this method. In multi-worker environments, override this to perform
+     * an atomic `UPDATE ... SET status=PENDING, process_after=?` in a single statement,
+     * and ensure `getUnprocessedMessages` filters `WHERE process_after IS NULL OR process_after <= NOW()`
+     * to prevent duplicate dispatch during the window between the two calls.
+     *
+     * @param id Message ID
+     * @param processAfter When to retry the message
+     */
+    scheduleRetry(_id: string, _processAfter: Date): Promise<void>;
+    /**
+     * Resets messages stuck in `PROCESSING` back to `PENDING` so they can be
+     * re-dispatched. Used for crash recovery: if a worker dies mid-batch, its
+     * in-flight messages remain `PROCESSING` forever without this.
+     *
+     * Default implementation is a no-op returning `0` — repositories that do not
+     * track a per-message "processing since" timestamp simply opt out. Override
+     * in concrete repositories, e.g.:
+     * `UPDATE outbox_messages SET status='PENDING' WHERE status='PROCESSING' AND updated_at < olderThan`.
+     *
+     * **Safety:** implementations MUST only reset messages whose processing
+     * started strictly before `olderThan`. `OutboxProcessor` always passes a past
+     * timestamp (`now - crashRecoveryThresholdMs`, with the threshold validated to
+     * be `>= messageTimeout`), so legitimately in-flight messages are never reset.
+     *
+     * @param olderThan Reset only `PROCESSING` messages last touched before this instant
+     * @returns Number of messages reset to `PENDING`
+     */
+    resetStaleProcessing(_olderThan: Date): Promise<number>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vytches/ddd-messaging",
-  "version": "0.27.0",
+  "version": "0.29.1",
   "description": "Outbox pattern and reliable message delivery",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -36,8 +36,7 @@
     "typescript": "^5.0.0",
     "vite": "^7.3.2",
     "vite-plugin-dts": "^4.0.0",
-    "vitest": "^2.0.0",
-    "@vytches/ddd-testing": "0.27.0"
+    "vitest": "^4.0.0"
   },
   "nx": {
     "tags": [
@@ -51,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@vytches/ddd-events": "0.27.0"
+    "@vytches/ddd-events": "0.29.1"
   },
   "scripts": {
     "build": "vite build",