@cratis/chronicle 1.0.2 → 2.1.0

package/connection/ChronicleConnectionString.ts

@@ -2,6 +2,11 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import * as grpc from '@grpc/grpc-js';
+import { formatServerAddress } from './formatServerAddress';
+import { LoadBalancerMode } from './LoadBalancerMode';
+
+const DEFAULT_PORT = 35000;
+const SRV_SCHEME = 'chronicle+srv';
 
 /**
  * Authentication mode for Chronicle connection.
@@ -19,22 +24,94 @@ export interface ChronicleServerAddress {
     port: number;
 }
 
+/**
+ * Splits a `host1:port1,host2:port2` host list on top-level commas, leaving commas that
+ * appear inside IPv6 bracket literals (`[::1]:35000`) intact.
+ */
+function splitHostList(value: string): string[] {
+    const entries: string[] = [];
+    let depth = 0;
+    let current = '';
+
+    for (const character of value) {
+        if (character === '[') {
+            depth++;
+        } else if (character === ']') {
+            depth--;
+        }
+
+        if (character === ',' && depth === 0) {
+            entries.push(current);
+            current = '';
+            continue;
+        }
+
+        current += character;
+    }
+
+    if (current.length > 0) {
+        entries.push(current);
+    }
+
+    return entries;
+}
+
+/**
+ * Parses a single `host:port` or `[ipv6]:port` entry, defaulting the port when omitted.
+ */
+function parseHostAndPort(entry: string): ChronicleServerAddress {
+    const trimmed = entry.trim();
+    let host: string;
+    let portPart: string;
+
+    if (trimmed.startsWith('[')) {
+        const closingIndex = trimmed.indexOf(']');
+        if (closingIndex === -1) {
+            throw new Error(`Invalid server address: ${trimmed}`);
+        }
+
+        host = trimmed.slice(1, closingIndex);
+        portPart = trimmed.slice(closingIndex + 1).replace(/^:/, '');
+    } else {
+        const colonIndex = trimmed.lastIndexOf(':');
+        host = colonIndex === -1 ? trimmed : trimmed.slice(0, colonIndex);
+        portPart = colonIndex === -1 ? '' : trimmed.slice(colonIndex + 1);
+    }
+
+    if (host.length === 0) {
+        throw new Error(`Invalid server address: ${trimmed}`);
+    }
+
+    if (portPart.length === 0) {
+        return { host, port: DEFAULT_PORT };
+    }
+
+    const port = Number(portPart);
+    if (!Number.isInteger(port)) {
+        throw new Error(`Invalid server address: ${trimmed}`);
+    }
+
+    return { host, port };
+}
+
 /**
  * Builder for constructing Chronicle connection strings.
  */
 export class ChronicleConnectionStringBuilder {
-    private static readonly _defaultPort = 35000;
-    private static readonly _hostKey = 'Host';
-    private static readonly _portKey = 'Port';
+    private static readonly _defaultPort = DEFAULT_PORT;
     private static readonly _usernameKey = 'Username';
     private static readonly _passwordKey = 'Password';
     private static readonly _schemeKey = 'Scheme';
     private static readonly _apiKeyKey = 'apiKey';
     private static readonly _disableTlsKey = 'disableTls';
+    private static readonly _skipTlsValidationKey = 'skipTlsValidation';
     private static readonly _certificatePathKey = 'certificatePath';
     private static readonly _certificatePasswordKey = 'certificatePassword';
+    private static readonly _loadBalancerKey = 'loadBalancer';
+    private static readonly _srvNameServerKey = 'srvNameServer';
 
     private readonly _properties = new Map<string, string>();
+    private _hosts: ChronicleServerAddress[] = [];
 
     constructor(connectionString?: string) {
         if (connectionString) {
@@ -42,21 +119,39 @@ export class ChronicleConnectionStringBuilder {
         }
     }
 
+    get hosts(): ChronicleServerAddress[] {
+        return this._hosts.length > 0 ? this._hosts : [{ host: 'localhost', port: ChronicleConnectionStringBuilder._defaultPort }];
+    }
+
+    set hosts(value: ChronicleServerAddress[]) {
+        this._hosts = value;
+    }
+
+    /**
+     * Convenience accessor for the first host in {@link hosts}. Setting it collapses the
+     * configuration to that single host, discarding any others previously set via
+     * {@link hosts} - the same "single server" reset a plain host/port connection string
+     * implies.
+     */
     get host(): string {
-        return this._properties.get(ChronicleConnectionStringBuilder._hostKey) || 'localhost';
+        return this.hosts[0].host;
     }
 
     set host(value: string) {
-        this._properties.set(ChronicleConnectionStringBuilder._hostKey, value);
+        this._hosts = [{ host: value, port: this.hosts[0].port }];
     }
 
+    /**
+     * Convenience accessor for the first host's port in {@link hosts}. Setting it collapses
+     * the configuration to that single host, discarding any others previously set via
+     * {@link hosts}.
+     */
     get port(): number {
-        const port = this._properties.get(ChronicleConnectionStringBuilder._portKey);
-        return port ? parseInt(port, 10) : ChronicleConnectionStringBuilder._defaultPort;
+        return this.hosts[0].port;
     }
 
     set port(value: number) {
-        this._properties.set(ChronicleConnectionStringBuilder._portKey, value.toString());
+        this._hosts = [{ host: this.hosts[0].host, port: value }];
     }
 
     get username(): string | undefined {
@@ -93,6 +188,14 @@ export class ChronicleConnectionStringBuilder {
         this._properties.set(ChronicleConnectionStringBuilder._schemeKey, value);
     }
 
+    /**
+     * Whether the connection string uses the DNS SRV lookup scheme (`chronicle+srv://`).
+     * Compared case-insensitively, matching {@link scheme}'s own parsing.
+     */
+    get isSrv(): boolean {
+        return this.scheme.toLowerCase() === SRV_SCHEME;
+    }
+
     get authenticationMode(): AuthenticationMode {
         const hasClientCredentials = !!this.username && !!this.password;
         const hasApiKey = !!this.apiKey;
@@ -133,6 +236,21 @@ export class ChronicleConnectionStringBuilder {
         this._properties.set(ChronicleConnectionStringBuilder._disableTlsKey, value.toString());
     }
 
+    /**
+     * Whether TLS certificate validation is skipped for the gRPC channel and OAuth token
+     * requests. Distinct from {@link disableTls}, which controls whether TLS is used at
+     * all. Defaults to `true` - set to `false` to require full certificate validation
+     * whenever TLS is on.
+     */
+    get skipTlsValidation(): boolean {
+        const raw = this._properties.get(ChronicleConnectionStringBuilder._skipTlsValidationKey);
+        return raw === undefined || raw === 'true';
+    }
+
+    set skipTlsValidation(value: boolean) {
+        this._properties.set(ChronicleConnectionStringBuilder._skipTlsValidationKey, value.toString());
+    }
+
     get certificatePath(): string | undefined {
         return this._properties.get(ChronicleConnectionStringBuilder._certificatePathKey);
     }
@@ -159,7 +277,52 @@ export class ChronicleConnectionStringBuilder {
         this._properties.delete(ChronicleConnectionStringBuilder._certificatePasswordKey);
     }
 
+    /**
+     * The strategy used to select one address from {@link hosts} (or the addresses
+     * resolved from a `chronicle+srv://` host) on every connect/reconnect attempt.
+     * Defaults to {@link LoadBalancerMode.LeastConnections}.
+     */
+    get loadBalancer(): LoadBalancerMode {
+        const raw = this._properties.get(ChronicleConnectionStringBuilder._loadBalancerKey);
+        if (!raw) {
+            return LoadBalancerMode.LeastConnections;
+        }
+
+        const knownModes = Object.values(LoadBalancerMode) as string[];
+        if (!knownModes.includes(raw)) {
+            throw new Error(`Unknown loadBalancer strategy '${raw}'. Expected one of: ${knownModes.join(', ')}`);
+        }
+
+        return raw as LoadBalancerMode;
+    }
+
+    set loadBalancer(value: LoadBalancerMode) {
+        this._properties.set(ChronicleConnectionStringBuilder._loadBalancerKey, value);
+    }
+
+    /**
+     * The `host[:port]` DNS name server used to resolve `chronicle+srv://` SRV records.
+     * Defaults to port 53 when no port is given. Undefined uses the system default
+     * resolver.
+     */
+    get srvNameServer(): string | undefined {
+        return this._properties.get(ChronicleConnectionStringBuilder._srvNameServerKey);
+    }
+
+    set srvNameServer(value: string | undefined) {
+        if (value) {
+            this._properties.set(ChronicleConnectionStringBuilder._srvNameServerKey, value);
+            return;
+        }
+
+        this._properties.delete(ChronicleConnectionStringBuilder._srvNameServerKey);
+    }
+
     build(): string {
+        if (this.isSrv && this.hosts.length > 1) {
+            throw new Error(`${SRV_SCHEME} connection strings support only a single host, found ${this.hosts.length}`);
+        }
+
         let result = `${this.scheme}://`;
 
         if (this.username) {
@@ -170,8 +333,7 @@ export class ChronicleConnectionStringBuilder {
             result += '@';
         }
 
-        result += this.host;
-        result += `:${this.port}`;
+        result += this.hosts.map(formatServerAddress).join(',');
 
         const queryParameters: string[] = [];
 
@@ -183,6 +345,10 @@ export class ChronicleConnectionStringBuilder {
             queryParameters.push('disableTls=true');
         }
 
+        if (!this.skipTlsValidation) {
+            queryParameters.push('skipTlsValidation=false');
+        }
+
         if (this.certificatePath) {
             queryParameters.push(`certificatePath=${encodeURIComponent(this.certificatePath)}`);
         }
@@ -191,17 +357,26 @@ export class ChronicleConnectionStringBuilder {
             queryParameters.push(`certificatePassword=${encodeURIComponent(this.certificatePassword)}`);
         }
 
+        if (this._properties.has(ChronicleConnectionStringBuilder._loadBalancerKey)) {
+            queryParameters.push(`loadBalancer=${encodeURIComponent(this.loadBalancer)}`);
+        }
+
+        if (this.srvNameServer) {
+            queryParameters.push(`srvNameServer=${encodeURIComponent(this.srvNameServer)}`);
+        }
+
         for (const [key, value] of this._properties) {
             if (
-                key !== ChronicleConnectionStringBuilder._hostKey &&
-                key !== ChronicleConnectionStringBuilder._portKey &&
                 key !== ChronicleConnectionStringBuilder._usernameKey &&
                 key !== ChronicleConnectionStringBuilder._passwordKey &&
                 key !== ChronicleConnectionStringBuilder._schemeKey &&
                 key !== ChronicleConnectionStringBuilder._apiKeyKey &&
                 key !== ChronicleConnectionStringBuilder._disableTlsKey &&
+                key !== ChronicleConnectionStringBuilder._skipTlsValidationKey &&
                 key !== ChronicleConnectionStringBuilder._certificatePathKey &&
-                key !== ChronicleConnectionStringBuilder._certificatePasswordKey
+                key !== ChronicleConnectionStringBuilder._certificatePasswordKey &&
+                key !== ChronicleConnectionStringBuilder._loadBalancerKey &&
+                key !== ChronicleConnectionStringBuilder._srvNameServerKey
             ) {
                 queryParameters.push(`${encodeURIComponent(key)}=${encodeURIComponent(value)}`);
             }
@@ -215,32 +390,54 @@ export class ChronicleConnectionStringBuilder {
     }
 
     private parseConnectionString(connectionString: string): void {
-        if (
-            connectionString.startsWith('chronicle://') ||
-            connectionString.startsWith('chronicle+srv://')
-        ) {
+        const lowerCased = connectionString.toLowerCase();
+        if (lowerCased.startsWith('chronicle://') || lowerCased.startsWith(`${SRV_SCHEME}://`)) {
             this.parseUrl(connectionString);
         }
     }
 
     private parseUrl(value: string): void {
         try {
-            const parsed = new URL(value);
-            this.scheme = parsed.protocol.replace(':', '');
-            this.host = parsed.hostname;
-
-            if (parsed.port) {
-                this.port = parseInt(parsed.port, 10);
+            const schemeSeparatorIndex = value.indexOf('://');
+            const scheme = value.slice(0, schemeSeparatorIndex);
+            this.scheme = scheme;
+
+            const rest = value.slice(schemeSeparatorIndex + 3);
+
+            // The authority (userinfo + hosts) ends at the first '/' or '?'; parsing tolerates
+            // an optional trailing slash immediately before the query string this way.
+            const pathIndex = [rest.indexOf('/'), rest.indexOf('?')]
+                .filter(index => index >= 0)
+                .sort((first, second) => first - second)[0];
+            const authority = pathIndex === undefined ? rest : rest.slice(0, pathIndex);
+            let query = '';
+            if (pathIndex !== undefined) {
+                const queryIndex = rest.indexOf('?', pathIndex);
+                query = queryIndex === -1 ? '' : rest.slice(queryIndex + 1);
             }
 
-            if (parsed.username) {
-                this.username = decodeURIComponent(parsed.username);
-                if (parsed.password) {
-                    this.password = decodeURIComponent(parsed.password);
+            // The userinfo separator is the LAST '@' in the authority, so a host portion never
+            // legitimately containing '@' can't be confused for one.
+            const authoritySeparatorIndex = authority.lastIndexOf('@');
+            let hostList = authority;
+            if (authoritySeparatorIndex >= 0) {
+                const userInfo = authority.slice(0, authoritySeparatorIndex);
+                hostList = authority.slice(authoritySeparatorIndex + 1);
+
+                const parts = userInfo.split(':');
+                this.username = decodeURIComponent(parts[0]);
+                if (parts.length > 1) {
+                    this.password = decodeURIComponent(parts[1]);
                 }
             }
 
-            for (const [key, queryValue] of new URLSearchParams(parsed.search)) {
+            const hosts = splitHostList(hostList).map(parseHostAndPort);
+            if (this.isSrv && hosts.length > 1) {
+                throw new Error(`${SRV_SCHEME} connection strings support only a single host, found ${hosts.length}`);
+            }
+            this.hosts = hosts;
+
+            for (const [key, queryValue] of new URLSearchParams(query)) {
                 this._properties.set(key, decodeURIComponent(queryValue));
             }
         } catch (error) {
@@ -256,23 +453,49 @@ export class ChronicleConnectionString {
     static readonly DEVELOPMENT_CLIENT = 'chronicle-dev-client';
     static readonly DEVELOPMENT_CLIENT_SECRET = 'chronicle-dev-secret';
     static readonly Default = new ChronicleConnectionString('chronicle://localhost:35000');
+    // skipTlsValidation defaults to true, so no explicit query parameter is needed here for
+    // this to connect to the Kernel's self-signed development certificate.
     static readonly Development = new ChronicleConnectionString(
         `chronicle://${ChronicleConnectionString.DEVELOPMENT_CLIENT}:${ChronicleConnectionString.DEVELOPMENT_CLIENT_SECRET}@localhost:35000`
     );
 
     private readonly _builder: ChronicleConnectionStringBuilder;
-    private readonly _serverAddress: ChronicleServerAddress;
+    private readonly _serverAddresses: ChronicleServerAddress[];
 
     constructor(connectionString: string) {
         this._builder = new ChronicleConnectionStringBuilder(connectionString);
-        this._serverAddress = {
-            host: this._builder.host,
-            port: this._builder.port
-        };
+        this._serverAddresses = this._builder.hosts;
+    }
+
+    /**
+     * The connection string's scheme, either `chronicle` or `chronicle+srv`.
+     */
+    get scheme(): string {
+        return this._builder.scheme;
     }
 
+    /**
+     * Whether the connection string uses the DNS SRV lookup scheme (`chronicle+srv://`).
+     */
+    get isSrv(): boolean {
+        return this._builder.isSrv;
+    }
+
+    /**
+     * Convenience accessor for the first entry in {@link serverAddresses}, for callers
+     * that only ever expect a single server address.
+     */
     get serverAddress(): ChronicleServerAddress {
-        return this._serverAddress;
+        return this._serverAddresses[0];
+    }
+
+    /**
+     * All server addresses parsed from a multi-host `chronicle://` connection string.
+     * For `chronicle+srv://` connection strings, this holds the single SRV lookup host,
+     * not the resolved addresses - resolve those via {@link ChronicleServerAddressResolver}.
+     */
+    get serverAddresses(): ChronicleServerAddress[] {
+        return this._serverAddresses;
     }
 
     get username(): string | undefined {
@@ -295,6 +518,14 @@ export class ChronicleConnectionString {
         return this._builder.disableTls;
     }
 
+    /**
+     * Whether TLS certificate validation is skipped. See
+     * {@link ChronicleConnectionStringBuilder.skipTlsValidation}.
+     */
+    get skipTlsValidation(): boolean {
+        return this._builder.skipTlsValidation;
+    }
+
     get certificatePath(): string | undefined {
         return this._builder.certificatePath;
     }
@@ -303,6 +534,20 @@ export class ChronicleConnectionString {
         return this._builder.certificatePassword;
     }
 
+    /**
+     * The strategy used to select one server address on every connect/reconnect attempt.
+     */
+    get loadBalancer(): LoadBalancerMode {
+        return this._builder.loadBalancer;
+    }
+
+    /**
+     * The `host[:port]` DNS name server used to resolve `chronicle+srv://` SRV records.
+     */
+    get srvNameServer(): string | undefined {
+        return this._builder.srvNameServer;
+    }
+
     withCredentials(username: string, password: string): ChronicleConnectionString {
         const builder = new ChronicleConnectionStringBuilder(this.toString());
         builder.username = username;
@@ -321,10 +566,19 @@ export class ChronicleConnectionString {
             return grpc.credentials.createInsecure();
         }
 
+        if (this.skipTlsValidation) {
+            // Chronicle generates a self-signed certificate in development, and skipTlsValidation
+            // defaults to true so this works without extra configuration. grpc-js has no
+            // per-error hook to accept only self-signed/untrusted-root chains the way a
+            // finer-grained validator would, so skipTlsValidation bypasses chain validation
+            // entirely. Set skipTlsValidation=false for a server with a verifiable certificate.
+            return grpc.credentials.createSsl(null, null, null, { rejectUnauthorized: false });
+        }
+
         return grpc.credentials.createSsl();
     }
 
     toString(): string {
         return this._builder.build();
     }
-}
+}

package/connection/ChronicleServerAddressResolver.spec.ts

@@ -0,0 +1,41 @@
+// 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 { ChronicleConnectionString } from './ChronicleConnectionString';
+import { ChronicleServerAddressResolver } from './ChronicleServerAddressResolver';
+import type { ChronicleSrvResolver } from './ChronicleSrvResolver';
+
+describe('ChronicleServerAddressResolver', () => {
+    describe('when resolving a plain multi-host connection string', () => {
+        const fakeSrvResolver = { resolve: vi.fn() };
+        const resolver = new ChronicleServerAddressResolver(fakeSrvResolver as unknown as ChronicleSrvResolver);
+        const connectionString = new ChronicleConnectionString('chronicle://host1:35001,host2:35002');
+
+        it('should pass through the parsed hosts unchanged', async () => {
+            const addresses = await resolver.resolve(connectionString);
+            expect(addresses).toEqual([{ host: 'host1', port: 35001 }, { host: 'host2', port: 35002 }]);
+        });
+
+        it('should never touch DNS', async () => {
+            await resolver.resolve(connectionString);
+            expect(fakeSrvResolver.resolve).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when resolving a chronicle+srv connection string', () => {
+        const fakeSrvResolver = { resolve: vi.fn().mockResolvedValue([{ host: 'node-a', port: 35001 }, { host: 'node-b', port: 35002 }]) };
+        const resolver = new ChronicleServerAddressResolver(fakeSrvResolver as unknown as ChronicleSrvResolver);
+        const connectionString = new ChronicleConnectionString('chronicle+srv://cluster.example.com/?srvNameServer=127.0.0.1:5353');
+
+        it('should delegate to the srv resolver with the srv host and name server', async () => {
+            await resolver.resolve(connectionString);
+            expect(fakeSrvResolver.resolve).toHaveBeenCalledWith('cluster.example.com', '127.0.0.1:5353');
+        });
+
+        it('should return the resolved addresses', async () => {
+            const addresses = await resolver.resolve(connectionString);
+            expect(addresses).toEqual([{ host: 'node-a', port: 35001 }, { host: 'node-b', port: 35002 }]);
+        });
+    });
+});

package/connection/ChronicleServerAddressResolver.ts

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ChronicleConnectionString, ChronicleServerAddress } from './ChronicleConnectionString';
+import { ChronicleSrvResolver } from './ChronicleSrvResolver';
+
+/**
+ * Resolves the effective list of Chronicle server addresses for a connection string.
+ * `chronicle+srv://` connection strings are resolved via DNS SRV lookup on every call;
+ * plain `chronicle://` connection strings pass their parsed host list through unchanged
+ * and never touch DNS.
+ */
+export class ChronicleServerAddressResolver {
+    /**
+     * Initializes a new instance of {@link ChronicleServerAddressResolver}.
+     * @param _srvResolver - The SRV resolver used for `chronicle+srv://` connection strings.
+     */
+    constructor(private readonly _srvResolver: ChronicleSrvResolver = new ChronicleSrvResolver()) {}
+
+    /**
+     * Resolves the server addresses for a connection string.
+     * @param connectionString - The connection string to resolve addresses for.
+     * @returns The resolved addresses.
+     */
+    async resolve(connectionString: ChronicleConnectionString): Promise<ChronicleServerAddress[]> {
+        if (!connectionString.isSrv) {
+            return connectionString.serverAddresses;
+        }
+
+        const [srvHost] = connectionString.serverAddresses;
+        return this._srvResolver.resolve(srvHost.host, connectionString.srvNameServer);
+    }
+}

package/connection/ChronicleSrvResolutionError.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Thrown when a `chronicle+srv://` connection string's DNS zone publishes no SRV records
+ * for the queried name.
+ */
+export class ChronicleSrvResolutionError extends Error {
+    constructor(name: string) {
+        super(`No SRV records found for '${name}'. Verify the DNS zone publishes _chronicle._tcp SRV records for this host.`);
+        this.name = 'ChronicleSrvResolutionError';
+    }
+}

package/connection/ChronicleSrvResolver.spec.ts

@@ -0,0 +1,103 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { SrvRecord } from 'dns';
+import { describe, expect, it, vi } from 'vitest';
+import { ChronicleSrvResolutionError } from './ChronicleSrvResolutionError';
+import { ChronicleSrvResolver } from './ChronicleSrvResolver';
+
+function createFakeResolver(records: SrvRecord[]) {
+    const setServers = vi.fn();
+    const resolveSrv = vi.fn().mockResolvedValue(records);
+    return { setServers, resolveSrv };
+}
+
+describe('ChronicleSrvResolver', () => {
+    describe('when resolving a host with multiple srv records', () => {
+        const records: SrvRecord[] = [
+            { name: 'node-b.example.com', port: 35002, priority: 10, weight: 5 },
+            { name: 'node-a.example.com', port: 35001, priority: 0, weight: 5 },
+            { name: 'node-c.example.com', port: 35003, priority: 0, weight: 10 }
+        ];
+        const fakeResolver = createFakeResolver(records);
+        const resolver = new ChronicleSrvResolver(() => fakeResolver as never);
+
+        it('should query the _chronicle._tcp SRV name', async () => {
+            await resolver.resolve('cluster.example.com');
+            expect(fakeResolver.resolveSrv).toHaveBeenCalledWith('_chronicle._tcp.cluster.example.com');
+        });
+
+        it('should sort ascending by priority then descending by weight', async () => {
+            const addresses = await resolver.resolve('cluster.example.com');
+            expect(addresses).toEqual([
+                { host: 'node-c.example.com', port: 35003 },
+                { host: 'node-a.example.com', port: 35001 },
+                { host: 'node-b.example.com', port: 35002 }
+            ]);
+        });
+    });
+
+    describe('when a srv target has a trailing dot', () => {
+        const fakeResolver = createFakeResolver([{ name: 'node-a.example.com.', port: 35001, priority: 0, weight: 0 }]);
+        const resolver = new ChronicleSrvResolver(() => fakeResolver as never);
+
+        it('should strip the trailing dot', async () => {
+            const addresses = await resolver.resolve('cluster.example.com');
+            expect(addresses[0].host).toBe('node-a.example.com');
+        });
+    });
+
+    describe('when no srv records are found', () => {
+        const fakeResolver = createFakeResolver([]);
+        const resolver = new ChronicleSrvResolver(() => fakeResolver as never);
+
+        it('should throw a ChronicleSrvResolutionError', async () => {
+            await expect(resolver.resolve('cluster.example.com')).rejects.toThrow(ChronicleSrvResolutionError);
+        });
+    });
+
+    describe('when a srvNameServer is specified without a port', () => {
+        const fakeResolver = createFakeResolver([{ name: 'node-a.example.com', port: 35001, priority: 0, weight: 0 }]);
+        const resolver = new ChronicleSrvResolver(() => fakeResolver as never);
+
+        it('should default the name server port to 53', async () => {
+            await resolver.resolve('cluster.example.com', '127.0.0.1');
+            expect(fakeResolver.setServers).toHaveBeenCalledWith(['127.0.0.1:53']);
+        });
+    });
+
+    describe('when a srvNameServer is specified with a port', () => {
+        const fakeResolver = createFakeResolver([{ name: 'node-a.example.com', port: 35001, priority: 0, weight: 0 }]);
+        const resolver = new ChronicleSrvResolver(() => fakeResolver as never);
+
+        it('should use the given port', async () => {
+            await resolver.resolve('cluster.example.com', '127.0.0.1:5353');
+            expect(fakeResolver.setServers).toHaveBeenCalledWith(['127.0.0.1:5353']);
+        });
+    });
+
+    describe('when no srvNameServer is specified', () => {
+        const fakeResolver = createFakeResolver([{ name: 'node-a.example.com', port: 35001, priority: 0, weight: 0 }]);
+        const resolver = new ChronicleSrvResolver(() => fakeResolver as never);
+
+        it('should not configure custom servers', async () => {
+            await resolver.resolve('cluster.example.com');
+            expect(fakeResolver.setServers).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when resolving twice', () => {
+        const records: SrvRecord[] = [{ name: 'node-a.example.com', port: 35001, priority: 0, weight: 0 }];
+        let resolverCreationCount = 0;
+        const resolver = new ChronicleSrvResolver(() => {
+            resolverCreationCount++;
+            return createFakeResolver(records) as never;
+        });
+
+        it('should create a fresh resolver for each call, never caching results', async () => {
+            await resolver.resolve('cluster.example.com');
+            await resolver.resolve('cluster.example.com');
+            expect(resolverCreationCount).toBe(2);
+        });
+    });
+});