@kronos-ts/axon-server 0.1.0

package/src/connection-manager.ts

@@ -0,0 +1,88 @@
+import type { AxonServerConnectionConfig, AxonServerConnection } from "./connection.js"
+import { connectToAxonServer } from "./connection.js"
+
+/**
+ * Manages Axon Server connections across multiple contexts.
+ *
+ * Creates and caches one connection per context. Used by the multi-tenancy
+ * extension to maintain separate channels for each tenant's context.
+ *
+ * Aligned with Java's `AxonServerConnectionManager`.
+ *
+ * ```typescript
+ * const manager = createConnectionManager({
+ *   componentName: "my-app",
+ *   host: "axon-server",
+ *   port: 8124,
+ * })
+ *
+ * const defaultConn = manager.getConnection("default")
+ * const tenantConn = manager.getConnection("tenant-a")
+ *
+ * await manager.disconnectAll()
+ * ```
+ */
+export interface AxonServerConnectionManager {
+  /**
+   * Get or create a connection for the given context.
+   * Connections are created lazily and cached.
+   */
+  getConnection(context: string): AxonServerConnection
+
+  /**
+   * Disconnect a specific context's connection.
+   */
+  disconnect(context: string): void
+
+  /**
+   * Disconnect all cached connections.
+   */
+  disconnectAll(): void
+
+  /**
+   * List all active context names.
+   */
+  activeContexts(): string[]
+}
+
+/**
+ * Creates a connection manager that lazily creates per-context connections.
+ *
+ * The base config (host, port, SSL, etc.) is shared across all contexts.
+ * Only the `context` field varies per connection.
+ */
+export function createConnectionManager(
+  baseConfig: Omit<AxonServerConnectionConfig, "context">,
+): AxonServerConnectionManager {
+  const connections = new Map<string, AxonServerConnection>()
+
+  return {
+    getConnection(context: string): AxonServerConnection {
+      let connection = connections.get(context)
+      if (!connection) {
+        connection = connectToAxonServer({ ...baseConfig, context })
+        connections.set(context, connection)
+      }
+      return connection
+    },
+
+    disconnect(context: string): void {
+      const connection = connections.get(context)
+      if (connection) {
+        connection.close()
+        connections.delete(context)
+      }
+    },
+
+    disconnectAll(): void {
+      for (const connection of connections.values()) {
+        connection.close()
+      }
+      connections.clear()
+    },
+
+    activeContexts(): string[] {
+      return [...connections.keys()]
+    },
+  }
+}

package/src/connection.ts

@@ -0,0 +1,272 @@
+import { createChannel, createClient, type Channel, type Client, type ChannelCredentials } from "nice-grpc"
+import { ChannelCredentials as GrpcChannelCredentials } from "@grpc/grpc-js"
+import { Metadata } from "nice-grpc"
+import { readFileSync } from "node:fs"
+import { PlatformServiceDefinition } from "./generated/control.js"
+import { CommandServiceDefinition } from "./generated/command.js"
+import { QueryServiceDefinition } from "./generated/query.js"
+import { DcbEventStoreDefinition, DcbSnapshotStoreDefinition } from "./generated/dcb.js"
+
+/**
+ * Configuration for connecting to Axon Server.
+ */
+export interface AxonServerConnectionConfig {
+  /**
+   * Host of the Axon Server. Defaults to "localhost".
+   * For single-server setups.
+   */
+  host?: string
+  /** gRPC port of the Axon Server. Defaults to 8124. */
+  port?: number
+  /**
+   * Multiple server addresses for cluster deployments.
+   * Each entry is `"host:port"`. When provided, overrides `host` and `port`.
+   * The connector tries servers in order until one connects, and fails over
+   * to the next on connection failure.
+   *
+   * Aligned with Java's `axon.axonserver.servers` property.
+   */
+  servers?: string[]
+  /** The context to connect to. Defaults to "default". */
+  context?: string
+  /** Name identifying this component to Axon Server. */
+  componentName: string
+  /** Unique client identifier. Defaults to a generated UUID. */
+  clientId?: string
+  /** Access token for authentication. Optional. */
+  token?: string
+  /** Reconnection interval in ms. Defaults to 2000. */
+  reconnectIntervalMs?: number
+  /** Maximum reconnection attempts before giving up. 0 = unlimited. Defaults to 0. */
+  maxReconnectAttempts?: number
+
+  /**
+   * gRPC keepalive ping interval in ms.
+   * Sends a ping after this period of inactivity to keep the connection alive.
+   * Default: 30000. Java's default is 1000ms but @grpc/grpc-js requires
+   * a minimum of 10000ms to avoid server-side RST_STREAM rejections.
+   */
+  keepAliveTimeMs?: number
+  /**
+   * gRPC keepalive timeout in ms.
+   * Connection is considered dead if no response within this window.
+   * Default: 10000.
+   */
+  keepAliveTimeoutMs?: number
+  /**
+   * Allow keepalive pings even when there are no active RPCs.
+   * Default: true.
+   */
+  keepAlivePermitWithoutCalls?: boolean
+
+  /**
+   * TLS/SSL configuration. When enabled, the connection uses a secure gRPC channel.
+   * Aligned with Java's `axon.axonserver.ssl-enabled` and `axon.axonserver.cert-file`.
+   */
+  ssl?: {
+    /** Enable TLS. When true, a secure channel is created. */
+    enabled: boolean
+    /**
+     * Path to the CA certificate file (PEM format) for server verification.
+     * If omitted, the system's default trust store is used.
+     */
+    certFile?: string
+    /**
+     * Path to the client certificate file (PEM) for mutual TLS.
+     * Only needed if Axon Server requires client certificates.
+     */
+    clientCertFile?: string
+    /**
+     * Path to the client private key file (PEM) for mutual TLS.
+     * Only needed if Axon Server requires client certificates.
+     */
+    clientKeyFile?: string
+  }
+}
+
+export type ConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting" | "closed"
+
+/**
+ * An active connection to Axon Server, providing typed gRPC clients
+ * for all services. Supports reconnection on failure.
+ */
+export interface AxonServerConnection {
+  /** The underlying gRPC channel. */
+  readonly channel: Channel
+  /** Platform service — connection management, topology. */
+  readonly platform: Client<typeof PlatformServiceDefinition>
+  /** Command service — dispatch and handle commands. */
+  readonly commands: Client<typeof CommandServiceDefinition>
+  /** Query service — dispatch and handle queries. */
+  readonly queries: Client<typeof QueryServiceDefinition>
+  /** Event store — event sourcing with Dynamic Consistency Boundaries. */
+  readonly eventStore: Client<typeof DcbEventStoreDefinition>
+  /** Snapshot store — state snapshots. */
+  readonly snapshotStore: Client<typeof DcbSnapshotStoreDefinition>
+  /** The resolved configuration. `servers` and `ssl` stay optional — they have no defaults. */
+  readonly config: Omit<Required<AxonServerConnectionConfig>, "servers" | "ssl"> & {
+    servers?: AxonServerConnectionConfig["servers"]
+    ssl?: AxonServerConnectionConfig["ssl"]
+  }
+  /** Current connection state. */
+  readonly state: ConnectionState
+  /**
+   * Register a callback invoked when the connection is (re)established.
+   * Used by buses to re-subscribe handlers after reconnection.
+   */
+  onReconnect(callback: () => void): void
+  /**
+   * Register a callback invoked when the connection is lost.
+   */
+  onDisconnect(callback: (error?: Error) => void): void
+  /** Close the connection permanently. No reconnection after this. */
+  close(): void
+  /**
+   * Attempt to reconnect if disconnected.
+   * Returns a promise that resolves when reconnected or rejects on failure.
+   */
+  reconnect(): Promise<void>
+}
+
+/**
+ * Connects to Axon Server and returns typed gRPC clients for all services.
+ *
+ * Configures gRPC channel-level keepalive to maintain persistent connections,
+ * aligned with Java's ManagedChannel keepalive settings.
+ */
+export function connectToAxonServer(config: AxonServerConnectionConfig): AxonServerConnection {
+  const resolvedConfig = {
+    host: config.host ?? "localhost",
+    port: config.port ?? 8124,
+    context: config.context ?? "default",
+    componentName: config.componentName,
+    clientId: config.clientId ?? crypto.randomUUID(),
+    token: config.token ?? "",
+    reconnectIntervalMs: config.reconnectIntervalMs ?? 2000,
+    maxReconnectAttempts: config.maxReconnectAttempts ?? 0,
+    keepAliveTimeMs: config.keepAliveTimeMs ?? 30000,
+    keepAliveTimeoutMs: config.keepAliveTimeoutMs ?? 10000,
+    keepAlivePermitWithoutCalls: config.keepAlivePermitWithoutCalls ?? true,
+    servers: config.servers,
+    ssl: config.ssl,
+  }
+
+  // Build gRPC channel credentials
+  const sslConfig = config.ssl
+  let credentials: ChannelCredentials | undefined
+
+  if (sslConfig?.enabled) {
+    const rootCerts = sslConfig.certFile ? readFileSync(sslConfig.certFile) : null
+    const clientKey = sslConfig.clientKeyFile ? readFileSync(sslConfig.clientKeyFile) : null
+    const clientCert = sslConfig.clientCertFile ? readFileSync(sslConfig.clientCertFile) : null
+    credentials = GrpcChannelCredentials.createSsl(rootCerts, clientKey, clientCert) as ChannelCredentials
+  }
+
+  // gRPC channel options — keepalive to maintain persistent connections
+  const channelOptions = {
+    "grpc.keepalive_time_ms": config.keepAliveTimeMs ?? 30000,
+    "grpc.keepalive_timeout_ms": config.keepAliveTimeoutMs ?? 10000,
+    "grpc.keepalive_permit_without_calls": (config.keepAlivePermitWithoutCalls ?? true) ? 1 : 0,
+  }
+
+  // Build server address list for failover
+  const serverAddresses = config.servers && config.servers.length > 0
+    ? config.servers
+    : [`${resolvedConfig.host}:${resolvedConfig.port}`]
+
+  let currentServerIndex = 0
+
+  function createGrpcChannel(): Channel {
+    const address = serverAddresses[currentServerIndex % serverAddresses.length]!
+    return credentials
+      ? createChannel(address, credentials, channelOptions)
+      : createChannel(address, undefined, channelOptions)
+  }
+
+  let channel = createGrpcChannel()
+  let state: ConnectionState = "connected"
+
+  const reconnectCallbacks: Array<() => void> = []
+  const disconnectCallbacks: Array<(error?: Error) => void> = []
+
+  function createClients() {
+    return {
+      platform: createClient(PlatformServiceDefinition, channel),
+      commands: createClient(CommandServiceDefinition, channel),
+      queries: createClient(QueryServiceDefinition, channel),
+      eventStore: createClient(DcbEventStoreDefinition, channel),
+      snapshotStore: createClient(DcbSnapshotStoreDefinition, channel),
+    }
+  }
+
+  let clients = createClients()
+
+  const connection: AxonServerConnection = {
+    get channel() { return channel },
+    get platform() { return clients.platform },
+    get commands() { return clients.commands },
+    get queries() { return clients.queries },
+    get eventStore() { return clients.eventStore },
+    get snapshotStore() { return clients.snapshotStore },
+    config: resolvedConfig,
+
+    get state() { return state },
+
+    onReconnect(callback) {
+      reconnectCallbacks.push(callback)
+    },
+
+    onDisconnect(callback) {
+      disconnectCallbacks.push(callback)
+    },
+
+    close() {
+      state = "closed"
+      channel.close()
+    },
+
+    async reconnect() {
+      if (state === "closed") {
+        throw new Error("Connection is permanently closed")
+      }
+      if (state === "connected" || state === "connecting") return
+
+      state = "reconnecting"
+      const maxAttempts = resolvedConfig.maxReconnectAttempts
+      let attempt = 0
+
+      while (state === "reconnecting") {
+        attempt++
+        try {
+          // Try the next server in the list on each reconnect attempt
+          currentServerIndex++
+          channel = createGrpcChannel()
+          clients = createClients()
+          state = "connected"
+
+          // Notify listeners that we're back
+          for (const cb of reconnectCallbacks) {
+            try { cb() } catch { /* ignore listener errors */ }
+          }
+          return
+        } catch (err) {
+          if (maxAttempts > 0 && attempt >= maxAttempts) {
+            state = "disconnected"
+            throw new Error(
+              `Failed to reconnect after ${attempt} attempts: ${err}`,
+            )
+          }
+
+          // Exponential backoff: base interval * 2^attempt, capped at 30s
+          const delay = Math.min(
+            resolvedConfig.reconnectIntervalMs * Math.pow(2, attempt - 1),
+            30000,
+          )
+          await new Promise((r) => setTimeout(r, delay))
+        }
+      }
+    },
+  }
+
+  return connection
+}

package/src/errors.ts

@@ -0,0 +1,223 @@
+/**
+ * Axon Server error codes — mapped from the Java framework's ErrorCode enum.
+ *
+ * Error codes follow the AXONIQ-XXXX pattern where the first digit
+ * indicates the category:
+ * - 1xxx: Authentication/instruction errors
+ * - 2xxx: Event publishing errors
+ * - 3xxx: Communication errors
+ * - 4xxx: Command errors
+ * - 5xxx: Query errors
+ * - 9xxx: Internal/storage errors
+ */
+export const AxonServerErrorCode = {
+  // Authentication & instructions
+  AUTHENTICATION_TOKEN_MISSING: "AXONIQ-1000",
+  AUTHENTICATION_INVALID_TOKEN: "AXONIQ-1001",
+  UNSUPPORTED_INSTRUCTION: "AXONIQ-1002",
+  INSTRUCTION_ACK_ERROR: "AXONIQ-1003",
+  INSTRUCTION_EXECUTION_ERROR: "AXONIQ-1004",
+
+  // Event publishing
+  EVENT_PAYLOAD_TOO_LARGE: "AXONIQ-2001",
+  NO_EVENT_STORE_MASTER_AVAILABLE: "AXONIQ-2100",
+  CONCURRENCY_EXCEPTION: "AXONIQ-2000",
+
+  // Communication
+  CONNECTION_FAILED: "AXONIQ-3001",
+  GRPC_MESSAGE_TOO_LARGE: "AXONIQ-3002",
+
+  // Commands
+  NO_HANDLER_FOR_COMMAND: "AXONIQ-4000",
+  COMMAND_EXECUTION_ERROR: "AXONIQ-4002",
+  COMMAND_DISPATCH_ERROR: "AXONIQ-4003",
+  COMMAND_CONCURRENCY_ERROR: "AXONIQ-4004",
+  COMMAND_EXECUTION_NON_TRANSIENT_ERROR: "AXONIQ-4005",
+
+  // Queries
+  NO_HANDLER_FOR_QUERY: "AXONIQ-5000",
+  QUERY_EXECUTION_ERROR: "AXONIQ-5001",
+  QUERY_DISPATCH_ERROR: "AXONIQ-5002",
+  QUERY_EXECUTION_NON_TRANSIENT_ERROR: "AXONIQ-5003",
+
+  // Internal/storage
+  DATAFILE_READ_ERROR: "AXONIQ-9000",
+  INDEX_READ_ERROR: "AXONIQ-9001",
+  DATAFILE_WRITE_ERROR: "AXONIQ-9100",
+  INDEX_WRITE_ERROR: "AXONIQ-9101",
+  DIRECTORY_CREATION_FAILED: "AXONIQ-9102",
+  VALIDATION_FAILED: "AXONIQ-9200",
+  TRANSACTION_ROLLED_BACK: "AXONIQ-9900",
+
+  // Default
+  OTHER: "AXONIQ-0001",
+} as const
+
+export type AxonServerErrorCodeValue = typeof AxonServerErrorCode[keyof typeof AxonServerErrorCode]
+
+// ---------------------------------------------------------------------------
+// Exception hierarchy
+// ---------------------------------------------------------------------------
+
+/**
+ * Base error for all Axon Server errors. Carries the error code
+ * and whether the error is transient (retryable).
+ */
+export class AxonServerError extends Error {
+  readonly errorCode: string
+  readonly transient: boolean
+
+  constructor(message: string, errorCode: string, transient: boolean) {
+    super(message)
+    this.name = "AxonServerError"
+    this.errorCode = errorCode
+    this.transient = transient
+  }
+}
+
+/** No handler registered for the dispatched command. */
+export class NoHandlerForCommandError extends AxonServerError {
+  constructor(message: string) {
+    super(message, AxonServerErrorCode.NO_HANDLER_FOR_COMMAND, false)
+    this.name = "NoHandlerForCommandError"
+  }
+}
+
+/** No handler registered for the dispatched query. */
+export class NoHandlerForQueryError extends AxonServerError {
+  constructor(message: string) {
+    super(message, AxonServerErrorCode.NO_HANDLER_FOR_QUERY, false)
+    this.name = "NoHandlerForQueryError"
+  }
+}
+
+/** Command handler execution failed (transient — may succeed on retry). */
+export class CommandExecutionError extends AxonServerError {
+  constructor(message: string, transient: boolean = true) {
+    super(
+      message,
+      transient
+        ? AxonServerErrorCode.COMMAND_EXECUTION_ERROR
+        : AxonServerErrorCode.COMMAND_EXECUTION_NON_TRANSIENT_ERROR,
+      transient,
+    )
+    this.name = "CommandExecutionError"
+  }
+}
+
+/** Query handler execution failed (transient — may succeed on retry). */
+export class QueryExecutionError extends AxonServerError {
+  constructor(message: string, transient: boolean = true) {
+    super(
+      message,
+      transient
+        ? AxonServerErrorCode.QUERY_EXECUTION_ERROR
+        : AxonServerErrorCode.QUERY_EXECUTION_NON_TRANSIENT_ERROR,
+      transient,
+    )
+    this.name = "QueryExecutionError"
+  }
+}
+
+/** Command dispatch failed (infrastructure error). */
+export class CommandDispatchError extends AxonServerError {
+  constructor(message: string) {
+    super(message, AxonServerErrorCode.COMMAND_DISPATCH_ERROR, true)
+    this.name = "CommandDispatchError"
+  }
+}
+
+/** Query dispatch failed (infrastructure error). */
+export class QueryDispatchError extends AxonServerError {
+  constructor(message: string) {
+    super(message, AxonServerErrorCode.QUERY_DISPATCH_ERROR, true)
+    this.name = "QueryDispatchError"
+  }
+}
+
+/** Optimistic concurrency violation (transient — retry with fresh state). */
+export class ConcurrencyError extends AxonServerError {
+  constructor(message: string) {
+    super(message, AxonServerErrorCode.CONCURRENCY_EXCEPTION, true)
+    this.name = "ConcurrencyError"
+  }
+}
+
+/** Connection to Axon Server failed. */
+export class ConnectionFailedError extends AxonServerError {
+  constructor(message: string) {
+    super(message, AxonServerErrorCode.CONNECTION_FAILED, true)
+    this.name = "ConnectionFailedError"
+  }
+}
+
+/** Authentication/authorization failed. */
+export class AuthenticationError extends AxonServerError {
+  constructor(message: string, code: string) {
+    super(message, code, false)
+    this.name = "AuthenticationError"
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Error code → exception mapping
+// ---------------------------------------------------------------------------
+
+const TRANSIENT_CODES = new Set<string>([
+  AxonServerErrorCode.COMMAND_EXECUTION_ERROR,
+  AxonServerErrorCode.QUERY_EXECUTION_ERROR,
+  AxonServerErrorCode.COMMAND_DISPATCH_ERROR,
+  AxonServerErrorCode.QUERY_DISPATCH_ERROR,
+  AxonServerErrorCode.CONNECTION_FAILED,
+  AxonServerErrorCode.GRPC_MESSAGE_TOO_LARGE,
+  AxonServerErrorCode.CONCURRENCY_EXCEPTION,
+  AxonServerErrorCode.COMMAND_CONCURRENCY_ERROR,
+  AxonServerErrorCode.NO_EVENT_STORE_MASTER_AVAILABLE,
+])
+
+/**
+ * Convert an Axon Server error code + message into a typed exception.
+ */
+export function mapErrorCode(errorCode: string, message: string): AxonServerError {
+  switch (errorCode) {
+    case AxonServerErrorCode.NO_HANDLER_FOR_COMMAND:
+      return new NoHandlerForCommandError(message)
+    case AxonServerErrorCode.NO_HANDLER_FOR_QUERY:
+      return new NoHandlerForQueryError(message)
+    case AxonServerErrorCode.COMMAND_EXECUTION_ERROR:
+      return new CommandExecutionError(message, true)
+    case AxonServerErrorCode.COMMAND_EXECUTION_NON_TRANSIENT_ERROR:
+      return new CommandExecutionError(message, false)
+    case AxonServerErrorCode.QUERY_EXECUTION_ERROR:
+      return new QueryExecutionError(message, true)
+    case AxonServerErrorCode.QUERY_EXECUTION_NON_TRANSIENT_ERROR:
+      return new QueryExecutionError(message, false)
+    case AxonServerErrorCode.COMMAND_DISPATCH_ERROR:
+      return new CommandDispatchError(message)
+    case AxonServerErrorCode.QUERY_DISPATCH_ERROR:
+      return new QueryDispatchError(message)
+    case AxonServerErrorCode.CONCURRENCY_EXCEPTION:
+    case AxonServerErrorCode.COMMAND_CONCURRENCY_ERROR:
+      return new ConcurrencyError(message)
+    case AxonServerErrorCode.CONNECTION_FAILED:
+    case AxonServerErrorCode.GRPC_MESSAGE_TOO_LARGE:
+      return new ConnectionFailedError(message)
+    case AxonServerErrorCode.AUTHENTICATION_TOKEN_MISSING:
+    case AxonServerErrorCode.AUTHENTICATION_INVALID_TOKEN:
+      return new AuthenticationError(message, errorCode)
+    default:
+      return new AxonServerError(
+        message,
+        errorCode,
+        TRANSIENT_CODES.has(errorCode),
+      )
+  }
+}
+
+/**
+ * Check if an error is transient (retryable).
+ */
+export function isTransientError(error: unknown): boolean {
+  if (error instanceof AxonServerError) return error.transient
+  return false
+}

package/src/event-processor-info.ts

@@ -0,0 +1,62 @@
+import type { EventProcessorInfo, EventProcessorInfo_SegmentStatus } from "./generated/control.js"
+
+/**
+ * Status of a single event processor, reported to Axon Server.
+ * Aligned with Java's EventProcessorInfo proto message.
+ */
+export interface ProcessorStatus {
+  readonly name: string
+  readonly running: boolean
+  readonly mode: "Tracking" | "Subscribing"
+  readonly isStreamingProcessor: boolean
+  readonly activeThreads: number
+  readonly availableThreads: number
+  readonly error: boolean
+  readonly errorMessage?: string
+  readonly tokenStoreIdentifier: string
+  readonly segments: SegmentStatus[]
+}
+
+export interface SegmentStatus {
+  readonly segmentId: number
+  readonly caughtUp: boolean
+  readonly replaying: boolean
+  readonly onePartOf: number
+  readonly tokenPosition: bigint
+  readonly errorState: string
+}
+
+/**
+ * Converts a ProcessorStatus to the proto EventProcessorInfo format.
+ */
+export function toEventProcessorInfo(status: ProcessorStatus): EventProcessorInfo {
+  return {
+    processorName: status.name,
+    mode: status.mode,
+    activeThreads: status.activeThreads,
+    running: status.running,
+    error: status.error,
+    segmentStatus: status.segments.map(toSegmentStatus),
+    availableThreads: status.availableThreads,
+    tokenStoreIdentifier: status.tokenStoreIdentifier,
+    isStreamingProcessor: status.isStreamingProcessor,
+    loadBalancingStrategyName: "",
+  }
+}
+
+function toSegmentStatus(seg: SegmentStatus): EventProcessorInfo_SegmentStatus {
+  return {
+    segmentId: seg.segmentId,
+    caughtUp: seg.caughtUp,
+    replaying: seg.replaying,
+    onePartOf: seg.onePartOf,
+    tokenPosition: seg.tokenPosition,
+    errorState: seg.errorState,
+  }
+}
+
+/**
+ * Supplier function that returns the current status of all event processors.
+ * Registered with the platform connection for periodic reporting.
+ */
+export type ProcessorStatusSupplier = () => ProcessorStatus[]