@cratis/chronicle 6.50.0 → 6.51.1

package/ChronicleClient.ts

@@ -27,6 +27,25 @@ import { TypeDiscoverer } from './types/index.js';
 import { takeUnregisteredModelBoundMappings } from './types/modelBoundPropertyMetadata.js';
 import { reachableReadModelTypes } from './readModels/rootReadModelTypes.js';
 
+const connectionIndicators = [
+    'deadline exceeded',
+    'unavailable',
+    'connection',
+    'connectivity',
+    'channel',
+    'socket',
+    'econnrefused',
+    'etimedout'
+];
+
+const errorCodeOf = (error: unknown): number | undefined => (error as { code?: number })?.code;
+
+const isTerminalServerError = (error: unknown): error is IncompatibleChronicleServer | RejectedChronicleCredentials =>
+    error instanceof IncompatibleChronicleServer || error instanceof RejectedChronicleCredentials;
+
+/** gRPC status codes DEADLINE_EXCEEDED (4), INTERNAL (13) and UNAVAILABLE (14) are worth a reconnect. */
+const hasReconnectableStatusCode = (error: unknown): boolean => [4, 13, 14].includes(Number(errorCodeOf(error) ?? -1));
+
 /**
  * Implements {@link IChronicleClient} by managing a gRPC connection to the
  * Chronicle Kernel via {@link ChronicleConnection}.
@@ -74,7 +93,12 @@ export class ChronicleClient implements IChronicleClient {
         const connectionOptions = options.connectionString.disableTls
             ? { connectionString: options.connectionString, credentials: options.connectionString.createCredentials() }
             : { connectionString: options.connectionString };
-        this._connection = new ChronicleConnection({ ...connectionOptions, logger: options.logger });
+        this._connection = new ChronicleConnection({
+            ...connectionOptions,
+            logger: options.logger,
+            maxReceiveMessageSize: options.maxReceiveMessageSize ?? undefined,
+            maxSendMessageSize: options.maxSendMessageSize ?? undefined
+        });
 
         this._logger.info('Created Chronicle client', {
             serverAddress: `${options.connectionString.serverAddress.host}:${options.connectionString.serverAddress.port}`,
@@ -118,46 +142,13 @@ export class ChronicleClient implements IChronicleClient {
     /** @inheritdoc */
     async getEventStore(name: string | EventStoreName, namespace?: string | EventStoreNamespaceName): Promise<IEventStore> {
         const storeName = typeof name === 'string' ? new EventStoreName(name) : name;
-        const namespaceName = namespace === undefined
-            ? EventStoreNamespaceName.default
-            : typeof namespace === 'string'
-                ? new EventStoreNamespaceName(namespace)
-                : namespace;
+        const namespaceName = this.toNamespaceName(namespace);
 
         return observeOperation('getEventStore', async span => {
             setTelemetryAttribute(span, 'eventStore', storeName.value);
             setTelemetryAttribute(span, 'namespace', namespaceName.value);
             try {
-                const store = await this.withReconnect('get_event_store', async () => {
-                    await this.ensureConnected();
-
-                    const key = `${storeName.value}/${namespaceName.value}`;
-                    const existing = this._stores.get(key);
-                    if (existing) {
-                        this._logger.verbose('Returning cached event store', {
-                            eventStore: storeName.value,
-                            namespace: namespaceName.value
-                        });
-                        return existing;
-                    }
-
-                    this._logger.debug('Ensuring event store exists in kernel', {
-                        eventStore: storeName.value
-                    });
-                    ensureCommandSuccess('ensure event store', await this._connection.eventStores.ensureEventStore({ Name: storeName.value }));
-
-                    const created = new EventStore(storeName, namespaceName, this._connection, this._lifecycle, this.options.defaultSinkTypeId, this.options.clientArtifactsProvider, this.options.reactorResultHandler, this.options.artifactActivator, this.options.readModelNamingPolicy, this.options.telemetry);
-                    this._stores.set(key, created);
-
-                    try {
-                        await this.registerArtifactsForStore(created, 'new-store');
-                        return created;
-                    } catch (error) {
-                        if (this._stores.get(key) === created) this._stores.delete(key);
-                        created.disposeObservations();
-                        throw error;
-                    }
-                });
+                const store = await this.withReconnect('get_event_store', () => this.getOrCreateEventStore(storeName, namespaceName));
 
                 ChronicleConventionMetrics.eventStoreRetrievals.add(1, {
                     [names.attributes.eventStore]: storeName.value,
@@ -179,6 +170,42 @@ export class ChronicleClient implements IChronicleClient {
         });
     }
 
+    private toNamespaceName(namespace: string | EventStoreNamespaceName | undefined): EventStoreNamespaceName {
+        if (namespace === undefined) return EventStoreNamespaceName.default;
+        return typeof namespace === 'string' ? new EventStoreNamespaceName(namespace) : namespace;
+    }
+
+    private async getOrCreateEventStore(storeName: EventStoreName, namespaceName: EventStoreNamespaceName): Promise<EventStore> {
+        await this.ensureConnected();
+
+        const key = `${storeName.value}/${namespaceName.value}`;
+        const existing = this._stores.get(key);
+        if (existing) {
+            this._logger.verbose('Returning cached event store', {
+                eventStore: storeName.value,
+                namespace: namespaceName.value
+            });
+            return existing;
+        }
+
+        this._logger.debug('Ensuring event store exists in kernel', {
+            eventStore: storeName.value
+        });
+        ensureCommandSuccess('ensure event store', await this._connection.eventStores.ensureEventStore({ Name: storeName.value }));
+
+        const created = new EventStore(storeName, namespaceName, this._connection, this._lifecycle, this.options.defaultSinkTypeId, this.options.clientArtifactsProvider, this.options.reactorResultHandler, this.options.artifactActivator, this.options.readModelNamingPolicy, this.options.telemetry);
+        this._stores.set(key, created);
+
+        try {
+            await this.registerArtifactsForStore(created, 'new-store');
+            return created;
+        } catch (error) {
+            if (this._stores.get(key) === created) this._stores.delete(key);
+            created.disposeObservations();
+            throw error;
+        }
+    }
+
     /** @inheritdoc */
     async getEventStores(): Promise<EventStoreName[]> {
         return observeOperation('getEventStores', async span => {
@@ -300,46 +327,7 @@ export class ChronicleClient implements IChronicleClient {
         if (this._connectionFailure) throw this._connectionFailure;
 
         if (!this._reconnectOperation) {
-            this._reconnectOperation = runInBackgroundContext(async () => {
-                this._logger.warn('Reconnecting to Chronicle kernel', {
-                    reason,
-                    error
-                });
-
-                if (this._lifecycle.isConnected) {
-                    await this._lifecycle.disconnected(disconnectError => {
-                        this._logger.error('Disconnected lifecycle callback failed', {
-                            error: disconnectError
-                        });
-                    });
-                }
-
-                let attempt = 0;
-                while (!this._isDisposed) {
-                    try {
-                        await this._connection.resetChannel();
-                        await this._connection.connect();
-                        await this._connection.server.getVersionInfo({}, { signal: AbortSignal.timeout(10_000) });
-                        this._consecutiveCredentialRejections = 0;
-                        this._logger.info('Reconnected to Chronicle kernel', { attempt: attempt + 1 });
-                        await this.startKernelKeepAlive();
-                        await this._lifecycle.connected(connectedError => {
-                            this._logger.error('Connected lifecycle callback failed after reconnect', {
-                                error: connectedError
-                            });
-                        });
-                        return;
-                    } catch (reconnectError) {
-                        const terminal = this.terminalConnectionError(reconnectError);
-                        if (terminal) {
-                            this.failConnection(terminal);
-                            throw terminal;
-                        }
-                        attempt++;
-                        await this.backOff(attempt, 'Reconnect attempt failed, retrying', reconnectError);
-                    }
-                }
-            }).finally(() => {
+            this._reconnectOperation = runInBackgroundContext(() => this.recoverConnection(reason, error)).finally(() => {
                 this._reconnectOperation = undefined;
             });
         }
@@ -347,6 +335,51 @@ export class ChronicleClient implements IChronicleClient {
         await this._reconnectOperation;
     }
 
+    private async recoverConnection(reason: string, error: unknown): Promise<void> {
+        this._logger.warn('Reconnecting to Chronicle kernel', {
+            reason,
+            error
+        });
+
+        if (this._lifecycle.isConnected) {
+            await this._lifecycle.disconnected(disconnectError => {
+                this._logger.error('Disconnected lifecycle callback failed', {
+                    error: disconnectError
+                });
+            });
+        }
+
+        await this.reconnectWithRetry();
+    }
+
+    private async reconnectWithRetry(): Promise<void> {
+        let attempt = 0;
+        while (!this._isDisposed) {
+            try {
+                await this._connection.resetChannel();
+                await this._connection.connect();
+                await this._connection.server.getVersionInfo({}, { signal: AbortSignal.timeout(10_000) });
+                this._consecutiveCredentialRejections = 0;
+                this._logger.info('Reconnected to Chronicle kernel', { attempt: attempt + 1 });
+                await this.startKernelKeepAlive();
+                await this._lifecycle.connected(connectedError => {
+                    this._logger.error('Connected lifecycle callback failed after reconnect', {
+                        error: connectedError
+                    });
+                });
+                return;
+            } catch (reconnectError) {
+                const terminal = this.terminalConnectionError(reconnectError);
+                if (terminal) {
+                    this.failConnection(terminal);
+                    throw terminal;
+                }
+                attempt++;
+                await this.backOff(attempt, 'Reconnect attempt failed, retrying', reconnectError);
+            }
+        }
+    }
+
     /**
      * Waits out the exponential backoff for a failed attempt and reports why.
      * The delay is jittered so a fleet of clients that lost the same kernel does
@@ -392,7 +425,7 @@ export class ChronicleClient implements IChronicleClient {
     }
 
     private terminalConnectionError(error: unknown): Error | undefined {
-        if (error instanceof IncompatibleChronicleServer || error instanceof RejectedChronicleCredentials) return error;
+        if (isTerminalServerError(error)) return error;
         const rejection = (error as { code?: number })?.code === 16 &&
             (this.options.connectionString.apiKey || this.hasOAuthCredentialRejection(error));
         this._consecutiveCredentialRejections = rejection ? this._consecutiveCredentialRejections + 1 : 0;
@@ -410,29 +443,20 @@ export class ChronicleClient implements IChronicleClient {
     }
 
     private shouldReconnect(error: unknown): boolean {
-        if (error instanceof IncompatibleChronicleServer || error instanceof RejectedChronicleCredentials) return false;
-        if ((error as { code?: number })?.code === 16 &&
-            (this.options.connectionString.apiKey || !!(error as { tokenFailure?: Error })?.tokenFailure)) return true;
-        const code = Number((error as { code?: number })?.code ?? -1);
-        const details = String((error as { details?: string })?.details ?? '');
-        const message = this.toErrorMessage(error);
+        if (isTerminalServerError(error)) return false;
+        return this.isRejectedAuthentication(error) ||
+            hasReconnectableStatusCode(error) ||
+            this.mentionsConnectionProblem(error);
+    }
 
-        if (code === 4 || code === 13 || code === 14) {
-            return true;
-        }
+    private isRejectedAuthentication(error: unknown): boolean {
+        if (errorCodeOf(error) !== 16) return false;
+        return !!this.options.connectionString.apiKey || !!(error as { tokenFailure?: Error })?.tokenFailure;
+    }
 
-        const connectionIndicators = [
-            'deadline exceeded',
-            'unavailable',
-            'connection',
-            'connectivity',
-            'channel',
-            'socket',
-            'econnrefused',
-            'etimedout'
-        ];
-
-        const combined = `${details} ${message}`.toLowerCase();
+    private mentionsConnectionProblem(error: unknown): boolean {
+        const details = String((error as { details?: string })?.details ?? '');
+        const combined = `${details} ${this.toErrorMessage(error)}`.toLowerCase();
         return connectionIndicators.some(indicator => combined.includes(indicator));
     }
 
@@ -452,10 +476,14 @@ export class ChronicleClient implements IChronicleClient {
         this._watchdogHandle.unref?.();
     }
 
+    private get cannotRunHealthCheck(): boolean {
+        return this._isDisposed || !this._lifecycle.isConnected || this._healthCheckInFlight;
+    }
+
     private async runHealthCheck(): Promise<void> {
         // A black-holed connection makes the probe itself hang, so without the
         // in-flight guard every tick would stack another one that never returns.
-        if (this._isDisposed || !this._lifecycle.isConnected || this._healthCheckInFlight) {
+        if (this.cannotRunHealthCheck) {
             return;
         }
 

package/ChronicleOptions.ts

@@ -24,6 +24,8 @@ type ChronicleOptionsConstructorParams = {
     reactorResultHandler?: ReactorResultHandler;
     artifactActivator?: ClientArtifactsActivator;
     readModelNamingPolicy?: ReadModelNamingPolicy;
+    maxReceiveMessageSize?: number | null;
+    maxSendMessageSize?: number | null;
 };
 
 type ChronicleOptionsFactoryParams = {
@@ -35,6 +37,8 @@ type ChronicleOptionsFactoryParams = {
     reactorResultHandler?: ReactorResultHandler;
     artifactActivator?: ClientArtifactsActivator;
     readModelNamingPolicy?: ReadModelNamingPolicy;
+    maxReceiveMessageSize?: number | null;
+    maxSendMessageSize?: number | null;
 };
 
 /**
@@ -103,6 +107,18 @@ export class ChronicleOptions {
      */
     readonly readModelNamingPolicy?: ReadModelNamingPolicy;
 
+    /**
+     * The largest gRPC message, in bytes, the client accepts from the kernel. Defaults to 100 MB, matching the
+     * other Chronicle clients. `null` leaves it at gRPC's own default of 4 MB, which is not recommended.
+     */
+    readonly maxReceiveMessageSize: number | null;
+
+    /**
+     * The largest gRPC message, in bytes, the client sends to the kernel. Defaults to 100 MB, matching the
+     * other Chronicle clients. `null` leaves it at gRPC's own default.
+     */
+    readonly maxSendMessageSize: number | null;
+
     private constructor(options: ChronicleOptionsConstructorParams) {
         this.connectionString = options.connectionString;
         this.programIdentifier = options.programIdentifier ?? 'Unknown';
@@ -114,6 +130,8 @@ export class ChronicleOptions {
         this.reactorResultHandler = options.reactorResultHandler;
         this.artifactActivator = options.artifactActivator;
         this.readModelNamingPolicy = options.readModelNamingPolicy;
+        this.maxReceiveMessageSize = options.maxReceiveMessageSize === undefined ? ChronicleOptions.defaultMaxMessageSize : options.maxReceiveMessageSize;
+        this.maxSendMessageSize = options.maxSendMessageSize === undefined ? ChronicleOptions.defaultMaxMessageSize : options.maxSendMessageSize;
         const spanNames = options.telemetry?.spanNames;
         if (spanNames !== undefined && spanNames !== 'legacy' && spanNames !== 'convention') {
             throw new TypeError('telemetry.spanNames must be legacy or convention.');
@@ -131,6 +149,9 @@ export class ChronicleOptions {
         this.logger = options.logger;
     }
 
+    /** The default maximum gRPC message size in bytes: 100 MB. */
+    static readonly defaultMaxMessageSize = 100 * 1024 * 1024;
+
     private static defaultDiscoveryPatterns(): string[] {
         const typescriptEntry = /\.(?:ts|tsx|mts|cts)$/i.test(process.argv[1] ?? '');
         const typescriptLoader = process.execArgv.some(arg => /(?:tsx|ts-node|--experimental-strip-types|--experimental-transform-types)/i.test(arg));
@@ -173,6 +194,8 @@ export class ChronicleOptions {
             reactorResultHandler: options?.reactorResultHandler,
             artifactActivator: options?.artifactActivator,
             readModelNamingPolicy: options?.readModelNamingPolicy,
+            maxReceiveMessageSize: options?.maxReceiveMessageSize,
+            maxSendMessageSize: options?.maxSendMessageSize,
             telemetry: options?.telemetry,
             logger: options?.logger
         });

package/dist/ChronicleClient.d.ts

@@ -40,6 +40,8 @@ export declare class ChronicleClient implements IChronicleClient {
     constructor(options: ChronicleOptions);
     /** @inheritdoc */
     getEventStore(name: string | EventStoreName, namespace?: string | EventStoreNamespaceName): Promise<IEventStore>;
+    private toNamespaceName;
+    private getOrCreateEventStore;
     /** @inheritdoc */
     getEventStores(): Promise<EventStoreName[]>;
     /** @inheritdoc */
@@ -47,6 +49,8 @@ export declare class ChronicleClient implements IChronicleClient {
     private connectWithRetry;
     private ensureConnected;
     private reconnect;
+    private recoverConnection;
+    private reconnectWithRetry;
     /**
      * Waits out the exponential backoff for a failed attempt and reports why.
      * The delay is jittered so a fleet of clients that lost the same kernel does
@@ -57,8 +61,11 @@ export declare class ChronicleClient implements IChronicleClient {
     private terminalConnectionError;
     private hasOAuthCredentialRejection;
     private shouldReconnect;
+    private isRejectedAuthentication;
+    private mentionsConnectionProblem;
     private toErrorMessage;
     private startConnectionWatchdog;
+    private get cannotRunHealthCheck();
     private runHealthCheck;
     private startKernelKeepAlive;
     private failConnection;

package/dist/ChronicleClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChronicleClient.d.ts","sourceRoot":"","sources":["../ChronicleClient.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAUzD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAS/C;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IAwBxC,QAAQ,CAAC,OAAO,EAAE,gBAAgB;IAvB9C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAQ;IACtD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAU;IAE/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsB;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IAExD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAE1D,OAAO,CAAC,eAAe,CAAC,CAAiC;IACzD,OAAO,CAAC,iBAAiB,CAAC,CAAgB;IAC1C,OAAO,CAAC,mBAAmB,CAAC,CAAgB;IAC5C,OAAO,CAAC,mBAAmB,CAAC,CAAgB;IAC5C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,yBAAyB,CAAC,CAAkB;IACpD,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,kBAAkB,CAAC,CAAQ;IACnC,OAAO,CAAC,gCAAgC,CAAK;IAE7C;;;OAGG;IACH,YAAqB,OAAO,EAAE,gBAAgB,EAiD7C;IAED,kBAAkB;IACZ,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,uBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC,CA6DrH;IAED,kBAAkB;IACZ,cAAc,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAuBhD;IAED,kBAAkB;IAClB,OAAO,IAAI,IAAI,CAqBd;YAEa,gBAAgB;YA4ChB,eAAe;YAuBf,SAAS;IAmDvB;;;;OAIG;YACW,OAAO;YAcP,aAAa;IAyB3B,OAAO,CAAC,uBAAuB;IAW/B,OAAO,CAAC,2BAA2B;IAOnC,OAAO,CAAC,eAAe;IA2BvB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,uBAAuB;YAQjB,cAAc;YAkBd,oBAAoB;IAmClC,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,0BAA0B;YAQpB,yBAAyB;CA4B1C"}
+{"version":3,"file":"ChronicleClient.d.ts","sourceRoot":"","sources":["../ChronicleClient.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAUzD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA4B/C;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IAwBxC,QAAQ,CAAC,OAAO,EAAE,gBAAgB;IAvB9C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAQ;IACtD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAU;IAE/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsB;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IAExD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAE1D,OAAO,CAAC,eAAe,CAAC,CAAiC;IACzD,OAAO,CAAC,iBAAiB,CAAC,CAAgB;IAC1C,OAAO,CAAC,mBAAmB,CAAC,CAAgB;IAC5C,OAAO,CAAC,mBAAmB,CAAC,CAAgB;IAC5C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,yBAAyB,CAAC,CAAkB;IACpD,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,kBAAkB,CAAC,CAAQ;IACnC,OAAO,CAAC,gCAAgC,CAAK;IAE7C;;;OAGG;IACH,YAAqB,OAAO,EAAE,gBAAgB,EAsD7C;IAED,kBAAkB;IACZ,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,uBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC,CA4BrH;IAED,OAAO,CAAC,eAAe;YAKT,qBAAqB;IA+BnC,kBAAkB;IACZ,cAAc,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAuBhD;IAED,kBAAkB;IAClB,OAAO,IAAI,IAAI,CAqBd;YAEa,gBAAgB;YA4ChB,eAAe;YAuBf,SAAS;YAYT,iBAAiB;YAiBjB,kBAAkB;IA4BhC;;;;OAIG;YACW,OAAO;YAcP,aAAa;IAyB3B,OAAO,CAAC,uBAAuB;IAW/B,OAAO,CAAC,2BAA2B;IAOnC,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,wBAAwB;IAKhC,OAAO,CAAC,yBAAyB;IAMjC,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,uBAAuB;IAQ/B,OAAO,KAAK,oBAAoB,GAE/B;YAEa,cAAc;YAkBd,oBAAoB;IAmClC,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,0BAA0B;YAQpB,yBAAyB;CA4B1C"}