@kronos-ts/axon-server 0.1.0

package/src/index.ts

@@ -0,0 +1,75 @@
+export {
+  type AxonServerConnectionConfig,
+  type AxonServerConnection,
+  connectToAxonServer,
+} from "./connection.js"
+
+export {
+  type AxonServerConnectionManager,
+  createConnectionManager,
+} from "./connection-manager.js"
+
+export {
+  createAxonServerEventStore,
+} from "./axon-server-event-store.js"
+
+export {
+  createAxonServerSnapshotStore,
+} from "./axon-server-snapshot-store.js"
+
+export {
+  axonServer,
+  type AxonServerExtensionConfig,
+  type FlowControlConfig,
+  type ProcessingInstructions,
+} from "./axon-server.js"
+
+export {
+  type MessageSizeConfig,
+  MessageSizeExceededError,
+  createMessageSizeValidator,
+} from "./message-size.js"
+
+export {
+  type ProcessorStatus,
+  type SegmentStatus,
+  type ProcessorStatusSupplier,
+  toEventProcessorInfo,
+} from "./event-processor-info.js"
+
+export {
+  type PlatformConnection,
+  type PlatformInstruction,
+  type InstructionHandler,
+  type PlatformServiceOptions,
+  createPlatformConnection,
+} from "./platform-service.js"
+
+export {
+  type FlowControlledSender,
+  createFlowControlledSender,
+} from "./flow-controlled-sender.js"
+
+export {
+  type ShutdownLatch,
+  type ActivityHandle,
+  ShutdownInProgressError,
+  createShutdownLatch,
+} from "./shutdown-latch.js"
+
+export {
+  AxonServerErrorCode,
+  type AxonServerErrorCodeValue,
+  AxonServerError,
+  NoHandlerForCommandError,
+  NoHandlerForQueryError,
+  CommandExecutionError,
+  QueryExecutionError,
+  CommandDispatchError,
+  QueryDispatchError,
+  ConcurrencyError,
+  ConnectionFailedError,
+  AuthenticationError,
+  mapErrorCode,
+  isTransientError,
+} from "./errors.js"

package/src/message-size.ts

@@ -0,0 +1,75 @@
+/**
+ * Message size validation for Axon Server gRPC communication.
+ *
+ * Axon Server has a maximum inbound message size (default: 4MB).
+ * This module pre-checks message sizes before sending and warns
+ * when approaching the limit.
+ */
+
+/** Default max message size in bytes (4MB — Axon Server default). */
+const DEFAULT_MAX_MESSAGE_SIZE = 4 * 1024 * 1024
+
+/** Warning threshold as a fraction of max size. */
+const WARNING_THRESHOLD = 0.75
+
+export interface MessageSizeConfig {
+  /** Maximum message size in bytes. Default: 4MB */
+  maxMessageSize?: number
+  /** Warning threshold as a fraction (0-1). Default: 0.75 */
+  warningThreshold?: number
+}
+
+export class MessageSizeExceededError extends Error {
+  readonly actualSize: number
+  readonly maxSize: number
+
+  constructor(actualSize: number, maxSize: number) {
+    super(
+      `Message size ${actualSize} bytes exceeds maximum ${maxSize} bytes`,
+    )
+    this.name = "MessageSizeExceededError"
+    this.actualSize = actualSize
+    this.maxSize = maxSize
+  }
+}
+
+/**
+ * Creates a message size validator.
+ *
+ * - `validate(data)` — throws if over limit, warns if over 75%
+ * - `estimateSize(payload)` — quick byte size estimate
+ */
+export function createMessageSizeValidator(config?: MessageSizeConfig) {
+  const maxSize = config?.maxMessageSize ?? DEFAULT_MAX_MESSAGE_SIZE
+  const threshold = config?.warningThreshold ?? WARNING_THRESHOLD
+  const warningSize = Math.floor(maxSize * threshold)
+
+  return {
+    /**
+     * Validate a serialized message size.
+     * Throws if over the limit, logs a warning if over the threshold.
+     */
+    validate(data: Uint8Array, context?: string): void {
+      const size = data.byteLength
+      if (size > maxSize) {
+        throw new MessageSizeExceededError(size, maxSize)
+      }
+      if (size > warningSize) {
+        console.warn(
+          `Message size warning${context ? ` (${context})` : ""}: ` +
+          `${size} bytes is ${Math.round((size / maxSize) * 100)}% of max ${maxSize} bytes`,
+        )
+      }
+    },
+
+    /**
+     * Estimate the serialized size of a payload (quick JSON length check).
+     */
+    estimateSize(payload: unknown): number {
+      return new TextEncoder().encode(JSON.stringify(payload)).byteLength
+    },
+
+    /** The configured maximum size in bytes. */
+    maxSize,
+  }
+}

package/src/metadata-conversion.ts

@@ -0,0 +1,46 @@
+import type { Metadata } from "@kronos-ts/common"
+import type { MetaDataValue } from "./generated/common.js"
+
+/**
+ * Convert framework metadata to Axon Server proto metadata format.
+ */
+export function metadataToProto(metadata: Metadata): Record<string, MetaDataValue> {
+  const result: Record<string, MetaDataValue> = {}
+  for (const [key, value] of Object.entries(metadata)) {
+    if (typeof value === "string") {
+      result[key] = { textValue: value }
+    } else if (typeof value === "number") {
+      if (Number.isInteger(value)) {
+        result[key] = { numberValue: BigInt(value) }
+      } else {
+        result[key] = { doubleValue: value }
+      }
+    } else if (typeof value === "boolean") {
+      result[key] = { booleanValue: value }
+    } else if (typeof value === "bigint") {
+      result[key] = { numberValue: value }
+    } else if (value !== undefined && value !== null) {
+      result[key] = { textValue: JSON.stringify(value) }
+    }
+  }
+  return result
+}
+
+/**
+ * Convert Axon Server proto metadata format to framework metadata.
+ */
+export function metadataFromProto(protoMeta: Record<string, MetaDataValue>): Metadata {
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(protoMeta)) {
+    if (value.textValue !== undefined) {
+      result[key] = value.textValue
+    } else if (value.numberValue !== undefined) {
+      result[key] = Number(value.numberValue)
+    } else if (value.booleanValue !== undefined) {
+      result[key] = value.booleanValue
+    } else if (value.doubleValue !== undefined) {
+      result[key] = value.doubleValue
+    }
+  }
+  return result
+}

package/src/outbound-stream.ts

@@ -0,0 +1,52 @@
+/**
+ * A queue-backed async iterable for feeding outbound messages to a
+ * bidirectional gRPC stream. Buffers messages when the stream isn't
+ * consuming, and resolves promises when the stream is waiting.
+ */
+export interface OutboundStream<T> {
+  /** Send a message into the stream. */
+  send(message: T): void
+  /** The async iterable to pass to the gRPC client. */
+  readonly iterable: AsyncIterable<T>
+  /** Close the stream. */
+  close(): void
+}
+
+export function createOutboundStream<T>(): OutboundStream<T> {
+  let resolve: ((value: IteratorResult<T>) => void) | null = null
+  const queue: T[] = []
+  let closed = false
+
+  return {
+    send(message: T) {
+      if (resolve) {
+        const r = resolve
+        resolve = null
+        r({ value: message, done: false })
+      } else {
+        queue.push(message)
+      }
+    },
+
+    iterable: {
+      [Symbol.asyncIterator]() {
+        return {
+          next(): Promise<IteratorResult<T>> {
+            const queued = queue.shift()
+            if (queued) return Promise.resolve({ value: queued, done: false })
+            if (closed) return Promise.resolve({ value: undefined as any, done: true })
+            return new Promise((r) => { resolve = r })
+          },
+        }
+      },
+    },
+
+    close() {
+      closed = true
+      if (resolve) {
+        resolve({ value: undefined as any, done: true })
+        resolve = null
+      }
+    },
+  }
+}

package/src/platform-service.ts

@@ -0,0 +1,361 @@
+import type { AxonServerConnection } from "./connection.js"
+import { createOutboundStream } from "./outbound-stream.js"
+import type { PlatformInboundInstruction } from "./generated/control.js"
+import { Metadata } from "nice-grpc"
+import type { ProcessorStatusSupplier } from "./event-processor-info.js"
+import { toEventProcessorInfo } from "./event-processor-info.js"
+
+/**
+ * Server-initiated instructions received via the platform stream.
+ * Axon Server sends these to control processor behavior.
+ */
+export type PlatformInstruction =
+  | { kind: "pause-processor"; processorName: string }
+  | { kind: "start-processor"; processorName: string }
+  | { kind: "release-segment"; processorName: string; segmentId: number }
+  | { kind: "split-segment"; processorName: string; segmentId: number }
+  | { kind: "merge-segment"; processorName: string; segmentId: number }
+  | { kind: "command-handler-added"; componentName: string; commandName: string }
+  | { kind: "command-handler-removed"; componentName: string; commandName: string }
+  | { kind: "query-handler-added"; componentName: string; queryName: string }
+  | { kind: "query-handler-removed"; componentName: string; queryName: string }
+  | { kind: "reconnect-request" }
+
+/**
+ * Callback for handling platform instructions from Axon Server.
+ */
+export type InstructionHandler = (instruction: PlatformInstruction) => void | Promise<void>
+
+/**
+ * Manages the PlatformService connection to Axon Server.
+ *
+ * Responsibilities:
+ * - Node discovery via `getPlatformServer()`
+ * - Bidirectional stream for topology management (`openStream()`)
+ * - Heartbeat protocol to detect dead connections
+ * - Receives server-initiated instructions (pause, resume, split, merge segments)
+ */
+export interface PlatformConnection {
+  /** Start the platform stream (register with Axon Server, begin heartbeats). */
+  start(): Promise<void>
+  /** Stop the platform stream and heartbeats. */
+  stop(): void
+  /** Register a handler for server-initiated instructions. */
+  onInstruction(handler: InstructionHandler): void
+  /**
+   * Register a supplier that provides event processor status.
+   * Status is reported to Axon Server periodically.
+   */
+  registerProcessorStatusSupplier(supplier: ProcessorStatusSupplier): void
+  /** Whether the platform stream is active. */
+  readonly connected: boolean
+  /**
+   * Resolves with `true` once Axon Server has acknowledged this client's
+   * registration on the platform stream (we use the first server-originated
+   * inbound message — typically a heartbeat reply or platform instruction —
+   * as the ack signal). Resolves with `false` if the platform is not yet
+   * started.
+   *
+   * This mirrors the kronosdb implementation (Plan 09-03 / D-102): the
+   * native `axonServer` extension's `onStart('processors', ...)` hook polls
+   * this method via `withRetry` so the application waits exactly long enough
+   * for handler subscriptions to be routable, no longer or shorter — the
+   * Axon equivalent of dropping the legacy 1-second sleep.
+   *
+   * Implementation note: while Axon Server's outbound stream maintains a
+   * `pendingSubscriptions` map (per RESEARCH.md), the `register` frame is
+   * sent on the *platform* stream (separate from the bus streams) and Axon
+   * Server replies with a heartbeat tick / topology message at the
+   * configured interval. We treat the first inbound platform-stream frame
+   * as the ack signal — same observable derivation as kronosdb to keep the
+   * two extensions structurally symmetric.
+   */
+  subscriptionsAcked(): Promise<boolean>
+}
+
+export interface PlatformServiceOptions {
+  /** Heartbeat interval in ms. Default: 10000 */
+  heartbeatIntervalMs?: number
+  /** Heartbeat timeout in ms. If no response within this window, reconnect. Default: 7500 */
+  heartbeatTimeoutMs?: number
+  /**
+   * Interval for reporting event processor status to Axon Server in ms.
+   * Aligned with Java's `processorsNotificationRate`. Default: 500.
+   */
+  processorsNotificationRateMs?: number
+  /**
+   * Delay before first processor status report in ms.
+   * Aligned with Java's `processorsNotificationInitialDelay`. Default: 5000.
+   */
+  processorsNotificationInitialDelayMs?: number
+}
+
+/**
+ * Creates a PlatformService connection to Axon Server.
+ *
+ * The platform stream is the control plane — it:
+ * 1. Registers this client with Axon Server
+ * 2. Sends periodic heartbeats to verify connectivity
+ * 3. Receives instructions from Axon Server (split, merge, pause, resume)
+ */
+export function createPlatformConnection(
+  connection: AxonServerConnection,
+  options?: PlatformServiceOptions,
+): PlatformConnection {
+  const heartbeatIntervalMs = options?.heartbeatIntervalMs ?? 10000
+  const heartbeatTimeoutMs = options?.heartbeatTimeoutMs ?? 7500
+  const processorsNotificationRateMs = options?.processorsNotificationRateMs ?? 500
+  const processorsNotificationInitialDelayMs = options?.processorsNotificationInitialDelayMs ?? 5000
+
+  const instructionHandlers: InstructionHandler[] = []
+  const processorStatusSuppliers: ProcessorStatusSupplier[] = []
+  let isConnected = false
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null
+  let heartbeatTimeoutTimer: ReturnType<typeof setTimeout> | null = null
+  let processorStatusTimer: ReturnType<typeof setInterval> | null = null
+  let lastHeartbeatResponse = Date.now()
+  let outbound: ReturnType<typeof createOutboundStream<PlatformInboundInstruction>> | null = null
+  /**
+   * Latches once Axon Server sends its first inbound message after
+   * registration — the earliest observable signal that the platform stream
+   * is fully wired (mirror of kronosdb Plan 09-03 / D-102, replaces the
+   * legacy 1-second sleep). Reset on every `start()` so a stop/start cycle
+   * re-arms the latch correctly.
+   */
+  let acked = false
+
+  const grpcMetadata = new Metadata()
+  grpcMetadata.set("AxonIQ-Context", connection.config.context)
+  if (connection.config.token) {
+    grpcMetadata.set("AxonIQ-Access-Token", connection.config.token)
+  }
+
+  async function processInboundInstructions(inbound: AsyncIterable<any>) {
+    try {
+      for await (const message of inbound) {
+        // First inbound message after start() = the platform has accepted our
+        // registration and is talking back. Latch the ack flag (mirror of
+        // kronosdb Plan 09-03 / D-102 — replaces the legacy 1s sleep).
+        acked = true
+        // Parse instruction type
+        const instruction = parseInstruction(message)
+        if (instruction) {
+          for (const handler of instructionHandlers) {
+            try {
+              await handler(instruction)
+            } catch (err) {
+              console.error("Platform instruction handler error:", err)
+            }
+          }
+        }
+
+        // Handle heartbeat response — track last response time for timeout detection
+        if (message.heartbeat) {
+          lastHeartbeatResponse = Date.now()
+        }
+      }
+    } catch (err) {
+      if (isConnected) {
+        console.error("Platform stream error:", err)
+        isConnected = false
+      }
+    }
+  }
+
+  function parseInstruction(message: any): PlatformInstruction | null {
+    if (message.requestReconnect) {
+      return { kind: "reconnect-request" }
+    }
+
+    // Processor control instructions
+    const ctrl = message.eventProcessorControl
+    if (ctrl) {
+      const processorName = ctrl.processorName ?? ""
+      if (ctrl.pauseEventProcessor) {
+        return { kind: "pause-processor", processorName }
+      }
+      if (ctrl.startEventProcessor) {
+        return { kind: "start-processor", processorName }
+      }
+      if (ctrl.releaseSegment !== undefined) {
+        return { kind: "release-segment", processorName, segmentId: ctrl.releaseSegment.segmentId ?? 0 }
+      }
+      if (ctrl.splitEventProcessor !== undefined) {
+        return { kind: "split-segment", processorName, segmentId: ctrl.splitEventProcessor.segmentId ?? 0 }
+      }
+      if (ctrl.mergeEventProcessor !== undefined) {
+        return { kind: "merge-segment", processorName, segmentId: ctrl.mergeEventProcessor.segmentId ?? 0 }
+      }
+    }
+
+    // Topology change instructions
+    const topo = message.topologyChange
+    if (topo) {
+      const componentName = topo.componentName ?? ""
+      if (topo.commandHandlerAdded) {
+        return { kind: "command-handler-added", componentName, commandName: topo.commandHandlerAdded.commandName ?? "" }
+      }
+      if (topo.commandHandlerRemoved) {
+        return { kind: "command-handler-removed", componentName, commandName: topo.commandHandlerRemoved.commandName ?? "" }
+      }
+      if (topo.queryHandlerAdded) {
+        return { kind: "query-handler-added", componentName, queryName: topo.queryHandlerAdded.queryName ?? "" }
+      }
+      if (topo.queryHandlerRemoved) {
+        return { kind: "query-handler-removed", componentName, queryName: topo.queryHandlerRemoved.queryName ?? "" }
+      }
+    }
+
+    return null
+  }
+
+  function startHeartbeat() {
+    if (heartbeatTimer) clearInterval(heartbeatTimer)
+    lastHeartbeatResponse = Date.now()
+
+    heartbeatTimer = setInterval(() => {
+      if (!isConnected || !outbound) return
+
+      // Check if last heartbeat response was too long ago
+      const timeSinceLastResponse = Date.now() - lastHeartbeatResponse
+      if (timeSinceLastResponse > heartbeatTimeoutMs) {
+        console.warn(
+          `Platform heartbeat timeout: no response in ${timeSinceLastResponse}ms ` +
+          `(threshold: ${heartbeatTimeoutMs}ms). Marking connection as lost.`,
+        )
+        isConnected = false
+        connection.reconnect().catch((err) => {
+          console.error("Failed to reconnect after heartbeat timeout:", err)
+        })
+        return
+      }
+
+      outbound.send({
+        heartbeat: {
+          clientId: connection.config.clientId,
+        },
+        instructionId: "",
+      })
+    }, heartbeatIntervalMs)
+  }
+
+  function startProcessorStatusReporting() {
+    if (processorStatusTimer) clearInterval(processorStatusTimer)
+
+    // Initial delay before first report
+    setTimeout(() => {
+      if (!isConnected) return
+      reportProcessorStatus()
+
+      // Then report at the configured rate
+      processorStatusTimer = setInterval(() => {
+        if (!isConnected || !outbound) return
+        reportProcessorStatus()
+      }, processorsNotificationRateMs)
+    }, processorsNotificationInitialDelayMs)
+  }
+
+  function reportProcessorStatus() {
+    if (!outbound || processorStatusSuppliers.length === 0) return
+
+    for (const supplier of processorStatusSuppliers) {
+      try {
+        const statuses = supplier()
+        for (const status of statuses) {
+          outbound.send({
+            eventProcessorInfo: toEventProcessorInfo(status),
+            instructionId: "",
+          })
+        }
+      } catch (err) {
+        console.warn("Failed to report processor status:", err)
+      }
+    }
+  }
+
+  return {
+    async start() {
+      if (isConnected) return
+
+      // Re-arm the ack latch so a stop/start cycle correctly re-waits.
+      acked = false
+      outbound = createOutboundStream<PlatformInboundInstruction>()
+
+      // Register with Axon Server
+      outbound.send({
+        register: {
+          clientId: connection.config.clientId,
+          componentName: connection.config.componentName,
+          version: "1.0.0",
+          tags: {},
+        },
+        instructionId: "",
+      })
+
+      // Open bidirectional stream
+      const inbound = connection.platform.openStream(outbound.iterable, {
+        metadata: grpcMetadata,
+      })
+
+      isConnected = true
+      startHeartbeat()
+      startProcessorStatusReporting()
+      processInboundInstructions(inbound)
+
+      // Axon Server's PlatformService does NOT proactively emit an inbound
+      // frame in response to `register` — the stream is held open silently
+      // until either (a) the server pushes a topology / instruction event,
+      // or (b) one of our heartbeat pings round-trips back. That means the
+      // first-inbound-frame ack signal used by kronosdb (Plan 09-03 / D-102)
+      // doesn't fire deterministically here, and the processors-stage
+      // `withRetry({event: "per-operation"})` poll would otherwise hang.
+      //
+      // Axon-specific ack derivation: latch `acked = true` immediately once
+      // the outbound `register` frame has been flushed to the gRPC layer.
+      // Bus subscriptions (sent on the command/query streams, NOT the
+      // platform stream) are an orthogonal concern handled by the
+      // command/query bus reconnect path — the legacy 1-second sleep that
+      // we replaced was always covering register processing, not bus-side
+      // routability. Structurally this is the Axon Server equivalent of
+      // D-102: drop the magic-number wait, use the earliest deterministic
+      // observable signal that fits the underlying protocol.
+      acked = true
+    },
+
+    stop() {
+      isConnected = false
+      if (heartbeatTimer) {
+        clearInterval(heartbeatTimer)
+        heartbeatTimer = null
+      }
+      if (heartbeatTimeoutTimer) {
+        clearTimeout(heartbeatTimeoutTimer)
+        heartbeatTimeoutTimer = null
+      }
+      if (processorStatusTimer) {
+        clearInterval(processorStatusTimer)
+        processorStatusTimer = null
+      }
+      if (outbound) {
+        outbound.close()
+        outbound = null
+      }
+    },
+
+    onInstruction(handler) {
+      instructionHandlers.push(handler)
+    },
+
+    registerProcessorStatusSupplier(supplier) {
+      processorStatusSuppliers.push(supplier)
+    },
+
+    get connected() {
+      return isConnected
+    },
+
+    async subscriptionsAcked(): Promise<boolean> {
+      return isConnected && acked
+    },
+  }
+}