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

package/LICENSE

@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

package/README.md

@@ -30,6 +30,66 @@ npm i --save apache-iggy
 
 ## basic usage
 
+### 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.
+
+### VSR framing
+
+Classic framing remains the default. Select VSR explicitly when connecting to
+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" },
+};
+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.
+
+The same npm package supports both framing modes. VSR currently supports TCP
+only and restricts `Client` to one pooled connection because authentication,
+request sequencing, and consumer-group assignments belong to one consensus
+session. Configurations requesting VSR over TLS or 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
+disconnect or eviction invalidates the session, and later work must register a
+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.
+
+`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.
+
+```typescript
+import { ResponseError } from "apache-iggy";
+
+try {
+  await client.sendBinaryRequest(60_000, Buffer.from("opaque request"));
+} catch (error) {
+  if (error instanceof ResponseError) {
+    console.error(error.commandCode, error.errorCode);
+  }
+}
+```
+
+The client includes its npm package version and the binary protocol crate
+version in VSR registration. An incompatible server rejects registration with
+a protocol-version error instead of accepting a mismatched wire contract.
+
 ```ts
 import { Client } from "apache-iggy";
 
@@ -60,7 +120,8 @@ npm run build
 
 ### test
 
-note: use env var `IGGY_TCP_ADDRESS="host:port"` to set server address for bdd and e2e tests.
+note: use env var `IGGY_TCP_ADDRESS="host:port"` to set the server
+address for bdd and e2e tests.
 
 #### unit tests
 

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

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

package/dist/client/client.config.js

@@ -0,0 +1,40 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// 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.transport === 'TLS')
+        throw new TypeError('VSR framing currently supports the TCP transport only');
+    if (protocol === 'vsr' &&
+        ((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 } } : {})
+    };
+};
+//# sourceMappingURL=client.config.js.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.config.test.d.ts.map

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

@@ -0,0 +1,68 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// 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';
+const config = () => ({
+    transport: 'TCP',
+    options: { host: '127.0.0.1', port: 8090 },
+    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 });
+        assert.equal(normalized.maxResponseFrameSize, DEFAULT_MAX_RESPONSE_FRAME_SIZE);
+    });
+    it('restricts VSR to one pooled connection', () => {
+        const normalized = normalizeClientConfig({
+            ...config(),
+            protocol: 'vsr'
+        });
+        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('rejects VSR over an untested TLS transport', () => {
+        assert.throws(() => normalizeClientConfig({
+            ...config(),
+            protocol: 'vsr',
+            transport: 'TLS'
+        }), /TCP transport only/);
+    });
+    it('rejects unsafe response frame limits', () => {
+        for (const maxResponseFrameSize of [0, 255, 1.5, Number.MAX_VALUE])
+            assert.throws(() => normalizeClientConfig({
+                ...config(),
+                maxResponseFrameSize
+            }), /maxResponseFrameSize/);
+    });
+});
+//# sourceMappingURL=client.config.test.js.map

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

@@ -1,21 +1,3 @@
-/**
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements.  See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership.  The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License.  You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied.  See the License for the
- * specific language governing permissions and limitations
- * under the License.
- */
 import { EventEmitter } from 'node:events';
 import type { Socket } from 'node:net';
 import type { ClientConfig } from "./client.type.js";
@@ -34,34 +16,54 @@ export declare class IggyConnection extends EventEmitter {
     connecting: boolean;
     /** Whether the connection is being intentionally closed */
     ending: boolean;
-    /** Whether waiting for more data to complete a response */
-    private waitingResponseEnd;
     /** Reconnection configuration */
     private reconnectOption;
     /** Number of reconnection attempts made */
     private reconnectCount;
-    /** Buffer for incomplete response data */
-    private readBuffers;
+    /** Shared promise for concurrent callers waiting on one connection attempt */
+    private connectPromise?;
+    /** Shared promise for callers waiting on automatic reconnection */
+    private reconnectPromise?;
+    /** Endpoint the client was configured with, kept across leader redirects */
+    private readonly seedOptions;
+    /** Incremental response frame decoder */
+    private responseDecoder;
     /**
      * Creates a new IggyConnection.
      *
      * @param config - Client configuration
      */
     constructor(config: ClientConfig);
+    /**
+     * Attaches the lifecycle listeners exactly once per socket instance.
+     * Attaching them in `connect()` would stack duplicate handlers whenever a
+     * failed attempt is retried on the same socket.
+     */
+    private _installSocket;
     /**
      * Establishes the connection to the server.
-     * Sets up event handlers for data, errors, and disconnection.
      *
      * @returns Promise that resolves when connected
      */
-    connect(): Promise<unknown>;
+    connect(): Promise<this>;
+    private _waitForConnection;
     /**
      * Attempts to reconnect to the server.
      * Respects maxRetries limit and emits error when exceeded.
      *
      * @param err - Optional error that triggered the reconnection
      */
-    reconnect(err?: Error): Promise<boolean | undefined>;
+    reconnect(err?: Error): Promise<this | undefined>;
+    private _reconnectUntilConnected;
+    /**
+     * Alternates reconnect dials between the current endpoint and the
+     * configured seed. After a leader redirect the current endpoint may die
+     * with the leader, and the seed is the way back to the rest of the cluster.
+     */
+    private _reconnectTarget;
+    redirect(host: string, port: number): Promise<void>;
+    abort(): void;
+    isConnectedTo(host: string, port: number): boolean;
     /**
      * Destroys the connection and marks it as ending.
      */
@@ -84,6 +86,7 @@ export declare class IggyConnection extends EventEmitter {
      * @param payload - Command payload
      * @returns True if the write was successful
      */
-    writeCommand(command: number, payload: Buffer): boolean;
+    writeCommand(command: number, payload: Buffer): void;
+    writeFrame(frame: Buffer): void;
 }
 //# sourceMappingURL=client.connection.d.ts.map