@kronos-ts/messaging 0.3.0 → 0.4.0

package/src/streaming-event-processor.ts

@@ -5,6 +5,14 @@ import type { StreamableEventSource, MessageStream, SequencedEvent } from "./eve
 import type { UoWRunner } from "./unit-of-work.js"
 import { runInNewUoW } from "./unit-of-work.js"
 import type { TokenStore } from "./token-store.js"
+import type { SequencedDeadLetterQueue, EnqueuePolicy, DeadLetter } from "./dead-letter-queue.js"
+import type { SequencingPolicy } from "./sequencing-policy.js"
+import { createDeadLetteringDelivery } from "./dead-lettering-handler.js"
+import { type DeadLetterListener, noOpDeadLetterListener } from "./dead-letter-listener.js"
+import {
+  type DeadLetterReprocessor,
+  createDeadLetterReprocessor,
+} from "./dead-letter-reprocessor.js"
 import type { EventProcessingErrorHandler } from "./tracking-event-processor.js"
 import { loggingErrorHandler } from "./tracking-event-processor.js"
 import type { HandlerEnhancerDefinition } from "./handler-enhancer.js"
@@ -55,6 +63,9 @@ export interface StreamingEventProcessor {
   start(): Promise<void>
   stop(): void
   resetTokens(startPosition?: bigint, resetContext?: unknown): Promise<void>
+  /** Replay parked dead letters back through the handlers (oldest matching
+   * sequence). No-op returning false when no DLQ is configured. */
+  reprocessDeadLetters(filter?: (sequenceId: string) => boolean): Promise<boolean>
   splitSegment(segmentId: number): Promise<boolean>
   mergeSegment(segmentId: number): Promise<boolean>
   releaseSegment(segmentId: number): Promise<void>
@@ -74,7 +85,27 @@ export interface StreamingEventProcessorOptions {
   onEventDelivery?: () => void
   unitOfWorkRunner?: UoWRunner
   tokenStore?: TokenStore
+  /**
+   * Dead letter queue for poison-pill handling. When set, a handler failure
+   * parks the event in the DLQ (per {@link enqueuePolicy}) and the batch
+   * commits so the token advances past it — instead of redelivering the batch
+   * forever. The enqueue runs inside the batch UnitOfWork, so it commits in the
+   * same transaction as the token update.
+   */
+  deadLetterQueue?: SequencedDeadLetterQueue
+  /** Decides whether a failed event is enqueued. Default: always enqueue. */
+  enqueuePolicy?: EnqueuePolicy
+  /** Decides each event's ordered sequence for the DLQ. Default: first tag value. */
+  sequencingPolicy?: SequencingPolicy
+  /** Observability hook for dead-letter lifecycle events. Default: no-op. */
+  deadLetterListener?: DeadLetterListener
+  /** When true, resetTokens() also clears this processor's DLQ (Axon allowReset). Default: false. */
+  resetClearsDeadLetters?: boolean
+  /** When set, automatically drains the DLQ on this interval (ms). Off by default. */
+  dlqRetryIntervalMs?: number
   batchSize?: number
+  /** Delay before retrying after a batch failure, in ms. Backs off to avoid hot-looping a deterministic failure. */
+  errorBackoffMs?: number
   errorHandler?: EventProcessingErrorHandler
   /** Optional handler enhancer applied to all event handlers at setup time. */
   handlerEnhancer?: HandlerEnhancerDefinition
@@ -95,7 +126,14 @@ export function createStreamingEventProcessor(
     onEventDelivery,
     unitOfWorkRunner = runInNewUoW,
     tokenStore,
-    batchSize = 100,
+    deadLetterQueue,
+    enqueuePolicy,
+    sequencingPolicy,
+    deadLetterListener = noOpDeadLetterListener(),
+    resetClearsDeadLetters = false,
+    dlqRetryIntervalMs,
+    batchSize = 1,
+    errorBackoffMs = 1000,
     errorHandler = loggingErrorHandler(name),
     handlerEnhancer,
     onReset,
@@ -103,6 +141,31 @@ export function createStreamingEventProcessor(
 
   const segment = 0
 
+  // Option A: when a DLQ is configured, handler failures are caught and parked
+  // (not propagated), so the batch commits and the token advances past the
+  // poison pill. Built once; invoked inside the batch UnitOfWork by deliverEvent.
+  const deadLetterDelivery = deadLetterQueue
+    ? createDeadLetteringDelivery({
+        queue: deadLetterQueue,
+        policy: enqueuePolicy,
+        sequencingPolicy,
+        listener: deadLetterListener,
+      })
+    : undefined
+
+  // Reprocessor: replays a parked letter through the same handlers, with the
+  // same ALS resources as live delivery, so dependencies resolve identically.
+  const reprocessor: DeadLetterReprocessor | undefined = deadLetterQueue
+    ? createDeadLetterReprocessor({
+        queue: deadLetterQueue,
+        policy: enqueuePolicy,
+        unitOfWorkRunner,
+        listener: deadLetterListener,
+        replay: replayDeadLetter,
+      })
+    : undefined
+  let dlqRetryTimer: ReturnType<typeof setInterval> | null = null
+
   const handlerMap = new Map<string, Array<EventHandlerRegistration<any>>>()
   for (const reg of eventHandlers) {
     const eventName = qualifiedNameToString(reg.descriptor.name)
@@ -158,6 +221,22 @@ export function createStreamingEventProcessor(
     } catch (err) {
       lastError = err instanceof Error ? err : new Error(String(err))
       console.error(`Event processor "${name}" error:`, err)
+      // Realign the live stream to the committed checkpoint. During batch
+      // accumulation the stream cursor (and any read-ahead buffer) advanced
+      // past this batch, but `token` was NOT advanced — the failing UnitOfWork
+      // never reached PREPARE_COMMIT. Closing discards the stream's buffer so
+      // the next cycle reopens at token.position() and re-reads — and thus
+      // redelivers — the failed batch. Without this the stream cursor outruns
+      // the checkpoint and the failed events are skipped until a restart.
+      // Mirrors Axon's close-and-reopen-from-token recovery. Back off before
+      // retrying so a deterministically failing handler can't hot-loop.
+      stream?.close()
+      stream = null
+      if (isRunning) {
+        if (processTimer !== null) clearTimeout(processTimer)
+        processTimer = setTimeout(processAvailable, errorBackoffMs)
+      }
+      return
     } finally {
       processing = false
     }
@@ -170,24 +249,26 @@ export function createStreamingEventProcessor(
   }
 
   async function processFromStream() {
-    if (!stream) return
+    // Lazily (re)open the stream at the committed token. The error path nulls
+    // `stream` so processing resumes from the checkpoint, not a stale cursor.
+    if (!stream) openStream()
 
     // Check for stream errors — reopen if needed
-    const streamError = stream.error()
+    const streamError = stream!.error()
     if (streamError) {
       console.error(`Event processor "${name}": stream error, reopening:`, streamError)
-      stream.close()
+      stream!.close()
       stream = null
       openStream()
       return
     }
 
     const batch: SequencedEvent[] = []
-    let event = stream.next()
+    let event = stream!.next()
     while (event && batch.length < batchSize) {
       batch.push(event)
-      if (batch.length < batchSize && stream.hasNextAvailable()) {
-        event = stream.next()
+      if (batch.length < batchSize && stream!.hasNextAvailable()) {
+        event = stream!.next()
       } else {
         break
       }
@@ -196,7 +277,7 @@ export function createStreamingEventProcessor(
     if (batch.length > 0) {
       caughtUp = false
       await processBatch(batch)
-      if (stream.hasNextAvailable()) {
+      if (stream!.hasNextAvailable()) {
         scheduleImmediate()
       }
     } else {
@@ -247,6 +328,14 @@ export function createStreamingEventProcessor(
     // Optional per-event callback (e.g. monitoring hooks registered inside the UoW).
     if (onEventDelivery) onEventDelivery()
 
+    // DLQ path: park failures, keep the batch committable (Option A). The DLQ
+    // delivery enforces per-sequence ordering and never propagates, so the
+    // errorHandler / batch-redelivery path is bypassed while a DLQ is active.
+    if (deadLetterDelivery) {
+      await deadLetterDelivery.deliver(sequencedEvent, handlers)
+      return
+    }
+
     for (const reg of handlers) {
       try {
         await reg.handler({ ...event, sequence: sequencedEvent.sequence })
@@ -256,6 +345,27 @@ export function createStreamingEventProcessor(
     }
   }
 
+  // Replay a parked dead letter through the handlers, re-establishing the same
+  // ALS resources as live delivery. Throws on the first handler failure so the
+  // reprocessor can requeue the letter (delivery is at-least-once → handlers
+  // must be idempotent).
+  async function replayDeadLetter(letter: DeadLetter): Promise<void> {
+    const event = letter.message
+    const eventName = qualifiedNameToString(event.name)
+    const handlers = handlerMap.get(eventName)
+    if (!handlers || handlers.length === 0) return
+
+    if (stateManager !== undefined) setResource(STATE_MANAGER_KEY, stateManager as any)
+    if (commandBus !== undefined) setResource(COMMAND_BUS_KEY, commandBus)
+    if (queryBus !== undefined) setResource(QUERY_BUS_KEY, queryBus)
+
+    const position =
+      typeof letter.diagnostics.position === "number" ? BigInt(letter.diagnostics.position) : 0n
+    for (const reg of handlers) {
+      await reg.handler({ ...event, sequence: position })
+    }
+  }
+
   function scheduleImmediate() {
     if (processTimer !== null) {
       clearTimeout(processTimer)
@@ -287,6 +397,13 @@ export function createStreamingEventProcessor(
       isRunning = true
       openStream()
       scheduleImmediate()
+      if (reprocessor && dlqRetryIntervalMs && dlqRetryIntervalMs > 0) {
+        dlqRetryTimer = setInterval(() => {
+          void reprocessor.reprocessAll().catch((err) => {
+            console.error(`Event processor "${name}": scheduled DLQ drain failed:`, err)
+          })
+        }, dlqRetryIntervalMs)
+      }
     },
 
     stop() {
@@ -295,12 +412,21 @@ export function createStreamingEventProcessor(
         clearTimeout(processTimer)
         processTimer = null
       }
+      if (dlqRetryTimer !== null) {
+        clearInterval(dlqRetryTimer)
+        dlqRetryTimer = null
+      }
       if (stream) {
         stream.close()
         stream = null
       }
     },
 
+    async reprocessDeadLetters(filter?: (sequenceId: string) => boolean) {
+      if (!reprocessor) return false
+      return reprocessor.reprocess(filter)
+    },
+
     async resetTokens(startPosition: bigint = 0n, resetContext?: unknown) {
       if (isRunning) {
         throw new Error(`Processor "${name}" must be stopped before resetting tokens`)
@@ -322,6 +448,12 @@ export function createStreamingEventProcessor(
         await tokenStore.store(name, segment, token)
       }
 
+      // Axon allowReset: only clear parked letters when opted in (a replay
+      // re-derives view state, making prior dead letters meaningless).
+      if (resetClearsDeadLetters && deadLetterQueue) {
+        await deadLetterQueue.clear()
+      }
+
       if (onReset) {
         await onReset()
       }

package/src/subscribing-event-processor.ts

@@ -27,6 +27,12 @@ export type { SubscribableEventSource } from "./event-bus.js"
  * - Processes events synchronously with the publisher
  * - Is suitable for in-memory projections that don't need persistence
  *
+ * It also does **not** support a dead-letter queue — deliberately. A DLQ exists
+ * to let a processor advance its token past a poison pill and reprocess later;
+ * a subscribing processor has no token and runs in the publisher's call stack,
+ * so a failure must surface to the publisher (via the error handler), not be
+ * silently parked. Use a tracking/streaming processor with `.deadLetterQueue()`
+ * when you need dead-lettering.
  */
 export interface SubscribingEventProcessor {
   readonly name: string

package/src/tracking-event-processor.ts

@@ -5,6 +5,14 @@ import type { StreamableEventSource, MessageStream, SequencedEvent } from "./eve
 import type { UoWRunner } from "./unit-of-work.js"
 import { runInNewUoW } from "./unit-of-work.js"
 import type { TokenStore } from "./token-store.js"
+import type { SequencedDeadLetterQueue, EnqueuePolicy, DeadLetter } from "./dead-letter-queue.js"
+import type { SequencingPolicy } from "./sequencing-policy.js"
+import { createDeadLetteringDelivery } from "./dead-lettering-handler.js"
+import { type DeadLetterListener, noOpDeadLetterListener } from "./dead-letter-listener.js"
+import {
+  type DeadLetterReprocessor,
+  createDeadLetterReprocessor,
+} from "./dead-letter-reprocessor.js"
 import type { TrackingToken } from "./tracking-token.js"
 import {
   globalSequenceToken,
@@ -47,6 +55,12 @@ export interface TrackingEventProcessor {
    * The processor must be stopped before calling this.
    */
   resetTokens(startPosition?: bigint, resetContext?: unknown): Promise<void>
+  /**
+   * Replay parked dead letters back through the handlers (the oldest matching
+   * sequence). No-op returning false when no DLQ is configured. Safe to call
+   * whether or not the processor is running.
+   */
+  reprocessDeadLetters(filter?: (sequenceId: string) => boolean): Promise<boolean>
 }
 
 export interface TrackingEventProcessorOptions {
@@ -63,6 +77,24 @@ export interface TrackingEventProcessorOptions {
   onEventDelivery?: () => void
   unitOfWorkRunner?: UoWRunner
   tokenStore?: TokenStore
+  /**
+   * Dead letter queue for poison-pill handling. When set, a handler failure
+   * parks the event in the DLQ (per {@link enqueuePolicy}) and the batch
+   * commits so the token advances past it — instead of redelivering the batch
+   * forever. The enqueue runs inside the batch UnitOfWork, so it commits in the
+   * same transaction as the token update.
+   */
+  deadLetterQueue?: SequencedDeadLetterQueue
+  /** Decides whether a failed event is enqueued. Default: always enqueue. */
+  enqueuePolicy?: EnqueuePolicy
+  /** Decides each event's ordered sequence for the DLQ. Default: first tag value. */
+  sequencingPolicy?: SequencingPolicy
+  /** Observability hook for dead-letter lifecycle events. Default: no-op. */
+  deadLetterListener?: DeadLetterListener
+  /** When true, resetTokens() also clears this processor's DLQ (Axon allowReset). Default: false. */
+  resetClearsDeadLetters?: boolean
+  /** When set, automatically drains the DLQ on this interval (ms). Off by default. */
+  dlqRetryIntervalMs?: number
   /** Polling interval when no events are available (ms). Default: 500. */
   pollingIntervalMs?: number
   batchSize?: number
@@ -118,8 +150,14 @@ export function createTrackingEventProcessor(
     onEventDelivery,
     unitOfWorkRunner = runInNewUoW,
     tokenStore,
+    deadLetterQueue,
+    enqueuePolicy,
+    sequencingPolicy,
+    deadLetterListener = noOpDeadLetterListener(),
+    resetClearsDeadLetters = false,
+    dlqRetryIntervalMs,
     pollingIntervalMs = 500,
-    batchSize = 100,
+    batchSize = 1,
     errorHandler = loggingErrorHandler(name),
     handlerEnhancer,
     onReset,
@@ -127,6 +165,31 @@ export function createTrackingEventProcessor(
 
   const segment = 0
 
+  // Option A: when a DLQ is configured, handler failures are caught and parked
+  // (not propagated), so the batch commits and the token advances past the
+  // poison pill. Built once; invoked inside the batch UnitOfWork by deliverEvent.
+  const deadLetterDelivery = deadLetterQueue
+    ? createDeadLetteringDelivery({
+        queue: deadLetterQueue,
+        policy: enqueuePolicy,
+        sequencingPolicy,
+        listener: deadLetterListener,
+      })
+    : undefined
+
+  // Reprocessor: replays a parked letter through the same handlers, with the
+  // same ALS resources as live delivery, so dependencies resolve identically.
+  const reprocessor: DeadLetterReprocessor | undefined = deadLetterQueue
+    ? createDeadLetterReprocessor({
+        queue: deadLetterQueue,
+        policy: enqueuePolicy,
+        unitOfWorkRunner,
+        listener: deadLetterListener,
+        replay: replayDeadLetter,
+      })
+    : undefined
+  let dlqRetryTimer: ReturnType<typeof setInterval> | null = null
+
   const handlerMap = new Map<string, Array<EventHandlerRegistration<any>>>()
   for (const reg of eventHandlers) {
     const eventName = qualifiedNameToString(reg.descriptor.name)
@@ -224,6 +287,16 @@ export function createTrackingEventProcessor(
       }
     } catch (err) {
       console.error(`Event processor "${name}" error during poll:`, err)
+      // Realign the live stream to the committed checkpoint. During batch
+      // accumulation the stream cursor (and any read-ahead buffer) advanced
+      // past this batch, but `token` was NOT advanced — the failing UnitOfWork
+      // never reached PREPARE_COMMIT. Closing discards the stream's buffer so
+      // the next poll reopens at token.position() and re-reads — and thus
+      // redelivers — the failed batch. Without this the stream cursor outruns
+      // the checkpoint and the failed events are skipped until a restart.
+      // Mirrors Axon's close-and-reopen-from-token recovery.
+      stream?.close()
+      stream = null
       if (isRunning) pollTimer = setTimeout(poll, pollingIntervalMs * 2)
     } finally {
       processing = false
@@ -266,6 +339,14 @@ export function createTrackingEventProcessor(
     // Optional per-event callback (e.g. monitoring hooks registered inside the UoW).
     if (onEventDelivery) onEventDelivery()
 
+    // DLQ path: park failures, keep the batch committable (Option A). The DLQ
+    // delivery enforces per-sequence ordering and never propagates, so the
+    // errorHandler / batch-redelivery path is bypassed while a DLQ is active.
+    if (deadLetterDelivery) {
+      await deadLetterDelivery.deliver(sequencedEvent, handlers)
+      return
+    }
+
     for (const reg of handlers) {
       try {
         await reg.handler({ ...event, sequence: sequencedEvent.sequence })
@@ -275,6 +356,27 @@ export function createTrackingEventProcessor(
     }
   }
 
+  // Replay a parked dead letter through the handlers, re-establishing the same
+  // ALS resources as live delivery. Throws on the first handler failure so the
+  // reprocessor can requeue the letter (delivery is at-least-once → handlers
+  // must be idempotent).
+  async function replayDeadLetter(letter: DeadLetter): Promise<void> {
+    const event = letter.message
+    const eventName = qualifiedNameToString(event.name)
+    const handlers = handlerMap.get(eventName)
+    if (!handlers || handlers.length === 0) return
+
+    if (stateManager !== undefined) setResource(STATE_MANAGER_KEY, stateManager as any)
+    if (commandBus !== undefined) setResource(COMMAND_BUS_KEY, commandBus)
+    if (queryBus !== undefined) setResource(QUERY_BUS_KEY, queryBus)
+
+    const position =
+      typeof letter.diagnostics.position === "number" ? BigInt(letter.diagnostics.position) : 0n
+    for (const reg of handlers) {
+      await reg.handler({ ...event, sequence: position })
+    }
+  }
+
   function scheduleImmediate() {
     if (pollTimer !== null) {
       clearTimeout(pollTimer)
@@ -293,6 +395,15 @@ export function createTrackingEventProcessor(
       await initialize()
       isRunning = true
       poll()
+      // Optional scheduled DLQ drain — operators can also trigger reprocessing
+      // manually via reprocessDeadLetters().
+      if (reprocessor && dlqRetryIntervalMs && dlqRetryIntervalMs > 0) {
+        dlqRetryTimer = setInterval(() => {
+          void reprocessor.reprocessAll().catch((err) => {
+            console.error(`Event processor "${name}": scheduled DLQ drain failed:`, err)
+          })
+        }, dlqRetryIntervalMs)
+      }
     },
 
     stop() {
@@ -301,12 +412,21 @@ export function createTrackingEventProcessor(
         clearTimeout(pollTimer)
         pollTimer = null
       }
+      if (dlqRetryTimer !== null) {
+        clearInterval(dlqRetryTimer)
+        dlqRetryTimer = null
+      }
       if (stream) {
         stream.close()
         stream = null
       }
     },
 
+    async reprocessDeadLetters(filter?: (sequenceId: string) => boolean) {
+      if (!reprocessor) return false
+      return reprocessor.reprocess(filter)
+    },
+
     async resetTokens(startPosition: bigint = 0n, resetContext?: unknown) {
       if (isRunning) {
         throw new Error(`Processor "${name}" must be stopped before resetting tokens`)
@@ -328,6 +448,13 @@ export function createTrackingEventProcessor(
         await tokenStore.store(name, segment, token)
       }
 
+      // Axon allowReset: a replay re-derives view state from scratch, so stale
+      // dead letters from the prior run are meaningless. Only clear when opted
+      // in — otherwise parked letters survive a reset for manual handling.
+      if (resetClearsDeadLetters && deadLetterQueue) {
+        await deadLetterQueue.clear()
+      }
+
       if (onReset) {
         await onReset()
       }