@kronos-ts/messaging 0.1.0

package/src/tracking-event-processor.ts

@@ -0,0 +1,336 @@
+import { emptyMetadata, qualifiedNameToString } from "@kronos-ts/common"
+import type { EventHandlerRegistration } from "./handler.js"
+import type { EventHandlerDefinition } from "./event-handler.js"
+import type { StreamableEventSource, MessageStream, SequencedEvent } from "./event-source.js"
+import type { UoWRunner } from "./unit-of-work.js"
+import { runInNewUoW } from "./unit-of-work.js"
+import type { TokenStore } from "./token-store.js"
+import type { TrackingToken } from "./tracking-token.js"
+import {
+  globalSequenceToken,
+  replayToken,
+  isReplayToken,
+  isReplaying,
+  advanceToken,
+} from "./tracking-token.js"
+import { REPLAY_STATE_KEY } from "./replay-token.js"
+import { setResource, onPrepareCommit } from "./processing-state.js"
+import type { HandlerEnhancerDefinition } from "./handler-enhancer.js"
+import type { CommandBus } from "./command-bus.js"
+import type { QueryBus } from "./query-bus.js"
+import { STATE_MANAGER_KEY } from "@kronos-ts/eventsourcing"
+import { COMMAND_BUS_KEY } from "./send.js"
+import { QUERY_BUS_KEY } from "./emit-update.js"
+
+/**
+ * A tracking event processor that reads events from a streamable event source
+ * and delivers them to registered event handlers.
+ *
+ * Uses {@link StreamableEventSource.open} to get a persistent {@link MessageStream}.
+ * Each batch of events is processed within a UnitOfWork, enabling
+ * transactional event processing and coordinated token updates.
+ *
+ * Supports replay via {@link resetTokens} — the processor can be stopped,
+ * reset to a starting position, and restarted.
+ */
+export interface TrackingEventProcessor {
+  readonly name: string
+  readonly running: boolean
+  /** Current effective position in the event stream. */
+  readonly position: bigint
+  /** Whether the processor is currently replaying events. */
+  readonly replaying: boolean
+  start(): Promise<void>
+  stop(): void
+  /**
+   * Reset the processor to replay events from a starting position.
+   * The processor must be stopped before calling this.
+   */
+  resetTokens(startPosition?: bigint, resetContext?: unknown): Promise<void>
+}
+
+export interface TrackingEventProcessorOptions {
+  name: string
+  eventSource: StreamableEventSource
+  eventHandlers: ReadonlyArray<EventHandlerDefinition>
+  /** State manager injected into ALS at handler-invocation entry (D-44). */
+  stateManager?: unknown
+  /** Command bus injected into ALS at handler-invocation entry (D-44). */
+  commandBus?: CommandBus
+  /** Query bus injected into ALS at handler-invocation entry (D-44). */
+  queryBus?: QueryBus
+  /** Optional per-event callback fired inside the UoW before handler invocation (e.g. monitoring). */
+  onEventDelivery?: () => void
+  unitOfWorkRunner?: UoWRunner
+  tokenStore?: TokenStore
+  /** Polling interval when no events are available (ms). Default: 500. */
+  pollingIntervalMs?: number
+  batchSize?: number
+  errorHandler?: EventProcessingErrorHandler
+  /** Optional handler enhancer applied to all event handlers at setup time. */
+  handlerEnhancer?: HandlerEnhancerDefinition
+  /** Reset callback invoked from resetTokens(). */
+  onReset?: () => Promise<void> | void
+}
+
+/**
+ * Determines what happens when an event handler fails.
+ */
+export interface EventProcessingErrorHandler {
+  handleError(error: unknown, eventName: string, position: bigint): void | Promise<void>
+}
+
+/**
+ * Logs errors and continues processing. Default behavior.
+ */
+export function loggingErrorHandler(processorName: string): EventProcessingErrorHandler {
+  return {
+    handleError(error, eventName, position) {
+      console.error(
+        `Event processor "${processorName}": handler failed for "${eventName}" at position ${position}:`,
+        error,
+      )
+    },
+  }
+}
+
+/**
+ * Rethrows errors, aborting the current batch and triggering rollback.
+ */
+export function propagatingErrorHandler(): EventProcessingErrorHandler {
+  return {
+    handleError(error) {
+      throw error
+    },
+  }
+}
+
+export function createTrackingEventProcessor(
+  options: TrackingEventProcessorOptions,
+): TrackingEventProcessor {
+  const {
+    name,
+    eventSource,
+    eventHandlers,
+    stateManager,
+    commandBus,
+    queryBus,
+    onEventDelivery,
+    unitOfWorkRunner = runInNewUoW,
+    tokenStore,
+    pollingIntervalMs = 500,
+    batchSize = 100,
+    errorHandler = loggingErrorHandler(name),
+    handlerEnhancer,
+    onReset,
+  } = options
+
+  const segment = 0
+
+  const handlerMap = new Map<string, Array<EventHandlerRegistration<any>>>()
+  for (const reg of eventHandlers) {
+    const eventName = qualifiedNameToString(reg.descriptor.name)
+    if (!handlerMap.has(eventName)) {
+      handlerMap.set(eventName, [])
+    }
+    const enhanced = handlerEnhancer
+      ? {
+          ...reg,
+          handler: handlerEnhancer.wrapHandler(reg.handler, {
+            messageType: "event" as const,
+            messageName: eventName,
+            handlerGroup: name,
+          }),
+        }
+      : reg
+    handlerMap.get(eventName)!.push(enhanced as EventHandlerRegistration<any>)
+  }
+
+  let token: TrackingToken = globalSequenceToken(0n)
+  let isRunning = false
+  let stream: MessageStream<SequencedEvent> | null = null
+  let pollTimer: ReturnType<typeof setTimeout> | null = null
+  let processing = false
+
+  async function initialize() {
+    if (tokenStore) {
+      await tokenStore.initializeSegments(name, 1)
+      const stored = await tokenStore.get(name, segment)
+      if (stored !== undefined) {
+        token = stored
+      }
+    }
+  }
+
+  function openStream() {
+    stream = eventSource.open({ position: token.position() })
+    stream.setCallback(() => {
+      if (isRunning && !processing) {
+        scheduleImmediate()
+      }
+    })
+  }
+
+  async function poll() {
+    if (!isRunning || processing) return
+    processing = true
+
+    try {
+      if (!stream) {
+        openStream()
+      }
+
+      // Check for stream errors — reopen if needed
+      if (stream!.error()) {
+        console.error(`Event processor "${name}": stream error, reopening:`, stream!.error())
+        stream!.close()
+        stream = null
+        openStream()
+        processing = false
+        return
+      }
+
+      const batch: SequencedEvent[] = []
+      let event = stream!.next()
+      while (event && batch.length < batchSize) {
+        batch.push(event)
+        if (batch.length < batchSize && stream!.hasNextAvailable()) {
+          event = stream!.next()
+        } else {
+          break
+        }
+      }
+
+      if (batch.length > 0) {
+        await processBatch(batch)
+        if (isRunning) {
+          if (stream!.hasNextAvailable()) {
+            scheduleImmediate()
+          }
+          // else: stream callback will wake us when events arrive
+        }
+      } else {
+        // If replay is done and no more events, unwrap
+        if (isReplayToken(token)) {
+          token = globalSequenceToken(token.position())
+          if (tokenStore) {
+            await tokenStore.store(name, segment, token)
+          }
+        }
+        // No events available — wait for callback or poll again after interval
+        if (isRunning) {
+          pollTimer = setTimeout(poll, pollingIntervalMs)
+        }
+      }
+    } catch (err) {
+      console.error(`Event processor "${name}" error during poll:`, err)
+      if (isRunning) pollTimer = setTimeout(poll, pollingIntervalMs * 2)
+    } finally {
+      processing = false
+    }
+  }
+
+  async function processBatch(batch: SequencedEvent[]) {
+    let batchEndToken: TrackingToken = token
+
+    await unitOfWorkRunner(emptyMetadata(), async () => {
+      for (const sequencedEvent of batch) {
+        setResource(REPLAY_STATE_KEY, { replaying: isReplaying(batchEndToken) })
+
+        await deliverEvent(sequencedEvent)
+
+        batchEndToken = advanceToken(batchEndToken, sequencedEvent.sequence + 1n)
+      }
+
+      if (tokenStore) {
+        onPrepareCommit(async () => {
+          await tokenStore.store(name, segment, batchEndToken)
+          await tokenStore.extendClaim(name, segment, name)
+        })
+      }
+    })
+
+    token = batchEndToken
+  }
+
+  async function deliverEvent(sequencedEvent: SequencedEvent) {
+    const event = sequencedEvent.event
+    const eventName = qualifiedNameToString(event.name)
+    const handlers = handlerMap.get(eventName)
+    if (!handlers || handlers.length === 0) return
+
+    // D-44 wiring: write framework components into ALS at per-event invocation entry.
+    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)
+    // Optional per-event callback (e.g. monitoring hooks registered inside the UoW).
+    if (onEventDelivery) onEventDelivery()
+
+    for (const reg of handlers) {
+      try {
+        await reg.handler(event.payload, event.metadata)
+      } catch (err) {
+        await errorHandler.handleError(err, eventName, sequencedEvent.sequence)
+      }
+    }
+  }
+
+  function scheduleImmediate() {
+    if (pollTimer !== null) {
+      clearTimeout(pollTimer)
+    }
+    pollTimer = setTimeout(poll, 0)
+  }
+
+  return {
+    get name() { return name },
+    get running() { return isRunning },
+    get position() { return token.position() },
+    get replaying() { return isReplaying(token) },
+
+    async start() {
+      if (isRunning) return
+      await initialize()
+      isRunning = true
+      poll()
+    },
+
+    stop() {
+      isRunning = false
+      if (pollTimer !== null) {
+        clearTimeout(pollTimer)
+        pollTimer = null
+      }
+      if (stream) {
+        stream.close()
+        stream = null
+      }
+    },
+
+    async resetTokens(startPosition: bigint = 0n, resetContext?: unknown) {
+      if (isRunning) {
+        throw new Error(`Processor "${name}" must be stopped before resetting tokens`)
+      }
+
+      const headPosition = await eventSource.getHeadPosition()
+
+      if (headPosition <= startPosition) {
+        token = globalSequenceToken(startPosition)
+      } else {
+        token = replayToken(
+          globalSequenceToken(headPosition),
+          globalSequenceToken(startPosition),
+          resetContext,
+        )
+      }
+
+      if (tokenStore) {
+        await tokenStore.store(name, segment, token)
+      }
+
+      if (onReset) {
+        await onReset()
+      }
+    },
+  }
+}

package/src/tracking-token.ts

@@ -0,0 +1,231 @@
+/**
+ * A tracking token represents a processor's position in an event stream.
+ *
+ * This interface is extensible — event store implementations can define
+ * their own token types (e.g., a PostgreSQL extension might track
+ * commit timestamps alongside sequence positions).
+ *
+ * The framework ships two built-in implementations:
+ * - `GlobalSequenceToken` — for sequential event stores (in-memory, Axon Server)
+ * - `ReplayToken` — wraps any token to mark replay-in-progress state
+ *
+ * Tokens are immutable. All operations return new instances.
+ */
+export interface TrackingToken {
+  /**
+   * Discriminant for type narrowing and serialization.
+   * Each token implementation has a unique kind string.
+   */
+  readonly kind: string
+
+  /**
+   * The effective read position in the event stream.
+   * Used by the event source to know where to start reading.
+   */
+  position(): bigint
+
+  /**
+   * Does this token's position include all events covered by the other?
+   * Returns true if every event that `other` has seen, this token has also seen.
+   *
+   * Used for replay completion detection and segment merging.
+   */
+  covers(other: TrackingToken): boolean
+
+  /**
+   * Create a token representing the lower bound of this and another token.
+   * When opening a shared stream for multiple segments, use the lower bound
+   * to ensure no events are missed by any segment.
+   */
+  lowerBound(other: TrackingToken): TrackingToken
+
+  /**
+   * Create a token representing the upper bound of this and another token.
+   * Represents the furthest position — used for segment merging.
+   */
+  upperBound(other: TrackingToken): TrackingToken
+
+  /**
+   * Check if this token represents the same position as the other.
+   * Default: `this.covers(other) && other.covers(this)`.
+   */
+  samePositionAs(other: TrackingToken): boolean
+}
+
+// ---------------------------------------------------------------------------
+// GlobalSequenceToken
+// ---------------------------------------------------------------------------
+
+export interface GlobalSequenceToken extends TrackingToken {
+  readonly kind: "global-sequence"
+  readonly sequence: bigint
+}
+
+/**
+ * Creates a token for a global-sequence event store (monotonically increasing positions).
+ * This is the default token type for in-memory stores and Axon Server.
+ */
+export function globalSequenceToken(sequence: bigint): GlobalSequenceToken {
+  return {
+    kind: "global-sequence",
+    sequence,
+    position: () => sequence,
+    covers: (other) => sequence >= other.position(),
+    lowerBound: (other) => globalSequenceToken(sequence < other.position() ? sequence : other.position()),
+    upperBound: (other) => globalSequenceToken(sequence > other.position() ? sequence : other.position()),
+    samePositionAs: (other) => sequence === other.position(),
+  }
+}
+
+/**
+ * Sentinel token representing the beginning of the event stream.
+ * A processor starting with FIRST_TOKEN will read from position 0.
+ */
+export const FIRST_TOKEN: TrackingToken = globalSequenceToken(0n)
+
+/**
+ * Sentinel token representing the tail of the event stream.
+ * A processor starting with LATEST_TOKEN will skip all existing events
+ * and only process new events appended after startup.
+ */
+export const LATEST_TOKEN: TrackingToken = {
+  kind: "latest",
+  position: () => BigInt(Number.MAX_SAFE_INTEGER),
+  covers: () => true,
+  lowerBound: (other) => other,
+  upperBound: () => LATEST_TOKEN,
+  samePositionAs: (other) => other === LATEST_TOKEN || (other.kind === "latest"),
+}
+
+// ---------------------------------------------------------------------------
+// ReplayToken
+// ---------------------------------------------------------------------------
+
+export interface ReplayToken extends TrackingToken {
+  readonly kind: "replay"
+  /** The wrapped token representing current progress during replay. */
+  readonly currentToken: TrackingToken
+  /** The token representing the position when reset was triggered. Events before this are replayed. */
+  readonly tokenAtReset: TrackingToken
+  /** Optional user-provided context (e.g., reason for the reset). */
+  readonly resetContext?: unknown
+}
+
+/**
+ * Creates a replay token that wraps another token to mark replay-in-progress.
+ *
+ * During replay, events are re-delivered from `currentToken` up to `tokenAtReset`.
+ * Once `currentToken.covers(tokenAtReset)`, the replay is complete and the
+ * token unwraps to the current position.
+ *
+ * @param tokenAtReset The head position when reset was triggered
+ * @param currentToken Where replay is currently reading from
+ * @param resetContext Optional user-provided context
+ */
+export function replayToken(
+  tokenAtReset: TrackingToken,
+  currentToken: TrackingToken,
+  resetContext?: unknown,
+): ReplayToken {
+  return {
+    kind: "replay",
+    currentToken,
+    tokenAtReset,
+    resetContext,
+
+    position: () => currentToken.position(),
+
+    covers: (other) => currentToken.covers(other),
+
+    lowerBound: (other) => {
+      const inner = currentToken.lowerBound(other)
+      // If the lower bound is still within replay range, keep the replay wrapper
+      if (!inner.covers(tokenAtReset)) {
+        return replayToken(tokenAtReset, inner, resetContext)
+      }
+      return inner
+    },
+
+    upperBound: (other) => {
+      const inner = currentToken.upperBound(other)
+      // If the upper bound has passed the reset point, replay is done
+      if (inner.covers(tokenAtReset)) {
+        return inner
+      }
+      return replayToken(tokenAtReset, inner, resetContext)
+    },
+
+    samePositionAs: (other) => currentToken.samePositionAs(other),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+export function isReplayToken(token: TrackingToken): token is ReplayToken {
+  return token.kind === "replay"
+}
+
+export function isGlobalSequenceToken(token: TrackingToken): token is GlobalSequenceToken {
+  return token.kind === "global-sequence"
+}
+
+// ---------------------------------------------------------------------------
+// Token operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Advance a token to a new position. If the token is a ReplayToken and
+ * the new position covers the reset point, unwraps to a plain token.
+ */
+export function advanceToken(token: TrackingToken, newPosition: bigint): TrackingToken {
+  const advanced = globalSequenceToken(newPosition)
+
+  if (!isReplayToken(token)) {
+    return advanced
+  }
+
+  // Check if replay is complete
+  if (advanced.covers(token.tokenAtReset)) {
+    return advanced
+  }
+
+  // Still replaying — wrap the advanced position
+  return replayToken(token.tokenAtReset, advanced, token.resetContext)
+}
+
+/**
+ * Check whether the given token represents a replay in progress.
+ * Returns true if the token is a ReplayToken AND the current position
+ * has not yet passed the reset position.
+ *
+ * A ReplayToken that has been fully replayed (current covers reset)
+ * would have been unwrapped by advanceToken — so any ReplayToken
+ * that still exists is mid-replay.
+ */
+export function isReplaying(token: TrackingToken): boolean {
+  return isReplayToken(token)
+}
+
+/**
+ * Unwrap a token to its innermost non-replay token.
+ * If the token is not a ReplayToken, returns it unchanged.
+ */
+export function unwrapToken(token: TrackingToken): TrackingToken {
+  if (isReplayToken(token)) {
+    return unwrapToken(token.currentToken)
+  }
+  return token
+}
+
+/**
+ * Check if an event at the given position was already processed before
+ * the reset (i.e., it's a replayed event, not a new one).
+ *
+ * Uses the token's `covers()` semantics: if the reset token covers
+ * the event position, then the event existed before the reset.
+ */
+export function wasProcessedBeforeReset(token: ReplayToken, eventPosition: bigint): boolean {
+  return token.tokenAtReset.covers(globalSequenceToken(eventPosition))
+}

package/src/transaction.ts

@@ -0,0 +1,98 @@
+import { resourceKey, type ResourceKey } from "@kronos-ts/common"
+import {
+  processingStateStorage,
+  setResource,
+  on,
+  onError,
+  Phase,
+} from "./processing-state.js"
+import type { UoWRunner } from "./unit-of-work.js"
+
+/**
+ * Manages transaction lifecycle. Users provide an implementation
+ * for their specific database/ORM.
+ *
+ * The framework calls begin/commit/rollback — users never touch these directly.
+ */
+export interface TransactionManager<T = unknown> {
+  begin(): Promise<T>
+  commit(tx: T): Promise<void>
+  rollback(tx: T): Promise<void>
+}
+
+/**
+ * A no-op transaction manager for when no database transactions are needed.
+ */
+export function noTransactionManager(): TransactionManager<void> {
+  return {
+    begin: async () => {},
+    commit: async () => {},
+    rollback: async () => {},
+  }
+}
+
+/** Resource key for storing the active transaction in the active UnitOfWork's ALS-backed resources. */
+export const TRANSACTION_KEY: ResourceKey<unknown> = resourceKey("transaction")
+
+/**
+ * Get the active transaction from the active UnitOfWork's ALS-backed resources.
+ * Returns undefined if no UnitOfWork is active or no transaction has been stored.
+ *
+ * ORM integrations use this to participate in the framework's transaction:
+ * ```
+ * const db = drizzle(pool, {
+ *   transaction: () => getActiveTransaction(),
+ * })
+ * ```
+ *
+ * Permissive undefined-return preserved (D-12 / D-23): callers outside a UoW
+ * get `undefined`, NOT a NoActiveUnitOfWork throw — this is an ORM escape hatch,
+ * not a framework-internal accessor.
+ */
+export function getActiveTransaction<T = unknown>(): T | undefined {
+  const state = processingStateStorage.getStore()
+  if (!state) return undefined
+  return state.resources.get(TRANSACTION_KEY.symbol) as T | undefined
+}
+
+/**
+ * Wraps a delegate runner with transaction management. The transaction is:
+ * - Started before the delegate's action runs
+ * - Available via `getActiveTransaction()` throughout
+ * - Committed in the COMMIT phase
+ * - Rolled back on error
+ *
+ * The transaction is stored as a resource on the active UoW's ALS state,
+ * so all phases (PRE_INVOCATION through AFTER_COMMIT) and any code calling
+ * `getActiveTransaction()` inside the UoW see it.
+ *
+ * ```
+ * const txRunner = transactionalUnitOfWorkFactory(runInUoW, myTransactionManager)
+ * await txRunner(metadata, async () => { ... })
+ * ```
+ *
+ * Plan 03-04 (CTX-04 / D-34): rewritten as a composable runner wrapper.
+ * Previously took/returned `UnitOfWorkFactory`; the UoW interface and
+ * factory are gone, so this now takes/returns `UoWRunner`. The name is
+ * preserved despite the shape change — public docs and extension code
+ * import `transactionalUnitOfWorkFactory` by name. Phase 9 (Extension
+ * Migration) can rename if the kronos() app API warrants.
+ */
+export function transactionalUnitOfWorkFactory<T>(
+  delegate: UoWRunner,
+  txManager: TransactionManager<T>,
+): UoWRunner {
+  return async (metadata, action) => {
+    const tx = await txManager.begin()
+    return delegate(metadata, async () => {
+      setResource(TRANSACTION_KEY, tx)
+      on(Phase.COMMIT, async () => {
+        await txManager.commit(tx)
+      })
+      onError(async () => {
+        await txManager.rollback(tx)
+      })
+      return action()
+    })
+  }
+}