apache-iggy 0.10.0-edge.1 → 0.10.0-edge.3

package/README.md

@@ -71,7 +71,13 @@ new session. Transient not-committed responses retry the exact encoded request
 within one bounded deadline. A disconnected mutation is never replayed under a
 new session.
 
-When the server's `[heartbeat]` eviction is enabled, configure the client's `heartbeatInterval` below the server heartbeat interval. Client heartbeats are disabled when `heartbeatInterval` is unset.
+The client pings every `heartbeatInterval` milliseconds, 5000 by default, which
+keeps an idle session alive when the server's `[heartbeat]` eviction is enabled.
+The server evicts a connection silent for 36 s, which is 1.2 x its 30 s
+heartbeat interval. Raising the client interval past that window, or setting it
+to 0 to disable client heartbeats, exposes an idle consumer-group member to
+eviction; a connection holding no group membership is left alone. Any other
+unusable value is rejected instead of silently disabling the heartbeat.
 
 `sendBinaryRequest(code, payload)` sends an arbitrary command code. Known replicated commands use their registered operation, while unknown codes reach the server as non-replicated requests and are rejected by servers that do not register them.
 

package/dist/client/client.config.d.ts

@@ -1,4 +1,11 @@
 import type { ClientConfig } from './client.type.js';
 export declare const DEFAULT_MAX_RESPONSE_FRAME_SIZE: number;
+/**
+ * The server evicts a connection silent for 36 s (1.2 x its 30 s heartbeat
+ * interval). 5 s matches the other SDKs and survives several skipped pings.
+ */
+export declare const DEFAULT_HEARTBEAT_INTERVAL: number;
+/** Node's largest timer delay: setInterval clamps anything above it to 1 ms. */
+export declare const MAX_HEARTBEAT_INTERVAL = 2147483647;
 export declare const normalizeClientConfig: (config: ClientConfig) => ClientConfig;
 //# sourceMappingURL=client.config.d.ts.map

package/dist/client/client.config.js

@@ -15,6 +15,13 @@
 // specific language governing permissions and limitations
 // under the License.
 export const DEFAULT_MAX_RESPONSE_FRAME_SIZE = 64 * 1024 * 1024;
+/**
+ * The server evicts a connection silent for 36 s (1.2 x its 30 s heartbeat
+ * interval). 5 s matches the other SDKs and survives several skipped pings.
+ */
+export const DEFAULT_HEARTBEAT_INTERVAL = 5 * 1000;
+/** Node's largest timer delay: setInterval clamps anything above it to 1 ms. */
+export const MAX_HEARTBEAT_INTERVAL = 2_147_483_647;
 export const normalizeClientConfig = (config) => {
     const maxResponseFrameSize = config.maxResponseFrameSize ?? DEFAULT_MAX_RESPONSE_FRAME_SIZE;
     if (!Number.isSafeInteger(maxResponseFrameSize) ||
@@ -22,10 +29,20 @@ export const normalizeClientConfig = (config) => {
         throw new TypeError('maxResponseFrameSize must be a safe integer of at least 256 bytes');
     if ((config.poolSize?.min ?? 1) > 1 || (config.poolSize?.max ?? 1) > 1)
         throw new TypeError('VSR clients currently support exactly one pooled connection');
+    // Only 0 disables the heartbeat. Anything else unusable has to throw here:
+    // the default below is nullish-only, so a value that is negative, fractional
+    // or above MAX_HEARTBEAT_INTERVAL reaches setInterval, which clamps it to
+    // 1 ms and floods the server.
+    const heartbeatInterval = config.heartbeatInterval ?? DEFAULT_HEARTBEAT_INTERVAL;
+    if (!Number.isSafeInteger(heartbeatInterval) ||
+        heartbeatInterval < 0 ||
+        heartbeatInterval > MAX_HEARTBEAT_INTERVAL)
+        throw new TypeError(`heartbeatInterval must be a safe integer of milliseconds between 0 and ${MAX_HEARTBEAT_INTERVAL} (0 disables heartbeats)`);
     return {
         ...config,
         options: { ...config.options },
         maxResponseFrameSize,
+        heartbeatInterval,
         poolSize: { min: 1, max: 1 }
     };
 };

package/dist/client/client.config.test.js

@@ -16,7 +16,7 @@
 // under the License.
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
-import { DEFAULT_MAX_RESPONSE_FRAME_SIZE, normalizeClientConfig } from './client.config.js';
+import { DEFAULT_HEARTBEAT_INTERVAL, DEFAULT_MAX_RESPONSE_FRAME_SIZE, normalizeClientConfig } from './client.config.js';
 const config = () => ({
     transport: 'TCP',
     options: { host: '127.0.0.1', port: 8090 },
@@ -27,6 +27,23 @@ describe('normalizeClientConfig', () => {
         const normalized = normalizeClientConfig(config());
         assert.equal(normalized.maxResponseFrameSize, DEFAULT_MAX_RESPONSE_FRAME_SIZE);
     });
+    it('enables the heartbeat by default and honours an explicit interval', () => {
+        assert.equal(DEFAULT_HEARTBEAT_INTERVAL, 5000);
+        assert.equal(normalizeClientConfig(config()).heartbeatInterval, DEFAULT_HEARTBEAT_INTERVAL);
+        assert.equal(normalizeClientConfig({ ...config(), heartbeatInterval: 1000 })
+            .heartbeatInterval, 1000);
+        assert.equal(normalizeClientConfig({ ...config(), heartbeatInterval: 0 })
+            .heartbeatInterval, 0);
+    });
+    it('rejects unusable heartbeat intervals', () => {
+        for (const heartbeatInterval of [
+            -1, -5000, Number.NaN, 1.5, 2_147_483_648, 2 ** 32, Number.MAX_VALUE
+        ])
+            assert.throws(() => normalizeClientConfig({
+                ...config(),
+                heartbeatInterval
+            }), /heartbeatInterval/);
+    });
     it('restricts the client to one pooled connection', () => {
         const normalized = normalizeClientConfig(config());
         assert.deepEqual(normalized.poolSize, { min: 1, max: 1 });

package/dist/client/client.socket.d.ts

@@ -18,6 +18,12 @@ export declare class CommandResponseStream extends EventEmitter {
     private vsrSession;
     /** Shared authentication attempt for concurrent callers */
     private authenticationPromise?;
+    /** Whether a login is already being moved to the leader */
+    private settlingLeader;
+    /** How long a leaderless roster is polled before settling in place */
+    private leaderlessWaitBudget;
+    /** Delay between roster reads while the cluster elects */
+    private leaderlessPollInterval;
     /** Calls that have acquired this stream but have not fully settled */
     private pendingSubmissions;
     /** Whether the stream is currently processing a command */
@@ -42,7 +48,7 @@ export declare class CommandResponseStream extends EventEmitter {
     _init(): void;
     /**
      * Sends a command to the server.
-     * Automatically handles connection and authentication if needed.
+     * Automatically handles connection, authentication and leader settlement.
      *
      * @param command - Command code to send
      * @param payload - Command payload buffer
@@ -70,7 +76,28 @@ export declare class CommandResponseStream extends EventEmitter {
     private _processVsr;
     private _exchange;
     private isUnloggedCommand;
-    private _ensureVsrLeader;
+    /**
+     * Moves a freshly authenticated session to the cluster leader.
+     *
+     * Only the leader accepts replicated commands, and the roster read is
+     * auth-gated, so the topology cannot be inspected before a login binds a
+     * session. The redirect drops that session along with the socket, so the
+     * login is replayed on the leader and its answer supersedes the one from the
+     * node the client dialed. Leadership can move between the roster read and
+     * the replay, so each freshly bound hop rechecks the roster under a bounded
+     * redirect budget.
+     *
+     * @returns The leader's login response, or undefined when the client stays
+     */
+    private _settleOnLeader;
+    /**
+     * Reads the cluster roster and picks the endpoint to settle on.
+     *
+     * Best effort: an unreadable roster, `Unauthenticated` included (the session
+     * died between the login and this read), keeps the client on its current
+     * node instead of failing a login that already succeeded.
+     */
+    private _readLeaderEndpoint;
     /**
      * Fails all queued commands with the given error.
      *

package/dist/client/client.socket.js

@@ -26,6 +26,9 @@ import { decodeVsrResponse, prepareVsrCommand, readRegisteredSession, VsrEvictio
 import { normalizeClientConfig } from './client.config.js';
 const VSR_RESPONSE_TIMEOUT_MS = 30_000;
 const VSR_RETRY_INTERVAL_MS = 50;
+const LEADERLESS_WAIT_BUDGET_MS = 5_000;
+const LEADERLESS_POLL_INTERVAL_MS = 250;
+const MAX_LEADER_REDIRECTS = 3;
 const TRANSIENT_NOT_COMMITTED = 57;
 const TRANSIENT_NOT_ACCEPTED = 58;
 /**
@@ -58,6 +61,12 @@ export class CommandResponseStream extends EventEmitter {
     vsrSession;
     /** Shared authentication attempt for concurrent callers */
     authenticationPromise;
+    /** Whether a login is already being moved to the leader */
+    settlingLeader;
+    /** How long a leaderless roster is polled before settling in place */
+    leaderlessWaitBudget;
+    /** Delay between roster reads while the cluster elects */
+    leaderlessPollInterval;
     /** Calls that have acquired this stream but have not fully settled */
     pendingSubmissions;
     /** Whether the stream is currently processing a command */
@@ -85,6 +94,9 @@ export class CommandResponseStream extends EventEmitter {
         this._execQueue = [];
         this.vsrSession = new VsrSession();
         this.authenticationPromise = undefined;
+        this.settlingLeader = false;
+        this.leaderlessWaitBudget = LEADERLESS_WAIT_BUDGET_MS;
+        this.leaderlessPollInterval = LEADERLESS_POLL_INTERVAL_MS;
         this.pendingSubmissions = 0;
         this.heartbeatInFlight = false;
         this._init();
@@ -109,7 +121,7 @@ export class CommandResponseStream extends EventEmitter {
     }
     /**
      * Sends a command to the server.
-     * Automatically handles connection and authentication if needed.
+     * Automatically handles connection, authentication and leader settlement.
      *
      * @param command - Command code to send
      * @param payload - Command payload buffer
@@ -122,11 +134,9 @@ export class CommandResponseStream extends EventEmitter {
             const { handleResponse = true, last = true } = options;
             if (!this.connection.connected)
                 await this.connection.connect();
-            if (isLoginCommand(command))
-                await this._ensureVsrLeader();
             if (!this.isAuthenticated && !this.isUnloggedCommand(command))
                 await this.authenticate(this.options.credentials);
-            return await new Promise((resolve, reject) => {
+            const response = await new Promise((resolve, reject) => {
                 const job = {
                     command,
                     payload,
@@ -140,6 +150,16 @@ export class CommandResponseStream extends EventEmitter {
                     this._execQueue.unshift(job);
                 this._processQueue();
             });
+            if (!isLoginCommand(command) || this.settlingLeader)
+                return response;
+            this.settlingLeader = true;
+            try {
+                const settled = await this._settleOnLeader(command, payload);
+                return settled ?? response;
+            }
+            finally {
+                this.settlingLeader = false;
+            }
         }
         finally {
             this.pendingSubmissions -= 1;
@@ -309,31 +329,82 @@ export class CommandResponseStream extends EventEmitter {
             }
         });
     }
+    // `GetClusterMetadata` is deliberately absent: the server auth-gates it,
+    // so the client authenticates before reading the topology. A login dialed
+    // at a backup still succeeds because the server forwards the register to
+    // the primary.
     isUnloggedCommand(command) {
-        return UNLOGGED_COMMAND_CODE.includes(command) ||
-            command === COMMAND_CODE.GetClusterMetadata;
+        return UNLOGGED_COMMAND_CODE.includes(command);
     }
-    async _ensureVsrLeader() {
-        for (let attempt = 0; attempt < 3; attempt += 1) {
-            // Queue the metadata fetch instead of writing directly: a bare write
-            // would race an in-flight exchange and both would wake on the same
-            // response event.
-            const response = await this.sendCommand(GET_CLUSTER_METADATA.code, GET_CLUSTER_METADATA.serialize(), { last: false });
-            const metadata = GET_CLUSTER_METADATA.deserialize(response);
-            if (metadata.nodes.length <= 1)
-                return;
-            const leader = metadata.nodes.find((node) => node.role === 'Leader' && node.status === 'Healthy');
-            if (!leader) {
-                await delay(100);
-                continue;
+    /**
+     * Moves a freshly authenticated session to the cluster leader.
+     *
+     * Only the leader accepts replicated commands, and the roster read is
+     * auth-gated, so the topology cannot be inspected before a login binds a
+     * session. The redirect drops that session along with the socket, so the
+     * login is replayed on the leader and its answer supersedes the one from the
+     * node the client dialed. Leadership can move between the roster read and
+     * the replay, so each freshly bound hop rechecks the roster under a bounded
+     * redirect budget.
+     *
+     * @returns The leader's login response, or undefined when the client stays
+     */
+    async _settleOnLeader(loginCommand, loginPayload) {
+        let settledResponse;
+        for (let redirects = 0; redirects < MAX_LEADER_REDIRECTS; redirects += 1) {
+            const leader = await this._readLeaderEndpoint();
+            if (!leader || this.connection.isConnectedTo(leader.host, leader.port))
+                return settledResponse;
+            await this.connection.redirect(leader.host, leader.port);
+            settledResponse = await this.sendCommand(loginCommand, loginPayload, { last: false });
+        }
+        debug(`leader settlement reached its ${MAX_LEADER_REDIRECTS}-hop budget, ` +
+            'staying on the current node');
+        return settledResponse;
+    }
+    /**
+     * Reads the cluster roster and picks the endpoint to settle on.
+     *
+     * Best effort: an unreadable roster, `Unauthenticated` included (the session
+     * died between the login and this read), keeps the client on its current
+     * node instead of failing a login that already succeeded.
+     */
+    async _readLeaderEndpoint() {
+        // A cluster can be transiently leaderless: a restarted node cedes the
+        // primaryship its stale view assigns it, and the roster reports no leader
+        // until the peers' election completes. That window is roughly one heartbeat
+        // timeout, so poll through it rather than settling on a replica that denies
+        // every replicated command for its whole retry budget.
+        const deadline = Date.now() + this.leaderlessWaitBudget;
+        while (true) {
+            // Reading without a session would re-enter authentication, which awaits
+            // the very login this settlement runs inside of. The session can also die
+            // between polls, so this holds for every pass, not just the first.
+            if (!this.isAuthenticated)
+                return undefined;
+            try {
+                // Queue the metadata fetch instead of writing directly: a bare write
+                // would race an in-flight exchange and both would wake on the same
+                // response event.
+                const response = await this.sendCommand(GET_CLUSTER_METADATA.code, GET_CLUSTER_METADATA.serialize(), { last: false });
+                const metadata = GET_CLUSTER_METADATA.deserialize(response);
+                if (metadata.nodes.length <= 1)
+                    return undefined;
+                const leader = metadata.nodes.find((node) => node.role === 'Leader' && node.status === 'Healthy');
+                if (leader)
+                    return { host: leader.ip, port: leader.endpoints.tcp };
+            }
+            catch (error) {
+                debug('cluster metadata is unreadable, staying on this node', error);
+                return undefined;
             }
-            if (!this.connection.isConnectedTo(leader.ip, leader.endpoints.tcp)) {
-                await this.connection.redirect(leader.ip, leader.endpoints.tcp);
-                continue;
+            if (Date.now() >= deadline) {
+                debug('cluster metadata named no healthy leader within ' +
+                    `${this.leaderlessWaitBudget} ms, staying on this node`);
+                return undefined;
             }
-            return;
+            await delay(this.leaderlessPollInterval);
         }
-        throw new Error('VSR cluster has no healthy leader');
     }
     /**
      * Fails all queued commands with the given error.
@@ -448,6 +519,9 @@ export class CommandResponseStream extends EventEmitter {
                 }
             }
         }, interval);
+        // A pending heartbeat must not be the reason the process stays up: a script
+        // that never calls destroy() would otherwise hang on exit.
+        this.heartbeatIntervalHandler.unref();
     }
     /**
      * Returns the underlying socket as a readable stream.

package/dist/client/client.socket.test.js

@@ -166,6 +166,12 @@ const vsrConfig = (port) => ({
     credentials: { username: 'iggy', password: 'iggy' },
     reconnect: { enabled: false, interval: 100, maxRetries: 1 }
 });
+/** Shrinks the leaderless poll so a test observes it without waiting on it. */
+const compressLeaderlessPoll = (client, budget) => {
+    const settlement = client;
+    settlement.leaderlessWaitBudget = budget;
+    settlement.leaderlessPollInterval = 1;
+};
 describe('VSR client socket', () => {
     it('exchanges VSR frames over TLS', async () => {
         const server = await startVsrServer((frame, socket) => singleNodeHandler(server.port)(frame, socket), 'TLS');
@@ -197,13 +203,15 @@ describe('VSR client socket', () => {
             assert.equal(response.status, 0);
             const operations = server.frames.map((frame) => frame.readUInt8(REQUEST_OFFSET.operation));
             assert.deepEqual(operations, [
-                Operation.NonReplicated,
                 Operation.Register,
+                Operation.NonReplicated,
                 Operation.NonReplicated
             ]);
-            const register = server.frames[1];
+            const register = server.frames[0];
             assert.equal(register.readBigUInt64LE(REQUEST_OFFSET.request), 0n);
             assert.equal(register.readBigUInt64LE(REQUEST_OFFSET.session), 0n);
+            const settlement = server.frames[1];
+            assert.equal(settlement.readUInt32LE(REQUEST_OFFSET.reserved), COMMAND_CODE.GetClusterMetadata);
             const request = server.frames[2];
             assert.equal(request.readBigUInt64LE(REQUEST_OFFSET.session), TEST_SESSION);
             assert.equal(request.readUInt32LE(REQUEST_OFFSET.reserved), 60_001);
@@ -292,15 +300,20 @@ describe('VSR client socket', () => {
             await server.close();
         }
     });
-    it('redirects a direct login to the advertised leader before registering', async () => {
+    it('redirects a login to the advertised leader and registers there', async () => {
         const leader = await startVsrServer((frame, socket) => singleNodeHandler(leader.port)(frame, socket));
         const follower = await startVsrServer((frame, socket) => {
-            const code = frame.readUInt32LE(REQUEST_OFFSET.reserved);
-            if (code === COMMAND_CODE.GetClusterMetadata) {
+            const operation = frame.readUInt8(REQUEST_OFFSET.operation);
+            if (operation === Operation.Register) {
+                socket.write(replyFrame(Operation.Register, registerReplyBody()));
+                return;
+            }
+            if (frame.readUInt32LE(REQUEST_OFFSET.reserved) ===
+                COMMAND_CODE.GetClusterMetadata) {
                 socket.write(replyFrame(Operation.NonReplicated, twoNodeMetadataBody(follower.port, leader.port)));
                 return;
             }
-            socket.write(replyFrame(frame.readUInt8(REQUEST_OFFSET.operation), Buffer.alloc(0), 3));
+            socket.write(replyFrame(operation, Buffer.alloc(0), 58));
         });
         const client = new CommandResponseStream(vsrConfig(follower.port));
         try {
@@ -313,12 +326,19 @@ describe('VSR client socket', () => {
             assert.equal(response.status, 0);
             assert.equal(client.isAuthenticated, true);
             const followerOperations = follower.frames.map((frame) => frame.readUInt8(REQUEST_OFFSET.operation));
-            assert.deepEqual(followerOperations, [Operation.NonReplicated]);
+            assert.deepEqual(followerOperations, [
+                Operation.Register,
+                Operation.NonReplicated
+            ]);
+            await client.sendCommand(60_018, Buffer.alloc(0));
             const leaderOperations = leader.frames.map((frame) => frame.readUInt8(REQUEST_OFFSET.operation));
             assert.deepEqual(leaderOperations, [
+                Operation.Register,
                 Operation.NonReplicated,
-                Operation.Register
+                Operation.NonReplicated
             ]);
+            assert.equal(leader.frames[2].readUInt32LE(REQUEST_OFFSET.reserved), 60_018);
+            assert.equal(follower.frames.length, 2);
         }
         finally {
             client.destroy();
@@ -326,6 +346,156 @@ describe('VSR client socket', () => {
             await follower.close();
         }
     });
+    it('rechecks leadership after a redirected login', async () => {
+        const leader = await startVsrServer((frame, socket) => singleNodeHandler(leader.port)(frame, socket));
+        const intermediate = await startVsrServer((frame, socket) => {
+            const operation = frame.readUInt8(REQUEST_OFFSET.operation);
+            if (operation === Operation.Register) {
+                socket.write(replyFrame(Operation.Register, registerReplyBody()));
+                return;
+            }
+            socket.write(replyFrame(Operation.NonReplicated, twoNodeMetadataBody(intermediate.port, leader.port)));
+        });
+        const follower = await startVsrServer((frame, socket) => {
+            const operation = frame.readUInt8(REQUEST_OFFSET.operation);
+            if (operation === Operation.Register) {
+                socket.write(replyFrame(Operation.Register, registerReplyBody()));
+                return;
+            }
+            socket.write(replyFrame(Operation.NonReplicated, twoNodeMetadataBody(follower.port, intermediate.port)));
+        });
+        const client = new CommandResponseStream(vsrConfig(follower.port));
+        try {
+            await client.authenticate(vsrConfig(follower.port).credentials);
+            await client.sendCommand(60_019, Buffer.alloc(0));
+            assert.deepEqual(follower.frames.map((frame) => frame.readUInt8(REQUEST_OFFSET.operation)), [Operation.Register, Operation.NonReplicated]);
+            assert.deepEqual(intermediate.frames.map((frame) => frame.readUInt8(REQUEST_OFFSET.operation)), [Operation.Register, Operation.NonReplicated]);
+            assert.equal(leader.frames[2].readUInt32LE(REQUEST_OFFSET.reserved), 60_019);
+        }
+        finally {
+            client.destroy();
+            await follower.close();
+            await intermediate.close();
+            await leader.close();
+        }
+    });
+    it('keeps a single-node login on its node', async () => {
+        const server = await startVsrServer((frame, socket) => singleNodeHandler(server.port)(frame, socket));
+        const client = new CommandResponseStream(vsrConfig(server.port));
+        try {
+            await client.authenticate(vsrConfig(server.port).credentials);
+            const operations = server.frames.map((frame) => frame.readUInt8(REQUEST_OFFSET.operation));
+            assert.deepEqual(operations, [
+                Operation.Register,
+                Operation.NonReplicated
+            ]);
+            assert.equal(server.frames[1].readUInt32LE(REQUEST_OFFSET.reserved), COMMAND_CODE.GetClusterMetadata);
+            assert.equal(client.isAuthenticated, true);
+        }
+        finally {
+            client.destroy();
+            await server.close();
+        }
+    });
+    it('polls a leaderless roster before redirecting to the elected leader', async () => {
+        const leader = await startVsrServer((frame, socket) => singleNodeHandler(leader.port)(frame, socket));
+        let rosterReads = 0;
+        const follower = await startVsrServer((frame, socket) => {
+            const operation = frame.readUInt8(REQUEST_OFFSET.operation);
+            if (operation === Operation.Register) {
+                socket.write(replyFrame(Operation.Register, registerReplyBody()));
+                return;
+            }
+            rosterReads += 1;
+            // The first answer is mid-election: neither node holds the leader role.
+            socket.write(replyFrame(Operation.NonReplicated, rosterReads === 1
+                ? twoNodeMetadataBody(follower.port, leader.port, 1)
+                : twoNodeMetadataBody(follower.port, leader.port)));
+        });
+        const client = new CommandResponseStream(vsrConfig(follower.port));
+        compressLeaderlessPoll(client, 1_000);
+        try {
+            await client.authenticate(vsrConfig(follower.port).credentials);
+            assert.equal(rosterReads, 2);
+            const leaderOperations = leader.frames.map((frame) => frame.readUInt8(REQUEST_OFFSET.operation));
+            assert.deepEqual(leaderOperations, [
+                Operation.Register,
+                Operation.NonReplicated
+            ]);
+            assert.equal(client.isAuthenticated, true);
+        }
+        finally {
+            client.destroy();
+            await leader.close();
+            await follower.close();
+        }
+    });
+    it('keeps a login alive when the session dies mid-poll', async () => {
+        let rosterReads = 0;
+        const server = await startVsrServer((frame, socket) => {
+            const operation = frame.readUInt8(REQUEST_OFFSET.operation);
+            if (operation === Operation.Register) {
+                socket.write(replyFrame(Operation.Register, registerReplyBody()));
+                return;
+            }
+            rosterReads += 1;
+            // The roster stays leaderless and the session dies in the same breath.
+            // Polling on without a session would re-enter authentication, which
+            // awaits the login being settled, and the login would never return.
+            socket.write(Buffer.concat([
+                replyFrame(Operation.NonReplicated, twoNodeMetadataBody(server.port, server.port, 1)),
+                evictionFrame(EvictionReason.NoSession)
+            ]));
+        });
+        const client = new CommandResponseStream(vsrConfig(server.port));
+        compressLeaderlessPoll(client, 1_000);
+        try {
+            const outcome = await Promise.race([
+                client.authenticate(vsrConfig(server.port).credentials)
+                    .then(() => 'authenticated'),
+                // Unreferenced so a passing run is not held open by the stall timer.
+                new Promise((resolve) => {
+                    setTimeout(() => resolve('stalled'), 500).unref();
+                })
+            ]);
+            assert.equal(outcome, 'authenticated');
+            assert.equal(rosterReads, 1);
+        }
+        finally {
+            client.destroy();
+            await server.close();
+        }
+    });
+    it('keeps a login on its node when no leader appears in the budget', async () => {
+        const unavailable = await startVsrServer(() => { });
+        const unavailablePort = unavailable.port;
+        await unavailable.close();
+        // The roster marks its leader-role node unhealthy on a dead port, so a
+        // redirect would fail the dial instead of passing unnoticed.
+        const server = await startVsrServer((frame, socket) => {
+            const operation = frame.readUInt8(REQUEST_OFFSET.operation);
+            if (operation === Operation.Register) {
+                socket.write(replyFrame(Operation.Register, registerReplyBody()));
+                return;
+            }
+            socket.write(replyFrame(Operation.NonReplicated, twoNodeMetadataBody(server.port, unavailablePort, 0, 1)));
+        });
+        const client = new CommandResponseStream(vsrConfig(server.port));
+        compressLeaderlessPoll(client, 0);
+        try {
+            await client.authenticate(vsrConfig(server.port).credentials);
+            const operations = server.frames.map((frame) => frame.readUInt8(REQUEST_OFFSET.operation));
+            assert.deepEqual(operations, [
+                Operation.Register,
+                Operation.NonReplicated
+            ]);
+            assert.equal(client.isAuthenticated, true);
+        }
+        finally {
+            client.destroy();
+            await server.close();
+        }
+    });
     it('rejects instead of hanging while a connection attempt is unresolved', async () => {
         const server = await startVsrServer(() => { });
         const port = server.port;
@@ -502,19 +672,6 @@ describe('VSR client socket', () => {
             await server.close();
         }
     });
-    it('rejects a cluster without a healthy leader', async () => {
-        const server = await startVsrServer((frame, socket) => {
-            socket.write(replyFrame(frame.readUInt8(REQUEST_OFFSET.operation), twoNodeMetadataBody(server.port, server.port, 1)));
-        });
-        const client = new CommandResponseStream(vsrConfig(server.port));
-        try {
-            await assert.rejects(() => client.sendCommand(60_010, Buffer.alloc(0)), /VSR cluster has no healthy leader/);
-        }
-        finally {
-            client.destroy();
-            await server.close();
-        }
-    });
     it('shares token authentication between concurrent callers', async () => {
         const server = await startVsrServer((frame, socket) => singleNodeHandler(server.port)(frame, socket));
         const client = new CommandResponseStream({

package/dist/client/client.type.d.ts

@@ -125,7 +125,12 @@ export type ClientConfig = {
     poolSize?: PoolSizeOption;
     /** Automatic reconnection configuration */
     reconnect?: ReconnectOption;
-    /** Interval for sending heartbeat pings in milliseconds */
+    /**
+     * Interval for sending heartbeat pings in milliseconds, as an integer
+     * between 0 and Node's timer ceiling. Defaults to 5000. Set to 0 to disable
+     * client heartbeats; any other unusable value is rejected rather than
+     * silently disabling them.
+     */
     heartbeatInterval?: number;
     /** Maximum accepted response frame size in bytes */
     maxResponseFrameSize?: number;

package/dist/debug.js

@@ -16,7 +16,7 @@
 // under the License.
 //
 import assert from 'node:assert/strict';
-import { Client } from './client/index.js';
+import { Client, DEFAULT_HEARTBEAT_INTERVAL } from './client/index.js';
 import { uuidv7, uuidv4 } from 'uuidv7';
 import { groupConsumerStream } from './stream/consumer-stream.js';
 import { PollingStrategy } from './wire/index.js';
@@ -41,7 +41,7 @@ const opt = {
         interval: 10 * 1000,
         maxRetries: 10
     },
-    heartbeatInterval: 5 * 1000
+    heartbeatInterval: DEFAULT_HEARTBEAT_INTERVAL
 };
 const c = new Client(opt);
 const cleanup = async () => {

package/dist/e2e/tcp.topic.e2e.js

@@ -29,8 +29,7 @@ describe('e2e -> topic', async () => {
             name: topicName,
             partitionCount: 0,
             compressionAlgorithm: 1,
-            messageExpiry: 0n,
-            replicationFactor: 1
+            messageExpiry: 0n
         });
         assert.ok(TOPIC);
     });

package/dist/e2e/tls.system.e2e.js

@@ -21,13 +21,11 @@
 // To run them locally:
 //
 //   1. Start the server with TLS:
-//      TODO(hubcio): change to iggy-server once legacy server is removed
-//      (core/server has VSR support)
 //        IGGY_ROOT_USERNAME=iggy IGGY_ROOT_PASSWORD=iggy \
 //        IGGY_TCP_TLS_ENABLED=true \
 //        IGGY_TCP_TLS_CERT_FILE=core/certs/iggy_cert.pem \
 //        IGGY_TCP_TLS_KEY_FILE=core/certs/iggy_key.pem \
-//        cargo r --bin iggy-server-ng --features vsr
+//        cargo r --bin iggy-server
 //
 //   2. Run the tests:
 //        cd foreign/node

package/dist/wire/command-set.d.ts

@@ -82,6 +82,7 @@ type MessageAPI = ReturnType<typeof messageAPI>;
 declare const systemAPI: (c: ClientProvider) => {
     ping: (arg: void) => Promise<boolean>;
     getStats: (arg: void) => Promise<import("./system/get-stats.command.js").Stats>;
+    describeOptions: (arg: import("./system/describe-options.command.js").DescribeOptions) => Promise<import("./system/describe-options.command.js").OptionSpec[]>;
 };
 type SystemAPI = ReturnType<typeof systemAPI>;
 declare const clusterAPI: (c: ClientProvider) => {