@kronos-ts/axon-server 0.3.2 → 0.4.0

package/src/connection.ts

@@ -1,11 +1,23 @@
-import { createChannel, createClient, type Channel, type Client, type ChannelCredentials } from "nice-grpc"
+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 { withRetry, healthCheck, type ResilienceConfig, type Serializer } from "@kronos-ts/core"
 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"
+import { shutdownLatch, type ShutdownLatch } from "./shutdown-latch.js"
+import {
+  platformConnection,
+  type PlatformConnection,
+  type PlatformServiceOptions,
+} from "./platform-service.js"
 
 /**
  * Configuration for connecting to Axon Server.
@@ -84,7 +96,12 @@ export interface AxonServerConnectionConfig {
   }
 }
 
-export type ConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting" | "closed"
+export type ConnectionState =
+  | "disconnected"
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "closed"
 
 /**
  * An active connection to Axon Server, providing typed gRPC clients
@@ -159,7 +176,11 @@ export function connectToAxonServer(config: AxonServerConnectionConfig): AxonSer
     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
+    credentials = GrpcChannelCredentials.createSsl(
+      rootCerts,
+      clientKey,
+      clientCert,
+    ) as ChannelCredentials
   }
 
   // gRPC channel options — keepalive to maintain persistent connections
@@ -170,9 +191,10 @@ export function connectToAxonServer(config: AxonServerConnectionConfig): AxonSer
   }
 
   // Build server address list for failover
-  const serverAddresses = config.servers && config.servers.length > 0
-    ? config.servers
-    : [`${resolvedConfig.host}:${resolvedConfig.port}`]
+  const serverAddresses =
+    config.servers && config.servers.length > 0
+      ? config.servers
+      : [`${resolvedConfig.host}:${resolvedConfig.port}`]
 
   let currentServerIndex = 0
 
@@ -202,15 +224,29 @@ export function connectToAxonServer(config: AxonServerConnectionConfig): AxonSer
   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 },
+    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 },
+    get state() {
+      return state
+    },
 
     onReconnect(callback) {
       reconnectCallbacks.push(callback)
@@ -246,15 +282,17 @@ export function connectToAxonServer(config: AxonServerConnectionConfig): AxonSer
 
           // Notify listeners that we're back
           for (const cb of reconnectCallbacks) {
-            try { cb() } catch { /* ignore listener errors */ }
+            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}`,
-            )
+            throw new Error(`Failed to reconnect after ${attempt} attempts: ${err}`)
           }
 
           // Exponential backoff: base interval * 2^attempt, capped at 30s
@@ -270,3 +308,217 @@ export function connectToAxonServer(config: AxonServerConnectionConfig): AxonSer
 
   return connection
 }
+
+// ---------------------------------------------------------------------------
+// The shared RESOURCE: one channel, the platform stream on it, start()/close()
+// ---------------------------------------------------------------------------
+
+/**
+ * Everything the shared Axon Server resource needs: where to dial, and how to
+ * put a payload on the wire.
+ *
+ * THE SERIALIZER IS A PROPERTY OF THIS CLIENT'S WIRE, not of a context and not
+ * of a bus. Every event, snapshot, command payload and query result this
+ * process exchanges with Axon Server goes through the same codec, so it is
+ * named once, here — which is also what leaves
+ * `axonServerEventStore(conn, context)` and `axonServerCommandBus(conn, local)`
+ * their honest two-argument shapes.
+ */
+export interface AxonServerConnectionOptions extends AxonServerConnectionConfig {
+  /** Payload codec for every message this client exchanges with Axon Server. */
+  serializer: Serializer
+  /** Retry / health-check policy for the initial connect and stream re-establishment. */
+  resilience?: Partial<ResilienceConfig>
+  /** Platform stream tuning — heartbeat and processor-status cadence. */
+  platformService?: PlatformServiceOptions
+  /**
+   * How long {@link AxonServerConnectionHandle.start} waits for Axon Server's
+   * routing tables to register the subscribe frames sent on the command/query
+   * streams. This is the entire data-path readiness barrier.
+   *
+   * It is a timed wait rather than an observed signal because nothing on the
+   * client can observe it: subscribes travel on the bus streams, and the
+   * platform stream — which is where an ack would arrive — is a different
+   * stream that Axon Server holds open silently after `register`. Default:
+   * 1000, matching the legacy enhancer.
+   */
+  busSubscriptionAckDelayMs?: number
+}
+
+/**
+ * What a context-scoped STORE borrows from the connection: the gRPC clients and
+ * the codec. Narrower than the handle on purpose — a test can drive a store
+ * with a fake `connection` and nothing else.
+ */
+export interface AxonServerStoreSource {
+  readonly connection: AxonServerConnection
+  readonly serializer: Serializer
+}
+
+/** What a BUS borrows: a store's two, plus the drain latch and the retry policy. */
+export interface AxonServerBusSource extends AxonServerStoreSource {
+  /**
+   * The connection-wide drain latch. In-flight dispatches register on it and
+   * `close()` waits for them, so a bus never has the transport pulled out from
+   * under a call it is still awaiting.
+   */
+  readonly shutdown: ShutdownLatch
+  readonly resilience?: Partial<ResilienceConfig>
+}
+
+/** What the CONTROL PLANE borrows: the platform stream, and only that. */
+export interface AxonServerPlatformSource {
+  readonly platform: PlatformConnection
+}
+
+/**
+ * The RESOURCE an Axon Server deployment shares: one gRPC channel, the platform
+ * stream riding on it, and the lifecycle pair.
+ *
+ * The stores and buses are NOT on it — `axonServerEventStore(conn, context)`,
+ * `axonServerCommandBus(conn, local)` and friends are plain functions over
+ * this, and a caller who wants only commands builds only that one. Multiple
+ * contexts share this ONE channel: the per-call `AxonIQ-Context` header is what
+ * separates them.
+ */
+export interface AxonServerConnectionHandle extends AxonServerBusSource, AxonServerPlatformSource {
+  /** Config after defaults — the resolved host, context, client id. */
+  readonly config: AxonServerConnection["config"]
+  /**
+   * DATA-PATH START. Two things, both data path:
+   *
+   *   1. arm heartbeat-driven reconnect detection on the platform stream, and
+   *   2. wait until Axon Server can route to the handlers subscribed on the bus
+   *      streams.
+   *
+   * Call AFTER `kronos` — the subscribe frames must already be on the wire for
+   * the readiness wait to mean anything. Takes no arguments and arms no
+   * control-plane state.
+   */
+  start(): Promise<void>
+  /** Drain in-flight bus work, stop the platform stream, close the channel. */
+  close(): Promise<void>
+}
+
+/**
+ * Open the shared Axon Server connection.
+ *
+ * ```ts
+ * const axon = await axonServerConnection({
+ *   componentName: "university-service",
+ *   host, port,
+ *   serializer: jsonSerializer(),
+ * })
+ * const eventStore    = axonServerEventStore(axon, "default")
+ * const snapshotStore = axonServerSnapshotStore(axon, "default")
+ * const commandBus = interceptingCommandBus(
+ *   axonServerCommandBus(axon, simpleCommandBus(unitOfWork)), lineage)
+ * const queryBus = interceptingQueryBus(
+ *   axonServerQueryBus(axon, simpleQueryBus(unitOfWork)), lineage)
+ *
+ * const app = kronos({ states, commandHandlers, queryHandlers })
+ * await axon.start()                  // readiness barrier: the server can route to us
+ * // opt in to remote administration
+ * const control = await axonServerControlPlane(axon, app.processors.values())
+ * // …
+ * await app.stop(); await control.close(); await axon.close()
+ * ```
+ *
+ * ASYNC ON PURPOSE. Connecting before anything is built is what removes the
+ * lazy proxies and subscribe-buffering the container version needed: by the
+ * time `kronos` subscribes a handler, the gRPC streams are already live.
+ *
+ * REMOTE ADMINISTRATION IS NOT IN HERE. Processor instructions and processor
+ * status reporting are the platform CONTROL PLANE — they are neither
+ * persistence nor transport, and lived on this object only because they share
+ * the gRPC connection. See `control-plane.ts`.
+ *
+ * Axon-specific protocol invariants are preserved byte-for-byte:
+ *
+ *   - CLIENT_SUPPORTS_STREAMING capability advertised on every dispatched query;
+ *   - AxonIQ-Context + AxonIQ-Access-Token gRPC metadata headers on every
+ *     outbound stream/RPC (see `contextView`);
+ *   - permits-AFTER-subscriptions stream ordering on the initial handshake AND
+ *     on reconnect;
+ *   - shutdown ordering: drain latch → platform.stop → connection.close.
+ */
+export async function axonServerConnection(
+  options: AxonServerConnectionOptions,
+): Promise<AxonServerConnectionHandle> {
+  const {
+    serializer,
+    resilience,
+    platformService,
+    busSubscriptionAckDelayMs,
+    ...connectionConfig
+  } = options
+
+  const connection = await withRetry(async () => connectToAxonServer(connectionConfig), {
+    event: "initial-connect",
+    ...resilience,
+  })
+
+  // Health-check ping with warn-then-continue (D-100). AxonServerConnection has
+  // no dedicated probe surface today; the gRPC channel itself is created
+  // eagerly in connectToAxonServer so the meaningful probe is a round-trip — we
+  // approximate via a soft no-op promise that satisfies the threshold contract.
+  // Real network failure is surfaced by the first bus call against the channel.
+  await healthCheck(async () => undefined, {
+    thresholdMs: resilience?.healthCheckThresholdMs,
+    log: resilience?.log,
+  })
+
+  // ONE latch for the connection. Both buses ride the same channel, so "drain
+  // in-flight work before the transport goes away" is one question, not two.
+  const shutdown = shutdownLatch()
+
+  // Built here, started by the control plane (or by `start()` below for the data
+  // path's half). Constructing it eagerly is what lets the control plane be a
+  // separate object at all — and it keeps `platformService` tuning and `stop()`
+  // ownership in one place, so the documented shutdown order holds whether or
+  // not anyone opted in.
+  const platform = platformConnection(connection, platformService)
+
+  return {
+    connection,
+    config: connection.config,
+    serializer,
+    resilience,
+    shutdown,
+    platform,
+
+    async start() {
+      // RECONNECT DETECTION IS DATA PATH. The heartbeat on the platform stream
+      // is what notices a dead channel and calls `connection.reconnect()`; both
+      // buses hook `connection.onReconnect(...)` to rebuild their own streams.
+      // Arming it used to be a side effect of `platform.start()`, which only
+      // `axonServerControlPlane(...)` calls — so a service that never opted into
+      // remote administration had NO reconnect detection at all and would sit on
+      // a dead channel forever. It is armed here, unconditionally.
+      //
+      // `armConnectionMonitoring()` opens the stream and starts heartbeats but
+      // arms NO processor status reporting; that stays the control plane's, and
+      // a later `platform.start()` adds it to this same live stream. Both calls
+      // are idempotent, so either order works.
+      await platform.armConnectionMonitoring()
+
+      // The only thing the data path has to wait for: Axon Server's
+      // command/query routing tables registering the subscribe frames sent on
+      // the BUS streams. It cannot be derived from the platform stream, because
+      // subscribes travel on a different stream entirely — and the platform
+      // stream's own `subscriptionsAcked()` latch says nothing about them (it
+      // latches unconditionally once `register` has been flushed). So this
+      // barrier is the settle wait, deliberately independent of whether the
+      // platform stream is up at all. The legacy enhancer carried the same wait.
+      await new Promise((r) => setTimeout(r, busSubscriptionAckDelayMs ?? 1000))
+    },
+
+    async close() {
+      await shutdown.initiateShutdown()
+      // Idempotent, and independent of `control.close()` — a connection that was
+      // never administered still stops a platform stream someone else started.
+      platform.stop()
+      connection.close()
+    },
+  }
+}

package/src/context-view.ts

@@ -0,0 +1,46 @@
+import { Metadata } from "nice-grpc"
+import type { AxonServerStoreSource } from "./connection.js"
+
+/**
+ * A context-scoped view of the ONE shared connection.
+ *
+ * Contexts are Axon Server's tenancy boundary, and they are a per-CALL header —
+ * not a per-channel property. `AxonIQ-Context` selects the context on every
+ * outbound stream and RPC, so `axonServerEventStore(conn, "tenant-a")` and
+ * `axonServerEventStore(conn, "tenant-b")` are two views over one gRPC channel,
+ * exactly as one connection served one context before. Nothing about the
+ * channel, the codec or the drain latch differs between them; only this header
+ * does, which is why the whole difference fits in one small record.
+ */
+export interface AxonServerContextView extends AxonServerStoreSource {
+  /** The Axon Server context every call through this view addresses. */
+  readonly context: string
+  /**
+   * The gRPC metadata headers Axon Server requires. `AxonIQ-Context` is
+   * mandatory (it identifies the context); `AxonIQ-Access-Token` is optional
+   * auth. Both must be attached to every outbound stream/RPC — preserved
+   * verbatim from the legacy enhancer.
+   *
+   * A function rather than a value so a caller that opens one long-lived stream
+   * can hoist it, and one that makes many unary calls can hand each its own.
+   */
+  metadata(): Metadata
+}
+
+/** Scope a connection to one Axon Server context. */
+export function contextView(source: AxonServerStoreSource, context: string): AxonServerContextView {
+  const { connection, serializer } = source
+  return {
+    connection,
+    serializer,
+    context,
+    metadata() {
+      const metadata = new Metadata()
+      metadata.set("AxonIQ-Context", context)
+      if (connection.config.token) {
+        metadata.set("AxonIQ-Access-Token", connection.config.token)
+      }
+      return metadata
+    },
+  }
+}

package/src/control-plane.ts

@@ -11,19 +11,19 @@
  *   2. outbound — the client periodically reports each processor's status so
  *      the Axon Dashboard can render it.
  *
- * It lived inside `axonServer().start()` only because it shares the gRPC
+ * It lived inside the backend's `start()` only because it shares the gRPC
  * connection with the data path. It is now separate and OPT-IN: a service that
- * nobody administers remotely simply never builds one, and `axonServer()`
- * matches `postgres()` / `rabbitmq()` — components plus an argument-less
- * `start()` readiness barrier.
+ * nobody administers remotely simply never builds one, and
+ * `axonServerConnection()` is left with an argument-less `start()` readiness
+ * barrier and nothing else.
  *
  * ```ts
- * const axon = await axonServer({ ... })
- * const app  = kronos({ components: { ...axon.components }, modules })
+ * const axon = await axonServerConnection({ ... })
+ * const app  = kronos({ states, commandHandlers, queryHandlers, eventHandlers })
  * await axon.start()                                  // data path only
  *
  * // opt in to remote administration
- * const control = await axonServerControlPlane(axon.platform, app.processors.values())
+ * const control = await axonServerControlPlane(axon, app.processors.values())
  * // …
  * await app.stop(); await control.close(); await axon.close()
  * ```
@@ -38,7 +38,7 @@
  * start — all three inside one function, so there is no call order for a
  * caller to get wrong.
  */
-import type { PlatformConnection } from "./platform-service.js"
+import type { AxonServerPlatformSource } from "./connection.js"
 import type { ProcessorStatus, SegmentStatus } from "./event-processor-info.js"
 
 /**
@@ -90,9 +90,7 @@ export interface AxonServerControlPlane {
 }
 
 /** Map the managed processors into the status shape the platform stream reports. */
-function processorStatuses(
-  processors: Iterable<ManagedEventProcessor>,
-): ProcessorStatus[] {
+function processorStatuses(processors: Iterable<ManagedEventProcessor>): ProcessorStatus[] {
   return Array.from(processors, (proc) => {
     const isStreamingProcessor = proc.supportsReset?.() !== false
     const perSegment = proc.processingStatus?.()
@@ -132,9 +130,10 @@ function processorStatuses(
 /**
  * Wire remote administration onto an Axon Server platform stream and start it.
  *
- * `platform` is `axonServer(...).platform` — the backend builds the platform
- * connection (it owns the gRPC connection and the `platformService` tuning) but
- * never starts it, because starting it is exactly what this function is for.
+ * `conn` is the shared connection from `axonServerConnection(...)`. It owns the
+ * gRPC channel and the `platformService` tuning, and it builds the platform
+ * stream — but it never starts the control-plane half, because starting that is
+ * exactly what this function is for.
  *
  * `processors` are the LIVE processor instances, which only exist after
  * `kronos` has built them — that is why this cannot be folded back into the
@@ -143,7 +142,7 @@ function processorStatuses(
  * Caveat on that call: `kronos` types `processors` as
  * `ReadonlyMap<string, unknown>`, so `.values()` needs a cast today —
  * `app.processors.values() as Iterable<ManagedEventProcessor>`. Narrowing that
- * map in `@kronos-ts/app` would remove the cast; this package cannot.
+ * map in `@kronos-ts/core` would remove the cast; this package cannot.
  *
  * The collection is SNAPSHOTTED into a name-keyed map here, once. That is
  * deliberate: a one-shot iterator (`Map.values()` is one) would otherwise yield
@@ -152,9 +151,10 @@ function processorStatuses(
  * only the membership of the set is fixed at construction.
  */
 export async function axonServerControlPlane(
-  platform: PlatformConnection,
+  conn: AxonServerPlatformSource,
   processors: Iterable<ManagedEventProcessor> = [],
 ): Promise<AxonServerControlPlane> {
+  const { platform } = conn
   // Name-keyed view so server-initiated instructions route to the right one.
   const byName = new Map<string, ManagedEventProcessor>()
   for (const proc of processors) byName.set(proc.name, proc)
@@ -181,7 +181,7 @@ export async function axonServerControlPlane(
 
   platform.registerProcessorStatusSupplier(() => processorStatuses(byName.values()))
 
-  // ORDERING: strictly AFTER both registrations — see the file-level JSDoc.
+  // ORDERING: strictly AFTER both handlers — see the file-level JSDoc.
   // An instruction arriving in the gap would be dropped; an early status
   // request would find no supplier.
   await platform.start()

package/src/index.ts

@@ -1,29 +1,24 @@
 export {
   type AxonServerConnectionConfig,
   type AxonServerConnection,
+  type AxonServerConnectionOptions,
+  type AxonServerConnectionHandle,
+  type AxonServerStoreSource,
+  type AxonServerBusSource,
+  type AxonServerPlatformSource,
   connectToAxonServer,
+  axonServerConnection,
 } from "./connection.js"
 
-export {
-  type AxonServerConnectionManager,
-  connectionManager,
-} from "./connection-manager.js"
-
-export {
-  axonServerEventStore,
-} from "./axon-server-event-store.js"
+export { axonServerEventStore } from "./axon-server-event-store.js"
 
-export {
-  axonServerSnapshotStore,
-} from "./axon-server-snapshot-store.js"
+export { axonServerSnapshotStore } from "./axon-server-snapshot-store.js"
 
 export {
-  axonServer,
-  distributedCommandBus,
-  distributedQueryBus,
-  type AxonServerConfig,
-  type AxonServerBackend,
-  type AxonServerComponents,
+  axonServerCommandBus,
+  axonServerQueryBus,
+  type AxonServerCommandBusOptions,
+  type AxonServerQueryBusOptions,
   type FlowControlConfig,
   type ProcessingInstructions,
 } from "./axon-server.js"
@@ -83,4 +78,3 @@ export {
   mapErrorCode,
   isTransientError,
 } from "./errors.js"
-export type { AxonServerOptions } from "./axon-server.js"

package/src/metadata-conversion.ts

@@ -1,4 +1,4 @@
-import type { Metadata } from "@kronos-ts/common"
+import type { Metadata } from "@kronos-ts/core"
 import type { MetaDataValue } from "./generated/common.js"
 
 /**