@kronos-ts/axon-server 0.5.0 → 0.7.0

package/src/bounded-read.ts

@@ -0,0 +1,43 @@
+/**
+ * A read that never answers is cancelled and asked once more.
+ *
+ * WHY THIS EXISTS. Under Bun, a gRPC call whose response has fully arrived —
+ * headers, the message, trailers carrying an OK status, the HTTP/2 stream
+ * closed cleanly — can still never complete on the client. grpc-js releases
+ * an OK status only once the stream's `end` event has fired, and Bun's http2
+ * client intermittently never emits it (Node does). The Axon integration
+ * suites hit it about one run in four on a loaded machine, on `source` and on
+ * the snapshot store's `getLast`; the command handler above the read then
+ * never replies, and Axon Server cancels the command at its own 300 s timeout.
+ *
+ * A deadline is the one lever this side of grpc-js: a cancelled call DOES
+ * surface, because a non-OK status needs no `end`. The reads this guards are
+ * idempotent, so the answer to a lost one is simply to ask again. A second
+ * loss is reported rather than retried forever.
+ */
+export async function boundedRead<T>(
+  deadlineMs: number,
+  read: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  for (let attempt = 1; ; attempt++) {
+    const cancel = new AbortController()
+    const timer = setTimeout(() => cancel.abort(), deadlineMs)
+    try {
+      return await read(cancel.signal)
+    } catch (err) {
+      if (!cancel.signal.aborted) throw err
+      if (attempt === 2) {
+        throw new Error(
+          `Axon Server read did not complete within ${deadlineMs} ms, twice in a row`,
+          { cause: err },
+        )
+      }
+      console.warn(
+        `Axon Server read did not complete within ${deadlineMs} ms; cancelled it and asking again ` +
+          "(a known Bun http2 client fault: the stream's end event is lost, see bounded-read.ts)",
+      )
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+}

package/src/connection.ts

@@ -1,6 +1,7 @@
+import { withMessagingTimeout } from "@kronos-ts/core"
 import {
   createChannel,
-  createClient,
+  waitForChannelReady,  createClient,
   type Channel,
   type Client,
   type ChannelCredentials,
@@ -71,6 +72,17 @@ export type AxonServerConnectionConfig = {
    * Default: true.
    */
   keepAlivePermitWithoutCalls?: boolean
+  /**
+   * How long a read (`source`, the snapshot store's `getLast`, `getHead`) may
+   * take before it is cancelled and asked once more. A read whose answer has
+   * fully arrived can still never complete under Bun — its http2 client
+   * intermittently loses the stream's `end` event, and grpc-js releases an OK
+   * status only after it — so without a bound a command handler parks on the
+   * read until Axon Server cancels the command (300 s). Reads are idempotent;
+   * a lost one is simply repeated. Raise this if a single sourcing read of
+   * yours legitimately takes longer. Default: 15000.
+   */
+  readTimeoutMs?: number
 
   /**
    * TLS/SSL configuration. When enabled, the connection uses a secure gRPC channel.
@@ -165,6 +177,7 @@ export function connectToAxonServer(config: AxonServerConnectionConfig): AxonSer
     keepAliveTimeMs: config.keepAliveTimeMs ?? 30000,
     keepAliveTimeoutMs: config.keepAliveTimeoutMs ?? 10000,
     keepAlivePermitWithoutCalls: config.keepAlivePermitWithoutCalls ?? true,
+    readTimeoutMs: config.readTimeoutMs ?? 15000,
     servers: config.servers,
     ssl: config.ssl,
   }
@@ -189,6 +202,12 @@ export function connectToAxonServer(config: AxonServerConnectionConfig): AxonSer
     "grpc.keepalive_time_ms": config.keepAliveTimeMs ?? 30000,
     "grpc.keepalive_timeout_ms": config.keepAliveTimeoutMs ?? 10000,
     "grpc.keepalive_permit_without_calls": (config.keepAlivePermitWithoutCalls ?? true) ? 1 : 0,
+    // Own subchannel pool per channel. grpc-js pools subchannels PROCESS-WIDE by
+    // target address by default, so a later connection to the same host:port —
+    // a fresh container on a reused mapped port, in a test process that already
+    // talked to another one — can be handed the previous server's HTTP/2
+    // session, and its unary calls hang until the server-side timeout.
+    "grpc.use_local_subchannel_pool": 1,
   }
 
   // Build server address list for failover
@@ -208,6 +227,9 @@ export function connectToAxonServer(config: AxonServerConnectionConfig): AxonSer
 
   let channel = createGrpcChannel()
   let state: ConnectionState = "connected"
+  let reconnectPromise: Promise<void> | undefined
+  let retryTimer: ReturnType<typeof setTimeout> | undefined
+  let finishRetryDelay: (() => void) | undefined
 
   const reconnectCallbacks: Array<() => void> = []
   const disconnectCallbacks: Array<(error?: Error) => void> = []
@@ -258,52 +280,59 @@ export function connectToAxonServer(config: AxonServerConnectionConfig): AxonSer
     },
 
     close() {
+      if (state === "closed") return
       state = "closed"
+      for (const callback of disconnectCallbacks) {
+        try { callback() } catch { /* Listener failures cannot prevent teardown. */ }
+      }
+      clearTimeout(retryTimer)
+      finishRetryDelay?.()
       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 */
+    reconnect() {
+      if (state === "closed") return Promise.reject(new Error("Connection is permanently closed"))
+      if (reconnectPromise) return reconnectPromise
+      reconnectPromise = (async () => {
+        state = "reconnecting"
+        channel.close()
+        for (const callback of disconnectCallbacks) {
+          try { callback() } catch { /* Listener failures cannot prevent recovery. */ }
+        }
+        let attempt = 0
+        while (state === "reconnecting") {
+          attempt++
+          try {
+            currentServerIndex++
+            channel = createGrpcChannel()
+            // Channel construction is lazy. Only report recovery once the new
+            // transport is ready, otherwise a dead server falsely "succeeds".
+            await waitForChannelReady(channel, new Date(Date.now() + resolvedConfig.keepAliveTimeoutMs))
+            if ((state as ConnectionState) === "closed") return
+            clients = createClients()
+            state = "connected"
+            for (const callback of reconnectCallbacks) {
+              try { callback() } catch { /* Listener failures are isolated. */ }
             }
+            return
+          } catch (error) {
+            channel.close()
+            if ((state as ConnectionState) === "closed") return
+            if (resolvedConfig.maxReconnectAttempts > 0 && attempt >= resolvedConfig.maxReconnectAttempts) {
+              state = "disconnected"
+              throw new Error(`Failed to reconnect after ${attempt} attempts: ${error}`)
+            }
+            const backoff = Math.min(resolvedConfig.reconnectIntervalMs * 2 ** (attempt - 1), 30000)
+            await new Promise<void>((resolve) => {
+              finishRetryDelay = resolve
+              retryTimer = setTimeout(resolve, backoff * (0.75 + Math.random() * 0.5))
+            })
+            finishRetryDelay = undefined
           }
-          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))
         }
-      }
+      })().finally(() => { reconnectPromise = undefined })
+      return reconnectPromise
+
     },
   }
 
@@ -326,6 +355,8 @@ export function connectToAxonServer(config: AxonServerConnectionConfig): AxonSer
  * their honest two-argument shapes.
  */
 export type AxonServerConnectionOptions = AxonServerConnectionConfig & {
+  /** Maximum graceful drain time; transport closes even when this expires. Default: 30000ms. */
+  shutdownTimeoutMs?: number
   /** 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. */
@@ -516,11 +547,12 @@ export async function axonServerConnection(
     },
 
     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()
+      try {
+        await withMessagingTimeout(shutdown.initiateShutdown(), options.shutdownTimeoutMs ?? 30000, "Messaging shutdown")
+      } finally {
+        platform.stop()
+        connection.close()
+      }
     },
   }
 }

package/src/control-plane.ts

@@ -6,8 +6,9 @@
  * 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;
+ *      start-processor) which have to be routed to the live processor of that
+ *      name; segment instructions (split, merge, release) are ignored, a kronos
+ *      processor has one lane;
  *   2. outbound — the client periodically reports each processor's status so
  *      the Axon Dashboard can render it.
  *
@@ -39,19 +40,12 @@
  * caller to get wrong.
  */
 import type { AxonServerPlatformSource } from "./connection.js"
-import type { ProcessorStatus, SegmentStatus } from "./event-processor-info.js"
+import type { ProcessorStatus } 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.
+ * A processor Axon Server is allowed to observe and control. `RunningProcessor`
+ * satisfies it structurally; everything past `name` is optional so a foreign
+ * processor-shaped object is skipped rather than crashed on.
  */
 export type ManagedEventProcessor = {
   readonly name: string
@@ -60,19 +54,12 @@ export type ManagedEventProcessor = {
   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
+  status?(): {
+    readonly caughtUp?: boolean
+    readonly replaying?: boolean
+    readonly position?: bigint
+    readonly error?: Error
+  }
 }
 
 /**
@@ -92,37 +79,14 @@ export type AxonServerControlPlane = {
 /** 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: "",
-          },
-        ]
+    const status = proc.status?.()
     return {
       name: proc.name,
       running: proc.running ?? false,
-      mode: isStreamingProcessor ? "Tracking" : "Subscribing",
-      isStreamingProcessor,
-      activeThreads: proc.running ? 1 : 0,
-      availableThreads: 0,
-      error: false,
-      tokenStoreIdentifier: "",
-      segments,
+      caughtUp: status?.caughtUp ?? true,
+      replaying: status?.replaying ?? proc.replaying ?? false,
+      position: status?.position ?? proc.position ?? 0n,
+      error: status?.error?.message,
     }
   })
 }
@@ -167,15 +131,7 @@ export async function axonServerControlPlane(
       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
+      // release/split/merge-segment: a kronos processor has one lane. Ignored.
     }
   })
 

package/src/event-processor-info.ts

@@ -1,62 +1,41 @@
-import type { EventProcessorInfo, EventProcessorInfo_SegmentStatus } from "./generated/control.js"
+import type { EventProcessorInfo } from "./generated/control.js"
 
 /**
- * Status of a single event processor, reported to Axon Server.
- * Aligned with Java's EventProcessorInfo proto message.
+ * What a processor reports about itself. SIX FIELDS — see the kronosdb
+ * package's twin for why the wire's thread counts, token-store identifier and
+ * per-segment list are filled with constants here rather than carried.
  */
 export type 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 type SegmentStatus = {
-  readonly segmentId: number
   readonly caughtUp: boolean
   readonly replaying: boolean
-  readonly onePartOf: number
-  readonly tokenPosition: bigint
-  readonly errorState: string
+  readonly position: bigint
+  readonly error?: 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,
+    mode: "Tracking",
+    activeThreads: status.running ? 1 : 0,
     running: status.running,
-    error: status.error,
-    segmentStatus: status.segments.map(toSegmentStatus),
-    availableThreads: status.availableThreads,
-    tokenStoreIdentifier: status.tokenStoreIdentifier,
-    isStreamingProcessor: status.isStreamingProcessor,
+    error: status.error !== undefined,
+    segmentStatus: [
+      {
+        segmentId: 0,
+        caughtUp: status.caughtUp,
+        replaying: status.replaying,
+        onePartOf: 1,
+        tokenPosition: status.position,
+        errorState: status.error ?? "",
+      },
+    ],
+    availableThreads: 0,
+    tokenStoreIdentifier: "",
+    isStreamingProcessor: true,
     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[]

package/src/flow-controlled-sender.ts

@@ -33,29 +33,49 @@ export function flowControlledSender<T>(
   onError?: (error: Error) => void,
   maxBufferSize: number = 256,
 ): FlowControlledSender<T> {
+  if (!Number.isSafeInteger(maxBufferSize) || maxBufferSize <= 0) throw new RangeError("maxBufferSize must be a positive integer")
   const buffer: T[] = []
   let permits = 0
   let isActive = true
+  let completionRequested = false
+
+  function fail(error: Error) {
+    if (!isActive) return
+    isActive = false
+    buffer.length = 0
+    onError?.(error)
+  }
+  function sendOne(value: T) {
+    try { send(value) }
+    catch (error) {
+      fail(error instanceof Error ? error : new Error(String(error)))
+      throw error
+    }
+  }
+  function finishIfDrained() {
+    if (isActive && completionRequested && !buffer.length) {
+      isActive = false
+      onComplete?.()
+    }
+  }
+
 
   function drain() {
     while (permits > 0 && buffer.length > 0 && isActive) {
       const value = buffer.shift()!
       permits--
-      try {
-        send(value)
-      } catch (err) {
-        console.warn("FlowControlledSender: send error", err)
-      }
+      sendOne(value)
     }
+    finishIfDrained()
   }
 
   return {
     offer(value: T): boolean {
-      if (!isActive) return false
+      if (!isActive || completionRequested) return false
 
       if (permits > 0) {
         permits--
-        send(value)
+        sendOne(value)
         return true
       }
 
@@ -68,24 +88,23 @@ export function flowControlledSender<T>(
     },
 
     addPermits(count: number) {
+      if (!Number.isSafeInteger(count) || count <= 0 || !Number.isSafeInteger(permits + count)) throw new RangeError("Permits must be positive safe integers")
+      if (!isActive) return
       permits += count
       drain()
     },
 
     complete() {
-      isActive = false
-      buffer.length = 0
-      if (onComplete) onComplete()
+      completionRequested = true
+      finishIfDrained()
     },
 
     completeExceptionally(error: Error) {
-      isActive = false
-      buffer.length = 0
-      if (onError) onError(error)
+      fail(error)
     },
 
     get active() {
-      return isActive
+      return isActive && !completionRequested
     },
   }
 }

package/src/index.ts

@@ -37,7 +37,6 @@ export {
 
 export {
   type ProcessorStatus,
-  type SegmentStatus,
   type ProcessorStatusSupplier,
   toEventProcessorInfo,
 } from "./event-processor-info.js"

package/src/outbound-stream.ts

@@ -1,52 +1,82 @@
-/**
- * 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.
- */
+/** Bounded single-consumer queue feeding a gRPC request stream. */
 export type 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. */
+  /** Wait until the consumer has requested the next frame after this batch. Not a server acknowledgement. */
+  flush(): Promise<void>
+  readonly buffered: number
   close(): void
 }
 
-export function outboundStream<T>(): OutboundStream<T> {
-  let resolve: ((value: IteratorResult<T>) => void) | null = null
+export function outboundStream<T>(maxBuffered = 4096): OutboundStream<T> {
+  if (!Number.isSafeInteger(maxBuffered) || maxBuffered <= 0) throw new RangeError("maxBuffered must be a positive integer")
+  let resolve: ((value: IteratorResult<T>) => void) | undefined
   const queue: T[] = []
   let closed = false
-
+  let claimed = false
+  let handingOff = false
+  let flushed: { promise: Promise<void>; resolve(): void; reject(error: Error): void } | undefined
+  function acknowledgeRead() {
+    handingOff = false
+    if (!queue.length) { flushed?.resolve(); flushed = undefined }
+  }
+  const done = (): IteratorResult<T> => ({ value: undefined, done: true })
+  function close() {
+    closed = true
+    if (!queue.length && !handingOff) { flushed?.resolve(); flushed = undefined }
+    resolve?.(done())
+    resolve = undefined
+  }
   return {
-    send(message: T) {
+    get buffered() { return queue.length },
+    flush() {
+      if (!queue.length && !handingOff) return Promise.resolve()
+      if (closed) return Promise.reject(new Error("Outbound stream closed before flush"))
+      if (!flushed) {
+        let resolve!: () => void, reject!: (error: Error) => void
+        const promise = new Promise<void>((a, b) => { resolve = a; reject = b })
+        flushed = { promise, resolve, reject }
+      }
+      return flushed.promise
+    },
+    send(message) {
+      if (closed) throw new Error("Outbound stream is closed")
       if (resolve) {
-        const r = resolve
-        resolve = null
-        r({ value: message, done: false })
+        const waiter = resolve
+        resolve = undefined
+        handingOff = true
+        waiter({ value: message, done: false })
       } else {
+        if (queue.length >= maxBuffered) throw new Error("Outbound stream buffer overflow")
         queue.push(message)
       }
     },
-
     iterable: {
       [Symbol.asyncIterator]() {
+        if (claimed) throw new Error("Outbound stream supports one consumer")
+        claimed = true
         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 })
+            acknowledgeRead()
+            if (queue.length) {
+              handingOff = true
+              return Promise.resolve({ value: queue.shift()!, done: false })
+            }
+            if (closed) return Promise.resolve(done())
+            if (resolve) return Promise.reject(new Error("Concurrent outbound stream reads are not supported"))
             return new Promise((r) => { resolve = r })
           },
+          return(): Promise<IteratorResult<T>> {
+            queue.length = 0
+            flushed?.reject(new Error("Outbound stream cancelled before flush"))
+            flushed = undefined
+            handingOff = false
+            close()
+            return Promise.resolve(done())
+          },
         }
       },
     },
-
-    close() {
-      closed = true
-      if (resolve) {
-        resolve({ value: undefined as any, done: true })
-        resolve = null
-      }
-    },
+    close,
   }
 }