@kronos-ts/messaging 0.1.0

package/src/span-factory.ts

@@ -0,0 +1,81 @@
+import type { Message } from "./message.js"
+
+/**
+ * A span representing a unit of tracing work.
+ * Start the span, do work, then end it.
+ *
+ */
+export interface Span {
+  /** Start the span. Returns the span for chaining. */
+  start(): Span
+  /** End the span normally. */
+  end(): void
+  /** Record an error on the span and end it. */
+  recordException(error: Error): void
+}
+
+/**
+ * Provides custom attributes to add to spans.
+ *
+ */
+export interface SpanAttributesProvider {
+  provideAttributes(message: Message): Record<string, string>
+}
+
+/**
+ * Factory for creating tracing spans around message processing.
+ *
+ * The SpanFactory is the core tracing abstraction. Implementations
+ * (e.g., OpenTelemetry) provide the actual span creation and context
+ * propagation. The framework calls these methods during dispatch and
+ * handling.
+ *
+ */
+export interface SpanFactory {
+  /** Create a root trace span (no parent). */
+  createRootTrace(operationName: string): Span
+
+  /**
+   * Create a span for handling a message (consumer side).
+   * Extracts trace context from the parent message's metadata.
+   */
+  createHandlerSpan(operationName: string, parentMessage: Message): Span
+
+  /**
+   * Create a span for dispatching a message (producer side).
+   * Links to the parent message's trace context.
+   */
+  createDispatchSpan(operationName: string, parentMessage: Message): Span
+
+  /** Create a span for internal framework operations. */
+  createInternalSpan(operationName: string): Span
+
+  /**
+   * Inject trace context into a message's metadata so it propagates
+   * across message boundaries.
+   */
+  propagateContext<M extends Message>(message: M): M
+
+  /** Register a custom span attribute provider. */
+  registerSpanAttributeProvider(provider: SpanAttributesProvider): void
+}
+
+/**
+ * A no-op span factory. Default when no tracing is configured.
+ */
+export function noOpSpanFactory(): SpanFactory {
+  const noOpSpan: Span = {
+    start() { return this },
+    end() {},
+    recordException() {},
+  }
+
+  return {
+    createRootTrace() { return noOpSpan },
+    createHandlerSpan() { return noOpSpan },
+    createDispatchSpan() { return noOpSpan },
+    createInternalSpan() { return noOpSpan },
+    propagateContext<M extends Message>(message: M) { return message },
+    registerSpanAttributeProvider() {},
+  }
+}

package/src/streaming-event-processor.ts

@@ -0,0 +1,351 @@
+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 { EventProcessingErrorHandler } from "./tracking-event-processor.js"
+import { loggingErrorHandler } from "./tracking-event-processor.js"
+import type { HandlerEnhancerDefinition } from "./handler-enhancer.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 { 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 streaming event processor that uses push-based event delivery
+ * via {@link MessageStream}.
+ *
+ * Architecture:
+ * - Opens a MessageStream from the event source via {@link StreamableEventSource.open}
+ * - When events become available (via setCallback), pulls them
+ * - Processes batches within a UnitOfWork
+ * - Stores token at PREPARE_COMMIT (same transaction as handler work)
+ *
+ */
+export interface EventProcessorStatus {
+  readonly segmentId: number
+  readonly position: bigint
+  readonly replaying: boolean
+  readonly caughtUp: boolean
+  readonly error?: Error
+}
+
+export interface StreamingEventProcessor {
+  readonly name: string
+  readonly running: boolean
+  readonly position: bigint
+  readonly replaying: boolean
+  /** Status per segment. */
+  processingStatus(): Map<number, EventProcessorStatus>
+  /** Whether this processor supports reset (always true if not running). */
+  supportsReset(): boolean
+  start(): Promise<void>
+  stop(): void
+  resetTokens(startPosition?: bigint, resetContext?: unknown): Promise<void>
+  splitSegment(segmentId: number): Promise<boolean>
+  mergeSegment(segmentId: number): Promise<boolean>
+  releaseSegment(segmentId: number): Promise<void>
+}
+
+export interface StreamingEventProcessorOptions {
+  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
+  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
+}
+
+export function createStreamingEventProcessor(
+  options: StreamingEventProcessorOptions,
+): StreamingEventProcessor {
+  const {
+    name,
+    eventSource,
+    eventHandlers,
+    stateManager,
+    commandBus,
+    queryBus,
+    onEventDelivery,
+    unitOfWorkRunner = runInNewUoW,
+    tokenStore,
+    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 processTimer: ReturnType<typeof setTimeout> | null = null
+  let processing = false
+  let caughtUp = false
+  let lastError: Error | undefined
+
+  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 processAvailable() {
+    if (!isRunning || processing) return
+    processing = true
+
+    try {
+      await processFromStream()
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err))
+      console.error(`Event processor "${name}" error:`, err)
+    } finally {
+      processing = false
+    }
+
+    if (isRunning && stream) {
+      if (stream.hasNextAvailable()) {
+        scheduleImmediate()
+      }
+    }
+  }
+
+  async function processFromStream() {
+    if (!stream) return
+
+    // Check for stream errors — reopen if needed
+    const streamError = stream.error()
+    if (streamError) {
+      console.error(`Event processor "${name}": stream error, reopening:`, streamError)
+      stream.close()
+      stream = null
+      openStream()
+      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) {
+      caughtUp = false
+      await processBatch(batch)
+      if (stream.hasNextAvailable()) {
+        scheduleImmediate()
+      }
+    } else {
+      caughtUp = true
+      if (isReplayToken(token)) {
+        token = globalSequenceToken(token.position())
+        if (tokenStore) {
+          await tokenStore.store(name, segment, token)
+        }
+      }
+    }
+  }
+
+  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)
+          // Extend claim to prevent expiry during long batches
+          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 (processTimer !== null) {
+      clearTimeout(processTimer)
+    }
+    processTimer = setTimeout(processAvailable, 0)
+  }
+
+  return {
+    get name() { return name },
+    get running() { return isRunning },
+    get position() { return token.position() },
+    get replaying() { return isReplaying(token) },
+
+    processingStatus() {
+      const status = new Map<number, EventProcessorStatus>()
+      status.set(segment, {
+        segmentId: segment,
+        position: token.position(),
+        replaying: isReplaying(token),
+        caughtUp,
+        error: lastError,
+      })
+      return status
+    },
+
+    async start() {
+      if (isRunning) return
+      await initialize()
+      isRunning = true
+      openStream()
+      scheduleImmediate()
+    },
+
+    stop() {
+      isRunning = false
+      if (processTimer !== null) {
+        clearTimeout(processTimer)
+        processTimer = 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()
+      }
+    },
+
+    async splitSegment(_segmentId: number): Promise<boolean> {
+      if (!tokenStore) return false
+      console.warn(`Processor "${name}": segment splitting requires multi-segment support (not yet implemented)`)
+      return false
+    },
+
+    async mergeSegment(_segmentId: number): Promise<boolean> {
+      if (!tokenStore) return false
+      console.warn(`Processor "${name}": segment merging requires multi-segment support (not yet implemented)`)
+      return false
+    },
+
+    async releaseSegment(_segmentId: number): Promise<void> {
+      if (!tokenStore) return
+      await tokenStore.releaseClaim(name, segment, name)
+    },
+
+    supportsReset() {
+      return !isRunning
+    },
+  }
+}

package/src/subscribing-event-processor.ts

@@ -0,0 +1,169 @@
+import { emptyMetadata, qualifiedNameToString } from "@kronos-ts/common"
+import type { EventMessage } from "./message.js"
+import type { EventHandlerRegistration } from "./handler.js"
+import type { EventHandlerDefinition } from "./event-handler.js"
+import type { UoWRunner } from "./unit-of-work.js"
+import { runInNewUoW } from "./unit-of-work.js"
+import type { EventProcessingErrorHandler } from "./tracking-event-processor.js"
+import { loggingErrorHandler } from "./tracking-event-processor.js"
+import type { SubscribableEventSource } from "./event-bus.js"
+import type { CommandBus } from "./command-bus.js"
+import type { QueryBus } from "./query-bus.js"
+import type { HandlerEnhancerDefinition } from "./handler-enhancer.js"
+import { setResource } from "./processing-state.js"
+import { STATE_MANAGER_KEY } from "@kronos-ts/eventsourcing"
+import { COMMAND_BUS_KEY } from "./send.js"
+import { QUERY_BUS_KEY } from "./emit-update.js"
+
+// Re-export for backward compatibility
+export type { SubscribableEventSource } from "./event-bus.js"
+
+/**
+ * A push-based event processor that subscribes directly to an event source.
+ *
+ * Unlike tracking/streaming processors, the subscribing processor:
+ * - Does **not** use a token store (no position tracking)
+ * - Does **not** support replay or reset
+ * - Processes events synchronously with the publisher
+ * - Is suitable for in-memory projections that don't need persistence
+ *
+ */
+export interface SubscribingEventProcessor {
+  readonly name: string
+  readonly running: boolean
+  start(): void
+  stop(): void
+  /** Always returns false — subscribing processors don't support reset. */
+  supportsReset(): boolean
+}
+
+export interface SubscribingEventProcessorOptions {
+  name: string
+  eventSource: SubscribableEventSource
+  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
+  errorHandler?: EventProcessingErrorHandler
+  /**
+   * Plan 09-01: optional handler enhancer applied to each event handler at
+   * registration time. Symmetric to TrackingEventProcessor.handlerEnhancer.
+   * When set, each registered handler is wrapped via wrapHandler with
+   * messageType "event" and the group name as handlerGroup.
+   */
+  handlerEnhancer?: HandlerEnhancerDefinition
+}
+
+/**
+ * Creates a subscribing event processor.
+ *
+ * The processor subscribes to the event source and processes events
+ * within a UnitOfWork as they arrive. Events are delivered on the
+ * publisher's call stack (synchronous with append).
+ */
+export function createSubscribingEventProcessor(
+  options: SubscribingEventProcessorOptions,
+): SubscribingEventProcessor {
+  const {
+    name,
+    eventSource,
+    eventHandlers,
+    stateManager,
+    commandBus,
+    queryBus,
+    onEventDelivery,
+    unitOfWorkRunner = runInNewUoW,
+    errorHandler = loggingErrorHandler(name),
+    handlerEnhancer,
+  } = options
+
+  // Build handler lookup: eventName → handler[]
+  // Plan 09-01: when a handlerEnhancer is supplied, wrap each handler at
+  // registration time symmetric to TrackingEventProcessor. Plan 11-02:
+  // handlerGroup is now the processor name (no separate group identity).
+  const handlerMap = new Map<string, EventHandlerRegistration<any>[]>()
+  for (const reg of eventHandlers) {
+    const eventName = qualifiedNameToString(reg.descriptor.name)
+    const enhanced = handlerEnhancer
+      ? {
+          ...reg,
+          handler: handlerEnhancer.wrapHandler(reg.handler, {
+            messageType: "event" as const,
+            messageName: eventName,
+            handlerGroup: name,
+          }),
+        }
+      : reg
+    const existing = handlerMap.get(eventName)
+    if (existing) {
+      existing.push(enhanced as EventHandlerRegistration<any>)
+    } else {
+      handlerMap.set(eventName, [enhanced as EventHandlerRegistration<any>])
+    }
+  }
+
+  let isRunning = false
+  let unsubscribe: (() => void) | null = null
+
+  async function handleEvents(events: ReadonlyArray<EventMessage>) {
+    if (!isRunning || events.length === 0) return
+
+    await unitOfWorkRunner(emptyMetadata(), async () => {
+      for (const event of events) {
+        await deliverEvent(event)
+      }
+    })
+  }
+
+  async function deliverEvent(event: EventMessage) {
+    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) {
+        // SubscribingEventProcessor doesn't have position tracking,
+        // so pass -1n as position indicator
+        await errorHandler.handleError(err, eventName, -1n)
+      }
+    }
+  }
+
+  return {
+    get name() { return name },
+    get running() { return isRunning },
+
+    start() {
+      if (isRunning) return
+      isRunning = true
+      unsubscribe = eventSource.subscribe(handleEvents)
+    },
+
+    stop() {
+      isRunning = false
+      if (unsubscribe) {
+        unsubscribe()
+        unsubscribe = null
+      }
+    },
+
+    supportsReset() {
+      return false
+    },
+  }
+}