@kronos-ts/axon-server 0.2.10 → 0.3.0

package/src/connection-manager.ts

@@ -10,7 +10,7 @@ import { connectToAxonServer } from "./connection.js"
  * Aligned with Java's `AxonServerConnectionManager`.
  *
  * ```typescript
- * const manager = createConnectionManager({
+ * const manager = connectionManager({
  *   componentName: "my-app",
  *   host: "axon-server",
  *   port: 8124,
@@ -51,7 +51,7 @@ export interface AxonServerConnectionManager {
  * The base config (host, port, SSL, etc.) is shared across all contexts.
  * Only the `context` field varies per connection.
  */
-export function createConnectionManager(
+export function connectionManager(
   baseConfig: Omit<AxonServerConnectionConfig, "context">,
 ): AxonServerConnectionManager {
   const connections = new Map<string, AxonServerConnection>()

package/src/control-plane.ts

@@ -0,0 +1,195 @@
+/**
+ * The Axon Server PLATFORM CONTROL PLANE — remote administration, extracted
+ * out of the backend.
+ *
+ * This is not persistence and it is not transport. It is the pair of duties
+ * Axon Server's admin surface needs from a client:
+ *
+ *   1. inbound — Axon Server pushes processor instructions (pause-processor,
+ *      start-processor, release-segment, split-segment, merge-segment) which
+ *      have to be routed to the live processor of that name;
+ *   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
+ * 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.
+ *
+ * ```ts
+ * const axon = await axonServer({ ... })
+ * const app  = kronos({ components: { ...axon.components }, modules })
+ * await axon.start()                                  // data path only
+ *
+ * // opt in to remote administration
+ * const control = await axonServerControlPlane(axon.platform, app.processors.values())
+ * // …
+ * await app.stop(); await control.close(); await axon.close()
+ * ```
+ *
+ * ORDERING INVARIANT (the reason this is an async factory rather than a
+ * constructor plus a separate `start()`): the instruction handler and the
+ * status supplier MUST both be registered BEFORE `platform.start()` sends the
+ * `register` frame. An instruction that arrives in the gap between `start()`
+ * and `onInstruction(...)` is dropped on the floor, and a status request that
+ * arrives before `registerProcessorStatusSupplier(...)` finds no supplier and
+ * reports the client as having no processors at all. Register, register, then
+ * 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 { ProcessorStatus, SegmentStatus } from "./event-processor-info.js"
+
+/**
+ * A processor Axon Server is allowed to observe and control.
+ *
+ * The container version reached for `app.processors()` and cast the result to
+ * `any` before poking at `start` / `stop` / `releaseSegment` / … — this is that
+ * cast, written down. Both `TrackingEventProcessor` and
+ * `StreamingEventProcessor` satisfy it structurally; anything else that can
+ * name itself and answer some of these calls does too. Every member past the
+ * name is optional because Axon Server asks for things a given processor kind
+ * may not implement (a subscribing processor has no segments), and the
+ * instruction handler simply skips what is absent.
+ */
+export interface ManagedEventProcessor {
+  readonly name: string
+  readonly running?: boolean
+  readonly replaying?: boolean
+  readonly position?: bigint
+  start?(): Promise<void> | void
+  stop?(): void
+  supportsReset?(): boolean
+  processingStatus?(): ReadonlyMap<
+    number,
+    {
+      readonly position?: bigint
+      readonly caughtUp?: boolean
+      readonly replaying?: boolean
+      readonly error?: Error
+    }
+  >
+  releaseSegment?(segmentId: number): Promise<unknown> | unknown
+  splitSegment?(segmentId: number): Promise<unknown> | unknown
+  mergeSegment?(segmentId: number): Promise<unknown> | unknown
+}
+
+/**
+ * A running control plane. The platform stream is live; instructions are being
+ * routed and status is being reported until `close()`.
+ */
+export interface AxonServerControlPlane {
+  /**
+   * The processors this control plane addresses, keyed by name — the snapshot
+   * taken at construction. Exposed for introspection and tests.
+   */
+  readonly processors: ReadonlyMap<string, ManagedEventProcessor>
+  /** Stop the platform stream. Idempotent, and safe to call before `axon.close()`. */
+  close(): Promise<void>
+}
+
+/** Map the managed processors into the status shape the platform stream reports. */
+function processorStatuses(
+  processors: Iterable<ManagedEventProcessor>,
+): ProcessorStatus[] {
+  return Array.from(processors, (proc) => {
+    const isStreamingProcessor = proc.supportsReset?.() !== false
+    const perSegment = proc.processingStatus?.()
+    const segments: SegmentStatus[] = perSegment
+      ? Array.from(perSegment.entries()).map(([segmentId, status]) => ({
+          segmentId,
+          caughtUp: status.caughtUp ?? false,
+          replaying: status.replaying ?? false,
+          onePartOf: 1,
+          tokenPosition: status.position ?? 0n,
+          errorState: status.error?.message ?? "",
+        }))
+      : [
+          {
+            segmentId: 0,
+            caughtUp: true,
+            replaying: proc.replaying ?? false,
+            onePartOf: 1,
+            tokenPosition: proc.position ?? 0n,
+            errorState: "",
+          },
+        ]
+    return {
+      name: proc.name,
+      running: proc.running ?? false,
+      mode: isStreamingProcessor ? "Tracking" : "Subscribing",
+      isStreamingProcessor,
+      activeThreads: proc.running ? 1 : 0,
+      availableThreads: 0,
+      error: false,
+      tokenStoreIdentifier: "",
+      segments,
+    }
+  })
+}
+
+/**
+ * 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.
+ *
+ * `processors` are the LIVE processor instances, which only exist after
+ * `kronos` has built them — that is why this cannot be folded back into the
+ * backend factory. Pass `app.processors.values()`.
+ *
+ * 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.
+ *
+ * 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
+ * nothing on the second status report. The processor OBJECTS are live, so each
+ * report still reads current `running` / `position` / segment state off them —
+ * only the membership of the set is fixed at construction.
+ */
+export async function axonServerControlPlane(
+  platform: PlatformConnection,
+  processors: Iterable<ManagedEventProcessor> = [],
+): Promise<AxonServerControlPlane> {
+  // 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)
+
+  platform.onInstruction(async (instruction) => {
+    switch (instruction.kind) {
+      case "pause-processor":
+        byName.get(instruction.processorName)?.stop?.()
+        break
+      case "start-processor":
+        await byName.get(instruction.processorName)?.start?.()
+        break
+      case "release-segment":
+        await byName.get(instruction.processorName)?.releaseSegment?.(instruction.segmentId)
+        break
+      case "split-segment":
+        await byName.get(instruction.processorName)?.splitSegment?.(instruction.segmentId)
+        break
+      case "merge-segment":
+        await byName.get(instruction.processorName)?.mergeSegment?.(instruction.segmentId)
+        break
+    }
+  })
+
+  platform.registerProcessorStatusSupplier(() => processorStatuses(byName.values()))
+
+  // ORDERING: strictly AFTER both registrations — 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()
+
+  return {
+    processors: byName,
+    async close() {
+      platform.stop()
+    },
+  }
+}

package/src/flow-controlled-sender.ts

@@ -27,7 +27,7 @@ export interface FlowControlledSender<T> {
  * @param send Function called to actually send an update downstream.
  * @param maxBufferSize Maximum number of updates to buffer. Default: 256.
  */
-export function createFlowControlledSender<T>(
+export function flowControlledSender<T>(
   send: (value: T) => void,
   onComplete?: () => void,
   onError?: (error: Error) => void,

package/src/index.ts

@@ -6,28 +6,38 @@ export {
 
 export {
   type AxonServerConnectionManager,
-  createConnectionManager,
+  connectionManager,
 } from "./connection-manager.js"
 
 export {
-  createAxonServerEventStore,
+  axonServerEventStore,
 } from "./axon-server-event-store.js"
 
 export {
-  createAxonServerSnapshotStore,
+  axonServerSnapshotStore,
 } from "./axon-server-snapshot-store.js"
 
 export {
   axonServer,
-  type AxonServerExtensionConfig,
+  distributedCommandBus,
+  distributedQueryBus,
+  type AxonServerConfig,
+  type AxonServerBackend,
+  type AxonServerComponents,
   type FlowControlConfig,
   type ProcessingInstructions,
 } from "./axon-server.js"
 
+export {
+  axonServerControlPlane,
+  type AxonServerControlPlane,
+  type ManagedEventProcessor,
+} from "./control-plane.js"
+
 export {
   type MessageSizeConfig,
   MessageSizeExceededError,
-  createMessageSizeValidator,
+  messageSizeValidator,
 } from "./message-size.js"
 
 export {
@@ -42,19 +52,19 @@ export {
   type PlatformInstruction,
   type InstructionHandler,
   type PlatformServiceOptions,
-  createPlatformConnection,
+  platformConnection,
 } from "./platform-service.js"
 
 export {
   type FlowControlledSender,
-  createFlowControlledSender,
+  flowControlledSender,
 } from "./flow-controlled-sender.js"
 
 export {
   type ShutdownLatch,
   type ActivityHandle,
   ShutdownInProgressError,
-  createShutdownLatch,
+  shutdownLatch,
 } from "./shutdown-latch.js"
 
 export {
@@ -73,3 +83,4 @@ export {
   mapErrorCode,
   isTransientError,
 } from "./errors.js"
+export type { AxonServerOptions } from "./axon-server.js"

package/src/message-size.ts

@@ -39,7 +39,7 @@ export class MessageSizeExceededError extends Error {
  * - `validate(data)` — throws if over limit, warns if over 75%
  * - `estimateSize(payload)` — quick byte size estimate
  */
-export function createMessageSizeValidator(config?: MessageSizeConfig) {
+export function messageSizeValidator(config?: MessageSizeConfig) {
   const maxSize = config?.maxMessageSize ?? DEFAULT_MAX_MESSAGE_SIZE
   const threshold = config?.warningThreshold ?? WARNING_THRESHOLD
   const warningSize = Math.floor(maxSize * threshold)

package/src/outbound-stream.ts

@@ -12,7 +12,7 @@ export interface OutboundStream<T> {
   close(): void
 }
 
-export function createOutboundStream<T>(): OutboundStream<T> {
+export function outboundStream<T>(): OutboundStream<T> {
   let resolve: ((value: IteratorResult<T>) => void) | null = null
   const queue: T[] = []
   let closed = false

package/src/platform-service.ts

@@ -1,5 +1,5 @@
 import type { AxonServerConnection } from "./connection.js"
-import { createOutboundStream } from "./outbound-stream.js"
+import { outboundStream } from "./outbound-stream.js"
 import type { PlatformInboundInstruction } from "./generated/control.js"
 import { Metadata } from "nice-grpc"
 import type { ProcessorStatusSupplier } from "./event-processor-info.js"
@@ -36,9 +36,40 @@ export type InstructionHandler = (instruction: PlatformInstruction) => void | Pr
  * - Receives server-initiated instructions (pause, resume, split, merge segments)
  */
 export interface PlatformConnection {
-  /** Start the platform stream (register with Axon Server, begin heartbeats). */
+  /**
+   * DATA PATH. Open the platform stream, register this client, and arm the
+   * heartbeat that calls `connection.reconnect()` when the server stops
+   * answering.
+   *
+   * This is split out of {@link start} deliberately. Reconnect detection is a
+   * property of the CONNECTION, and the command/query buses hook
+   * `connection.onReconnect(...)` to re-establish their own streams — so a
+   * service that never opts into remote administration still needs it. When it
+   * lived only inside `start()` (which only the control plane calls), such a
+   * service had no heartbeat-driven reconnect detection on its data path at all
+   * and would sit on a dead channel indefinitely.
+   *
+   * Arms NOTHING control-plane-specific: no processor status reporting. Safe to
+   * call repeatedly; a stream that is already up is left alone.
+   */
+  armConnectionMonitoring(): Promise<void>
+  /**
+   * CONTROL PLANE. Everything {@link armConnectionMonitoring} does, plus
+   * periodic processor status reporting.
+   *
+   * Idempotent in both halves: if the data path already opened the stream, this
+   * only adds status reporting; if it did not, this opens the stream too.
+   */
   start(): Promise<void>
-  /** Stop the platform stream and heartbeats. */
+  /**
+   * Stop the platform stream, heartbeats and status reporting.
+   *
+   * Note that this tears down the SHARED stream — including the data path's
+   * reconnect detection. `axonServerControlPlane(...).close()` calls it, which
+   * is correct in the documented shutdown order (`app.stop()` → `control.close()`
+   * → `axon.close()`) but means closing a control plane on a still-running
+   * service disarms reconnect detection with it.
+   */
   stop(): void
   /** Register a handler for server-initiated instructions. */
   onInstruction(handler: InstructionHandler): void
@@ -98,7 +129,7 @@ export interface PlatformServiceOptions {
  * 2. Sends periodic heartbeats to verify connectivity
  * 3. Receives instructions from Axon Server (split, merge, pause, resume)
  */
-export function createPlatformConnection(
+export function platformConnection(
   connection: AxonServerConnection,
   options?: PlatformServiceOptions,
 ): PlatformConnection {
@@ -109,12 +140,27 @@ export function createPlatformConnection(
 
   const instructionHandlers: InstructionHandler[] = []
   const processorStatusSuppliers: ProcessorStatusSupplier[] = []
+  /**
+   * Instructions that arrived before anything registered a handler.
+   *
+   * The control plane registers its handler before calling `start()`, but the
+   * DATA path now opens the same stream via `armConnectionMonitoring()` — which
+   * runs before any control plane exists. That leaves a window in which Axon
+   * Server can push an instruction at a client with nothing to route it to.
+   * Buffering makes the window harmless instead of merely forbidden: the first
+   * `onInstruction` registration drains this queue in arrival order. Mirrors the
+   * kronosdb platform connection, which has had this since its backend started
+   * the stream for `subscriptionsAcked()`.
+   */
+  const pendingInstructions: PlatformInstruction[] = []
   let isConnected = false
   let heartbeatTimer: ReturnType<typeof setInterval> | null = null
   let heartbeatTimeoutTimer: ReturnType<typeof setTimeout> | null = null
   let processorStatusTimer: ReturnType<typeof setInterval> | null = null
+  /** Guards against arming the status-report timer twice — see `startProcessorStatusReporting`. */
+  let processorStatusArmed = false
   let lastHeartbeatResponse = Date.now()
-  let outbound: ReturnType<typeof createOutboundStream<PlatformInboundInstruction>> | null = null
+  let outbound: ReturnType<typeof outboundStream<PlatformInboundInstruction>> | null = null
   /**
    * Latches once Axon Server sends its first inbound message after
    * registration — the earliest observable signal that the platform stream
@@ -140,6 +186,11 @@ export function createPlatformConnection(
         // Parse instruction type
         const instruction = parseInstruction(message)
         if (instruction) {
+          if (instructionHandlers.length === 0) {
+            // Nothing to route to yet — hold it for the first registration
+            // rather than dropping it.
+            pendingInstructions.push(instruction)
+          }
           for (const handler of instructionHandlers) {
             try {
               await handler(instruction)
@@ -240,6 +291,14 @@ export function createPlatformConnection(
   }
 
   function startProcessorStatusReporting() {
+    // Idempotency guard. The control plane may call `start()` after the data
+    // path already brought the stream up, and `start()` is itself documented as
+    // safe to call twice. Without this flag a second call inside the initial
+    // delay window would leave TWO pending timeouts, each of which installs an
+    // interval, and only the last would be tracked in `processorStatusTimer` —
+    // the first would leak past `stop()`.
+    if (processorStatusArmed) return
+    processorStatusArmed = true
     if (processorStatusTimer) clearInterval(processorStatusTimer)
 
     // Initial delay before first report
@@ -273,57 +332,87 @@ export function createPlatformConnection(
     }
   }
 
-  return {
-    async start() {
-      if (isConnected) return
-
-      // Re-arm the ack latch so a stop/start cycle correctly re-waits.
-      acked = false
-      outbound = createOutboundStream<PlatformInboundInstruction>()
+  /**
+   * Open the platform stream and arm the heartbeat. Shared by
+   * `armConnectionMonitoring()` (data path) and `start()` (control plane);
+   * whichever runs first opens it, the other finds it up and returns.
+   */
+  function openPlatformStream() {
+    if (isConnected) return
+
+    // A heartbeat timeout clears `isConnected` WITHOUT going through `stop()`,
+    // so a later call can land here with the dropped stream's outbound still
+    // open. Close it before replacing the reference, or it leaks. This is more
+    // reachable now that the data path arms the heartbeat: previously only a
+    // control plane could get here after a timeout.
+    if (outbound) {
+      outbound.close()
+      outbound = null
+    }
 
-      // Register with Axon Server
-      outbound.send({
-        register: {
-          clientId: connection.config.clientId,
-          componentName: connection.config.componentName,
-          version: "1.0.0",
-          tags: {},
-        },
-        instructionId: "",
-      })
+    // Re-arm the ack latch so a stop/start cycle correctly re-waits.
+    acked = false
+    outbound = outboundStream<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
+    // DATA PATH: the heartbeat is what calls connection.reconnect() on
+    // timeout, which is what the command/query buses hang their stream
+    // re-establishment off. It belongs to every service, administered or not.
+    startHeartbeat()
+    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
+  }
 
-      // Open bidirectional stream
-      const inbound = connection.platform.openStream(outbound.iterable, {
-        metadata: grpcMetadata,
-      })
+  return {
+    async armConnectionMonitoring() {
+      openPlatformStream()
+    },
 
-      isConnected = true
-      startHeartbeat()
+    async start() {
+      openPlatformStream()
       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
+      // A stopped stream's un-routed backlog is stale — do not replay it if a
+      // handler registers later.
+      pendingInstructions.length = 0
+      processorStatusArmed = false
       if (heartbeatTimer) {
         clearInterval(heartbeatTimer)
         heartbeatTimer = null
@@ -343,7 +432,22 @@ export function createPlatformConnection(
     },
 
     onInstruction(handler) {
+      const isFirst = instructionHandlers.length === 0
       instructionHandlers.push(handler)
+
+      // Drain anything that arrived before a handler existed, in arrival order.
+      if (isFirst && pendingInstructions.length > 0) {
+        const backlog = pendingInstructions.splice(0, pendingInstructions.length)
+        void (async () => {
+          for (const instruction of backlog) {
+            try {
+              await handler(instruction)
+            } catch (err) {
+              console.error("Platform instruction handler error:", err)
+            }
+          }
+        })()
+      }
     },
 
     registerProcessorStatusSupplier(supplier) {

package/src/shutdown-latch.ts

@@ -43,7 +43,7 @@ export class ShutdownInProgressError extends Error {
   }
 }
 
-export function createShutdownLatch(): ShutdownLatch {
+export function shutdownLatch(): ShutdownLatch {
   let activeCount = 0
   let shuttingDown = false
   let drainResolve: (() => void) | null = null