@cratis/chronicle 1.0.2 → 2.1.0

package/connection/ChronicleSrvResolver.ts

@@ -0,0 +1,57 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Resolver } from 'dns/promises';
+import type { ChronicleServerAddress } from './ChronicleConnectionString';
+import { ChronicleSrvResolutionError } from './ChronicleSrvResolutionError';
+
+const DEFAULT_DNS_PORT = 53;
+
+/**
+ * Resolves Chronicle server addresses from DNS SRV records for `chronicle+srv://`
+ * connection strings, querying `_chronicle._tcp.<host>` the same way the .NET reference
+ * client does. Every call performs a fresh DNS query - results are never cached here, so
+ * that reconnects always pick up membership changes.
+ */
+export class ChronicleSrvResolver {
+    /**
+     * Initializes a new instance of {@link ChronicleSrvResolver}.
+     * @param _createResolver - Factory creating the `dns.promises.Resolver` used for each
+     * resolution. Overridable for testing; defaults to a fresh `Resolver` per call.
+     */
+    constructor(private readonly _createResolver: () => Resolver = () => new Resolver()) {}
+
+    /**
+     * Resolves the SRV records for a `chronicle+srv://` host.
+     * @param host - The host portion of the `chronicle+srv://` connection string.
+     * @param nameServer - Optional `host[:port]` DNS name server to query instead of the
+     * system default. Defaults to port 53 when no port is given.
+     * @returns The resolved addresses, sorted ascending by priority and then descending by
+     * weight, per RFC 2782.
+     */
+    async resolve(host: string, nameServer?: string): Promise<ChronicleServerAddress[]> {
+        const resolver = this._createResolver();
+
+        if (nameServer) {
+            resolver.setServers([this.withDefaultPort(nameServer)]);
+        }
+
+        const name = `_chronicle._tcp.${host}`;
+        const records = await resolver.resolveSrv(name);
+
+        if (records.length === 0) {
+            throw new ChronicleSrvResolutionError(name);
+        }
+
+        return records
+            .slice()
+            .sort((first, second) => first.priority - second.priority || second.weight - first.weight)
+            // SRV targets are frequently returned as FQDNs with a trailing root '.'.
+            .map(record => ({ host: record.name.replace(/\.$/, ''), port: record.port }));
+    }
+
+    private withDefaultPort(nameServer: string): string {
+        const colonIndex = nameServer.lastIndexOf(':');
+        return colonIndex === -1 ? `${nameServer}:${DEFAULT_DNS_PORT}` : nameServer;
+    }
+}

package/connection/ConnectionLifecycle.spec.ts

@@ -0,0 +1,109 @@
+// 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 { ConnectionLifecycle } from './ConnectionLifecycle';
+
+const ignoreErrors = () => { };
+
+describe('ConnectionLifecycle', () => {
+    describe('when connected', () => {
+        it('should report being connected', async () => {
+            const lifecycle = new ConnectionLifecycle();
+
+            await lifecycle.connected(ignoreErrors);
+
+            expect(lifecycle.isConnected).toBe(true);
+        });
+
+        it('should invoke every connected handler', async () => {
+            const lifecycle = new ConnectionLifecycle();
+            const first = vi.fn().mockResolvedValue(undefined);
+            const second = vi.fn().mockResolvedValue(undefined);
+            lifecycle.onConnected(first);
+            lifecycle.onConnected(second);
+
+            await lifecycle.connected(ignoreErrors);
+
+            expect(first).toHaveBeenCalledOnce();
+            expect(second).toHaveBeenCalledOnce();
+        });
+
+        it('should isolate a failing handler from the others', async () => {
+            const lifecycle = new ConnectionLifecycle();
+            const failing = vi.fn().mockRejectedValue(new Error('registration failed'));
+            const succeeding = vi.fn().mockResolvedValue(undefined);
+            const onError = vi.fn();
+            lifecycle.onConnected(failing);
+            lifecycle.onConnected(succeeding);
+
+            await lifecycle.connected(onError);
+
+            expect(succeeding).toHaveBeenCalledOnce();
+            expect(onError).toHaveBeenCalledOnce();
+        });
+    });
+
+    describe('when disconnected', () => {
+        it('should report not being connected', async () => {
+            const lifecycle = new ConnectionLifecycle();
+            await lifecycle.connected(ignoreErrors);
+
+            await lifecycle.disconnected(ignoreErrors);
+
+            expect(lifecycle.isConnected).toBe(false);
+        });
+
+        it('should rotate the connection id', async () => {
+            const lifecycle = new ConnectionLifecycle();
+            const before = lifecycle.connectionId;
+
+            await lifecycle.disconnected(ignoreErrors);
+
+            // The kernel keys observer subscriptions by connection id, so reusing an
+            // evicted id after a reconnect leaves the client registered as a ghost.
+            expect(lifecycle.connectionId).not.toBe(before);
+        });
+
+        it('should rotate the connection id only after the handlers have run', async () => {
+            const lifecycle = new ConnectionLifecycle();
+            const idDuringHandler = { value: '' };
+            lifecycle.onDisconnected(async () => {
+                idDuringHandler.value = lifecycle.connectionId;
+            });
+            const before = lifecycle.connectionId;
+
+            await lifecycle.disconnected(ignoreErrors);
+
+            // Handlers tear down subscriptions registered under the *old* id, so they
+            // must still see it while they run.
+            expect(idDuringHandler.value).toBe(before);
+        });
+
+        it('should invoke every disconnected handler', async () => {
+            const lifecycle = new ConnectionLifecycle();
+            const first = vi.fn().mockResolvedValue(undefined);
+            const second = vi.fn().mockResolvedValue(undefined);
+            lifecycle.onDisconnected(first);
+            lifecycle.onDisconnected(second);
+
+            await lifecycle.disconnected(ignoreErrors);
+
+            expect(first).toHaveBeenCalledOnce();
+            expect(second).toHaveBeenCalledOnce();
+        });
+    });
+
+    describe('when a handler is unsubscribed', () => {
+        it('should not invoke it again', async () => {
+            const lifecycle = new ConnectionLifecycle();
+            const handler = vi.fn().mockResolvedValue(undefined);
+            const unsubscribe = lifecycle.onConnected(handler);
+
+            unsubscribe();
+            await lifecycle.connected(ignoreErrors);
+
+            expect(handler).not.toHaveBeenCalled();
+        });
+    });
+});

package/connection/ILoadBalancerStrategy.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ChronicleServerAddress } from './ChronicleConnectionString';
+
+/**
+ * Selects one server address from a list of candidates for a connect/reconnect attempt.
+ */
+export interface ILoadBalancerStrategy {
+    /**
+     * Selects one address from the given candidates.
+     * @param candidates - The addresses to select from. Never empty.
+     * @returns A promise resolving to the selected address.
+     */
+    select(candidates: ChronicleServerAddress[]): Promise<ChronicleServerAddress>;
+}

package/connection/KernelKeepAlive.spec.ts

@@ -0,0 +1,175 @@
+// 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 type { ConnectRequest } from '@cratis/chronicle.contracts';
+import { KernelKeepAlive, type IKeepAliveConnections } from './KernelKeepAlive';
+
+const request = { ConnectionId: 'connection-1' } as unknown as ConnectRequest;
+
+const timeouts = { idleTimeoutMs: 50, answerTimeoutMs: 50 };
+
+/**
+ * A `Connect` stream the spec drives by hand — push keep-alives, end it, or simply
+ * leave it silent to model the kernel evicting a client without closing the stream.
+ */
+function createStream() {
+    const pending: Array<(result: IteratorResult<unknown>) => void> = [];
+    const queued: Array<IteratorResult<unknown>> = [];
+
+    const push = (result: IteratorResult<unknown>) => {
+        const waiter = pending.shift();
+        if (waiter) {
+            waiter(result);
+        } else {
+            queued.push(result);
+        }
+    };
+
+    return {
+        sendKeepAlive: () => push({ done: false, value: { ConnectionId: 'connection-1' } }),
+        end: () => push({ done: true, value: undefined }),
+        asIterable: (): AsyncIterable<unknown> => ({
+            [Symbol.asyncIterator]: () => ({
+                next: () => {
+                    const ready = queued.shift();
+                    if (ready) {
+                        return Promise.resolve(ready);
+                    }
+
+                    return new Promise<IteratorResult<unknown>>(resolve => pending.push(resolve));
+                }
+            })
+        })
+    };
+}
+
+function createConnections(stream: AsyncIterable<unknown>, answer = vi.fn().mockResolvedValue({})) {
+    return {
+        connections: { connect: () => stream, connectionKeepAlive: answer } as unknown as IKeepAliveConnections,
+        answer
+    };
+}
+
+const flush = () => new Promise(resolve => setTimeout(resolve, 0));
+
+describe('KernelKeepAlive', () => {
+    describe('when the kernel sends keep-alives', () => {
+        it('should answer every one of them', async () => {
+            const stream = createStream();
+            const { connections, answer } = createConnections(stream.asIterable());
+            const controller = new AbortController();
+
+            stream.sendKeepAlive();
+            await new KernelKeepAlive(connections, vi.fn(), timeouts).start(request, controller.signal);
+
+            stream.sendKeepAlive();
+            await flush();
+            stream.sendKeepAlive();
+            await flush();
+
+            controller.abort();
+
+            // Each answer is what bumps LastSeen on the kernel; missing them gets the
+            // client evicted while the stream stays open.
+            expect(answer).toHaveBeenCalledTimes(3);
+        });
+
+        it('should not report the connection as lost', async () => {
+            const stream = createStream();
+            const { connections } = createConnections(stream.asIterable());
+            const onConnectionLost = vi.fn();
+            const controller = new AbortController();
+
+            stream.sendKeepAlive();
+            await new KernelKeepAlive(connections, onConnectionLost, timeouts).start(request, controller.signal);
+
+            stream.sendKeepAlive();
+            await flush();
+            controller.abort();
+
+            expect(onConnectionLost).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when the stream goes silent', () => {
+        it('should report the connection as lost', async () => {
+            const stream = createStream();
+            const { connections } = createConnections(stream.asIterable());
+            const onConnectionLost = vi.fn();
+
+            stream.sendKeepAlive();
+            await new KernelKeepAlive(connections, onConnectionLost, timeouts).start(request, new AbortController().signal);
+
+            // The kernel does not close the stream when its watchdog evicts a client,
+            // so silence — not an error — is what a half-disconnect looks like.
+            await new Promise(resolve => setTimeout(resolve, 100));
+
+            expect(onConnectionLost).toHaveBeenCalledOnce();
+        });
+    });
+
+    describe('when the stream ends', () => {
+        it('should report the connection as lost', async () => {
+            const stream = createStream();
+            const { connections } = createConnections(stream.asIterable());
+            const onConnectionLost = vi.fn();
+
+            stream.sendKeepAlive();
+            await new KernelKeepAlive(connections, onConnectionLost, timeouts).start(request, new AbortController().signal);
+
+            stream.end();
+            await flush();
+
+            expect(onConnectionLost).toHaveBeenCalledWith('keep-alive-stream-ended', expect.anything());
+        });
+    });
+
+    describe('when answering a keep-alive fails', () => {
+        it('should report the connection as lost', async () => {
+            const stream = createStream();
+            const answer = vi.fn().mockResolvedValueOnce({}).mockRejectedValue(new Error('unavailable'));
+            const { connections } = createConnections(stream.asIterable(), answer);
+            const onConnectionLost = vi.fn();
+
+            stream.sendKeepAlive();
+            await new KernelKeepAlive(connections, onConnectionLost, timeouts).start(request, new AbortController().signal);
+
+            stream.sendKeepAlive();
+            await flush();
+
+            expect(onConnectionLost).toHaveBeenCalledWith('keep-alive-failed', expect.anything());
+        });
+    });
+
+    describe('when the kernel never sends a first keep-alive', () => {
+        it('should fail to start rather than hang', async () => {
+            const stream = createStream();
+            const { connections } = createConnections(stream.asIterable());
+
+            // Every caller waiting on the connection queues behind this, so it must
+            // never be allowed to wait forever.
+            await expect(
+                new KernelKeepAlive(connections, vi.fn(), timeouts).start(request, new AbortController().signal)
+            ).rejects.toThrow(/Timed out waiting for the first keep-alive/);
+        });
+    });
+
+    describe('when the keep-alive has been aborted', () => {
+        it('should not report the connection as lost', async () => {
+            const stream = createStream();
+            const { connections } = createConnections(stream.asIterable());
+            const onConnectionLost = vi.fn();
+            const controller = new AbortController();
+
+            stream.sendKeepAlive();
+            await new KernelKeepAlive(connections, onConnectionLost, timeouts).start(request, controller.signal);
+
+            controller.abort();
+            await new Promise(resolve => setTimeout(resolve, 100));
+
+            // A deliberate shutdown is not a lost connection and must not trigger a reconnect.
+            expect(onConnectionLost).not.toHaveBeenCalled();
+        });
+    });
+});

package/connection/KernelKeepAlive.ts

@@ -0,0 +1,161 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { diag } from '@opentelemetry/api';
+import type { ConnectRequest } from '@cratis/chronicle.contracts';
+
+/**
+ * Overrides for how long {@link KernelKeepAlive} waits before giving up on the kernel.
+ */
+export interface KeepAliveTimeouts {
+    /** How long to wait for a keep-alive before treating the connection as dead. */
+    idleTimeoutMs?: number;
+    /** How long a single answer may take before the connection is considered dead. */
+    answerTimeoutMs?: number;
+}
+
+/**
+ * The subset of the connection service {@link KernelKeepAlive} needs, so it can be
+ * exercised without a live kernel.
+ */
+export interface IKeepAliveConnections {
+    connect(request: ConnectRequest, options?: { signal?: AbortSignal }): AsyncIterable<unknown>;
+    connectionKeepAlive(request: object, options?: { signal?: AbortSignal }): Promise<unknown>;
+}
+
+/**
+ * Drives the client half of Chronicle's keep-alive ping-pong.
+ *
+ * The kernel pushes a `ConnectionKeepAlive` down the `Connect` server stream once
+ * per second, and for each one the client must call the separate unary
+ * `ConnectionKeepAlive` RPC back — that is what bumps `LastSeen` on the kernel and
+ * keeps the client registered. A client that stops answering is evicted, its
+ * observers are unsubscribed, and reactors and reducers go silent while appends
+ * keep working.
+ *
+ * Eviction does not close the `Connect` stream, so a dead session usually presents
+ * as a stream that simply goes quiet rather than one that errors. Both a gap
+ * between keep-alives and an ended stream therefore mean the same thing: the
+ * connection is gone and the client must reconnect.
+ */
+export class KernelKeepAlive {
+    /**
+     * How long to wait for a keep-alive before treating the connection as dead.
+     * The kernel emits one per second and evicts clients whose `LastSeen` falls
+     * more than five seconds behind, which is the threshold the C# client uses too.
+     */
+    static readonly defaultIdleTimeoutMs = 5000;
+
+    /** How long a single answer may take before the connection is considered dead. */
+    static readonly defaultAnswerTimeoutMs = 5000;
+
+    private readonly _logger = diag.createComponentLogger({
+        namespace: '@cratis/chronicle/KernelKeepAlive'
+    });
+
+    private readonly _idleTimeoutMs: number;
+    private readonly _answerTimeoutMs: number;
+
+    /**
+     * Creates a new {@link KernelKeepAlive}.
+     * @param connections - The connection service to ping-pong with.
+     * @param onConnectionLost - Called once when the connection is found to be dead.
+     * @param timeouts - Overrides for the default timeouts.
+     */
+    constructor(
+        private readonly connections: IKeepAliveConnections,
+        private readonly onConnectionLost: (reason: string, error: unknown) => void,
+        timeouts: KeepAliveTimeouts = {}
+    ) {
+        this._idleTimeoutMs = timeouts.idleTimeoutMs ?? KernelKeepAlive.defaultIdleTimeoutMs;
+        this._answerTimeoutMs = timeouts.answerTimeoutMs ?? KernelKeepAlive.defaultAnswerTimeoutMs;
+    }
+
+    /**
+     * Opens the `Connect` stream and answers the first keep-alive, establishing the
+     * client's registration with the kernel. Resolves once the kernel has been heard
+     * from; the ongoing ping-pong then continues in the background until the
+     * connection is lost or `signal` is aborted.
+     * @param request - The connect request identifying this client.
+     * @param signal - Aborted to stop the keep-alive entirely.
+     */
+    async start(request: ConnectRequest, signal: AbortSignal): Promise<void> {
+        const stream = this.connections.connect(request, { signal });
+        const iterator = stream[Symbol.asyncIterator]();
+
+        // A kernel that accepts the stream but never sends anything must not hang
+        // the connect indefinitely — every caller awaiting the connection would
+        // block forever behind it.
+        const first = await this.withTimeout(
+            iterator.next(),
+            this._idleTimeoutMs,
+            'Timed out waiting for the first keep-alive from the kernel'
+        );
+
+        if (first.done) {
+            throw new Error('Connection service stream ended before sending first keep-alive');
+        }
+
+        await this.answer(first.value, signal);
+        void this.run(iterator, signal);
+    }
+
+    private async run(iterator: AsyncIterator<unknown, unknown>, signal: AbortSignal): Promise<void> {
+        try {
+            while (!signal.aborted) {
+                const result = await this.withTimeout(
+                    iterator.next(),
+                    this._idleTimeoutMs,
+                    'No keep-alive received from the kernel within the idle timeout'
+                );
+
+                if (result.done) {
+                    this.connectionLost('keep-alive-stream-ended', new Error('Keep-alive stream ended'));
+                    return;
+                }
+
+                await this.answer(result.value, signal);
+            }
+        } catch (error) {
+            if (!signal.aborted) {
+                this.connectionLost('keep-alive-failed', error);
+            }
+        }
+    }
+
+    private async answer(keepAlive: unknown, signal: AbortSignal): Promise<void> {
+        // An answer that never returns would stop the loop draining the stream, which
+        // gets the client evicted just as surely as never answering at all.
+        await this.withTimeout(
+            this.connections.connectionKeepAlive(keepAlive as object, { signal }),
+            this._answerTimeoutMs,
+            'Timed out answering a kernel keep-alive'
+        );
+    }
+
+    private connectionLost(reason: string, error: unknown): void {
+        this._logger.warn('Kernel keep-alive lost the connection', {
+            reason,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        this.onConnectionLost(reason, error);
+    }
+
+    private async withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
+        let handle: ReturnType<typeof setTimeout> | undefined;
+
+        try {
+            return await Promise.race([
+                promise,
+                new Promise<never>((_, reject) => {
+                    handle = setTimeout(() => reject(new Error(message)), timeoutMs);
+                    handle.unref?.();
+                })
+            ]);
+        } finally {
+            if (handle) {
+                clearTimeout(handle);
+            }
+        }
+    }
+}

package/connection/LeastConnectionsLoadBalancerStrategy.spec.ts

@@ -0,0 +1,159 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ChronicleServerAddress } from './ChronicleConnectionString';
+import { LeastConnectionsLoadBalancerStrategy } from './LeastConnectionsLoadBalancerStrategy';
+
+function textResponse(body: string, ok = true): Response {
+    return { ok, text: () => Promise.resolve(body) } as Response;
+}
+
+describe('LeastConnectionsLoadBalancerStrategy', () => {
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+
+    describe('when selecting from an empty candidate list', () => {
+        const strategy = new LeastConnectionsLoadBalancerStrategy(false, 0);
+
+        it('should throw', async () => {
+            await expect(strategy.select([])).rejects.toThrow();
+        });
+    });
+
+    describe('when selecting from a single candidate', () => {
+        const fetchMock = vi.fn();
+        const strategy = new LeastConnectionsLoadBalancerStrategy(false, 0);
+        const candidate: ChronicleServerAddress = { host: 'host1', port: 35000 };
+
+        beforeEach(() => vi.stubGlobal('fetch', fetchMock));
+
+        it('should return it immediately without probing', async () => {
+            const selected = await strategy.select([candidate]);
+            expect(selected).toEqual(candidate);
+            expect(fetchMock).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when candidates report different connection counts', () => {
+        const fetchMock = vi.fn((url: string, options?: { method?: string }) => {
+            if (options?.method === 'POST') {
+                return Promise.resolve(textResponse(''));
+            }
+            if (url.includes('host1')) {
+                return Promise.resolve(textResponse('5'));
+            }
+            if (url.includes('host2')) {
+                return Promise.resolve(textResponse('1'));
+            }
+            return Promise.resolve(textResponse('9'));
+        });
+        const strategy = new LeastConnectionsLoadBalancerStrategy(false, 0);
+        const candidates: ChronicleServerAddress[] = [
+            { host: 'host1', port: 35000 },
+            { host: 'host2', port: 35000 },
+            { host: 'host3', port: 35000 }
+        ];
+
+        beforeEach(() => vi.stubGlobal('fetch', fetchMock));
+
+        it('should select the candidate reporting the lowest count', async () => {
+            const selected = await strategy.select(candidates);
+            expect(selected).toEqual({ host: 'host2', port: 35000 });
+        });
+
+        it('should probe every candidate on the /connections/count route', async () => {
+            await strategy.select(candidates);
+            for (const candidate of candidates) {
+                expect(fetchMock).toHaveBeenCalledWith(
+                    `https://${candidate.host}:${candidate.port}/connections/count`,
+                    expect.anything()
+                );
+            }
+        });
+
+        it('should best-effort reserve a slot on the selected candidate', async () => {
+            await strategy.select(candidates);
+            expect(fetchMock).toHaveBeenCalledWith(
+                'https://host2:35000/connections/reserve',
+                expect.objectContaining({ method: 'POST' })
+            );
+        });
+    });
+
+    describe('when a candidate fails to respond', () => {
+        const fetchMock = vi.fn((url: string, options?: { method?: string }) => {
+            if (options?.method === 'POST') {
+                return Promise.resolve(textResponse(''));
+            }
+            if (url.includes('host1')) {
+                return Promise.reject(new Error('connection refused'));
+            }
+            return Promise.resolve(textResponse('3'));
+        });
+        const strategy = new LeastConnectionsLoadBalancerStrategy(false, 0);
+        const candidates: ChronicleServerAddress[] = [{ host: 'host1', port: 35000 }, { host: 'host2', port: 35000 }];
+
+        beforeEach(() => vi.stubGlobal('fetch', fetchMock));
+
+        it('should not fail the whole selection round', async () => {
+            await expect(strategy.select(candidates)).resolves.toBeDefined();
+        });
+
+        it('should never select the unreachable candidate over a responder', async () => {
+            const selected = await strategy.select(candidates);
+            expect(selected).toEqual({ host: 'host2', port: 35000 });
+        });
+    });
+
+    describe('when a candidate responds with a non-2xx status or an unparsable body', () => {
+        const fetchMock = vi.fn((url: string, options?: { method?: string }) => {
+            if (options?.method === 'POST') {
+                return Promise.resolve(textResponse(''));
+            }
+            if (url.includes('host1')) {
+                return Promise.resolve(textResponse('not-a-number'));
+            }
+            if (url.includes('host2')) {
+                return Promise.resolve(textResponse('irrelevant', false));
+            }
+            return Promise.resolve(textResponse('7'));
+        });
+        const strategy = new LeastConnectionsLoadBalancerStrategy(false, 0);
+        const candidates: ChronicleServerAddress[] = [
+            { host: 'host1', port: 35000 },
+            { host: 'host2', port: 35000 },
+            { host: 'host3', port: 35000 }
+        ];
+
+        beforeEach(() => vi.stubGlobal('fetch', fetchMock));
+
+        it('should treat both as maximally loaded and select the real responder', async () => {
+            const selected = await strategy.select(candidates);
+            expect(selected).toEqual({ host: 'host3', port: 35000 });
+        });
+    });
+
+    describe('when every candidate reports the same count', () => {
+        const fetchMock = vi.fn((_url: string, options?: { method?: string }) =>
+            Promise.resolve(textResponse(options?.method === 'POST' ? '' : '2')));
+        const strategy = new LeastConnectionsLoadBalancerStrategy(false, 0);
+        const candidates: ChronicleServerAddress[] = [
+            { host: 'host1', port: 35000 },
+            { host: 'host2', port: 35000 },
+            { host: 'host3', port: 35000 }
+        ];
+
+        beforeEach(() => vi.stubGlobal('fetch', fetchMock));
+
+        it('should break the tie randomly rather than always picking the first', async () => {
+            const selections = new Set<string>();
+            for (let attempt = 0; attempt < 30; attempt++) {
+                const selected = await strategy.select(candidates);
+                selections.add(`${selected.host}:${selected.port}`);
+            }
+            expect(selections.size).toBeGreaterThan(1);
+        });
+    });
+});