@kronos-ts/axon-server 0.4.0 → 0.5.0

package/src/resilience.ts

@@ -0,0 +1,149 @@
+/**
+ * Connection resilience — PACKAGE-PRIVATE.
+ *
+ * Exponential backoff with full jitter, per-event attempt caps, terminal-error
+ * short-circuit, and a warn-then-continue health probe. Nothing here is
+ * exported from this package's barrel.
+ *
+ * It used to live in `@kronos-ts/core`, and it does not belong there. Core is
+ * only what cannot be a helper, and this is a helper by every test: it touches
+ * no core shape, no message, no unit of work — it is `setTimeout` and a loop
+ * over a function anybody could have written. Its only consumers were the
+ * transports and the pool, core's own `src/` never called it, and a helper
+ * lives with its users. Same reasoning that moved each persistence package's
+ * transaction glue out of core, applied one folder up.
+ *
+ * Each consuming package keeps its own copy, carrying only what it uses, so
+ * each can also state its own retry policy without negotiating with the others.
+ */
+
+/** Classified retry sites used by transport extensions (D-97). */
+export type RetryEvent =
+  | "initial-connect"
+  | "reconnect"
+  | "per-operation"
+  | "health-check"
+
+export type ResilienceConfig = {
+  /** Initial backoff delay (ms). Default: 100. */
+  initialDelayMs: number
+  /** Cap for backoff (ms). Default: 30_000. */
+  maxDelayMs: number
+  /** Max retry attempts before giving up. Per-event defaults applied if not provided. */
+  maxAttempts: number
+  /** Base for exponential growth. Default: 2. */
+  multiplier: number
+  /** Health-check threshold (ms) before warn-then-continue. Default: 5000. */
+  healthCheckThresholdMs: number
+  /** Optional logger. Defaults to console.warn. */
+  log?: (msg: string) => void
+  /** Per-attempt classification: returns false to short-circuit (terminal error). */
+  isRetryable?: (err: unknown) => boolean
+}
+
+const DEFAULTS: Omit<ResilienceConfig, "log" | "isRetryable"> = {
+  initialDelayMs: 100,
+  maxDelayMs: 30_000,
+  maxAttempts: 10,
+  multiplier: 2,
+  healthCheckThresholdMs: 5_000,
+}
+
+const ATTEMPTS_BY_EVENT: Record<RetryEvent, number> = {
+  "initial-connect": 10,
+  "reconnect": 30,
+  "per-operation": 5,
+  "health-check": 3,
+}
+
+function resolveConfig(
+  event: RetryEvent,
+  partial?: Partial<ResilienceConfig>,
+): ResilienceConfig {
+  return {
+    ...DEFAULTS,
+    maxAttempts: ATTEMPTS_BY_EVENT[event],
+    ...partial,
+  }
+}
+
+function fullJitterDelay(attempt: number, cfg: ResilienceConfig): number {
+  const exponential = Math.min(
+    cfg.initialDelayMs * Math.pow(cfg.multiplier, attempt),
+    cfg.maxDelayMs,
+  )
+  return Math.random() * exponential
+}
+
+/**
+ * Run `fn` with exponential-backoff full-jitter retries.
+ *
+ * Resolves with the first successful result, or rejects with the last error
+ * after `maxAttempts` exhausted. If `isRetryable(err)` returns false on any
+ * attempt, the error is rethrown immediately (terminal error short-circuit).
+ *
+ * D-101: opts may carry caller-supplied resilience overrides — this is the
+ * per-extension knob path (`kronosDbConnection({ resilience: { ... } })`).
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  opts: { event: RetryEvent } & Partial<ResilienceConfig>,
+): Promise<T> {
+  const cfg = resolveConfig(opts.event, opts)
+  let lastErr: unknown
+  for (let attempt = 0; attempt < cfg.maxAttempts; attempt++) {
+    try {
+      return await fn()
+    } catch (err) {
+      lastErr = err
+      if (cfg.isRetryable && !cfg.isRetryable(err)) throw err
+      if (attempt === cfg.maxAttempts - 1) break
+      const delay = fullJitterDelay(attempt, cfg)
+      cfg.log?.(
+        `[kronos:resilience] ${opts.event} attempt ${attempt + 1}/${cfg.maxAttempts} ` +
+          `failed; retrying in ${Math.round(delay)}ms — ${
+            (err as Error)?.message ?? String(err)
+          }`,
+      )
+      await new Promise((r) => setTimeout(r, delay))
+    }
+  }
+  throw lastErr
+}
+
+/**
+ * Run a health-check probe with warn-then-continue semantics (D-100).
+ *
+ * Resolves WITHOUT throwing on success OR after `thresholdMs` elapses with
+ * the probe still pending — production loops should NEVER stall on a flaky
+ * health probe. Failures (rejection or threshold breach) emit a single warn
+ * via `log` and otherwise resolve normally.
+ */
+export async function healthCheck(
+  fn: () => Promise<void>,
+  opts: { thresholdMs?: number; log?: (msg: string) => void } = {},
+): Promise<void> {
+  const threshold = opts.thresholdMs ?? DEFAULTS.healthCheckThresholdMs
+  const log = opts.log ?? ((m: string) => console.warn(m))
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    await Promise.race([
+      fn(),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error("health-check threshold exceeded")),
+          threshold,
+        )
+      }),
+    ])
+  } catch (err) {
+    log(
+      `[kronos:resilience] health-check soft-failed (${
+        (err as Error)?.message ?? String(err)
+      }); continuing`,
+    )
+    // warn-then-continue: do NOT rethrow.
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}

package/src/shutdown-latch.ts

@@ -10,7 +10,7 @@
  *
  * This is the TypeScript equivalent of AF5's ShutdownLatch pattern.
  */
-export interface ShutdownLatch {
+export type ShutdownLatch = {
   /**
    * Register an in-flight activity. Throws if shutdown is in progress.
    * Call `end()` on the returned handle when the activity completes.
@@ -31,7 +31,7 @@ export interface ShutdownLatch {
   readonly activeCount: number
 }
 
-export interface ActivityHandle {
+export type ActivityHandle = {
   /** Mark this activity as complete. */
   end(): void
 }

package/dist/axon-server-snapshot-store.d.ts

@@ -1,12 +0,0 @@
-import type { SnapshotStore } from "@kronos-ts/core";
-import type { AxonServerStoreSource } from "./connection.js";
-/**
- * A SnapshotStore over Axon Server's gRPC snapshot service, in one context.
- *
- * Uses the `DcbSnapshotStore` gRPC service to store and retrieve state
- * snapshots. `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.
- */
-export declare function axonServerSnapshotStore(conn: AxonServerStoreSource, context: string): SnapshotStore;
-//# sourceMappingURL=axon-server-snapshot-store.d.ts.map

package/dist/axon-server-snapshot-store.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"axon-server-snapshot-store.d.ts","sourceRoot":"","sources":["../src/axon-server-snapshot-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,iBAAiB,CAAA;AAE9D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAgD5D;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,MAAM,GACd,aAAa,CAgDf"}

package/dist/axon-server-snapshot-store.js

@@ -1,82 +0,0 @@
-import { contextView } from "./context-view.js";
-// ---------------------------------------------------------------------------
-// Conversion — framework Snapshot ↔ proto Snapshot
-// ---------------------------------------------------------------------------
-const encoder = new TextEncoder();
-function createSnapshotConverters(serializer) {
-    return {
-        snapshotToProto(snapshot) {
-            const serialized = serializer.serialize(snapshot.payload, "snapshot", "");
-            return {
-                name: "",
-                version: "",
-                payload: serialized.data,
-                timestamp: BigInt(snapshot.timestamp),
-                metadata: snapshot.metadata,
-            };
-        },
-        snapshotFromProto(proto, position) {
-            const payload = proto.payload.length > 0
-                ? serializer.deserialize({ data: proto.payload, type: "snapshot", revision: "" })
-                : {};
-            return {
-                position,
-                payload,
-                timestamp: Number(proto.timestamp),
-                metadata: proto.metadata ?? {},
-            };
-        },
-    };
-}
-function encodeKey(stateName, id) {
-    const idStr = typeof id === "object" && id !== null ? JSON.stringify(id) : String(id);
-    return encoder.encode(`${stateName}:${idStr}`);
-}
-// ---------------------------------------------------------------------------
-// Axon Server snapshot store
-// ---------------------------------------------------------------------------
-/**
- * A SnapshotStore over Axon Server's gRPC snapshot service, in one context.
- *
- * Uses the `DcbSnapshotStore` gRPC service to store and retrieve state
- * snapshots. `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.
- */
-export function axonServerSnapshotStore(conn, context) {
-    const { connection, serializer, metadata: createAxonMetadata } = contextView(conn, context);
-    const { snapshotToProto, snapshotFromProto } = createSnapshotConverters(serializer);
-    return {
-        async store(stateName, id, snapshot) {
-            await connection.snapshotStore.add({
-                key: encodeKey(stateName, id),
-                sequence: snapshot.position,
-                prune: true,
-                snapshot: snapshotToProto(snapshot),
-            }, { metadata: createAxonMetadata() });
-        },
-        async load(stateName, id) {
-            try {
-                const response = await connection.snapshotStore.getLast({ key: encodeKey(stateName, id) }, { metadata: createAxonMetadata() });
-                if (!response.snapshot) {
-                    return undefined;
-                }
-                return snapshotFromProto(response.snapshot, response.sequence);
-            }
-            catch (err) {
-                // Axon Server throws when no snapshot exists — treat as "not found"
-                if (String(err).includes("No snapshot found")) {
-                    return undefined;
-                }
-                throw err;
-            }
-        },
-        async deleteSnapshots(stateName, id) {
-            await connection.snapshotStore.delete({
-                key: encodeKey(stateName, id),
-                toSequence: BigInt(Number.MAX_SAFE_INTEGER),
-            }, { metadata: createAxonMetadata() });
-        },
-    };
-}
-//# sourceMappingURL=axon-server-snapshot-store.js.map

package/dist/axon-server-snapshot-store.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"axon-server-snapshot-store.js","sourceRoot":"","sources":["../src/axon-server-snapshot-store.ts"],"names":[],"mappings":"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"}

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

@@ -1,110 +0,0 @@
-import type { SnapshotStore, Snapshot } from "@kronos-ts/core"
-import type { Serializer } from "@kronos-ts/core"
-import type { AxonServerStoreSource } from "./connection.js"
-import { contextView } from "./context-view.js"
-import type { Snapshot as ProtoSnapshot } from "./generated/dcb.js"
-
-// ---------------------------------------------------------------------------
-// Conversion — framework Snapshot ↔ proto Snapshot
-// ---------------------------------------------------------------------------
-
-const encoder = new TextEncoder()
-
-function createSnapshotConverters(serializer: Serializer) {
-  return {
-    snapshotToProto(snapshot: Snapshot): ProtoSnapshot {
-      const serialized = serializer.serialize(snapshot.payload, "snapshot", "")
-      return {
-        name: "",
-        version: "",
-        payload: serialized.data,
-        timestamp: BigInt(snapshot.timestamp),
-        metadata: snapshot.metadata,
-      }
-    },
-
-    snapshotFromProto(proto: ProtoSnapshot, position: bigint): Snapshot {
-      const payload =
-        proto.payload.length > 0
-          ? serializer.deserialize({ data: proto.payload, type: "snapshot", revision: "" })
-          : {}
-
-      return {
-        position,
-        payload,
-        timestamp: Number(proto.timestamp),
-        metadata: proto.metadata ?? {},
-      }
-    },
-  }
-}
-
-function encodeKey(stateName: string, id: unknown): Uint8Array {
-  const idStr = typeof id === "object" && id !== null ? JSON.stringify(id) : String(id)
-  return encoder.encode(`${stateName}:${idStr}`)
-}
-
-// ---------------------------------------------------------------------------
-// Axon Server snapshot store
-// ---------------------------------------------------------------------------
-
-/**
- * A SnapshotStore over Axon Server's gRPC snapshot service, in one context.
- *
- * Uses the `DcbSnapshotStore` gRPC service to store and retrieve state
- * snapshots. `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.
- */
-export function axonServerSnapshotStore(
-  conn: AxonServerStoreSource,
-  context: string,
-): SnapshotStore {
-  const { connection, serializer, metadata: createAxonMetadata } = contextView(conn, context)
-  const { snapshotToProto, snapshotFromProto } = createSnapshotConverters(serializer)
-
-  return {
-    async store(stateName: string, id: unknown, snapshot: Snapshot): Promise<void> {
-      await connection.snapshotStore.add(
-        {
-          key: encodeKey(stateName, id),
-          sequence: snapshot.position,
-          prune: true,
-          snapshot: snapshotToProto(snapshot),
-        },
-        { metadata: createAxonMetadata() },
-      )
-    },
-
-    async load(stateName: string, id: unknown): Promise<Snapshot | undefined> {
-      try {
-        const response = await connection.snapshotStore.getLast(
-          { key: encodeKey(stateName, id) },
-          { metadata: createAxonMetadata() },
-        )
-
-        if (!response.snapshot) {
-          return undefined
-        }
-
-        return snapshotFromProto(response.snapshot, response.sequence)
-      } catch (err) {
-        // Axon Server throws when no snapshot exists — treat as "not found"
-        if (String(err).includes("No snapshot found")) {
-          return undefined
-        }
-        throw err
-      }
-    },
-
-    async deleteSnapshots(stateName: string, id: unknown): Promise<void> {
-      await connection.snapshotStore.delete(
-        {
-          key: encodeKey(stateName, id),
-          toSequence: BigInt(Number.MAX_SAFE_INTEGER),
-        },
-        { metadata: createAxonMetadata() },
-      )
-    },
-  }
-}