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

package/README.md

@@ -22,7 +22,7 @@ note: previous works on node.js http client has been moved to [iggy-node-http-cl
 npm i --save apache-iggy@edge
 ```
 
-Use the `edge` package with server 0.9.0 or `edge`. Stable Node SDK 0.8.0 uses the older wire protocol. For a local server with the example credentials, follow the [example setup](../../examples/node/README.md#running-examples).
+Use matching SDK and server builds from the coordinated VSR release. Older builds are incompatible. This release requires fresh server storage (`IGGY-METADATA-CHANGE-LOG-1`). Existing incompatible data is refused unchanged. For a local server with the example credentials, follow the [example setup](../../examples/node/README.md#running-examples).
 
 ## basic usage
 
@@ -51,29 +51,203 @@ 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.
 
-Sends encode `Partitioning.PartitionId`, `Partitioning.Balanced` or
-`Partitioning.MessageKey` in the payload. The server resolves the target
-partition at admission.
-
-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
-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.
+Sends always carry an explicit partition id. The client resolves
+`Partitioning.Balanced` round-robin and `Partitioning.MessageKey` as XXH32
+(seed 0) of the key modulo the topic's partition count, as the Rust SDK does.
+The count is cached per topic. The client reads it again after a refused send,
+and after the client deletes a stream or a topic or creates or deletes
+partitions. A raw `SendMessages` command without an explicit partition id
+fails with error code 5 before the client sends it.
+
+Partition commands carry a context containing the partition incarnation, owner
+generation and metadata operation. Pass the context of an earlier poll reply to
+keep an offset write or continuation tied to that history. Otherwise the client
+captures the route context. Non-admission retries and uncertain-operation replay
+preserve the first captured context, request identity and payload. Route refreshes
+change the destination. Lifecycle error 88 retries with a fresh ID and the same
+context. A send without caller-supplied context can refresh history once after
+error 87; explicit contexts return that error. A new call can capture newer
+metadata progress.
+
+Route discovery uses command 105. Sends, polls and offset reads/writes use the
+partition primary; other commands use the metadata primary. One logical client
+owns a shared session, a monotonic request counter and one multiplexed link per
+replica. Healthy links survive primary changes. Each link dials the address
+that its node advertises in the cluster roster. With a one-node roster, the
+link dials the configured endpoint instead. A single node behind a port
+mapping or a port-forward thus stays reachable. The legacy `poolSize` option
+accepts only one logical client; it does not limit replica links or concurrency.
+The public `Client._pool` property has been removed. Applications should use the
+client methods directly; the client owns its replica connections.
+
+A backup replica can miss a stream, topic or partition that the metadata primary
+already created. When such a replica replies "not found" (error 1009, 1010,
+2010, 2011 or 3007) to a route lookup or a partition command, the call looks up
+the route again and retries. If the deadline ends the call first, it fails with
+error 58. Only a "not found" reply from the metadata primary is final. A leader
+change can make the client's view of the metadata primary out of date. If the
+client believes that the replica that replied is the metadata primary, it reads
+the cluster roster from that replica. If the client has no link to the metadata
+primary, it also reads that roster. If that roster names this replica as the
+metadata primary, the reply is final.
+
+VSR authentication translates password and personal-access-token login into the
+Register handshake. Replacement links bind the existing session. Confirmed
+session expiry requires a new Register; an uncertain mutation is never replayed
+under that new session. An eviction that ends the session does not prove the
+outcome of a mutation that the client already wrote. That call ends with
+`OperationUncertainError`. A stale client eviction drops only its link, because
+the server keeps the session. The client binds the same session on a new link,
+as after any lost link, so retained operations and group membership stay.
+Explicit relogin logs out the previous session first.
+
+The client signs in by itself as the last sign-in of the caller, or with the
+configured `credentials` while the caller never signed in. After a logout, or
+after the server refuses those credentials, it does not sign in by itself, and
+a call fails with status 40 until the caller signs in again. A sign-in or
+logout of the caller ends each earlier call that has to wait for a new session:
+with status 40 if it sent nothing, or with `OperationUncertainError` if its
+outcome is unknown. An auto-commit or Next poll, which has no operation ID, ends with status 57 instead. A typed send and a group poll can send more than one
+command. If the caller signs in or logs out before the next command of such a
+call, the call fails with status 40. Only a call that waits for the client's own sign-in goes on
+under the new session. If the server refuses that sign-in, the call fails with
+status 40, and its `cause` holds the refusal. A call whose deadline ends while
+it waits for a session fails with status 58. So does a call that replicas refuse with 89 until its deadline.
+
+A reply with status 30 (`StaleClient`) says that the server no longer attaches
+the link to the session. This happens, for example, after the user was deleted
+or deactivated. A 30 refusal before commit fails a first attempt with that
+error. After an earlier written attempt, it does not prove the outcome, so that
+call ends with `OperationUncertainError`. The client closes that link and binds
+the session on a new link, as after any lost link. A replica that replaced its
+client table refuses a live session the same way, so the bind decides. A live
+session stays, with its retained operations and group membership. An ended
+session refuses the bind, and the client signs in again.
+
+A committed 30 comes from the replicated session table, so that session ended.
+It is a proved outcome, like any other committed rejection, and the client
+drops the session at once and signs in again.
+
+### Mutation recovery and limits
+
+Receipt access follows the server's [session and revocation policy](../../core/server/README.md#sessions-and-retry-receipts).
+An unresolved operation cannot recover its receipt after its original session
+ends, even after a new login or account reactivation. A fresh send can duplicate
+that operation.
+
+Each node counts the messages in its stream, topic and system stats. After a
+successful send, a node that is not the partition primary shows the new count
+only after the next prepare or commit broadcast. When no other write follows,
+this delay is at most `cluster.commit_broadcast_interval` (500 ms by default).
+See [metadata freshness and counters](../../core/server/README.md#metadata-freshness-and-counters).
+
+Mutations share one FIFO lane per partition history, with a separate metadata
+lane. An uncertain mutation remains retained and blocks later mutations in its
+lane. `OperationUncertainError.operationId` and `LaneBlockedError.operationId`
+are exact `bigint` values. Use `resolveOperation(operationId, { deadline })` to
+replay the retained frame, where `deadline` is an absolute `Date.now()` timestamp
+in milliseconds. The default operation budget is 30 seconds, including admission,
+routing, link waits and retries.
+
+Resolution requires correlated committed-result proof. A proved business
+rejection returns the original error and releases the lane. An unproved denial
+keeps an uncertain operation retained. The client keeps the proved outcomes of
+its last `maxPendingOperations` replays, also across a session reset. If a
+resolver already proved the outcome, a later `resolveOperation` of the same ID
+returns it without a request. A `resolveOperation` call that waits for another
+replay of the same ID and reaches its deadline fails with
+`OperationUncertainError`.
+
+`abandonOperation(operationId)` releases the client lane without proving that
+the mutation failed. A replay that is already running keeps the lane until it
+ends, and the client keeps the outcome that it proves. Logout, session reset and
+destruction discard retained operations with their outcomes still unknown.
+`OperationNotRetainedError` does not establish the outcome: a reset or an
+abandon came before a proved outcome, or the proved outcome aged out.
+
+**Breaking change:** `Client.destroy()` aborts in-flight calls immediately and
+discards retained operations. It does not wait for outstanding calls to finish.
+Await those calls before destroying the client when their results are needed.
+
+Auto-commit and Next polls hold their partition lane only during the active call.
+Error 57, a lost reply or another unknown outcome ends the call immediately with status 57 and no
+retained operation ID. These polls never replay after uncertainty. Known
+non-admission errors 58/89 remain retryable; pure reads may retry lost replies.
+Before uncertainty, lifecycle error 88 retries with a fresh ID within the same
+deadline. After uncertainty, only committed-result proof can release the lane.
+
+Configure `maxPendingOperations` (default 256) and `maxPendingOperationBytes`
+(default 64 MiB) on the client. Admission waits before allocating an ID or freezing
+a mutation frame. Both limits must be positive. The byte budget includes the
+256-byte header and body; smaller positive budgets reject mutations that cannot
+fit while reads and login remain available. Oversized frames fail locally.
+Completion, abandonment and reset release the operation slot. Writer aliases keep bytes charged until they release
+the frame. These limits cover admitted active/retained frames, not caller buffers,
+queued API input snapshots, or read/control bodies. `sendBinaryRequest` preserves
+its immediate payload snapshot before awaiting a custom provider.
+
+An explicit sign-in uses its caller's credentials and supersedes automatic or
+queued sign-ins. A failed explicit attempt, including invalid input, timeout or
+cancellation, withdraws credentials from automatic sign-in until another explicit
+sign-in succeeds. This also discards a session whose Register succeeded when a
+later step of the explicit sign-in fails. Earlier calls keep their original
+lineage; only SDK recovery continues them under a replacement session.
+
+An established session has its own lifetime. Password or PAT changes and PAT
+expiry do not end it. Logout, session lease expiry, or user deactivation end the
+session and prevent its bind proof from restoring it.
 
 The client pings every `heartbeatInterval` milliseconds, 5000 by default, which
 keeps an idle session alive when the server's `[heartbeat]` eviction is enabled.
 `heartbeatInterval` also accepts a duration expression such as `"10s"` or
 `"1h 30m"`, like the Rust SDK.
-With the default heartbeat settings, a group member becomes eligible for
-eviction after 36 s of silence (1.2 x the 30 s interval); the verifier checks
-once per 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.
+With the default heartbeat settings, a client that sends nothing for 36 s
+(1.2 x the 30 s interval) stops renewing its session, and the server ends the
+session about 36 s later. The verifier checks once per interval and also evicts
+the connection of a consumer-group member that is silent past 36 s. If the
+client interval exceeds 36 s, the verifier evicts an idle group member. If it
+exceeds about 72 s, or is 0 to disable client heartbeats, any idle session
+expires. Any other unusable value is rejected instead of silently disabling the
+heartbeat.
+
+A replica link redials on its own after it drops, with jittered exponential
+backoff. `reconnect.maxRetries` limits one burst of redials, not the life of
+the client. While the client stays signed in, each heartbeat restarts a link
+that used its budget, with a fresh budget. A request does not redial a link. It
+retries within its deadline until the link returns. If the deadline ends before
+the request was sent and no replica refused it, it fails with status 58.
+`destroy()` and logout stop the restarts.
+
+When every link used its budget, a request fails with `NotConnectedError` and
+does not wait for its deadline. When no endpoint accepts a dial before its retry
+budget or its deadline ends, a sign-in also fails with `NotConnectedError`, and
+its `cause` holds the last dial error. In both cases a later call can succeed,
+because the heartbeat restarts the links and each sign-in dials again. If
+reconnection or heartbeats are disabled, nothing restarts a link that used its
+budget, so the request fails with a plain `Error` instead.
+
+When a poll fails with status 30, 40, 57, 58 or 89, `singleConsumerStream` and
+`groupConsumerStream` poll again after `interval`. They also poll again after a
+poll deadline, after a poll with unknown progress, after `NotConnectedError` and
+after `ConnectionClosedError`. That error reports a lost connected socket. The
+client binds the session again, signs in again,
+reconnects or routes again after these on its own. Any other error ends the
+stream. The server can also refuse a sign-in with status 40, for example for an
+inactive user. So after a 40 the stream waits for the next sign-in, and a
+refused sign-in ends the stream. If the reply of an auto-commit poll is lost,
+the stream can skip that batch.
+
+`singleConsumerStream` and `groupConsumerStream` sign in before they return the
+stream, and `groupConsumerStream` also joins its group. If the sign-in or the
+join fails, the call destroys its client and rejects with that error. If no
+endpoint accepts a dial before the retry budget or the 30 second sign-in
+deadline ends, the error is `NotConnectedError`. When a stream closes, it
+destroys its client. A group stream that is still signed in first leaves its
+group, so that the server gives its partitions to the other members at once. If
+the leave fails or takes more than 5 seconds, the membership ends when the
+session lease expires. If the client of a destroyed stream has no session, or
+loses it, the stream destroys the client at once. It does not wait for a poll
+or a sign-in that still runs.
 
 `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.
 
@@ -89,7 +263,7 @@ try {
 }
 ```
 
-The client includes its npm package version and the binary protocol crate
+The client includes its npm package version and the binary wire protocol
 version in VSR registration. An incompatible server rejects registration with
 a protocol-version error instead of accepting a mismatched wire contract.
 
@@ -122,7 +296,8 @@ const stats = await client.system.getStats();
 Supported schemes are `iggy://` (TCP, default) and `iggy+tcp://`. Credentials
 are `username:password` or a single personal access token. Options mirror the
 other SDKs: `tls`, `tls_domain`, `tls_ca_file`, `reconnection_retries`,
-`reconnection_interval`, `heartbeat_interval` and `nodelay`. `reestablish_after`
+`reconnection_interval`, `heartbeat_interval`, `nodelay`, `max_pending_operations`
+and `max_pending_operation_bytes`. `reestablish_after`
 is accepted for format compatibility but has no Node equivalent.
 
 note: `SimpleClient` does not accept a connection string: it wraps an existing
@@ -144,14 +319,120 @@ Durations accept the same expressions as the Rust SDK, for example `500ms`,
 `0`, `unlimited`, `disabled` and `none` map to zero. Unit-less numbers such as
 `5` are rejected.
 
+### resource options
+
+A stream can carry its own data encryption key. Build it with `StreamEncryptionKey.from` from exactly 32 random bytes, or from their canonical padded base64, and pass it to `stream.create` as `encryptionKey`. Never derive the key from a password, because its fingerprint is readable by anyone who can read the stream. A key that is not 32 bytes or canonical base64 is refused with error 70 before anything is sent.
+
+A `StreamEncryptionKey` keeps its own copy of the bytes and prints only its fingerprint through `util.inspect`, `JSON.stringify` and string conversion, so create arguments carrying it can be logged. Entries passed through `options` print as given, so an `encryption_key` entry there is refused with error 70 before anything is sent.
+
+The key travels inside the create request over whatever transport the client uses, so connect over TLS when the key must stay confidential. The server stores the key wrapped and never returns it: reads report only `encryptionKeySource`, `encryptionKeyFingerprint` and `encryptionKekFingerprints`. Without a key, a server with encryption enabled generates one for the stream and reports the source `server`.
+
+```ts
+import { randomBytes } from "node:crypto";
+import { Client, StreamEncryptionKey } from "apache-iggy";
+
+const client = new Client({
+  transport: "TLS",
+  options: { host: "localhost", port: 8090 },
+  credentials: { username: "iggy", password: "iggy" },
+});
+
+const key = StreamEncryptionKey.from(randomBytes(32));
+const stream = await client.stream.create({ name: "orders", encryptionKey: key });
+console.log(stream.encryptionKeySource); // "stream"
+console.log(stream.encryptionKeyFingerprint === key.fingerprint()); // true
+```
+
+`stream.update`, `topic.update` and `user.update` change only the keys they name and leave every other setting as it is, so an update without `name` keeps the name. `reset` returns a key to the server default. Use the `StreamOptionKey`, `TopicOptionKey` and `UserOptionKey` constants to name keys.
+
+Only the topic keys `message_expiry` and `max_topic_size` can be reset. Settings fixed at create, such as the topic compression algorithm, the partition resize policy or the stream key, have no update field.
+
+The SDK checks the typed fields and `reset` before sending, in the server's order and with its error codes (4041 for an unknown key, 4105 for a read-only key, 4103 for a create-only key, 4104 for a key without a default, then the name, username or status error). For a key this build has no field or constant for, pass `options` entries and `rawReset` names. The SDK sends those as they are and the server decides, so a refusal comes back from the server.
+
+The server returns 4108 when a non-root caller tries to rename root or change root's status, or when root tries to deactivate itself.
+
+```ts
+await client.topic.update({
+  streamId: "orders",
+  topicId: "events",
+  messageExpiry: 7_200_000_000n,
+  reset: ["max_topic_size"],
+});
+```
+
+Reads return every setting in `options` (keys the client set) and `derivedOptions` (keys the server filled). `u64` values stay `bigint`, so values above 2^53 keep their precision. `system.describeOptions({ scope: OptionsScope.Stream })` lists the keys a server accepts per scope, with `updatable`, `resettable`, `secret`, `readOnly` and `critical`.
+
+### metadata changes
+
+`system.getMetadataChanges` reads the node's change log: one record per public result of a committed metadata operation, such as a stream created, a topic renamed, a user's permissions changed or a session closed. A mirror keeps a cursor, asks for the records after it, and stores the returned `next` cursor. The call needs root or the global `manage_servers` permission.
+
+```ts
+import { setTimeout as sleep } from "node:timers/promises";
+import {
+  Client, MetadataChangeStart, MetadataChangeStatus,
+  type MetadataChangeGroup, type MetadataCurrentPageToken,
+} from "apache-iggy";
+
+const follow = async (client: Client, groups: MetadataChangeGroup[]) => {
+  let start: MetadataChangeStart = MetadataChangeStart.Earliest;
+  for (;;) {
+    const page = await client.system.getMetadataChanges({ start, groups });
+    switch (page.status) {
+      case MetadataChangeStatus.Ok:
+        for (const record of page.records)
+          console.log(record.op, record.kind, record.actorUserId, record.body);
+        if (page.next) start = MetadataChangeStart.After(page.next);
+        if (!page.hasMore) await sleep(1000);
+        break;
+      case MetadataChangeStatus.Behind:
+        await sleep(100);
+        break;
+      default:
+        start = await rebuild(client, groups);
+    }
+  }
+};
+
+/** Pages the current state, then returns the position to follow from. */
+const rebuild = async (client: Client, groups: MetadataChangeGroup[]) => {
+  let pageToken: MetadataCurrentPageToken | undefined;
+  for (;;) {
+    const page = await client.system.getMetadataChanges({
+      start: MetadataChangeStart.Current(pageToken), groups,
+    });
+    if (page.status === MetadataChangeStatus.Behind) {
+      await sleep(100);
+      continue;
+    }
+    if (page.status !== MetadataChangeStatus.Ok) {
+      pageToken = undefined;
+      continue;
+    }
+    for (const item of page.items)
+      console.log(item.group, item.body);
+    if (page.currentPageToken) pageToken = page.currentPageToken;
+    else if (page.next) return MetadataChangeStart.After(page.next);
+    else pageToken = undefined;
+  }
+};
+```
+
+`expired` means the log no longer holds the history after the cursor, and `reset` means the cursor belongs to another history, for example after the data directory was rebuilt. Either way the mirror rebuilds from current state pages and then follows the changes after the anchor they return.
+
+Current pages need the parent groups of every selected group, for example `topics` with `streams`. Keep a rebuilt state private until a change page answers `ok` with `hasMore` false and a `headOp` at or above the last current page's.
+
+Records narrow by `kind` and items by `group`, so `record.kind === "stream_created"` types `record.body` as a stream. A group or kind newer than this build arrives as `"unknown"` with the raw body and the wire codes in `groupCode` and `kindCode`, while a record of a newer kind keeps its known `group`, so a mirror that cannot apply it can stop without advancing its cursor. Ops, timestamps and 128-bit ids are `bigint`.
+
+A query that breaks the request rules, such as a limit outside 1 to 1000 or a time bound with a latest or current start, is refused with error 3 before anything is sent. `MetadataChangeCursor` and `MetadataCurrentPageToken` print and parse as the `mc1_` and `cs1_` text forms the HTTP API and the CLI use, and `JSON.stringify` writes them as that text.
+
 ## use sources
 
-Cluster auto-commit polling over TCP/TLS keeps group membership on the coordinator
-and uses separate connections to partition primaries. It requires server support
-for binary commands 14, 103 and 104. Pause binary auto-commit consumers for the
-whole upgrade: upgrade every server first, then the SDKs, and restart consumers
-so they rejoin their groups. Older SDKs can lose membership when a backup refuses
-an offset commit; the new SDK does not fall back to legacy polling.
+Cluster polling uses command 15 (`BindSession`), route discovery 105 and poll
+100. Commands 14, 103, 104 and 123 are retired. Pause consumers for the coordinated
+server/SDK upgrade and restart them to rejoin their groups. There is no fallback
+to retired polling commands.
+
+Stream, topic and user updates use the generic update command 16. The former update commands 35, 204 and 304 are retired.
 
 ### Install
 
@@ -180,6 +461,8 @@ npm run test:unit
 
 e2e test expect an iggy-server at tcp://127.0.0.1:8090
 
+The resource options tests also expect the server to run with encryption enabled and a config key (`IGGY_ENCRYPTION_ENABLED=true` and `IGGY_ENCRYPTION_KEY` set to the base64 of 32 bytes), so a stream created without a key reports a server-generated one. The keyed metadata changes case registered from the same file needs the config key too.
+
 ```bash
 npm run test:e2e
 ```

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

@@ -1,5 +1,7 @@
 import type { ClientConfig, ClientConfigOrString } from './client.type.js';
 export declare const DEFAULT_MAX_RESPONSE_FRAME_SIZE: number;
+export declare const DEFAULT_MAX_PENDING_OPERATIONS = 256;
+export declare const DEFAULT_MAX_PENDING_OPERATION_BYTES: 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.

package/dist/client/client.config.js

@@ -16,7 +16,10 @@
 // under the License.
 import { MAX_U32 } from '../constant.js';
 import { parseConnectionString } from './client.connection-string.js';
+import { HEADER_SIZE } from '../wire/vsr/header.js';
 export const DEFAULT_MAX_RESPONSE_FRAME_SIZE = 64 * 1024 * 1024;
+export const DEFAULT_MAX_PENDING_OPERATIONS = 256;
+export const DEFAULT_MAX_PENDING_OPERATION_BYTES = 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.
@@ -29,10 +32,16 @@ export const normalizeClientConfig = (config) => {
         config = parseConnectionString(config);
     const maxResponseFrameSize = config.maxResponseFrameSize ?? DEFAULT_MAX_RESPONSE_FRAME_SIZE;
     if (!Number.isSafeInteger(maxResponseFrameSize) ||
-        maxResponseFrameSize < 256)
+        maxResponseFrameSize < HEADER_SIZE)
         throw new TypeError('maxResponseFrameSize must be a safe integer of at least 256 bytes');
+    const maxPendingOperations = config.maxPendingOperations ?? DEFAULT_MAX_PENDING_OPERATIONS;
+    const maxPendingOperationBytes = config.maxPendingOperationBytes ?? DEFAULT_MAX_PENDING_OPERATION_BYTES;
+    if (!Number.isSafeInteger(maxPendingOperations) || maxPendingOperations <= 0)
+        throw new TypeError('maxPendingOperations must be a positive safe integer');
+    if (!Number.isSafeInteger(maxPendingOperationBytes) || maxPendingOperationBytes <= 0)
+        throw new TypeError('maxPendingOperationBytes must be a positive safe integer');
     if ((config.poolSize?.min ?? 1) > 1 || (config.poolSize?.max ?? 1) > 1)
-        throw new TypeError('VSR clients currently support exactly one pooled connection');
+        throw new TypeError('poolSize supports exactly one logical client; replica links are managed independently');
     // 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
@@ -65,6 +74,8 @@ export const normalizeClientConfig = (config) => {
         ...config,
         options: { ...config.options },
         maxResponseFrameSize,
+        maxPendingOperations,
+        maxPendingOperationBytes,
         heartbeatInterval,
         poolSize: { min: 1, max: 1 }
     };

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

@@ -73,13 +73,26 @@ describe('normalizeClientConfig', () => {
                 reconnect: { enabled: true, interval: 1000, maxRetries }
             }), /reconnect\.maxRetries/);
     });
-    it('restricts the client to one pooled connection', () => {
+    it('preserves the one-logical-client pool option', () => {
         const normalized = normalizeClientConfig(config());
         assert.deepEqual(normalized.poolSize, { min: 1, max: 1 });
         assert.throws(() => normalizeClientConfig({
             ...config(),
             poolSize: { max: 2 }
-        }), /exactly one pooled connection/);
+        }), /exactly one logical client/);
+    });
+    it('applies and validates shared mutation admission limits', () => {
+        const defaults = normalizeClientConfig(config());
+        assert.equal(defaults.maxPendingOperations, 256);
+        assert.equal(defaults.maxPendingOperationBytes, 64 * 1024 * 1024);
+        const bounded = normalizeClientConfig({ ...config(), maxPendingOperations: 1, maxPendingOperationBytes: 256 });
+        assert.equal(bounded.maxPendingOperations, 1);
+        assert.equal(bounded.maxPendingOperationBytes, 256);
+        for (const maxPendingOperations of [0, -1, 1.5, Number.NaN, Number.MAX_SAFE_INTEGER + 1])
+            assert.throws(() => normalizeClientConfig({ ...config(), maxPendingOperations }), /maxPendingOperations/);
+        assert.equal(normalizeClientConfig({ ...config(), maxPendingOperationBytes: 1 }).maxPendingOperationBytes, 1);
+        for (const maxPendingOperationBytes of [0, -1, 256.5, Number.NaN, Number.MAX_SAFE_INTEGER + 1])
+            assert.throws(() => normalizeClientConfig({ ...config(), maxPendingOperationBytes }), /maxPendingOperationBytes/);
     });
     it('supports TLS transport', () => {
         const normalized = normalizeClientConfig({

package/dist/client/client.connection-string.js

@@ -95,7 +95,7 @@ export const parseConnectionString = (connectionString) => {
             tls: false,
             reconnect: { ...CONNECTION_STRING_RECONNECT }
         };
-    const { tls, reconnect, heartbeatInterval, ...transportOptions } = options;
+    const { tls, reconnect, heartbeatInterval, maxPendingOperations, maxPendingOperationBytes, ...transportOptions } = options;
     const config = {
         transport: tls ? 'TLS' : 'TCP',
         options: {
@@ -112,6 +112,10 @@ export const parseConnectionString = (connectionString) => {
     };
     if (heartbeatInterval !== undefined)
         config.heartbeatInterval = heartbeatInterval;
+    if (maxPendingOperations !== undefined)
+        config.maxPendingOperations = maxPendingOperations;
+    if (maxPendingOperationBytes !== undefined)
+        config.maxPendingOperationBytes = maxPendingOperationBytes;
     return config;
 };
 const parseConnectionOptions = (optionsString) => {
@@ -169,6 +173,14 @@ const parseConnectionOptions = (optionsString) => {
             case 'heartbeat_interval':
                 parsed.heartbeatInterval = parseDuration(value);
                 break;
+            case 'max_pending_operations':
+            case 'max_pending_operation_bytes': {
+                const limit = parseNumber(name, value);
+                if (!Number.isSafeInteger(limit) || limit <= 0)
+                    throw new TypeError(`option "${name}" must be a positive safe integer`);
+                parsed[name === 'max_pending_operations' ? 'maxPendingOperations' : 'maxPendingOperationBytes'] = limit;
+                break;
+            }
             default:
                 throw new TypeError(`unknown option "${name}"`);
         }

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

@@ -17,8 +17,9 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import { MAX_U32 } from '../constant.js';
+import { HEADER_SIZE } from '../wire/vsr/header.js';
 import { parseConnectionString, parseDuration } from './client.connection-string.js';
-import { DEFAULT_HEARTBEAT_INTERVAL, normalizeClientConfig } from './client.config.js';
+import { DEFAULT_HEARTBEAT_INTERVAL, DEFAULT_MAX_PENDING_OPERATIONS, DEFAULT_MAX_PENDING_OPERATION_BYTES, normalizeClientConfig } from './client.config.js';
 describe('parseConnectionString', () => {
     it('parses the default scheme with password credentials', () => {
         assert.deepEqual(parseConnectionString('iggy://iggy:secret@127.0.0.1:8090'), {
@@ -62,6 +63,36 @@ describe('parseConnectionString', () => {
             heartbeatInterval: 10000
         });
     });
+    for (const scheme of ['iggy', 'iggy+tcp']) {
+        it(`maps mutation limits to client options for ${scheme}`, () => {
+            const config = parseConnectionString(`${scheme}://iggy:secret@localhost:8090` +
+                '?max_pending_operations=7&max_pending_operation_bytes=1024&nodelay=true');
+            assert.equal(config.maxPendingOperations, 7);
+            assert.equal(config.maxPendingOperationBytes, 1024);
+            assert.deepEqual(config.options, { host: 'localhost', port: 8090, noDelay: true });
+            const normalized = normalizeClientConfig(config);
+            assert.equal(normalized.maxPendingOperations, config.maxPendingOperations);
+            assert.equal(normalized.maxPendingOperationBytes, config.maxPendingOperationBytes);
+        });
+    }
+    for (const [option, field, minimum] of [
+        ['max_pending_operations', 'maxPendingOperations', 1],
+        ['max_pending_operation_bytes', 'maxPendingOperationBytes', 1]
+    ]) {
+        it(`accepts the minimum and safe-integer maximum for ${option}`, () => {
+            for (const value of [minimum, Number.MAX_SAFE_INTEGER]) {
+                const config = parseConnectionString(`iggy://iggy:secret@localhost:8090?${option}=${value}`);
+                assert.equal(config[field], value);
+                assert.equal(normalizeClientConfig(config)[field], value);
+            }
+        });
+        it(`rejects invalid and overflowing ${option}`, () => {
+            for (const value of ['', '0', '-1', '1.5', 'NaN', 'Infinity', '1e3',
+                String(minimum - 1), String(Number.MAX_SAFE_INTEGER + 1), '999999999999999999999']) {
+                assert.throws(() => parseConnectionString(`iggy://iggy:secret@localhost:8090?${option}=${value}`), TypeError, `accepted ${option}=${value}`);
+            }
+        });
+    }
     it('applies unlimited/1s reconnection defaults to partial options', () => {
         // retries alone keep the 1s interval; interval alone keeps unlimited.
         assert.deepEqual(parseConnectionString('iggy://iggy:secret@localhost:8090?reconnection_retries=3').reconnect, { enabled: true, interval: 1000, maxRetries: 3 });
@@ -137,6 +168,7 @@ describe('parseConnectionString', () => {
             'iggy://iggy:hunter2@localhost:8090?unknown=value',
             'iggy://iggy:hunter2@localhost:8090?tls=maybe',
             'iggy://iggy:hunter2@localhost:8090?reconnection_retries=three',
+            'iggy://iggy:hunter2@localhost:8090?max_pending_operations=0',
             'iggy://iggy:hunter2@localhost:70000'
         ]) {
             try {
@@ -199,8 +231,18 @@ describe('normalizeClientConfig with connection strings', () => {
             password: 'secret'
         });
         assert.equal(normalized.heartbeatInterval, DEFAULT_HEARTBEAT_INTERVAL);
+        assert.equal(normalized.maxPendingOperations, DEFAULT_MAX_PENDING_OPERATIONS);
+        assert.equal(normalized.maxPendingOperationBytes, DEFAULT_MAX_PENDING_OPERATION_BYTES);
         assert.deepEqual(normalized.poolSize, { min: 1, max: 1 });
     });
+    it('preserves the unspecified mutation limit when only one is configured', () => {
+        const count = normalizeClientConfig('iggy://iggy:secret@localhost:8090?max_pending_operations=7');
+        assert.equal(count.maxPendingOperations, 7);
+        assert.equal(count.maxPendingOperationBytes, DEFAULT_MAX_PENDING_OPERATION_BYTES);
+        const bytes = normalizeClientConfig(`iggy://iggy:secret@localhost:8090?max_pending_operation_bytes=${HEADER_SIZE}`);
+        assert.equal(bytes.maxPendingOperations, DEFAULT_MAX_PENDING_OPERATIONS);
+        assert.equal(bytes.maxPendingOperationBytes, HEADER_SIZE);
+    });
     it('rejects reconnect intervals beyond the node timer ceiling', () => {
         // Parses to 3_600_000_000 ms; setInterval would clamp it back to 1 ms.
         assert.throws(() => normalizeClientConfig('iggy://iggy:secret@localhost:8090?reconnection_interval=1000h'), /reconnect\.interval/);