@cratis/chronicle 1.0.2 → 2.1.0

package/ChronicleClient.ts

@@ -1,11 +1,13 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import * as os from 'os';
 import { diag } from '@opentelemetry/api';
 import { SpanStatusCode } from '@opentelemetry/api';
 import { ChronicleOptions } from './ChronicleOptions';
 import { ChronicleConnection } from './connection';
 import { ConnectionLifecycle } from './connection/ConnectionLifecycle';
+import { KernelKeepAlive } from './connection/KernelKeepAlive';
 import { EventStore } from './EventStore';
 import { EventStoreName } from './EventStoreName';
 import { EventStoreNamespaceName } from './EventStoreNamespaceName';
@@ -30,6 +32,7 @@ import { TypeDiscoverer } from './types';
  */
 export class ChronicleClient implements IChronicleClient {
     private static readonly _healthCheckIntervalMs = 5000;
+    private static readonly _maxBackoffMs = 30_000;
 
     private readonly _connection: ChronicleConnection;
     private readonly _stores: Map<string, EventStore> = new Map();
@@ -45,6 +48,7 @@ export class ChronicleClient implements IChronicleClient {
     private _discoveryOperation?: Promise<void>;
     private _isDisposed = false;
     private _keepAliveAbortController?: AbortController;
+    private _healthCheckInFlight = false;
 
     /**
      * Creates a new {@link ChronicleClient} using the provided options.
@@ -212,15 +216,16 @@ export class ChronicleClient implements IChronicleClient {
 
         while (!this._isDisposed) {
             try {
-                if (attempt > 0) {
-                    // Recreate the gRPC channel so we start from IDLE. A failed
-                    // probe can leave the channel in TRANSIENT_FAILURE, which gRPC
-                    // won't recover without a fresh channel. The contracts connect()
-                    // is also bypassed here — it uses watchConnectivityState and
-                    // rejects as soon as the state changes to CONNECTING (not READY),
-                    // making it unreliable for initial connection establishment.
-                    this._connection.resetChannel();
-                }
+                // Resolve (DNS SRV, when applicable) and select (load balancer strategy) a
+                // server address and rebuild the gRPC channel from scratch on every attempt,
+                // including the first — not just once at startup — so membership and load
+                // changes are always picked up. This also guarantees a fresh IDLE channel: a
+                // failed probe can leave a channel in TRANSIENT_FAILURE, which gRPC won't
+                // recover from without a new channel. The contracts connect() is bypassed
+                // here — it uses watchConnectivityState and rejects as soon as the state
+                // changes to CONNECTING (not READY), making it unreliable for initial
+                // connection establishment.
+                await this._connection.resetChannel();
 
                 this._logger.debug('Connecting to Chronicle kernel', { attempt: attempt + 1 });
 
@@ -240,13 +245,8 @@ export class ChronicleClient implements IChronicleClient {
 
             } catch (error) {
                 attempt++;
-                const delayMs = Math.min(1000 * Math.pow(2, attempt - 1), 30_000);
-                this._logger.warn('Connection attempt failed, retrying', {
-                    attempt,
-                    delayMs,
-                    error: this.toErrorMessage(error)
-                });
-                await new Promise(resolve => setTimeout(resolve, delayMs));
+                const delayMs = await this.backOff(attempt, 'Connection attempt failed, retrying', error);
+                this._logger.verbose('Backed off before next connection attempt', { attempt, delayMs });
             }
         }
 
@@ -290,7 +290,7 @@ export class ChronicleClient implements IChronicleClient {
                 let attempt = 0;
                 while (!this._isDisposed) {
                     try {
-                        this._connection.resetChannel();
+                        await this._connection.resetChannel();
                         await this._connection.server.getVersionInfo({}, { signal: AbortSignal.timeout(10_000) });
                         this._logger.info('Reconnected to Chronicle kernel', { attempt: attempt + 1 });
                         await this.startKernelKeepAlive();
@@ -302,13 +302,7 @@ export class ChronicleClient implements IChronicleClient {
                         return;
                     } catch (reconnectError) {
                         attempt++;
-                        const delayMs = Math.min(1000 * Math.pow(2, attempt - 1), 30_000);
-                        this._logger.warn('Reconnect attempt failed, retrying', {
-                            attempt,
-                            delayMs,
-                            error: this.toErrorMessage(reconnectError)
-                        });
-                        await new Promise(resolve => setTimeout(resolve, delayMs));
+                        await this.backOff(attempt, 'Reconnect attempt failed, retrying', reconnectError);
                     }
                 }
             })().finally(() => {
@@ -319,6 +313,25 @@ export class ChronicleClient implements IChronicleClient {
         await this._reconnectOperation;
     }
 
+    /**
+     * 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
+     * not come back in lockstep and knock it over again.
+     */
+    private async backOff(attempt: number, message: string, error: unknown): Promise<number> {
+        const ceiling = Math.min(1000 * Math.pow(2, attempt - 1), ChronicleClient._maxBackoffMs);
+        const delayMs = Math.round(ceiling / 2 + Math.random() * (ceiling / 2));
+
+        this._logger.warn(message, {
+            attempt,
+            delayMs,
+            error: this.toErrorMessage(error)
+        });
+
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+        return delayMs;
+    }
+
     private async withReconnect<T>(operation: string, action: () => Promise<T>): Promise<T> {
         try {
             return await action();
@@ -373,15 +386,20 @@ export class ChronicleClient implements IChronicleClient {
     }
 
     private async runHealthCheck(): Promise<void> {
-        if (this._isDisposed || !this._lifecycle.isConnected) {
+        // 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) {
             return;
         }
 
+        this._healthCheckInFlight = true;
         try {
-            await this._connection.server.getVersionInfo({});
+            await this._connection.server.getVersionInfo({}, { signal: AbortSignal.timeout(10_000) });
             this._logger.verbose('Connection health check passed');
         } catch (error) {
             await this.reconnect('watchdog-health-check', error);
+        } finally {
+            this._healthCheckInFlight = false;
         }
     }
 
@@ -390,45 +408,36 @@ export class ChronicleClient implements IChronicleClient {
         this._keepAliveAbortController = new AbortController();
         const { signal } = this._keepAliveAbortController;
 
-        const keepAliveStream = this._connection.connections.connect(
-            { ConnectionId: this._lifecycle.connectionId, ClientVersion: '1.0.0', IsRunningWithDebugger: false },
-            { signal }
+        // Losing the keep-alive means the kernel has stopped counting us as
+        // connected, so observers are already being torn down server-side.
+        // Reconnecting is the only way back — without this the client sits on a
+        // dead session, appends keep working, and reactors never fire again.
+        const keepAlive = new KernelKeepAlive(this._connection.connections, (reason, error) => {
+            if (this._isDisposed || signal.aborted) {
+                return;
+            }
+
+            void this.reconnect(reason, error);
+        });
+
+        await keepAlive.start(
+            {
+                ConnectionId: this._lifecycle.connectionId,
+                // TODO: Not derived from this package's own version anywhere yet; kept as
+                // the pre-existing hardcoded placeholder until such a mechanism exists.
+                ClientVersion: '1.0.0',
+                IsRunningWithDebugger: false,
+                ProcessId: process.pid,
+                ProcessPath: process.execPath,
+                MachineName: os.hostname(),
+                ClientType: 'TypeScript'
+            },
+            signal
         );
-        const iterator = keepAliveStream[Symbol.asyncIterator]();
-        const firstResult = await iterator.next();
-        if (firstResult.done) {
-            throw new Error('Connection service stream ended before sending first keep-alive');
-        }
 
-        await this._connection.connections.connectionKeepAlive(firstResult.value);
         this._logger.info('Client registered with kernel keep-alive mechanism', {
             connectionId: this._lifecycle.connectionId
         });
-
-        void this.runKeepAliveLoop(iterator, signal);
-    }
-
-    private async runKeepAliveLoop(iterator: AsyncIterator<unknown, void>, signal: AbortSignal): Promise<void> {
-        try {
-            while (!signal.aborted) {
-                const result = await iterator.next();
-                if (result.done) {
-                    this._logger.info('Keep-alive stream ended');
-                    break;
-                }
-
-                await this._connection.connections.connectionKeepAlive(result.value as object);
-                this._logger.verbose('Keep-alive ping responded', {
-                    connectionId: this._lifecycle.connectionId
-                });
-            }
-        } catch (err) {
-            if (!signal.aborted) {
-                this._logger.warn('Keep-alive loop ended with error', {
-                    error: this.toErrorMessage(err)
-                });
-            }
-        }
     }
 
     private async registerArtifactsForStore(store: EventStore, reason: string): Promise<void> {

package/ChronicleOptions.ts

@@ -107,14 +107,13 @@ export class ChronicleOptions {
     /**
      * Creates a {@link ChronicleOptions} instance for local development.
      * Connects to Chronicle on localhost:35000 using the standard development
-     * client credentials and with TLS disabled, matching the default Chronicle
-     * development server configuration.
+     * client credentials, matching the default Chronicle development server
+     * configuration. The Chronicle server requires TLS on its single port, so
+     * this connects over TLS against the server's self-signed development
+     * certificate.
      * @returns A new ChronicleOptions instance for development.
      */
     static development(options?: ChronicleOptionsFactoryParams): ChronicleOptions {
-        return ChronicleOptions.fromConnectionString(
-            'chronicle://chronicle-dev-client:chronicle-dev-secret@localhost:35000?disableTls=true',
-            options
-        );
+        return ChronicleOptions.fromConnectionString(ChronicleConnectionString.Development, options);
     }
 }

package/README.md

@@ -26,7 +26,7 @@ You need a Chronicle Kernel available before running samples or application code
 The easiest local setup is the development Docker image:
 
 ```bash
-docker run -p 35000:35000 -p 8080:8080 cratis/chronicle:latest-development
+docker run -p 35000:35000 cratis/chronicle:latest-development
 ```
 
 ## Getting Started

package/connection/ChronicleConnection.ts

@@ -30,7 +30,11 @@ import type { ClientMiddleware } from 'nice-grpc-common';
 import { Metadata } from 'nice-grpc-common';
 import { EventStoreSubscriptionsDefinition } from '../eventStoreSubscriptions/contracts';
 import { AuthenticationMode, ChronicleConnectionString } from './ChronicleConnectionString';
+import { ChronicleServerAddressResolver } from './ChronicleServerAddressResolver';
 import { ChronicleServices } from './ChronicleServices';
+import { formatServerAddress } from './formatServerAddress';
+import type { ILoadBalancerStrategy } from './ILoadBalancerStrategy';
+import { createLoadBalancerStrategy } from './LoadBalancerStrategyFactory';
 import { ITokenProvider, NoOpTokenProvider, OAuthTokenProvider } from './TokenProvider';
 
 /**
@@ -76,11 +80,6 @@ export interface ChronicleConnectionOptions {
      * Optional authentication authority URL. If not set, uses the Chronicle server itself.
      */
     authority?: string;
-
-    /**
-     * Optional management port for authentication endpoint. Defaults to 8080.
-     */
-    managementPort?: number;
 }
 
 /**
@@ -92,7 +91,10 @@ export class ChronicleConnection implements ChronicleServices {
     private _connections!: ConnectionServiceClient;
     private readonly _connectionString: ChronicleConnectionString;
     private readonly _tokenProvider: ITokenProvider;
+    private readonly _addressResolver: ChronicleServerAddressResolver;
+    private readonly _loadBalancerStrategy: ILoadBalancerStrategy;
     private _isConnected = false;
+    private _clientsReady: Promise<void>;
 
     constructor(private readonly _options: ChronicleConnectionOptions) {
         if (_options.connectionString) {
@@ -106,7 +108,15 @@ export class ChronicleConnection implements ChronicleServices {
         }
 
         this._tokenProvider = this.createTokenProvider();
-        this.createClients();
+        this._addressResolver = new ChronicleServerAddressResolver();
+        this._loadBalancerStrategy = createLoadBalancerStrategy(this._connectionString.loadBalancer, this._connectionString.skipTlsValidation);
+
+        this._clientsReady = this.createClients();
+        // Building the initial channel is async (address resolution + load balancer
+        // selection), so the constructor cannot await it. Real failures still surface to
+        // callers that await connect()/resetChannel(); this only prevents an unhandled
+        // rejection warning from the fire-and-forget initial build.
+        this._clientsReady.catch(() => {});
     }
 
     get connectionString(): ChronicleConnectionString {
@@ -202,37 +212,39 @@ export class ChronicleConnection implements ChronicleServices {
     }
 
     async connect(): Promise<void> {
+        await this._clientsReady;
         const deadline = new Date(Date.now() + (this._options.connectTimeout ?? 10_000));
         await waitForChannelReady(this._channel, deadline);
         this._isConnected = true;
     }
 
-    resetChannel(): void {
+    async resetChannel(): Promise<void> {
         try {
-            this._channel.close();
+            this._channel?.close();
         } catch {
             // Best-effort shutdown before recreating the channel.
         }
 
         this._isConnected = false;
-        this.createClients();
+        this._clientsReady = this.createClients();
+        await this._clientsReady;
     }
 
     async reconnect(): Promise<void> {
-        this.resetChannel();
+        await this.resetChannel();
         await this.connect();
     }
 
     disconnect(): void {
         this._isConnected = false;
-        this._channel.close();
+        this._channel?.close();
     }
 
     dispose(): void {
         this.disconnect();
     }
 
-    private createClients(): void {
+    private async createClients(): Promise<void> {
         const channelOptions: ChannelOptions = {};
 
         if (this._options.maxReceiveMessageSize !== undefined) {
@@ -243,7 +255,12 @@ export class ChronicleConnection implements ChronicleServices {
             channelOptions['grpc.max_send_message_length'] = this._options.maxSendMessageSize;
         }
 
-        const serverAddress = `${this._connectionString.serverAddress.host}:${this._connectionString.serverAddress.port}`;
+        // Re-resolved (DNS SRV, when applicable) and re-selected (load balancer strategy)
+        // on every call, so every connect/reconnect attempt picks up membership and load
+        // changes rather than pinning to whatever was selected at startup.
+        const candidates = await this._addressResolver.resolve(this._connectionString);
+        const selected = await this._loadBalancerStrategy.select(candidates);
+        const serverAddress = formatServerAddress(selected);
         const credentials = this._options.credentials ?? this._connectionString.createCredentials();
 
         this._channel = createChannel(serverAddress, credentials, channelOptions);
@@ -298,24 +315,27 @@ export class ChronicleConnection implements ChronicleServices {
     }
 
     private createOAuthTokenProvider(username: string, password: string): ITokenProvider {
-        const managementPort = this._options.managementPort ?? 8080;
+        // Chronicle serves the authentication endpoint on the same port as the rest of the
+        // Kernel, so the authority defaults to the connection string's server address.
+        const serverPort = this._connectionString.serverAddress.port;
         let authorityHost: string;
         let authorityPort: number;
 
         if (this._options.authority) {
             const authority = new URL(this._options.authority);
             authorityHost = authority.hostname;
-            authorityPort = authority.port ? parseInt(authority.port, 10) : managementPort;
+            authorityPort = authority.port ? parseInt(authority.port, 10) : serverPort;
         } else {
             authorityHost = this._connectionString.serverAddress.host;
-            authorityPort = managementPort;
+            authorityPort = serverPort;
         }
 
         const scheme = this._connectionString.disableTls ? 'http' : 'https';
         return new OAuthTokenProvider(
             `${scheme}://${authorityHost}:${authorityPort}/connect/token`,
             username,
-            password
+            password,
+            this._connectionString.skipTlsValidation
         );
     }
 

package/connection/ChronicleConnectionString.spec.ts

@@ -0,0 +1,227 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it, vi } from 'vitest';
+import { AuthenticationMode, ChronicleConnectionString, ChronicleConnectionStringBuilder } from './ChronicleConnectionString';
+import { LoadBalancerMode } from './LoadBalancerMode';
+
+describe('ChronicleConnectionStringBuilder', () => {
+    describe('when parsing a single host', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://localhost:35000');
+
+        it('should have the host', () => expect(builder.host).toBe('localhost'));
+        it('should have the port', () => expect(builder.port).toBe(35000));
+        it('should have one server address', () => expect(builder.hosts).toEqual([{ host: 'localhost', port: 35000 }]));
+        it('should not be srv', () => expect(builder.isSrv).toBe(false));
+    });
+
+    describe('when parsing a host without an explicit port', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://localhost');
+
+        it('should default the port to 35000', () => expect(builder.port).toBe(35000));
+    });
+
+    describe('when parsing multiple hosts', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://host1:35001,host2,host3:35003');
+
+        it('should have the first host as host', () => expect(builder.host).toBe('host1'));
+        it('should have the first port as port', () => expect(builder.port).toBe(35001));
+        it('should have three server addresses', () => expect(builder.hosts).toHaveLength(3));
+        it('should have the first server address', () => expect(builder.hosts[0]).toEqual({ host: 'host1', port: 35001 }));
+        it('should default the second host port', () => expect(builder.hosts[1]).toEqual({ host: 'host2', port: 35000 }));
+        it('should have the third server address', () => expect(builder.hosts[2]).toEqual({ host: 'host3', port: 35003 }));
+    });
+
+    describe('when parsing multiple hosts with authentication and options', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://admin:secret@host1,host2:35002/?skipTlsValidation=true');
+
+        it('should have the username', () => expect(builder.username).toBe('admin'));
+        it('should have the password', () => expect(builder.password).toBe('secret'));
+        it('should have two server addresses', () => expect(builder.hosts).toHaveLength(2));
+        it('should default the first host port', () => expect(builder.hosts[0]).toEqual({ host: 'host1', port: 35000 }));
+        it('should have the second server address', () => expect(builder.hosts[1]).toEqual({ host: 'host2', port: 35002 }));
+        it('should skip tls validation', () => expect(builder.skipTlsValidation).toBe(true));
+    });
+
+    describe('when parsing an IPv6 host in a multi-host list', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://[::1]:35001,host2');
+
+        it('should have the bracketed host without brackets', () => expect(builder.hosts[0]).toEqual({ host: '::1', port: 35001 }));
+        it('should have the second host', () => expect(builder.hosts[1]).toEqual({ host: 'host2', port: 35000 }));
+    });
+
+    describe('when parsing an IPv6 host without an explicit port', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://[::1]');
+
+        it('should default the port', () => expect(builder.hosts[0]).toEqual({ host: '::1', port: 35000 }));
+    });
+
+    describe('when parsing a srv url', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle+srv://cluster.example.com');
+
+        it('should have the srv scheme', () => expect(builder.scheme).toBe('chronicle+srv'));
+        it('should be srv', () => expect(builder.isSrv).toBe(true));
+        it('should have the correct host', () => expect(builder.host).toBe('cluster.example.com'));
+        it('should have the default port', () => expect(builder.port).toBe(35000));
+    });
+
+    describe('when parsing a srv url with multiple hosts', () => {
+        it('should throw', () => expect(() => new ChronicleConnectionStringBuilder('chronicle+srv://host1,host2')).toThrow());
+    });
+
+    describe('when parsing a srv url with a name server', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle+srv://cluster.example.com/?srvNameServer=127.0.0.1:5353');
+
+        it('should be srv', () => expect(builder.isSrv).toBe(true));
+        it('should have the name server', () => expect(builder.srvNameServer).toBe('127.0.0.1:5353'));
+        it('should include the name server when building', () =>
+            expect(builder.build()).toBe('chronicle+srv://cluster.example.com:35000?srvNameServer=127.0.0.1%3A5353'));
+    });
+
+    describe('when parsing a url with a trailing slash before the query string', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://localhost:35000/?apiKey=my-key');
+
+        it('should still parse the host', () => expect(builder.host).toBe('localhost'));
+        it('should still parse the query string', () => expect(builder.apiKey).toBe('my-key'));
+    });
+
+    describe('when parsing a url with a load balancer option', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://host1,host2/?loadBalancer=random');
+
+        it('should have the load balancer', () => expect(builder.loadBalancer).toBe(LoadBalancerMode.Random));
+        it('should include the load balancer when building', () =>
+            expect(builder.build()).toBe('chronicle://host1:35000,host2:35000?loadBalancer=random'));
+    });
+
+    describe('when no load balancer option is given', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://localhost:35000');
+
+        it('should default to least-connections', () => expect(builder.loadBalancer).toBe(LoadBalancerMode.LeastConnections));
+    });
+
+    describe('when parsing a url with an unknown load balancer option', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://localhost:35000/?loadBalancer=nonsense');
+
+        it('should throw', () => expect(() => builder.loadBalancer).toThrow());
+    });
+
+    describe('when building a connection string with multiple hosts', () => {
+        const builder = new ChronicleConnectionStringBuilder();
+        builder.hosts = [{ host: 'host1', port: 35001 }, { host: 'host2', port: 35000 }];
+
+        it('should include all hosts in the url', () => expect(builder.build()).toBe('chronicle://host1:35001,host2:35000'));
+        it('should round-trip through parsing', () => expect(new ChronicleConnectionStringBuilder(builder.build()).hosts).toEqual(builder.hosts));
+    });
+
+    describe('when building a connection string with an IPv6 host', () => {
+        const builder = new ChronicleConnectionStringBuilder();
+        builder.hosts = [{ host: '::1', port: 35000 }];
+
+        it('should bracket the IPv6 host', () => expect(builder.build()).toBe('chronicle://[::1]:35000'));
+    });
+
+    describe('when building a connection string with tls validation not skipped', () => {
+        const builder = new ChronicleConnectionStringBuilder();
+        builder.host = 'localhost';
+        builder.port = 35000;
+        builder.skipTlsValidation = false;
+
+        it('should include skipTlsValidation in the query string', () => expect(builder.build()).toBe('chronicle://localhost:35000?skipTlsValidation=false'));
+    });
+
+    describe('when setting host after hosts were set to multiple servers', () => {
+        const builder = new ChronicleConnectionStringBuilder();
+        builder.hosts = [{ host: 'host1', port: 35001 }, { host: 'host2', port: 35002 }];
+        builder.host = 'newhost';
+
+        it('should collapse to a single server', () => expect(builder.hosts).toEqual([{ host: 'newhost', port: 35001 }]));
+    });
+
+    describe('when getting authentication mode with client credentials', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://user:pass@localhost:35000');
+
+        it('should be client credentials', () => expect(builder.authenticationMode).toBe(AuthenticationMode.ClientCredentials));
+    });
+
+    describe('when getting authentication mode with an api key', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://localhost:35000/?apiKey=my-key');
+
+        it('should be api key', () => expect(builder.authenticationMode).toBe(AuthenticationMode.ApiKey));
+    });
+
+    describe('when getting authentication mode with both credentials and an api key', () => {
+        const builder = new ChronicleConnectionStringBuilder('chronicle://user:pass@localhost:35000/?apiKey=my-key');
+
+        it('should throw', () => expect(() => builder.authenticationMode).toThrow());
+    });
+});
+
+describe('ChronicleConnectionString', () => {
+    describe('when parsing a connection string with multiple hosts', () => {
+        const connectionString = new ChronicleConnectionString('chronicle://host1:35001,host2:35002');
+
+        it('should have all server addresses', () =>
+            expect(connectionString.serverAddresses).toEqual([{ host: 'host1', port: 35001 }, { host: 'host2', port: 35002 }]));
+        it('should have the first as the convenience server address', () =>
+            expect(connectionString.serverAddress).toEqual({ host: 'host1', port: 35001 }));
+    });
+
+    describe('when using the development connection string', () => {
+        const { Development } = ChronicleConnectionString;
+
+        it('should skip tls validation', () => expect(Development.skipTlsValidation).toBe(true));
+        it('should use the development client credentials', () => expect(Development.username).toBe(ChronicleConnectionString.DEVELOPMENT_CLIENT));
+    });
+
+    describe('when creating credentials without skipTlsValidation specified', () => {
+        it('should skip certificate chain validation by default', async () => {
+            vi.resetModules();
+            const createSsl = vi.fn().mockReturnValue('insecure-tls-credentials');
+            const createInsecure = vi.fn();
+            vi.doMock('@grpc/grpc-js', () => ({ credentials: { createSsl, createInsecure } }));
+
+            const { ChronicleConnectionString: MockedChronicleConnectionString } = await import('./ChronicleConnectionString');
+            const connectionString = new MockedChronicleConnectionString('chronicle://localhost:35000');
+            const credentials = connectionString.createCredentials();
+
+            expect(createSsl).toHaveBeenCalledWith(null, null, null, { rejectUnauthorized: false });
+            expect(credentials).toBe('insecure-tls-credentials');
+            vi.doUnmock('@grpc/grpc-js');
+        });
+    });
+
+    describe('when creating credentials with skipTlsValidation explicitly false', () => {
+        it('should validate the certificate chain', async () => {
+            vi.resetModules();
+            const createSsl = vi.fn().mockReturnValue('secure-credentials');
+            const createInsecure = vi.fn();
+            vi.doMock('@grpc/grpc-js', () => ({ credentials: { createSsl, createInsecure } }));
+
+            const { ChronicleConnectionString: MockedChronicleConnectionString } = await import('./ChronicleConnectionString');
+            const connectionString = new MockedChronicleConnectionString('chronicle://localhost:35000/?skipTlsValidation=false');
+            const credentials = connectionString.createCredentials();
+
+            expect(createSsl).toHaveBeenCalledWith();
+            expect(credentials).toBe('secure-credentials');
+            vi.doUnmock('@grpc/grpc-js');
+        });
+    });
+
+    describe('when creating credentials with disableTls', () => {
+        it('should create insecure credentials', async () => {
+            vi.resetModules();
+            const createSsl = vi.fn();
+            const createInsecure = vi.fn().mockReturnValue('plaintext-credentials');
+            vi.doMock('@grpc/grpc-js', () => ({ credentials: { createSsl, createInsecure } }));
+
+            const { ChronicleConnectionString: MockedChronicleConnectionString } = await import('./ChronicleConnectionString');
+            const connectionString = new MockedChronicleConnectionString('chronicle://localhost:35000/?disableTls=true');
+            const credentials = connectionString.createCredentials();
+
+            expect(createInsecure).toHaveBeenCalled();
+            expect(createSsl).not.toHaveBeenCalled();
+            expect(credentials).toBe('plaintext-credentials');
+            vi.doUnmock('@grpc/grpc-js');
+        });
+    });
+});