@kronos-ts/messaging 0.1.0

package/src/subscription-query.ts

@@ -0,0 +1,173 @@
+import { resourceKey, type ResourceKey } from "@kronos-ts/common"
+import type { QueryMessage } from "./message.js"
+import {
+  processingStateStorage,
+  computeIfAbsent,
+  onAfterCommit,
+} from "./processing-state.js"
+
+/**
+ * The result of a subscription query — initial result plus a stream
+ * of incremental updates.
+ *
+ * ```typescript
+ * const result = queryGateway.subscriptionQuery(GetCourseView, { courseId: "cs-101" })
+ * const initial = await result.initialResult
+ * console.log("Initial:", initial)
+ *
+ * for await (const update of result.updates) {
+ *   console.log("Update:", update)
+ * }
+ * ```
+ */
+export interface SubscriptionQueryResult {
+  /** The initial query result (same as a regular query dispatch). */
+  readonly initialResult: Promise<unknown>
+  /** Stream of incremental updates. Completes when the subscription is closed or completed by the emitter. */
+  readonly updates: AsyncIterable<unknown>
+  /** Close the subscription and release resources. */
+  close(): void
+}
+
+/**
+ * Internal update handler — receives updates from emitUpdate() calls
+ * and buffers them for the AsyncIterable consumer.
+ */
+export interface UpdateHandler {
+  /** The original subscription query message (for filter matching). */
+  readonly query: QueryMessage
+  /** Offer an update to the buffer. Returns false if buffer is full. */
+  offer(update: unknown): boolean
+  /** Mark the subscription as complete (no more updates). */
+  complete(): void
+  /** Mark the subscription as failed. */
+  completeExceptionally(error: Error): void
+  /** Whether this handler is still active. */
+  readonly active: boolean
+}
+
+/** Resource key for deferred update tasks in ProcessingContext. */
+const UPDATE_TASKS_KEY: ResourceKey<Array<() => void>> = resourceKey("subscriptionQueryUpdateTasks")
+
+/**
+ * Defers a task to AFTER_COMMIT if a UnitOfWork is active, otherwise runs
+ * it immediately.
+ *
+ * Ensures subscription query updates are only emitted after the
+ * transaction commits successfully.
+ *
+ * UoW presence is decided by ALS state
+ * (`processingStateStorage.getStore() !== undefined`) — same precedent as
+ * `correlationDataDispatchInterceptor` (Plan 02-03) and `getActiveTransaction`
+ * (Plan 02-04). CTX-01 / Plan 03-03: vestigial `_context` parameter removed.
+ */
+export function runAfterCommitOrImmediately(task: () => void): void {
+  if (processingStateStorage.getStore() !== undefined) {
+    const tasks = computeIfAbsent(UPDATE_TASKS_KEY, () => {
+      const list: Array<() => void> = []
+      onAfterCommit(() => {
+        for (const t of list) t()
+      })
+      return list
+    })
+    tasks.push(task)
+  } else {
+    task()
+  }
+}
+
+/**
+ * Creates a bounded async buffer that implements both UpdateHandler
+ * (for the producer side) and provides an AsyncIterable (for the consumer).
+ *
+ * @param query The subscription query message
+ * @param bufferSize Maximum number of buffered updates (default: 256)
+ */
+export function createUpdateHandler(
+  query: QueryMessage,
+  bufferSize: number = 256,
+): UpdateHandler & { iterable: AsyncIterable<unknown> } {
+  const buffer: unknown[] = []
+  let completed = false
+  let error: Error | undefined
+  let waiting: { resolve: (value: IteratorResult<unknown>) => void } | null = null
+
+  function wake() {
+    if (waiting && (buffer.length > 0 || completed)) {
+      const w = waiting
+      waiting = null
+      if (buffer.length > 0) {
+        w.resolve({ value: buffer.shift()!, done: false })
+      } else {
+        w.resolve({ value: undefined, done: true })
+      }
+    }
+  }
+
+  const handler: UpdateHandler & { iterable: AsyncIterable<unknown> } = {
+    query,
+
+    offer(update: unknown): boolean {
+      if (completed) return false
+      if (buffer.length >= bufferSize) return false
+      buffer.push(update)
+      wake()
+      return true
+    },
+
+    complete() {
+      completed = true
+      wake()
+    },
+
+    completeExceptionally(err: Error) {
+      error = err
+      completed = true
+      wake()
+    },
+
+    get active() {
+      return !completed
+    },
+
+    iterable: {
+      [Symbol.asyncIterator]() {
+        return {
+          next(): Promise<IteratorResult<unknown>> {
+            // If there's buffered data, return immediately
+            if (buffer.length > 0) {
+              return Promise.resolve({ value: buffer.shift()!, done: false })
+            }
+
+            // If completed, signal done
+            if (completed) {
+              if (error) return Promise.reject(error)
+              return Promise.resolve({ value: undefined, done: true })
+            }
+
+            // Wait for data or completion
+            return new Promise((resolve, reject) => {
+              waiting = {
+                resolve(result) {
+                  if (error && result.done) {
+                    reject(error)
+                  } else {
+                    resolve(result)
+                  }
+                },
+              }
+            })
+          },
+
+          return(): Promise<IteratorResult<unknown>> {
+            completed = true
+            buffer.length = 0
+            return Promise.resolve({ value: undefined, done: true })
+          },
+        }
+      },
+    },
+  }
+
+  return handler
+}

package/src/token-store.ts

@@ -0,0 +1,211 @@
+import type { TrackingToken } from "./tracking-token.js"
+
+/**
+ * Stores tracking tokens for event processors and manages segment claims.
+ *
+ * Each processor has a name and one or more segments. The token
+ * represents the processor's position in the event stream.
+ *
+ * Claim management enables distributed processing: multiple instances
+ * of the same processor each claim different segments, preventing
+ * double-processing.
+ *
+ * Implementations should participate in the active transaction when
+ * available (via `getActiveTransaction()`) so that token updates
+ * and projection updates are atomic.
+ */
+export interface TokenStore {
+  /**
+   * Store the token for a processor segment.
+   * Called during PREPARE_COMMIT phase (same transaction as handler work).
+   * The caller must own the claim for this segment.
+   */
+  store(processorName: string, segment: number, token: TrackingToken): Promise<void>
+
+  /**
+   * Get the current token for a processor segment.
+   * Returns undefined if no token has been stored (start from beginning).
+   */
+  get(processorName: string, segment: number): Promise<TrackingToken | undefined>
+
+  /**
+   * Initialize token segments for a processor if they don't exist yet.
+   * Called once during processor startup.
+   *
+   * @param processorName The processor name
+   * @param segmentCount Number of segments to initialize
+   */
+  initializeSegments(processorName: string, segmentCount: number): Promise<void>
+
+  /**
+   * Claim a segment for processing. Returns the current token for
+   * that segment. Throws `UnableToClaimTokenError` if the segment
+   * is already claimed by another instance.
+   *
+   * @param processorName The processor name
+   * @param segment The segment ID to claim
+   * @param ownerId Unique identifier of this instance
+   */
+  claimToken(processorName: string, segment: number, ownerId: string): Promise<TrackingToken | undefined>
+
+  /**
+   * Extend the claim lease for a segment without processing.
+   * Called periodically to prevent claim expiry during long batches.
+   */
+  extendClaim(processorName: string, segment: number, ownerId: string): Promise<void>
+
+  /**
+   * Release a segment claim, allowing other instances to pick it up.
+   */
+  releaseClaim(processorName: string, segment: number, ownerId: string): Promise<void>
+
+  /**
+   * Fetch all segment IDs that have tokens for a processor.
+   * Used during startup to discover available segments.
+   */
+  fetchSegments(processorName: string): Promise<number[]>
+
+  /**
+   * Fetch segment IDs that are not currently claimed by any instance.
+   * Used to discover segments available for claiming.
+   */
+  fetchAvailableSegments(processorName: string): Promise<number[]>
+
+  /**
+   * Delete the token for a segment (e.g., after merging).
+   */
+  deleteToken(processorName: string, segment: number): Promise<void>
+}
+
+/**
+ * Thrown when a segment claim cannot be acquired (already owned by another instance).
+ */
+export class UnableToClaimTokenError extends Error {
+  constructor(processorName: string, segment: number) {
+    super(`Unable to claim token for processor "${processorName}" segment ${segment}: already claimed`)
+    this.name = "UnableToClaimTokenError"
+  }
+}
+
+/**
+ * In-memory token store with claim management.
+ * Tokens and claims are lost on restart.
+ *
+ * @param claimTimeoutMs How long a claim lasts before it can be stolen (default: 10000ms)
+ */
+export function createInMemoryTokenStore(claimTimeoutMs: number = 10000): TokenStore {
+  interface TokenEntry {
+    token: TrackingToken | undefined
+    ownerId: string | null
+    claimedAt: number
+  }
+
+  const entries = new Map<string, TokenEntry>()
+
+  function key(processorName: string, segment: number): string {
+    return `${processorName}:${segment}`
+  }
+
+  function getEntry(processorName: string, segment: number): TokenEntry | undefined {
+    return entries.get(key(processorName, segment))
+  }
+
+  function isClaimExpired(entry: TokenEntry): boolean {
+    if (!entry.ownerId) return true
+    return Date.now() - entry.claimedAt > claimTimeoutMs
+  }
+
+  return {
+    async store(processorName, segment, token) {
+      const k = key(processorName, segment)
+      const entry = entries.get(k)
+      if (entry) {
+        entry.token = token
+        entry.claimedAt = Date.now() // Refresh claim on store
+      } else {
+        entries.set(k, { token, ownerId: null, claimedAt: Date.now() })
+      }
+    },
+
+    async get(processorName, segment) {
+      return getEntry(processorName, segment)?.token
+    },
+
+    async initializeSegments(processorName, segmentCount) {
+      for (let i = 0; i < segmentCount; i++) {
+        const k = key(processorName, i)
+        if (!entries.has(k)) {
+          entries.set(k, { token: undefined, ownerId: null, claimedAt: 0 })
+        }
+      }
+    },
+
+    async claimToken(processorName, segment, ownerId) {
+      const k = key(processorName, segment)
+      const entry = entries.get(k)
+
+      if (!entry) {
+        // Segment doesn't exist yet — create and claim
+        const newEntry: TokenEntry = { token: undefined, ownerId, claimedAt: Date.now() }
+        entries.set(k, newEntry)
+        return undefined
+      }
+
+      if (entry.ownerId === ownerId) {
+        // Already owned by this instance — refresh claim
+        entry.claimedAt = Date.now()
+        return entry.token
+      }
+
+      if (isClaimExpired(entry)) {
+        // Claim expired — steal it
+        entry.ownerId = ownerId
+        entry.claimedAt = Date.now()
+        return entry.token
+      }
+
+      throw new UnableToClaimTokenError(processorName, segment)
+    },
+
+    async extendClaim(processorName, segment, ownerId) {
+      const entry = getEntry(processorName, segment)
+      if (entry && entry.ownerId === ownerId) {
+        entry.claimedAt = Date.now()
+      }
+    },
+
+    async releaseClaim(processorName, segment, ownerId) {
+      const entry = getEntry(processorName, segment)
+      if (entry && entry.ownerId === ownerId) {
+        entry.ownerId = null
+        entry.claimedAt = 0
+      }
+    },
+
+    async fetchSegments(processorName) {
+      const segments: number[] = []
+      const prefix = `${processorName}:`
+      for (const k of entries.keys()) {
+        if (k.startsWith(prefix)) {
+          segments.push(parseInt(k.slice(prefix.length), 10))
+        }
+      }
+      return segments.sort((a, b) => a - b)
+    },
+
+    async fetchAvailableSegments(processorName) {
+      const segments: number[] = []
+      const prefix = `${processorName}:`
+      for (const [k, entry] of entries) {
+        if (k.startsWith(prefix) && (!entry.ownerId || isClaimExpired(entry))) {
+          segments.push(parseInt(k.slice(prefix.length), 10))
+        }
+      }
+      return segments.sort((a, b) => a - b)
+    },
+
+    async deleteToken(processorName, segment) {
+      entries.delete(key(processorName, segment))
+    },
+  }
+}

package/src/tracing-command-bus.ts

@@ -0,0 +1,52 @@
+import type { CommandBus } from "./command-bus.js"
+import type { CommandMessage } from "./message.js"
+import type { SpanFactory } from "./span-factory.js"
+
+/**
+ * A {@link CommandBus} decorator that wraps dispatch and handler invocations
+ * with tracing spans.
+ *
+ * Dispatch creates a "dispatch" span and propagates trace context into the
+ * message metadata. Subscribe wraps each handler with a "handle" span.
+ *
+ *
+ * @param delegate  The underlying command bus to decorate.
+ * @param spanFactory  The span factory for creating tracing spans.
+ * @returns A decorated command bus with tracing instrumentation.
+ */
+export function createTracingCommandBus(
+  delegate: CommandBus,
+  spanFactory: SpanFactory,
+): CommandBus {
+  return {
+    async dispatch(message: CommandMessage): Promise<unknown> {
+      const span = spanFactory.createDispatchSpan(`dispatch(${String(message.name)})`, message).start()
+      try {
+        const propagated = spanFactory.propagateContext(message)
+        const result = await delegate.dispatch(propagated)
+        span.end()
+        return result
+      } catch (err) {
+        span.recordException(err instanceof Error ? err : new Error(String(err)))
+        throw err
+      }
+    },
+
+    subscribe(
+      commandName: string,
+      handler: (message: CommandMessage) => Promise<unknown>,
+    ): void {
+      delegate.subscribe(commandName, async (msg: CommandMessage) => {
+        const span = spanFactory.createHandlerSpan(`handle(${commandName})`, msg).start()
+        try {
+          const result = await handler(msg)
+          span.end()
+          return result
+        } catch (err) {
+          span.recordException(err instanceof Error ? err : new Error(String(err)))
+          throw err
+        }
+      })
+    },
+  }
+}

package/src/tracing-handler-enhancer.ts

@@ -0,0 +1,34 @@
+import type { HandlerEnhancerDefinition, HandlerMetadata } from "./handler-enhancer.js"
+import type { SpanFactory } from "./span-factory.js"
+
+/**
+ * Handler enhancer that wraps message handler invocations with tracing spans.
+ *
+ * Creates an internal span per handler invocation, recording the handler
+ * name and message type as context. Errors are recorded on the span.
+ *
+ */
+export function tracingHandlerEnhancerDefinition(
+  spanFactory: SpanFactory,
+): HandlerEnhancerDefinition {
+  return {
+    wrapHandler<T extends (...args: any[]) => any>(
+      handler: T,
+      metadata: HandlerMetadata,
+    ): T {
+      const spanName = `${metadata.handlerGroup}.${metadata.messageName}`
+
+      return (async (...args: any[]) => {
+        const span = spanFactory.createInternalSpan(spanName).start()
+        try {
+          const result = await handler(...args)
+          span.end()
+          return result
+        } catch (error) {
+          span.recordException(error instanceof Error ? error : new Error(String(error)))
+          throw error
+        }
+      }) as unknown as T
+    },
+  }
+}