@kronos-ts/kronosdb 0.1.0

package/dist/service-definitions.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Re-exports the generated gRPC service definitions for KronosDB.
+ * Used internally by the connector and can be passed to connectToKronosDb().
+ */
+import { PlatformServiceDefinition } from "./generated/platform.js";
+import { CommandServiceDefinition } from "./generated/command.js";
+import { QueryServiceDefinition } from "./generated/query.js";
+import { EventStoreDefinition } from "./generated/eventstore.js";
+import { SnapshotStoreDefinition } from "./generated/snapshot.js";
+export declare const kronosDbServiceDefinitions: {
+    readonly platform: {
+        readonly name: "PlatformService";
+        readonly fullName: "kronosdb.platform.PlatformService";
+        readonly methods: {
+            readonly getPlatformServer: {
+                readonly name: "GetPlatformServer";
+                readonly requestType: typeof import("./generated/platform.js").ClientIdentification;
+                readonly requestStream: false;
+                readonly responseType: typeof import("./generated/platform.js").PlatformInfo;
+                readonly responseStream: false;
+                readonly options: {};
+            };
+            readonly openStream: {
+                readonly name: "OpenStream";
+                readonly requestType: typeof import("./generated/platform.js").PlatformInbound;
+                readonly requestStream: true;
+                readonly responseType: typeof import("./generated/platform.js").PlatformOutbound;
+                readonly responseStream: true;
+                readonly options: {};
+            };
+        };
+    };
+    readonly commands: {
+        readonly name: "CommandService";
+        readonly fullName: "kronosdb.command.CommandService";
+        readonly methods: {
+            readonly openStream: {
+                readonly name: "OpenStream";
+                readonly requestType: typeof import("./generated/command.js").CommandHandlerOutbound;
+                readonly requestStream: true;
+                readonly responseType: typeof import("./generated/command.js").CommandHandlerInbound;
+                readonly responseStream: true;
+                readonly options: {};
+            };
+            readonly dispatch: {
+                readonly name: "Dispatch";
+                readonly requestType: typeof import("./generated/command.js").Command;
+                readonly requestStream: false;
+                readonly responseType: typeof import("./generated/command.js").CommandResponse;
+                readonly responseStream: false;
+                readonly options: {};
+            };
+        };
+    };
+    readonly queries: {
+        readonly name: "QueryService";
+        readonly fullName: "kronosdb.query.QueryService";
+        readonly methods: {
+            readonly openStream: {
+                readonly name: "OpenStream";
+                readonly requestType: typeof import("./generated/query.js").QueryHandlerOutbound;
+                readonly requestStream: true;
+                readonly responseType: typeof import("./generated/query.js").QueryHandlerInbound;
+                readonly responseStream: true;
+                readonly options: {};
+            };
+            readonly query: {
+                readonly name: "Query";
+                readonly requestType: typeof import("./generated/query.js").QueryRequest;
+                readonly requestStream: false;
+                readonly responseType: typeof import("./generated/query.js").QueryResponse;
+                readonly responseStream: true;
+                readonly options: {};
+            };
+            readonly subscription: {
+                readonly name: "Subscription";
+                readonly requestType: typeof import("./generated/query.js").SubscriptionQueryRequest;
+                readonly requestStream: true;
+                readonly responseType: typeof import("./generated/query.js").SubscriptionQueryResponse;
+                readonly responseStream: true;
+                readonly options: {};
+            };
+        };
+    };
+    readonly eventStore: {
+        readonly name: "EventStore";
+        readonly fullName: "kronosdb.eventstore.EventStore";
+        readonly methods: {
+            readonly append: {
+                readonly name: "Append";
+                readonly requestType: typeof import("./generated/eventstore.js").AppendRequest;
+                readonly requestStream: true;
+                readonly responseType: typeof import("./generated/eventstore.js").AppendResponse;
+                readonly responseStream: false;
+                readonly options: {};
+            };
+            readonly source: {
+                readonly name: "Source";
+                readonly requestType: typeof import("./generated/eventstore.js").SourceRequest;
+                readonly requestStream: false;
+                readonly responseType: typeof import("./generated/eventstore.js").SourceResponse;
+                readonly responseStream: true;
+                readonly options: {};
+            };
+            readonly stream: {
+                readonly name: "Stream";
+                readonly requestType: typeof import("./generated/eventstore.js").StreamControl;
+                readonly requestStream: true;
+                readonly responseType: typeof import("./generated/eventstore.js").StreamResponse;
+                readonly responseStream: true;
+                readonly options: {};
+            };
+            readonly getHead: {
+                readonly name: "GetHead";
+                readonly requestType: typeof import("./generated/eventstore.js").GetHeadRequest;
+                readonly requestStream: false;
+                readonly responseType: typeof import("./generated/eventstore.js").GetHeadResponse;
+                readonly responseStream: false;
+                readonly options: {};
+            };
+            readonly getTail: {
+                readonly name: "GetTail";
+                readonly requestType: typeof import("./generated/eventstore.js").GetTailRequest;
+                readonly requestStream: false;
+                readonly responseType: typeof import("./generated/eventstore.js").GetTailResponse;
+                readonly responseStream: false;
+                readonly options: {};
+            };
+            readonly getTags: {
+                readonly name: "GetTags";
+                readonly requestType: typeof import("./generated/eventstore.js").GetTagsRequest;
+                readonly requestStream: false;
+                readonly responseType: typeof import("./generated/eventstore.js").GetTagsResponse;
+                readonly responseStream: false;
+                readonly options: {};
+            };
+            readonly getSequenceAt: {
+                readonly name: "GetSequenceAt";
+                readonly requestType: typeof import("./generated/eventstore.js").GetSequenceAtRequest;
+                readonly requestStream: false;
+                readonly responseType: typeof import("./generated/eventstore.js").GetSequenceAtResponse;
+                readonly responseStream: false;
+                readonly options: {};
+            };
+        };
+    };
+    readonly snapshotStore: {
+        readonly name: "SnapshotStore";
+        readonly fullName: "kronosdb.snapshot.SnapshotStore";
+        readonly methods: {
+            readonly add: {
+                readonly name: "Add";
+                readonly requestType: typeof import("./generated/snapshot.js").AddSnapshotRequest;
+                readonly requestStream: false;
+                readonly responseType: typeof import("./generated/snapshot.js").AddSnapshotResponse;
+                readonly responseStream: false;
+                readonly options: {};
+            };
+            readonly delete: {
+                readonly name: "Delete";
+                readonly requestType: typeof import("./generated/snapshot.js").DeleteSnapshotsRequest;
+                readonly requestStream: false;
+                readonly responseType: typeof import("./generated/snapshot.js").DeleteSnapshotsResponse;
+                readonly responseStream: false;
+                readonly options: {};
+            };
+            readonly list: {
+                readonly name: "List";
+                readonly requestType: typeof import("./generated/snapshot.js").ListSnapshotsRequest;
+                readonly requestStream: false;
+                readonly responseType: typeof import("./generated/snapshot.js").ListSnapshotsResponse;
+                readonly responseStream: true;
+                readonly options: {};
+            };
+            readonly getLast: {
+                readonly name: "GetLast";
+                readonly requestType: typeof import("./generated/snapshot.js").GetLastSnapshotRequest;
+                readonly requestStream: false;
+                readonly responseType: typeof import("./generated/snapshot.js").GetLastSnapshotResponse;
+                readonly responseStream: false;
+                readonly options: {};
+            };
+        };
+    };
+};
+export { PlatformServiceDefinition, CommandServiceDefinition, QueryServiceDefinition, EventStoreDefinition, SnapshotStoreDefinition, };
+//# sourceMappingURL=service-definitions.d.ts.map

package/dist/service-definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-definitions.d.ts","sourceRoot":"","sources":["../src/service-definitions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAM7B,CAAA;AAEV,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,GACxB,CAAA"}

package/dist/service-definitions.js

@@ -0,0 +1,18 @@
+/**
+ * Re-exports the generated gRPC service definitions for KronosDB.
+ * Used internally by the connector and can be passed to connectToKronosDb().
+ */
+import { PlatformServiceDefinition } from "./generated/platform.js";
+import { CommandServiceDefinition } from "./generated/command.js";
+import { QueryServiceDefinition } from "./generated/query.js";
+import { EventStoreDefinition } from "./generated/eventstore.js";
+import { SnapshotStoreDefinition } from "./generated/snapshot.js";
+export const kronosDbServiceDefinitions = {
+    platform: PlatformServiceDefinition,
+    commands: CommandServiceDefinition,
+    queries: QueryServiceDefinition,
+    eventStore: EventStoreDefinition,
+    snapshotStore: SnapshotStoreDefinition,
+};
+export { PlatformServiceDefinition, CommandServiceDefinition, QueryServiceDefinition, EventStoreDefinition, SnapshotStoreDefinition, };
+//# sourceMappingURL=service-definitions.js.map

package/dist/service-definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-definitions.js","sourceRoot":"","sources":["../src/service-definitions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,QAAQ,EAAE,yBAAyB;IACnC,QAAQ,EAAE,wBAAwB;IAClC,OAAO,EAAE,sBAAsB;IAC/B,UAAU,EAAE,oBAAoB;IAChC,aAAa,EAAE,uBAAuB;CAC9B,CAAA;AAEV,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,GACxB,CAAA"}

package/dist/shutdown-latch.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A shutdown latch that tracks in-flight operations and enables
+ * graceful shutdown by draining pending work.
+ */
+export interface ShutdownLatch {
+    registerActivity(): ActivityHandle;
+    initiateShutdown(): Promise<void>;
+    readonly shuttingDown: boolean;
+    readonly activeCount: number;
+}
+export interface ActivityHandle {
+    end(): void;
+}
+export declare class ShutdownInProgressError extends Error {
+    constructor(message?: string);
+}
+export declare function createShutdownLatch(): ShutdownLatch;
+//# sourceMappingURL=shutdown-latch.d.ts.map

package/dist/shutdown-latch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown-latch.d.ts","sourceRoot":"","sources":["../src/shutdown-latch.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,gBAAgB,IAAI,cAAc,CAAA;IAClC,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,IAAI,IAAI,CAAA;CACZ;AAED,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,GAAE,MAA+B;CAIrD;AAED,wBAAgB,mBAAmB,IAAI,aAAa,CAmDnD"}

package/dist/shutdown-latch.js

@@ -0,0 +1,51 @@
+export class ShutdownInProgressError extends Error {
+    constructor(message = "Shutdown in progress") {
+        super(message);
+        this.name = "ShutdownInProgressError";
+    }
+}
+export function createShutdownLatch() {
+    let activeCount = 0;
+    let shuttingDown = false;
+    let drainResolve = null;
+    function checkDrained() {
+        if (shuttingDown && activeCount === 0 && drainResolve) {
+            drainResolve();
+            drainResolve = null;
+        }
+    }
+    return {
+        registerActivity() {
+            if (shuttingDown) {
+                throw new ShutdownInProgressError();
+            }
+            activeCount++;
+            let ended = false;
+            return {
+                end() {
+                    if (ended)
+                        return;
+                    ended = true;
+                    activeCount--;
+                    checkDrained();
+                },
+            };
+        },
+        initiateShutdown() {
+            shuttingDown = true;
+            if (activeCount === 0) {
+                return Promise.resolve();
+            }
+            return new Promise((resolve) => {
+                drainResolve = resolve;
+            });
+        },
+        get shuttingDown() {
+            return shuttingDown;
+        },
+        get activeCount() {
+            return activeCount;
+        },
+    };
+}
+//# sourceMappingURL=shutdown-latch.js.map

package/dist/shutdown-latch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown-latch.js","sourceRoot":"","sources":["../src/shutdown-latch.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,UAAkB,sBAAsB;QAClD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;IACvC,CAAC;CACF;AAED,MAAM,UAAU,mBAAmB;IACjC,IAAI,WAAW,GAAG,CAAC,CAAA;IACnB,IAAI,YAAY,GAAG,KAAK,CAAA;IACxB,IAAI,YAAY,GAAwB,IAAI,CAAA;IAE5C,SAAS,YAAY;QACnB,IAAI,YAAY,IAAI,WAAW,KAAK,CAAC,IAAI,YAAY,EAAE,CAAC;YACtD,YAAY,EAAE,CAAA;YACd,YAAY,GAAG,IAAI,CAAA;QACrB,CAAC;IACH,CAAC;IAED,OAAO;QACL,gBAAgB;YACd,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,IAAI,uBAAuB,EAAE,CAAA;YACrC,CAAC;YAED,WAAW,EAAE,CAAA;YACb,IAAI,KAAK,GAAG,KAAK,CAAA;YAEjB,OAAO;gBACL,GAAG;oBACD,IAAI,KAAK;wBAAE,OAAM;oBACjB,KAAK,GAAG,IAAI,CAAA;oBACZ,WAAW,EAAE,CAAA;oBACb,YAAY,EAAE,CAAA;gBAChB,CAAC;aACF,CAAA;QACH,CAAC;QAED,gBAAgB;YACd,YAAY,GAAG,IAAI,CAAA;YAEnB,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;gBACtB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;YAC1B,CAAC;YAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;gBAC7B,YAAY,GAAG,OAAO,CAAA;YACxB,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,IAAI,YAAY;YACd,OAAO,YAAY,CAAA;QACrB,CAAC;QAED,IAAI,WAAW;YACb,OAAO,WAAW,CAAA;QACpB,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@kronos-ts/kronosdb",
+  "version": "0.1.0",
+  "description": "KronosDB extension for Kronos — native event store transport.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "author": "Theo Emanuelsson",
+  "homepage": "https://github.com/KronosDB/kronos-ts/tree/main/packages/extensions/kronosdb#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KronosDB/kronos-ts.git",
+    "directory": "packages/extensions/kronosdb"
+  },
+  "bugs": {
+    "url": "https://github.com/KronosDB/kronos-ts/issues"
+  },
+  "keywords": [
+    "kronos",
+    "event-sourcing",
+    "cqrs",
+    "dcb",
+    "typescript",
+    "kronosdb"
+  ],
+  "sideEffects": false,
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__",
+    "!src/**/*.test.ts",
+    "!src/**/*.bench.ts"
+  ],
+  "scripts": {
+    "generate-proto": "grpc_tools_node_protoc --ts_proto_out=./src/generated --ts_proto_opt=outputServices=nice-grpc,outputServices=generic-definitions,useExactTypes=false,esModuleInterop=true,forceLong=bigint --proto_path=./proto ./proto/*.proto",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@kronos-ts/common": "workspace:*",
+    "@kronos-ts/app": "workspace:*",
+    "@kronos-ts/eventsourcing": "workspace:*",
+    "@kronos-ts/messaging": "workspace:*",
+    "@kronos-ts/modelling": "workspace:*",
+    "@bufbuild/protobuf": "^2.3",
+    "@grpc/grpc-js": "^1.12",
+    "nice-grpc": "^2.1",
+    "nice-grpc-common": "^2.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "grpc-tools": "^1.12",
+    "grpc_tools_node_protoc_ts": "^5.3",
+    "testcontainers": "^11.13.0",
+    "ts-proto": "^2.6"
+  }
+}

package/src/connection.ts

@@ -0,0 +1,235 @@
+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 {
+  kronosDbServiceDefinitions,
+  PlatformServiceDefinition,
+  CommandServiceDefinition,
+  QueryServiceDefinition,
+  EventStoreDefinition,
+  SnapshotStoreDefinition,
+} from "./service-definitions.js"
+
+/**
+ * Configuration for connecting to KronosDB.
+ */
+export interface KronosDbConnectionConfig {
+  /** Host of the KronosDB server. Defaults to "localhost". */
+  host?: string
+  /** gRPC port of the KronosDB server. Defaults to 50051. */
+  port?: number
+  /**
+   * Multiple server addresses for cluster deployments.
+   * Each entry is `"host:port"`. When provided, overrides `host` and `port`.
+   * The connector tries servers in order and fails over to the next on failure.
+   */
+  servers?: string[]
+  /** The context to connect to. Defaults to "default". */
+  context?: string
+  /** Name identifying this component to KronosDB. */
+  componentName: string
+  /** Unique client identifier. Defaults to a generated UUID. */
+  clientId?: string
+  /** Access token for authentication. Optional. */
+  token?: string
+  /** Reconnection interval in ms. Defaults to 2000. */
+  reconnectIntervalMs?: number
+  /** Maximum reconnection attempts before giving up. 0 = unlimited. Defaults to 0. */
+  maxReconnectAttempts?: number
+
+  /** gRPC keepalive ping interval in ms. Default: 30000. */
+  keepAliveTimeMs?: number
+  /** gRPC keepalive timeout in ms. Default: 10000. */
+  keepAliveTimeoutMs?: number
+  /** Allow keepalive pings without active RPCs. Default: true. */
+  keepAlivePermitWithoutCalls?: boolean
+
+  /** TLS/SSL configuration. */
+  ssl?: {
+    enabled: boolean
+    certFile?: string
+    clientCertFile?: string
+    clientKeyFile?: string
+  }
+}
+
+export type ConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting" | "closed"
+
+/**
+ * An active connection to KronosDB, providing typed gRPC clients
+ * for all services. Supports reconnection on failure.
+ */
+export interface KronosDbConnection {
+  readonly channel: Channel
+  /** Platform service client. */
+  readonly platform: Client<typeof PlatformServiceDefinition>
+  /** Command service client. */
+  readonly commands: Client<typeof CommandServiceDefinition>
+  /** Query service client. */
+  readonly queries: Client<typeof QueryServiceDefinition>
+  /** Event store client. */
+  readonly eventStore: Client<typeof EventStoreDefinition>
+  /** Snapshot store client. */
+  readonly snapshotStore: Client<typeof SnapshotStoreDefinition>
+  /** The resolved configuration. `servers` and `ssl` stay optional — they have no defaults. */
+  readonly config: Omit<Required<KronosDbConnectionConfig>, "servers" | "ssl"> & {
+    servers?: KronosDbConnectionConfig["servers"]
+    ssl?: KronosDbConnectionConfig["ssl"]
+  }
+  readonly state: ConnectionState
+  onReconnect(callback: () => void): void
+  onDisconnect(callback: (error?: Error) => void): void
+  close(): void
+  reconnect(): Promise<void>
+}
+
+/**
+ * Creates gRPC metadata for KronosDB requests.
+ * Injects context and optional auth token as headers.
+ */
+export function createKronosMetadata(config: { context: string; token: string }): Metadata {
+  const metadata = new Metadata()
+  metadata.set("kronosdb-context", config.context)
+  if (config.token) {
+    metadata.set("kronosdb-token", config.token)
+  }
+  return metadata
+}
+
+/**
+ * Connects to KronosDB and returns typed gRPC clients for all services.
+ *
+ * Configures gRPC channel-level keepalive to maintain persistent connections.
+ */
+export function connectToKronosDb(config: KronosDbConnectionConfig): KronosDbConnection {
+  const serviceDefinitions = kronosDbServiceDefinitions
+  const resolvedConfig = {
+    host: config.host ?? "localhost",
+    port: config.port ?? 50051,
+    context: config.context ?? "default",
+    componentName: config.componentName,
+    clientId: config.clientId ?? crypto.randomUUID(),
+    token: config.token ?? "",
+    reconnectIntervalMs: config.reconnectIntervalMs ?? 2000,
+    maxReconnectAttempts: config.maxReconnectAttempts ?? 0,
+    keepAliveTimeMs: config.keepAliveTimeMs ?? 30000,
+    keepAliveTimeoutMs: config.keepAliveTimeoutMs ?? 10000,
+    keepAlivePermitWithoutCalls: config.keepAlivePermitWithoutCalls ?? true,
+    servers: config.servers,
+    ssl: config.ssl,
+  }
+
+  const sslConfig = config.ssl
+  let credentials: ChannelCredentials | undefined
+
+  if (sslConfig?.enabled) {
+    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
+  }
+
+  const channelOptions = {
+    "grpc.keepalive_time_ms": config.keepAliveTimeMs ?? 30000,
+    "grpc.keepalive_timeout_ms": config.keepAliveTimeoutMs ?? 10000,
+    "grpc.keepalive_permit_without_calls": (config.keepAlivePermitWithoutCalls ?? true) ? 1 : 0,
+  }
+
+  const serverAddresses = config.servers && config.servers.length > 0
+    ? config.servers
+    : [`${resolvedConfig.host}:${resolvedConfig.port}`]
+
+  let currentServerIndex = 0
+
+  function createGrpcChannel(): Channel {
+    const address = serverAddresses[currentServerIndex % serverAddresses.length]!
+    return credentials
+      ? createChannel(address, credentials, channelOptions)
+      : createChannel(address, undefined, channelOptions)
+  }
+
+  let channel = createGrpcChannel()
+  let state: ConnectionState = "connected"
+
+  const reconnectCallbacks: Array<() => void> = []
+  const disconnectCallbacks: Array<(error?: Error) => void> = []
+
+  function createClients() {
+    return {
+      platform: createClient(serviceDefinitions.platform, channel),
+      commands: createClient(serviceDefinitions.commands, channel),
+      queries: createClient(serviceDefinitions.queries, channel),
+      eventStore: createClient(serviceDefinitions.eventStore, channel),
+      snapshotStore: createClient(serviceDefinitions.snapshotStore, channel),
+    }
+  }
+
+  let clients = createClients()
+
+  const connection: KronosDbConnection = {
+    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 },
+
+    onReconnect(callback) {
+      reconnectCallbacks.push(callback)
+    },
+
+    onDisconnect(callback) {
+      disconnectCallbacks.push(callback)
+    },
+
+    close() {
+      state = "closed"
+      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 {
+          currentServerIndex++
+          channel = createGrpcChannel()
+          clients = createClients()
+          state = "connected"
+
+          for (const cb of reconnectCallbacks) {
+            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}`,
+            )
+          }
+
+          const delay = Math.min(
+            resolvedConfig.reconnectIntervalMs * Math.pow(2, attempt - 1),
+            30000,
+          )
+          await new Promise((r) => setTimeout(r, delay))
+        }
+      }
+    },
+  }
+
+  return connection
+}