apache-iggy 0.9.0-edge.1 → 0.10.0-edge.2

package/README.md

@@ -32,18 +32,17 @@ npm i --save apache-iggy
 
 ### Response frame limit
 
-**Compatibility note:** response frames larger than `maxResponseFrameSize` (default 64 MiB) are now rejected and close the connection under both framing modes. This is a behavior change for existing classic-framing clients. Raise the limit in the client configuration when polling very large batches.
+**Compatibility note:** response frames larger than `maxResponseFrameSize` (default 64 MiB) are rejected and close the connection. Raise the limit in the client configuration when polling very large batches.
 
 ### VSR framing
 
-Classic framing remains the default. Select VSR explicitly when connecting to
-an Iggy VSR server:
+The SDK speaks the VSR wire protocol exclusively and requires an Iggy VSR
+server:
 
 ```typescript
 import { SimpleClient, getRawClient } from "apache-iggy";
 
 const config = {
-  protocol: "vsr" as const,
   transport: "TCP" as const,
   options: { host: "127.0.0.1", port: 8090 },
   credentials: { username: "iggy", password: "iggy" },
@@ -52,12 +51,18 @@ const client = new SimpleClient(getRawClient(config));
 const stats = await client.system.getStats();
 ```
 
-VSR is a runtime protocol choice in Node.js, not a build feature. Codes absent
-from the SDK command table use `Operation::NonReplicated` and carry the command
-code in the request header's reserved field. The server remains authoritative
-for classifying or rejecting extension commands.
+Codes absent from the SDK command table use `Operation::NonReplicated` and
+carry the command code in the request header's reserved field. The server
+remains authoritative for classifying or rejecting extension commands.
 
-The same npm package supports both framing modes over TCP and TLS. VSR restricts `Client` to one pooled connection because authentication, request sequencing, and consumer-group assignments belong to one consensus session. Configurations requesting more than one pooled connection fail before a socket is opened.
+Sends must use explicit `Partitioning.PartitionId` partitioning: the client
+routes each request to a partition-scoped namespace, so broker-side balancing
+(`Partitioning.Balanced`) and key hashing (`Partitioning.MessageKey`) are
+rejected before the request is sent.
+<!-- TODO(hubcio): Balanced and MessageKey partitioning to be implemented;
+not decided yet whether it'll be on server side or client side. -->
+
+VSR works over TCP and TLS. It restricts `Client` to one pooled connection because authentication, request sequencing, and consumer-group assignments belong to one consensus session. Configurations requesting more than one pooled connection fail before a socket is opened.
 
 VSR authentication translates the existing password and personal-access-token
 login APIs into the register handshake required by the consensus protocol. A
@@ -68,7 +73,7 @@ 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.
 
-`sendBinaryRequest(code, payload)` has the same signature under classic and VSR framing. 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. Classic request bytes remain unchanged.
+`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.
 
 ```typescript
 import { ResponseError } from "apache-iggy";

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

@@ -1,6 +1,4 @@
-import type { ClientConfig, Protocol } from './client.type.js';
+import type { ClientConfig } from './client.type.js';
 export declare const DEFAULT_MAX_RESPONSE_FRAME_SIZE: number;
-export declare const normalizeClientConfig: (config: ClientConfig) => ClientConfig & {
-    protocol: Protocol;
-};
+export declare const normalizeClientConfig: (config: ClientConfig) => ClientConfig;
 //# sourceMappingURL=client.config.d.ts.map

package/dist/client/client.config.js

@@ -15,24 +15,18 @@
 // specific language governing permissions and limitations
 // under the License.
 export const DEFAULT_MAX_RESPONSE_FRAME_SIZE = 64 * 1024 * 1024;
-const isProtocol = (value) => value === 'classic' || value === 'vsr';
 export const normalizeClientConfig = (config) => {
-    const protocol = config.protocol ?? 'classic';
-    if (!isProtocol(protocol))
-        throw new TypeError(`unsupported wire protocol: ${String(protocol)}`);
     const maxResponseFrameSize = config.maxResponseFrameSize ?? DEFAULT_MAX_RESPONSE_FRAME_SIZE;
     if (!Number.isSafeInteger(maxResponseFrameSize) ||
         maxResponseFrameSize < 256)
         throw new TypeError('maxResponseFrameSize must be a safe integer of at least 256 bytes');
-    if (protocol === 'vsr' &&
-        ((config.poolSize?.min ?? 1) > 1 || (config.poolSize?.max ?? 1) > 1))
+    if ((config.poolSize?.min ?? 1) > 1 || (config.poolSize?.max ?? 1) > 1)
         throw new TypeError('VSR clients currently support exactly one pooled connection');
     return {
         ...config,
-        protocol,
         options: { ...config.options },
         maxResponseFrameSize,
-        ...(protocol === 'vsr' ? { poolSize: { min: 1, max: 1 } } : {})
+        poolSize: { min: 1, max: 1 }
     };
 };
 //# sourceMappingURL=client.config.js.map

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

@@ -23,40 +23,23 @@ const config = () => ({
     credentials: { username: 'iggy', password: 'iggy' }
 });
 describe('normalizeClientConfig', () => {
-    it('defaults to classic without changing classic pool sizing', () => {
-        const normalized = normalizeClientConfig({
-            ...config(),
-            poolSize: { min: 2, max: 4 }
-        });
-        assert.equal(normalized.protocol, 'classic');
-        assert.deepEqual(normalized.poolSize, { min: 2, max: 4 });
+    it('applies the default response frame limit', () => {
+        const normalized = normalizeClientConfig(config());
         assert.equal(normalized.maxResponseFrameSize, DEFAULT_MAX_RESPONSE_FRAME_SIZE);
     });
-    it('restricts VSR to one pooled connection', () => {
-        const normalized = normalizeClientConfig({
-            ...config(),
-            protocol: 'vsr'
-        });
+    it('restricts the client to one pooled connection', () => {
+        const normalized = normalizeClientConfig(config());
         assert.deepEqual(normalized.poolSize, { min: 1, max: 1 });
         assert.throws(() => normalizeClientConfig({
             ...config(),
-            protocol: 'vsr',
             poolSize: { max: 2 }
         }), /exactly one pooled connection/);
     });
-    it('rejects invalid protocols before opening a socket', () => {
-        assert.throws(() => normalizeClientConfig({
-            ...config(),
-            protocol: 'auto'
-        }), /unsupported wire protocol/);
-    });
-    it('supports VSR over TLS', () => {
+    it('supports TLS transport', () => {
         const normalized = normalizeClientConfig({
             ...config(),
-            protocol: 'vsr',
             transport: 'TLS'
         });
-        assert.equal(normalized.protocol, 'vsr');
         assert.equal(normalized.transport, 'TLS');
         assert.deepEqual(normalized.poolSize, { min: 1, max: 1 });
     });

package/dist/client/client.connection.d.ts

@@ -79,14 +79,6 @@ export declare class IggyConnection extends EventEmitter {
      * @param data - Incoming data buffer
      */
     _onData(data: Buffer): void;
-    /**
-     * Writes a command to the socket.
-     *
-     * @param command - Command code
-     * @param payload - Command payload
-     * @returns True if the write was successful
-     */
-    writeCommand(command: number, payload: Buffer): void;
     writeFrame(frame: Buffer): void;
 }
 //# sourceMappingURL=client.connection.d.ts.map

package/dist/client/client.connection.js

@@ -18,7 +18,6 @@
 import { EventEmitter } from 'node:events';
 import { createConnection } from 'node:net';
 import { connect as TLSConnect } from 'node:tls';
-import { serializeCommand } from './client.utils.js';
 import { debug } from './client.debug.js';
 import { DEFAULT_MAX_RESPONSE_FRAME_SIZE } from './client.config.js';
 import { ProtocolFrameError, ResponseFrameDecoder } from './client.frame.js';
@@ -121,7 +120,7 @@ export class IggyConnection extends EventEmitter {
         this.reconnectCount = 0;
         this.connectPromise = undefined;
         this.reconnectPromise = undefined;
-        this.responseDecoder = new ResponseFrameDecoder(config.protocol ?? 'classic', config.maxResponseFrameSize ?? DEFAULT_MAX_RESPONSE_FRAME_SIZE);
+        this.responseDecoder = new ResponseFrameDecoder(config.maxResponseFrameSize ?? DEFAULT_MAX_RESPONSE_FRAME_SIZE);
         this.socket = this._installSocket(getTransport(config));
     }
     /**
@@ -361,8 +360,7 @@ export class IggyConnection extends EventEmitter {
         debug('ONDATA', typeof data, Buffer.isBuffer(data), data?.length, this.responseDecoder.hasBufferedData);
         try {
             for (const response of this.responseDecoder.push(data)) {
-                if (this.config.protocol === 'vsr' &&
-                    peekCommand(response) === Command2.Eviction)
+                if (peekCommand(response) === Command2.Eviction)
                     this.emit('eviction', evictionError(response));
                 else
                     this.emit('response', response);
@@ -374,17 +372,6 @@ export class IggyConnection extends EventEmitter {
             this.socket.destroy();
         }
     }
-    /**
-     * Writes a command to the socket.
-     *
-     * @param command - Command code
-     * @param payload - Command payload
-     * @returns True if the write was successful
-     */
-    writeCommand(command, payload) {
-        const cmd = serializeCommand(command, payload);
-        this.socket.write(cmd);
-    }
     writeFrame(frame) {
         this.socket.write(frame);
     }

package/dist/client/client.connection.test.js

@@ -21,6 +21,8 @@ import { createServer, } from 'node:net';
 import { describe, it } from 'node:test';
 import { ProtocolFrameError } from './client.frame.js';
 import { IggyConnection } from './client.connection.js';
+import { Command2, HEADER_SIZE, REPLY_OFFSET } from '../wire/vsr/header.js';
+const FRAME_LIMIT = 2 * HEADER_SIZE;
 const startServer = async () => {
     const server = createServer();
     server.listen(0, '127.0.0.1');
@@ -28,7 +30,6 @@ const startServer = async () => {
     return server;
 };
 const connectionConfig = (server) => ({
-    protocol: 'classic',
     transport: 'TCP',
     options: {
         host: '127.0.0.1',
@@ -36,8 +37,15 @@ const connectionConfig = (server) => ({
     },
     credentials: { username: 'iggy', password: 'iggy' },
     reconnect: { enabled: false, interval: 0, maxRetries: 0 },
-    maxResponseFrameSize: 256
+    maxResponseFrameSize: FRAME_LIMIT
 });
+const replyFrame = (body) => {
+    const frame = Buffer.alloc(HEADER_SIZE + body.length);
+    frame.writeUInt32LE(frame.length, REPLY_OFFSET.size);
+    frame.writeUInt8(Command2.Reply, REPLY_OFFSET.command);
+    body.copy(frame, HEADER_SIZE);
+    return frame;
+};
 const closeConnection = async (connection, server) => {
     connection._destroy();
     if (!connection.socket.destroyed)
@@ -59,7 +67,7 @@ describe('IggyConnection', () => {
             await closeConnection(connection, server);
         }
     });
-    it('shares connection attempts, recognizes endpoints, and writes commands', async () => {
+    it('shares connection attempts, recognizes endpoints, and writes frames', async () => {
         const server = await startServer();
         const received = new Promise((resolve) => {
             server.once('connection', (socket) => {
@@ -78,10 +86,9 @@ describe('IggyConnection', () => {
                 host: 'broker.example'
             };
             assert.equal(connection.isConnectedTo('broker.example', server.address().port), true);
-            connection.writeCommand(1, Buffer.from('payload'));
-            const command = await received;
-            assert.equal(command.readUInt32LE(4), 1);
-            assert.deepEqual(command.subarray(8), Buffer.from('payload'));
+            const frame = replyFrame(Buffer.from('payload'));
+            connection.writeFrame(frame);
+            assert.deepEqual(await received, frame);
         }
         finally {
             await closeConnection(connection, server);
@@ -92,16 +99,13 @@ describe('IggyConnection', () => {
         const connection = new IggyConnection(connectionConfig(server));
         try {
             await connection.connect();
-            const body = Buffer.from('response');
-            const frame = Buffer.alloc(8 + body.length);
-            frame.writeUInt32LE(body.length, 4);
-            body.copy(frame, 8);
+            const frame = replyFrame(Buffer.from('response'));
             const response = once(connection, 'response');
             connection._onData(frame.subarray(0, 6));
             connection._onData(frame.subarray(6));
             assert.deepEqual((await response)[0], frame);
-            const malformed = Buffer.alloc(8);
-            malformed.writeUInt32LE(256, 4);
+            const malformed = replyFrame(Buffer.alloc(0));
+            malformed.writeUInt32LE(FRAME_LIMIT + 1, REPLY_OFFSET.size);
             const error = once(connection, 'error');
             connection._onData(malformed);
             assert.ok((await error)[0] instanceof ProtocolFrameError);
@@ -178,10 +182,7 @@ describe('IggyConnection', () => {
             assert.equal(await first, connection);
             assert.equal(connection.connected, true);
             assert.equal(connections, 2);
-            const body = Buffer.from('fresh');
-            const frame = Buffer.alloc(8 + body.length);
-            frame.writeUInt32LE(body.length, 4);
-            body.copy(frame, 8);
+            const frame = replyFrame(Buffer.from('fresh'));
             const response = once(connection, 'response');
             oldSocket.emit('data', Buffer.alloc(8));
             connection._onData(frame);

package/dist/client/client.frame.d.ts

@@ -1,4 +1,3 @@
-import type { Protocol } from './client.type.js';
 export declare class ProtocolFrameError extends Error {
     constructor(message: string);
 }
@@ -6,21 +5,19 @@ export type ExtractedFrames = {
     frames: Buffer[];
     remainder: Buffer;
 };
-export declare const extractResponseFrames: (protocol: Protocol, buffer: Buffer, maximumFrameSize: number) => ExtractedFrames;
+export declare const extractResponseFrames: (buffer: Buffer, maximumFrameSize: number) => ExtractedFrames;
 /**
  * Incrementally extracts response frames without repeatedly copying an
  * incomplete frame as new socket chunks arrive.
  */
 export declare class ResponseFrameDecoder {
-    private readonly protocol;
     private readonly maximumFrameSize;
-    private readonly headerSize;
     private chunks;
     private chunkIndex;
     private chunkOffset;
     private bufferedLength;
     private expectedFrameSize?;
-    constructor(protocol: Protocol, maximumFrameSize: number);
+    constructor(maximumFrameSize: number);
     get hasBufferedData(): boolean;
     clear(): void;
     push(data: Buffer): Buffer[];

package/dist/client/client.frame.js

@@ -14,34 +14,28 @@
 // KIND, either express or implied.  See the License for the
 // specific language governing permissions and limitations
 // under the License.
-import { HEADER_SIZE as VSR_HEADER_SIZE, readSize as readVsrSize } from '../wire/vsr/header.js';
-const CLASSIC_HEADER_SIZE = 8;
+import { HEADER_SIZE, readSize } from '../wire/vsr/header.js';
 export class ProtocolFrameError extends Error {
     constructor(message) {
         super(message);
         this.name = 'ProtocolFrameError';
     }
 }
-const headerSizeFor = (protocol) => protocol === 'vsr' ? VSR_HEADER_SIZE : CLASSIC_HEADER_SIZE;
-const declaredFrameSize = (protocol, header, maximumFrameSize) => {
-    const headerSize = headerSizeFor(protocol);
-    const declaredSize = protocol === 'vsr'
-        ? readVsrSize(header)
-        : CLASSIC_HEADER_SIZE + header.readUInt32LE(4);
-    if (declaredSize < headerSize)
-        throw new ProtocolFrameError(`declared ${protocol} frame size ${declaredSize} is below header size`);
+const declaredFrameSize = (header, maximumFrameSize) => {
+    const declaredSize = readSize(header);
+    if (declaredSize < HEADER_SIZE)
+        throw new ProtocolFrameError(`declared frame size ${declaredSize} is below header size`);
     if (declaredSize > maximumFrameSize)
-        throw new ProtocolFrameError(`declared ${protocol} frame size ${declaredSize} exceeds ` +
+        throw new ProtocolFrameError(`declared frame size ${declaredSize} exceeds ` +
             `the ${maximumFrameSize} byte limit`);
     return declaredSize;
 };
-export const extractResponseFrames = (protocol, buffer, maximumFrameSize) => {
-    const headerSize = headerSizeFor(protocol);
+export const extractResponseFrames = (buffer, maximumFrameSize) => {
     const frames = [];
     let offset = 0;
-    while (buffer.length - offset >= headerSize) {
+    while (buffer.length - offset >= HEADER_SIZE) {
         const available = buffer.length - offset;
-        const declaredSize = declaredFrameSize(protocol, buffer.subarray(offset, offset + headerSize), maximumFrameSize);
+        const declaredSize = declaredFrameSize(buffer.subarray(offset, offset + HEADER_SIZE), maximumFrameSize);
         if (available < declaredSize)
             break;
         frames.push(buffer.subarray(offset, offset + declaredSize));
@@ -59,18 +53,14 @@ export const extractResponseFrames = (protocol, buffer, maximumFrameSize) => {
  * incomplete frame as new socket chunks arrive.
  */
 export class ResponseFrameDecoder {
-    protocol;
     maximumFrameSize;
-    headerSize;
     chunks;
     chunkIndex;
     chunkOffset;
     bufferedLength;
     expectedFrameSize;
-    constructor(protocol, maximumFrameSize) {
-        this.protocol = protocol;
+    constructor(maximumFrameSize) {
         this.maximumFrameSize = maximumFrameSize;
-        this.headerSize = headerSizeFor(protocol);
         this.chunks = [];
         this.chunkIndex = 0;
         this.chunkOffset = 0;
@@ -95,9 +85,9 @@ export class ResponseFrameDecoder {
         const frames = [];
         while (true) {
             if (this.expectedFrameSize === undefined) {
-                if (this.bufferedLength < this.headerSize)
+                if (this.bufferedLength < HEADER_SIZE)
                     break;
-                this.expectedFrameSize = declaredFrameSize(this.protocol, this.peek(this.headerSize), this.maximumFrameSize);
+                this.expectedFrameSize = declaredFrameSize(this.peek(HEADER_SIZE), this.maximumFrameSize);
             }
             if (this.bufferedLength < this.expectedFrameSize)
                 break;

package/dist/client/client.frame.test.js

@@ -19,12 +19,6 @@ import { describe, it } from 'node:test';
 import { extractResponseFrames, ProtocolFrameError, ResponseFrameDecoder } from './client.frame.js';
 import { Command2, HEADER_SIZE, REPLY_OFFSET } from '../wire/vsr/header.js';
 const LIMIT = 1024;
-const classicFrame = (body) => {
-    const frame = Buffer.alloc(8 + body.length);
-    frame.writeUInt32LE(body.length, 4);
-    body.copy(frame, 8);
-    return frame;
-};
 const vsrFrame = (body) => {
     const frame = Buffer.alloc(HEADER_SIZE + body.length);
     frame.writeUInt32LE(frame.length, REPLY_OFFSET.size);
@@ -33,59 +27,50 @@ const vsrFrame = (body) => {
     return frame;
 };
 describe('extractResponseFrames', () => {
-    for (const protocol of ['classic', 'vsr']) {
-        const makeFrame = protocol === 'classic' ? classicFrame : vsrFrame;
-        it(`buffers ${protocol} headers split at every boundary`, () => {
-            const frame = makeFrame(Buffer.from('payload'));
-            const headerSize = protocol === 'classic' ? 8 : HEADER_SIZE;
-            for (let split = 0; split < headerSize; split += 1) {
-                const first = extractResponseFrames(protocol, frame.subarray(0, split), LIMIT);
-                assert.equal(first.frames.length, 0);
-                const second = extractResponseFrames(protocol, Buffer.concat([first.remainder, frame.subarray(split)]), LIMIT);
-                assert.deepEqual(second.frames, [frame]);
-                assert.equal(second.remainder.length, 0);
-            }
-        });
-        it(`buffers a fragmented ${protocol} body`, () => {
-            const frame = makeFrame(Buffer.from('payload'));
-            const split = frame.length - 2;
-            const first = extractResponseFrames(protocol, frame.subarray(0, split), LIMIT);
+    it('buffers headers split at every boundary', () => {
+        const frame = vsrFrame(Buffer.from('payload'));
+        for (let split = 0; split < HEADER_SIZE; split += 1) {
+            const first = extractResponseFrames(frame.subarray(0, split), LIMIT);
             assert.equal(first.frames.length, 0);
-            const second = extractResponseFrames(protocol, Buffer.concat([first.remainder, frame.subarray(split)]), LIMIT);
+            const second = extractResponseFrames(Buffer.concat([first.remainder, frame.subarray(split)]), LIMIT);
             assert.deepEqual(second.frames, [frame]);
-        });
-        it(`extracts coalesced ${protocol} frames and a partial tail`, () => {
-            const first = makeFrame(Buffer.from('one'));
-            const second = makeFrame(Buffer.from('two'));
-            const third = makeFrame(Buffer.from('three'));
-            const input = Buffer.concat([first, second, third.subarray(0, 3)]);
-            const extracted = extractResponseFrames(protocol, input, LIMIT);
-            assert.deepEqual(extracted.frames, [first, second]);
-            assert.deepEqual(extracted.remainder, third.subarray(0, 3));
-            assert.equal(extracted.remainder.buffer, input.buffer);
-        });
-    }
-    it('rejects a VSR size below the header', () => {
+            assert.equal(second.remainder.length, 0);
+        }
+    });
+    it('buffers a fragmented body', () => {
+        const frame = vsrFrame(Buffer.from('payload'));
+        const split = frame.length - 2;
+        const first = extractResponseFrames(frame.subarray(0, split), LIMIT);
+        assert.equal(first.frames.length, 0);
+        const second = extractResponseFrames(Buffer.concat([first.remainder, frame.subarray(split)]), LIMIT);
+        assert.deepEqual(second.frames, [frame]);
+    });
+    it('extracts coalesced frames and a partial tail', () => {
+        const first = vsrFrame(Buffer.from('one'));
+        const second = vsrFrame(Buffer.from('two'));
+        const third = vsrFrame(Buffer.from('three'));
+        const input = Buffer.concat([first, second, third.subarray(0, 3)]);
+        const extracted = extractResponseFrames(input, LIMIT);
+        assert.deepEqual(extracted.frames, [first, second]);
+        assert.deepEqual(extracted.remainder, third.subarray(0, 3));
+        assert.equal(extracted.remainder.buffer, input.buffer);
+    });
+    it('rejects a size below the header', () => {
         const frame = vsrFrame(Buffer.alloc(0));
         frame.writeUInt32LE(0, REPLY_OFFSET.size);
-        assert.throws(() => extractResponseFrames('vsr', frame, LIMIT), ProtocolFrameError);
+        assert.throws(() => extractResponseFrames(frame, LIMIT), ProtocolFrameError);
     });
-    it('rejects an oversized VSR frame before buffering its body', () => {
+    it('rejects an oversized frame before buffering its body', () => {
         const header = vsrFrame(Buffer.alloc(0));
         header.writeUInt32LE(LIMIT + 1, REPLY_OFFSET.size);
-        assert.throws(() => extractResponseFrames('vsr', header, LIMIT), ProtocolFrameError);
-    });
-    it('rejects an oversized classic frame before buffering its body', () => {
-        const header = classicFrame(Buffer.alloc(0));
-        header.writeUInt32LE(LIMIT, 4);
-        assert.throws(() => extractResponseFrames('classic', header, LIMIT), ProtocolFrameError);
+        assert.throws(() => extractResponseFrames(header, LIMIT), ProtocolFrameError);
     });
 });
 describe('ResponseFrameDecoder', () => {
     it('decodes bytewise input without losing coalesced frames', () => {
-        const decoder = new ResponseFrameDecoder('classic', LIMIT);
-        const first = classicFrame(Buffer.from('first'));
-        const second = classicFrame(Buffer.from('second'));
+        const decoder = new ResponseFrameDecoder(LIMIT);
+        const first = vsrFrame(Buffer.from('first'));
+        const second = vsrFrame(Buffer.from('second'));
         const input = Buffer.concat([first, second]);
         const frames = [];
         for (const byte of input)
@@ -94,16 +79,16 @@ describe('ResponseFrameDecoder', () => {
         assert.equal(decoder.hasBufferedData, false);
     });
     it('clears a partial frame', () => {
-        const decoder = new ResponseFrameDecoder('vsr', LIMIT);
-        decoder.push(vsrFrame(Buffer.from('body')).subarray(0, 100));
+        const decoder = new ResponseFrameDecoder(LIMIT);
+        decoder.push(vsrFrame(Buffer.from('body')).subarray(0, HEADER_SIZE - 2));
         assert.equal(decoder.hasBufferedData, true);
         decoder.clear();
         assert.equal(decoder.hasBufferedData, false);
     });
     it('rejects an oversized frame as soon as its header is complete', () => {
-        const decoder = new ResponseFrameDecoder('classic', LIMIT);
-        const header = Buffer.alloc(8);
-        header.writeUInt32LE(LIMIT, 4);
+        const decoder = new ResponseFrameDecoder(LIMIT);
+        const header = vsrFrame(Buffer.alloc(0));
+        header.writeUInt32LE(LIMIT + 1, REPLY_OFFSET.size);
         assert.throws(() => decoder.push(header), ProtocolFrameError);
     });
 });

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

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import type { ClientConfig, ClientCredentials, CommandResponse, PasswordCredentials, Protocol, RawClient, SendCommandOptions, TokenCredentials } from '../client/client.type.js';
+import type { ClientConfig, ClientCredentials, CommandResponse, PasswordCredentials, RawClient, SendCommandOptions, TokenCredentials } from '../client/client.type.js';
 export declare class VsrResponseTimeoutError extends Error {
     constructor(timeout: number);
 }
@@ -8,8 +8,6 @@ export declare class VsrResponseTimeoutError extends Error {
  * Implements command queuing, authentication, and heartbeat functionality.
  */
 export declare class CommandResponseStream extends EventEmitter {
-    /** Server wire protocol used by this connection */
-    readonly protocol: Protocol;
     /** Client configuration */
     private options;
     /** Underlying connection to the server */
@@ -20,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 */
@@ -44,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
@@ -69,11 +73,31 @@ export declare class CommandResponseStream extends EventEmitter {
      */
     _processNext(command: number, payload: Buffer, handleResp?: boolean): Promise<CommandResponse>;
     private _processVsrLogin;
-    private _processClassic;
     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.
      *