@kronos-ts/axon-server 0.4.0 → 0.6.0

package/src/axon-server-event-store.ts

@@ -11,7 +11,7 @@ import type {
   SequencedEvent,
   StreamingCondition,
 } from "@kronos-ts/core"
-import { messageStream, compileQuery } from "@kronos-ts/core"
+import { compileQuery } from "@kronos-ts/core"
 import type {
   EventStore,
   SourcingResult,
@@ -25,6 +25,7 @@ import { globalSequenceToken, FIRST_TOKEN } from "@kronos-ts/core"
 import { markerAt, noMarker } from "@kronos-ts/core"
 import type { AxonServerStoreSource } from "./connection.js"
 import { contextView } from "./context-view.js"
+import { boundedRead } from "./bounded-read.js"
 import type {
   Criterion,
   TagsAndNamesCriterion,
@@ -161,37 +162,37 @@ function createEventConverters(serializer: Serializer) {
  * a single gRPC Stream RPC call that stays open indefinitely, aligned with
  * Java's infinite {@code ResultStream}.
  */
+/**
+ * Axon Server's way of saying "there is nothing at or after that position".
+ *
+ * Matched on the gRPC status code first — `OUT_OF_RANGE` is 11 — with the
+ * server's own message as a second, narrower gate, so an unrelated future
+ * OUT_OF_RANGE is not swallowed along with it.
+ */
+function isStartPastHead(err: unknown): boolean {
+  const code = (err as { code?: unknown }).code
+  const details = String((err as { details?: unknown }).details ?? "")
+  return code === 11 && details.includes("Start sequence cannot be larger than end sequence")
+}
+
 export function axonServerEventStore(conn: AxonServerStoreSource, context: string): EventStore {
   const { connection, serializer, metadata: createAxonMetadata } = contextView(conn, context)
   const { eventToProto, eventFromProto } = createEventConverters(serializer)
 
-  // Push-based subscriber registry (EventBus.subscribe contract). Axon Server's
-  // own distribution is the server-side Stream RPC (see open()); these in-process
-  // subscribers are notified best-effort on every successful local append.
-  const subscribers = new Set<(events: ReadonlyArray<EventMessage>) => Promise<void>>()
-  async function notifySubscribers(events: ReadonlyArray<EventMessage>): Promise<void> {
-    for (const sub of subscribers) {
-      try {
-        await sub(events)
-      } catch {
-        /* ignore subscriber errors */
-      }
-    }
-  }
-
-  return {
-    async source(condition: SourcingCondition): Promise<SourcingResult> {
-      const criterions = criteriaToCriterions(compileQuery(condition.query))
+  async function sourceOnce(condition: SourcingCondition, signal: AbortSignal): Promise<SourcingResult> {
+    const criterions = criteriaToCriterions(compileQuery(condition.query))
+    const start = condition.start ?? 0n
 
-      const request = {
-        fromSequence: condition.start ?? 0n,
-        criterion: criterions,
-      }
+    const request = {
+      fromSequence: start,
+      criterion: criterions,
+    }
 
-      const events: EventMessage[] = []
-      let marker: ConsistencyMarker = noMarker()
+    const events: EventMessage[] = []
+    let marker: ConsistencyMarker = noMarker()
 
-      const stream = connection.eventStore.source(request, { metadata: createAxonMetadata() })
+    try {
+      const stream = connection.eventStore.source(request, { metadata: createAxonMetadata(), signal })
       for await (const response of stream) {
         if (response.event) {
           const taggedEvent = response.event
@@ -207,8 +208,30 @@ export function axonServerEventStore(conn: AxonServerStoreSource, context: strin
           marker = markerAt(response.consistencyMarker)
         }
       }
+    } catch (err) {
+      // READING PAST THE HEAD IS AN EMPTY ANSWER, NOT AN ERROR — and Axon
+      // Server disagrees, so this is where the two vocabularies are
+      // reconciled. `Source` fails OUT_OF_RANGE with "Start sequence cannot
+      // be larger than end sequence" whenever `fromSequence` is beyond the
+      // global head, which is the ORDINARY STEADY STATE of a snapshotted
+      // load: an entry written at the head means the very next read resumes
+      // at head + 1 and legitimately finds nothing.
+      //
+      // The marker is `start - 1`, and it is exact rather than conservative:
+      // the caller has already accounted for everything up to there (that is
+      // what asking to start later MEANS), and nothing can exist after it or
+      // the server would not have refused. So an append conditioned on this
+      // read is checked against precisely the range that was read.
+      if (!isStartPastHead(err)) throw err
+      return { events: [], marker: start > 0n ? markerAt(start - 1n) : noMarker() }
+    }
+
+    return { events, marker }
+  }
 
-      return { events, marker }
+  return {
+    source(condition: SourcingCondition): Promise<SourcingResult> {
+      return boundedRead(connection.config.readTimeoutMs, (signal) => sourceOnce(condition, signal))
     },
 
     async appendEvents(
@@ -239,7 +262,6 @@ export function axonServerEventStore(conn: AxonServerStoreSource, context: strin
             metadata: createAxonMetadata(),
           })
           responseMarker = response.consistencyMarker
-          await notifySubscribers(newEvents)
         },
         async afterCommit() {
           return markerAt(responseMarker ?? 0n)
@@ -267,7 +289,20 @@ export function axonServerEventStore(conn: AxonServerStoreSource, context: strin
         criterion: criterions,
       }
 
-      const grpcStream = connection.eventStore.stream(request, { metadata: createAxonMetadata() })
+      // `close()` must reach the server. This is a server-streaming call: the
+      // client sends nothing after the request, so the only way to end it from
+      // this side is to cancel it. Abandoning the async iterator does not do
+      // that — the `for await` below stays parked on the call until the next
+      // event arrives, which at the head of a quiet stream is never, and every
+      // closed stream leaves a live call behind on the server. With enough of
+      // them open, Axon Server stops answering later `source` reads (a 2-CPU
+      // container gets there after a handful): handlers never reply, and
+      // commands die at the server's own timeout.
+      const cancel = new AbortController()
+      const grpcStream = connection.eventStore.stream(request, {
+        metadata: createAxonMetadata(),
+        signal: cancel.signal,
+      })
 
       // Internal buffer for events pulled from the gRPC stream
       const buffer: SequencedEvent[] = []
@@ -296,7 +331,11 @@ export function axonServerEventStore(conn: AxonServerStoreSource, context: strin
           completed = true
           availableCallback?.()
         } catch (err) {
-          streamError = err instanceof Error ? err : new Error(String(err))
+          // Our own cancellation surfaces here as an AbortError; that is the
+          // stream closing as asked, not a failure to report.
+          if (!completed) {
+            streamError = err instanceof Error ? err : new Error(String(err))
+          }
           completed = true
           availableCallback?.()
         }
@@ -304,7 +343,7 @@ export function axonServerEventStore(conn: AxonServerStoreSource, context: strin
 
       startReading()
 
-      return messageStream<SequencedEvent>({
+      return {
         next() {
           return buffer.shift()
         },
@@ -332,13 +371,15 @@ export function axonServerEventStore(conn: AxonServerStoreSource, context: strin
         close() {
           completed = true
           availableCallback = null
-          // gRPC stream will be cancelled when the async iterator is abandoned
+          cancel.abort()
         },
-      })
+      }
     },
 
     async getHeadPosition(): Promise<bigint> {
-      const response = await connection.eventStore.getHead({}, { metadata: createAxonMetadata() })
+      const response = await boundedRead(connection.config.readTimeoutMs, (signal) =>
+        connection.eventStore.getHead({}, { metadata: createAxonMetadata(), signal }),
+      )
       return response.sequence
     },
 
@@ -347,21 +388,10 @@ export function axonServerEventStore(conn: AxonServerStoreSource, context: strin
     },
 
     async latestToken(): Promise<TrackingToken> {
-      const response = await connection.eventStore.getHead({}, { metadata: createAxonMetadata() })
+      const response = await boundedRead(connection.config.readTimeoutMs, (signal) =>
+        connection.eventStore.getHead({}, { metadata: createAxonMetadata(), signal }),
+      )
       return globalSequenceToken(response.sequence)
     },
-
-    // EventBus contract — publish = append without condition, then notify
-    // in-process subscribers.
-    async publish(events: ReadonlyArray<EventMessage>): Promise<void> {
-      await this.append(events)
-    },
-
-    subscribe(handler: (events: ReadonlyArray<EventMessage>) => Promise<void>): () => void {
-      subscribers.add(handler)
-      return () => {
-        subscribers.delete(handler)
-      }
-    },
   }
 }

package/src/axon-server-snapshotting-event-store.ts

@@ -0,0 +1,194 @@
+// ---------------------------------------------------------------------------
+// AXON SERVER SNAPSHOTS — the capability tier, served by `DcbSnapshotStore`.
+//
+// THE PROBE, AND WHAT IT SETTLED. Axon Server's public API defines both a
+// snapshot STORE service (`DcbSnapshotStore`: Add / Delete / List / GetLast)
+// and, on newer API drops, a fused `SnapshottedDcbEventStore.Source` whose
+// stream leads with the snapshot. Only the first of those is actually served:
+//
+//   axoniq/axonserver:2025.2.5   DcbSnapshotStore/GetLast   → answers
+//                                SnapshottedDcbEventStore/Source → UNIMPLEMENTED
+//   axoniq/axonserver:2026.0.4   same, both ways
+//
+// So there is no server-side fusion to call here — there is nothing on the
+// other end of the wire. The READ is therefore fused CLIENT-SIDE: `GetLast` for
+// the entry, then a source after its position, assembled into the one
+// `SourcingResult` a fold expects. Two round trips, the same answers, correct
+// today.
+//
+// When a server version does serve `SnapshottedDcbEventStore.Source`, the fused
+// call lands INSIDE this function — `source` stops making two calls and starts
+// making one — and no host changes a line, because the capability was never a
+// promise about round trips.
+// ---------------------------------------------------------------------------
+
+import type {
+  EventStore,
+  Snapshot,
+  SnapshotStoreCapability,
+  SourcingCondition,
+  SourcingResult,
+} from "@kronos-ts/core"
+import type { Serializer } from "@kronos-ts/core"
+import { withoutSnapshotKey } from "@kronos-ts/core"
+import type { AxonServerStoreSource } from "./connection.js"
+import { contextView } from "./context-view.js"
+import { boundedRead } from "./bounded-read.js"
+import type { Snapshot as ProtoSnapshot } from "./generated/dcb.js"
+
+// ---------------------------------------------------------------------------
+// Conversion — framework Snapshot ↔ proto Snapshot
+// ---------------------------------------------------------------------------
+
+const encoder = new TextEncoder()
+
+/**
+ * The proto message carries `name`, `version`, `timestamp` and a metadata map
+ * the narrowed seam has no equivalent for. `name` carries the cache key,
+ * `timestamp` is filled at write time for operators, and `version` stays EMPTY
+ * — snapshots have no versions, and inventing one to fill a proto field would
+ * be exactly the bookkeeping this design removed. The metadata map stays empty
+ * too: a cache entry carries no cargo.
+ */
+function createSnapshotConverters(serializer: Serializer) {
+  return {
+    snapshotToProto(name: string, snapshot: Snapshot): ProtoSnapshot {
+      const serialized = serializer.serialize(snapshot.state, name, "")
+      return {
+        name,
+        version: "",
+        payload: serialized.data,
+        timestamp: BigInt(Date.now()),
+        metadata: {},
+      }
+    },
+
+    snapshotFromProto(name: string, proto: ProtoSnapshot, position: bigint): Snapshot {
+      const state =
+        proto.payload.length > 0
+          ? serializer.deserialize({ data: proto.payload, type: name, revision: "" })
+          : {}
+
+      return { state, position }
+    },
+  }
+}
+
+function encodeKey(key: string): Uint8Array {
+  return encoder.encode(key)
+}
+
+// ---------------------------------------------------------------------------
+// Axon Server snapshot store
+// ---------------------------------------------------------------------------
+
+/**
+ * Add the snapshotting capability to an Axon Server-backed log.
+ *
+ * ```ts
+ * const eventStore = axonServerSnapshottingEventStore(
+ *   axonServerEventStore(axon, "default"),
+ *   axon,
+ *   "default",
+ * )
+ * ```
+ *
+ * ADDITIVE, NOT COLLAPSING. It returns `E & SnapshotStoreCapability` — the store you
+ * passed in, plus the write — so capabilities stack in either order and nothing
+ * the inner store carried is laundered on the way through.
+ *
+ * `context` is a per-call header, so this shares the one channel `conn` holds
+ * with every other context — see `contextView`. Payloads go through the
+ * connection's serializer.
+ *
+ * LATEST-ONLY, over a service that is not. `DcbSnapshotStore` keeps a sequence
+ * of snapshots per key; the capability keeps one. `add` therefore sets
+ * `prune: true`, so writing an entry retires the ones before it, and `getLast`
+ * is the only read. That is the narrowing doing its job: the framework programs
+ * against the cache it needs, not against everything the backend happens to
+ * offer.
+ */
+export function axonServerSnapshottingEventStore<E extends EventStore>(
+  next: E,
+  conn: AxonServerStoreSource,
+  context: string,
+): E & SnapshotStoreCapability {
+  const { connection, serializer, metadata: createAxonMetadata } = contextView(conn, context)
+  const { snapshotToProto, snapshotFromProto } = createSnapshotConverters(serializer)
+
+  /** The cached fold filed under `key`, or nothing — the first of the two calls. */
+  async function loadSnapshot(key: string): Promise<Snapshot | undefined> {
+    try {
+      const response = await boundedRead(connection.config.readTimeoutMs, (signal) =>
+        connection.snapshotStore.getLast(
+          { key: encodeKey(key) },
+          { metadata: createAxonMetadata(), signal },
+        ),
+      )
+
+      if (!response.snapshot) {
+        return undefined
+      }
+
+      return snapshotFromProto(key, response.snapshot, response.sequence)
+    } catch (err) {
+      // Axon Server throws rather than answering empty when no snapshot
+      // exists — and a cache miss is not an error to anybody upstream.
+      if (
+        String(err).includes("No snapshot found") ||
+        String(err).includes("not found")
+      ) {
+        return undefined
+      }
+      throw err
+    }
+  }
+
+  return {
+    ...next,
+
+    async storeSnapshot(key: string, snapshot: Snapshot): Promise<void> {
+      await connection.snapshotStore.add(
+        {
+          key: encodeKey(key),
+          sequence: snapshot.position,
+          prune: true,
+          snapshot: snapshotToProto(key, snapshot),
+        },
+        { metadata: createAxonMetadata() },
+      )
+    },
+
+    /**
+     * THE CLIENT-SIDE FUSION. Two calls, assembled into the one result a fold
+     * expects — and the cache is NEVER LOAD-BEARING, so a miss or an outright
+     * throw from the snapshot service both fall through to a full read.
+     */
+    async source(condition: SourcingCondition): Promise<SourcingResult> {
+      const key = condition.snapshot
+      if (key === undefined) return next.source(condition)
+
+      // The strategy is CONSUMED here; the store below gets a plain condition.
+      const plain = withoutSnapshotKey(condition)
+
+      let snapshot: Snapshot | undefined
+      try {
+        snapshot = await loadSnapshot(key.key)
+      } catch {
+        // A cache you cannot reach is a cache miss. Loads stay correct; they
+        // just cost what they always cost.
+        return next.source(plain)
+      }
+      if (snapshot === undefined) return next.source(plain)
+
+      // Resume AFTER the position the snapshot already folded; a condition that
+      // independently asked to start later keeps its own floor.
+      const resumeFrom = snapshot.position + 1n
+      const start =
+        plain.start !== undefined && plain.start > resumeFrom ? plain.start : resumeFrom
+
+      const result = await next.source({ ...plain, start })
+      return { ...result, snapshot }
+    },
+  } as E & SnapshotStoreCapability
+}