apache-iggy 0.10.0-edge.5 → 0.10.0-edge.7

package/README.md

@@ -161,7 +161,7 @@ npm run build
 ### test
 
 note: use env var `IGGY_TCP_ADDRESS="host:port"` to set the server
-address for bdd and e2e tests.
+address for e2e tests. bdd tests need more variables, see below.
 
 #### unit tests
 
@@ -179,15 +179,27 @@ npm run test:e2e
 
 #### bdd tests
 
-bdd test expect an iggy-server at tcp://127.0.0.1:8090
+the bdd suite has no defaults and fails when `IGGY_TCP_ADDRESS`,
+`IGGY_ROOT_USERNAME` or `IGGY_ROOT_PASSWORD` is missing. from the repository
+root run
 
 ```bash
-npm run test:bdd
+./scripts/run-bdd-tests.sh node
 ```
 
+the script starts the server and sets every variable, so none of them have to be
+exported by hand. to iterate against a server you started yourself, see
+[src/bdd/README.md](./src/bdd/README.md).
+
 #### run all test
 
-`npm run test` runs unit, bdd and e2e tests suite (expect an iggy-server at tcp://127.0.0.1:8090)
+`npm run test` runs unit, bdd and e2e tests suite against an iggy-server at
+tcp://127.0.0.1:8090, started with the same root credentials
+
+```bash
+IGGY_TCP_ADDRESS=127.0.0.1:8090 IGGY_ROOT_USERNAME=iggy IGGY_ROOT_PASSWORD=iggy \
+  npm run test
+```
 
 ### lint
 

package/dist/wire/error.code.js

@@ -158,6 +158,7 @@ export const translateErrorCode = (code) => {
         case '3021': return "Consumer offset for consumer with ID: {0} was not found.";
         case '3022': return "Failed to resolve consumer with ID: {0}";
         case '3023': return "Cannot open consumer offsets file for path: {0}";
+        case '3024': return "Consumer offset limit reached for partition, raise [partition] consumer_offsets_max";
         case '3013': return "Partition id space exhausted for this topic";
         // MESSAGE
         case '4000': return "Segment not found";

package/dist/wire/error.code.test.js

@@ -17,6 +17,9 @@
 import assert from 'node:assert/strict';
 import { it } from 'node:test';
 import { translateErrorCode } from './error.code.js';
+it('translates the consumer-offset capacity error', () => {
+    assert.equal(translateErrorCode(3024), 'Consumer offset limit reached for partition, raise [partition] consumer_offsets_max');
+});
 it('translates the consumer-group error range', () => {
     assert.equal(translateErrorCode(5000), 'Consumer group with ID: {0} for topic with ID: {1} was not found.');
     assert.equal(translateErrorCode(5001), 'error');

package/dist/wire/message/message.utils.d.ts

@@ -45,6 +45,20 @@ export declare const isValidMessageId: (x?: unknown) => x is MessageIdKind;
  * @throws Error if the ID format is invalid
  */
 export declare const serializeMessageId: (id?: unknown) => Buffer<ArrayBufferLike>;
+/**
+ * Mints a random 16-byte message ID from the pool, refilling when drained.
+ *
+ * @returns 16-byte buffer of random bytes owned by the caller
+ */
+export declare const mintMessageId: () => Buffer;
+/**
+ * Resolves a message ID to a 16-byte little-endian buffer, minting a random
+ * one when the ID is absent or zero.
+ *
+ * @param id - Optional message ID
+ * @returns 16-byte little-endian buffer containing a non-zero ID
+ */
+export declare const resolveMessageId: (id?: MessageIdKind) => Buffer;
 /**
  * Encodes messages into the canonical batch format.
  * Format: [batch header][frames], one frame per message.

package/dist/wire/message/message.utils.js

@@ -14,7 +14,7 @@
 // KIND, either express or implied.  See the License for the
 // specific language governing permissions and limitations
 // under the License.
-import { uuidv4 } from 'uuidv7';
+import { randomFillSync } from 'node:crypto';
 import { uint32ToBuf, u128ToBuf, uint8ToBuf } from '../number.utils.js';
 import { serializeHeaders } from './header.utils.js';
 import { serializeIdentifier } from '../identifier.utils.js';
@@ -23,6 +23,8 @@ import { parse as parseUUID } from '../uuid.utils.js';
 import { BATCH_HEADER_SIZE, FRAME_HEADER_SIZE, batchChecksum, frameChecksum, serializeBatchHeader, } from './iggy-header.utils.js';
 /** Size of the message ID in bytes (u128) */
 const MESSAGE_ID_SIZE = 16;
+/** Exclusive upper bound for a numeric message ID: it must be < 2^128 */
+const MESSAGE_ID_UPPER_BOUND = 1n << BigInt((MESSAGE_ID_SIZE * 8));
 /** Largest representable frame timestamp delta (u32, microseconds) */
 const MAX_TIMESTAMP_DELTA = 0xffffffffn;
 /**
@@ -52,6 +54,8 @@ export const serializeMessageId = (id) => {
         if (id < 0)
             throw new Error(`invalid message id: '${id}' (numeric id must be >= 0)`);
         const idValue = 'number' === typeof id ? BigInt(id) : id;
+        if (idValue >= MESSAGE_ID_UPPER_BOUND)
+            throw new Error(`invalid message id: '${id}' (numeric id must be < 2^${MESSAGE_ID_SIZE * 8})`);
         return u128ToBuf(idValue);
     }
     try {
@@ -62,17 +66,41 @@ export const serializeMessageId = (id) => {
         throw new Error(`invalid message id: '${id}' (use uuid string | number | bigint >= 0)`, { cause: err });
     }
 };
+/** Number of ids drawn from the pool per CSPRNG refill */
+const ID_POOL_COUNT = 4096;
+/** Pooled random bytes and a cursor into them, filled lazily on first mint */
+const idPool = Buffer.allocUnsafe(ID_POOL_COUNT * MESSAGE_ID_SIZE);
+let idPoolCursor = idPool.length; // past the end -> refill on first use
 /**
- * Serializes a message ID, minting a random UUID when the ID is
- * absent or zero.
+ * Mints a random 16-byte message ID from the pool, refilling when drained.
+ *
+ * @returns 16-byte buffer of random bytes owned by the caller
+ */
+export const mintMessageId = () => {
+    if (idPoolCursor + MESSAGE_ID_SIZE > idPool.length) {
+        randomFillSync(idPool);
+        idPoolCursor = 0;
+    }
+    const id = Buffer.allocUnsafe(MESSAGE_ID_SIZE);
+    idPool.copy(id, 0, idPoolCursor, idPoolCursor + MESSAGE_ID_SIZE);
+    idPoolCursor += MESSAGE_ID_SIZE;
+    return id;
+};
+/**
+ * Resolves a message ID to a 16-byte little-endian buffer, minting a random
+ * one when the ID is absent or zero.
  *
  * @param id - Optional message ID
  * @returns 16-byte little-endian buffer containing a non-zero ID
  */
-const resolveMessageId = (id) => {
+export const resolveMessageId = (id) => {
+    // An absent or zero id mints a random one.
+    if (id === undefined || id === 0 || id === 0n)
+        return mintMessageId();
     const bId = serializeMessageId(id);
-    return bId.every((byte) => byte === 0)
-        ? u128ToBuf(BigInt(`0x${uuidv4().replaceAll('-', '')}`))
+    // A string id can still be the all-zero nil UUID; mint in that case too.
+    return 'string' === typeof id && bId.every((byte) => byte === 0)
+        ? mintMessageId()
         : bId;
 };
 /**

package/dist/wire/message/message.utils.test.d.ts

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

package/dist/wire/message/message.utils.test.js

@@ -0,0 +1,107 @@
+// 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 { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { u128ToBuf } from "../number.utils.js";
+import { isValidMessageId, serializeMessageId, resolveMessageId, mintMessageId, } from "./message.utils.js";
+const MESSAGE_ID_SIZE = 16;
+const MAX_U128 = (1n << 128n) - 1n;
+const NIL_UUID = "00000000-0000-0000-0000-000000000000";
+const isZero = (b) => b.every((byte) => byte === 0);
+describe("isValidMessageId", () => {
+    it("accepts undefined, string, number, and bigint", () => {
+        assert.ok(isValidMessageId(undefined));
+        assert.ok(isValidMessageId("id"));
+        assert.ok(isValidMessageId(7));
+        assert.ok(isValidMessageId(7n));
+    });
+    it("rejects other types", () => {
+        assert.ok(!isValidMessageId(null));
+        assert.ok(!isValidMessageId({}));
+    });
+});
+describe("serializeMessageId", () => {
+    it("serializes undefined to a zero u128", () => {
+        assert.deepEqual(serializeMessageId(), Buffer.alloc(MESSAGE_ID_SIZE, 0));
+    });
+    it("serializes a number as little-endian u128", () => {
+        assert.deepEqual(serializeMessageId(7), u128ToBuf(7n));
+    });
+    it("serializes a bigint as little-endian u128", () => {
+        assert.deepEqual(serializeMessageId(8n), u128ToBuf(8n));
+    });
+    it("serializes a UUID string to the same bytes as its numeric value", () => {
+        const uuid = "00000000-0000-0000-0000-000000000007";
+        assert.deepEqual(serializeMessageId(uuid), u128ToBuf(7n));
+    });
+    it("accepts the largest u128", () => {
+        assert.deepEqual(serializeMessageId(MAX_U128), u128ToBuf(MAX_U128));
+    });
+    it("rejects a numeric id at or above 2^128", () => {
+        assert.throws(() => serializeMessageId(1n << 128n), /2\^128/);
+    });
+    it("rejects a negative numeric id", () => {
+        assert.throws(() => serializeMessageId(-1n), />= 0/);
+    });
+    it("rejects an unparsable string", () => {
+        assert.throws(() => serializeMessageId("not-a-uuid"), /invalid message id/);
+    });
+    it("rejects an invalid type", () => {
+        assert.throws(() => serializeMessageId({}), /invalid message id/);
+    });
+});
+describe("resolveMessageId", () => {
+    it("mints a non-zero id for undefined, 0, and 0n", () => {
+        for (const id of [undefined, 0, 0n]) {
+            const b = resolveMessageId(id);
+            assert.equal(b.length, MESSAGE_ID_SIZE);
+            assert.ok(!isZero(b));
+        }
+    });
+    it("mints for the all-zero nil UUID string", () => {
+        assert.ok(!isZero(resolveMessageId(NIL_UUID)));
+    });
+    it("passes a provided non-zero id through unchanged", () => {
+        assert.deepEqual(resolveMessageId(7n), serializeMessageId(7n));
+    });
+});
+describe("mintMessageId", () => {
+    it("returns a non-zero 16-byte buffer", () => {
+        const b = mintMessageId();
+        assert.equal(b.length, MESSAGE_ID_SIZE);
+        assert.ok(!isZero(b));
+    });
+    it("produces unique, non-zero ids across pool refills", () => {
+        const seen = new Set();
+        for (let i = 0; i < 10_000; i++) {
+            const hex = mintMessageId().toString("hex");
+            assert.notEqual(hex, "0".repeat(MESSAGE_ID_SIZE * 2));
+            seen.add(hex);
+        }
+        assert.equal(seen.size, 10_000);
+    });
+    it("returns owned bytes that survive a later refill", () => {
+        const first = mintMessageId().toString("hex");
+        const held = mintMessageId();
+        const snapshot = held.toString("hex");
+        for (let i = 0; i < 10_000; i++)
+            mintMessageId();
+        assert.equal(held.toString("hex"), snapshot);
+        assert.notEqual(snapshot, first);
+    });
+});
+//# sourceMappingURL=message.utils.test.js.map

package/dist/wire/message/send-messages.command.d.ts

@@ -28,9 +28,8 @@ export type SendMessagesConfirmation = {
      *
      * Delivery is at-least-once, so an earlier retry of the same batch may
      * already have committed at a lower offset: this never identifies a batch
-     * uniquely. A batch is confirmed once it is committed in memory, not once it
-     * is fsynced, so a crash-restart can stamp a later batch with an offset a
-     * client has already recorded.
+     * uniquely. Confirmation follows VSR quorum commit. Persisted message
+     * durability also requires recoverable stable-storage copies on the quorum.
      */
     baseOffset: bigint;
 };

package/dist/wire/number.utils.d.ts

@@ -76,13 +76,18 @@ export declare const floatToBuf: (v: number) => Buffer<ArrayBuffer>;
  */
 export declare const doubleToBuf: (v: number) => Buffer<ArrayBuffer>;
 /**
- * Converts a BigInt to a 128-bit unsigned integer Buffer in little-endian format.
+ * Converts a u128 value to a 16-byte unsigned integer Buffer in little-endian
+ * format.
  *
- * @param num - BigInt value to convert
- * @param width - Width in bytes (default: 16)
- * @returns Buffer containing the value in little-endian byte order
+ * Writes the two 64-bit halves directly rather than round-tripping through a hex
+ * string. `value` must be a non-negative integer below 2^128; anything outside
+ * that range throws (a `RangeError` from the underlying write), which is
+ * preferable to silently truncating a message id.
+ *
+ * @param value - u128 value (0 <= value < 2^128)
+ * @returns 16-byte buffer containing the value in little-endian byte order
  */
-export declare function u128ToBuf(num: bigint, width?: number): Buffer;
+export declare function u128ToBuf(value: bigint): Buffer;
 /**
  * Converts a 128-bit unsigned integer Buffer in little-endian format to a BigInt.
  *

package/dist/wire/number.utils.js

@@ -135,17 +135,25 @@ export const doubleToBuf = (v) => {
     b.writeDoubleLE(v);
     return b;
 };
+/** Mask selecting the low 64 bits of a u128, for little-endian half-writes. */
+const U64_MASK = 0xffffffffffffffffn;
 /**
- * Converts a BigInt to a 128-bit unsigned integer Buffer in little-endian format.
+ * Converts a u128 value to a 16-byte unsigned integer Buffer in little-endian
+ * format.
  *
- * @param num - BigInt value to convert
- * @param width - Width in bytes (default: 16)
- * @returns Buffer containing the value in little-endian byte order
+ * Writes the two 64-bit halves directly rather than round-tripping through a hex
+ * string. `value` must be a non-negative integer below 2^128; anything outside
+ * that range throws (a `RangeError` from the underlying write), which is
+ * preferable to silently truncating a message id.
+ *
+ * @param value - u128 value (0 <= value < 2^128)
+ * @returns 16-byte buffer containing the value in little-endian byte order
  */
-export function u128ToBuf(num, width = 16) {
-    const hex = num.toString(16);
-    const b = Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
-    return b.reverse();
+export function u128ToBuf(value) {
+    const b = Buffer.allocUnsafe(16);
+    b.writeBigUInt64LE(value & U64_MASK, 0);
+    b.writeBigUInt64LE(value >> 64n, 8);
+    return b;
 }
 /**
  * Converts a 128-bit unsigned integer Buffer in little-endian format to a BigInt.

package/dist/wire/number.utils.test.d.ts

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

package/dist/wire/number.utils.test.js

@@ -0,0 +1,55 @@
+// 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 { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { u128ToBuf } from "./number.utils.js";
+const MAX_U128 = (1n << 128n) - 1n;
+const hex = (v) => u128ToBuf(v).toString("hex");
+describe("u128ToBuf", () => {
+    it("encodes zero as 16 zero bytes", () => {
+        assert.equal(hex(0n), "0".repeat(32));
+    });
+    it("encodes a small value little-endian", () => {
+        assert.equal(hex(7n), "07" + "0".repeat(30));
+    });
+    it("orders all 16 bytes little-endian", () => {
+        // Distinct bytes so a byte-order slip is visible.
+        assert.equal(hex(0x0102030405060708090a0b0c0d0e0f10n), "100f0e0d0c0b0a090807060504030201");
+    });
+    it("spans the 64-bit half boundary", () => {
+        assert.equal(hex((1n << 64n) - 1n), "ff".repeat(8) + "00".repeat(8));
+        assert.equal(hex(1n << 64n), "00".repeat(8) + "01" + "00".repeat(7));
+    });
+    it("encodes the largest u128 as all ones", () => {
+        assert.equal(hex(MAX_U128), "ff".repeat(16));
+    });
+    it("round-trips through readBigUInt64LE halves", () => {
+        for (const v of [0n, 1n, 42n, 1n << 64n, MAX_U128]) {
+            const b = u128ToBuf(v);
+            const low = b.readBigUInt64LE(0);
+            const high = b.readBigUInt64LE(8);
+            assert.equal((high << 64n) | low, v);
+        }
+    });
+    it("throws for a value at or above 2^128", () => {
+        assert.throws(() => u128ToBuf(1n << 128n));
+    });
+    it("throws for a negative value", () => {
+        assert.throws(() => u128ToBuf(-1n));
+    });
+});
+//# sourceMappingURL=number.utils.test.js.map

package/dist/wire/options.utils.test.js

@@ -28,22 +28,25 @@ const prefixed = (block) => {
  *
  * Rust pins the identical bytes in `core/binary_protocol/src/primitives/options.rs`,
  * as do the Go and Java SDKs. Round-tripping through this SDK's own decoder proves
- * nothing about interoperability; these bytes are the contract.
+ * nothing about interoperability. This insertion-order vector covers Bool, Uint64
+ * and String values, independently of Rust's sorted map order.
  */
 const GOLDEN_OPTIONS_BLOCK = Buffer.from([
-    2, 13, 0, 0, 0,
-    ...Buffer.from('enforce_fsync'),
+    2, 20, 0, 0, 0,
+    ...Buffer.from('preallocate_segments'),
     3, 1, 0, 0, 0, 1,
     2, 12, 0, 0, 0,
     ...Buffer.from('segment_size'),
     12, 8, 0, 0, 0,
-    0, 0, 0, 64, 0, 0, 0, 0
+    0, 0, 0, 64, 0, 0, 0, 0,
+    2, 10, 0, 0, 0, 100, 117, 114, 97, 98, 105, 108, 105, 116, 121, 2, 9, 0, 0, 0, 112, 101, 114, 115, 105, 115, 116, 101, 100
 ]);
 describe('serializeOptions', () => {
     it('encodes the cross-SDK golden vector byte for byte', () => {
         const encoded = serializeOptions([
-            { key: 'enforce_fsync', value: HeaderValue.Bool(true) },
-            { key: 'segment_size', value: HeaderValue.Uint64(1073741824n) }
+            { key: 'preallocate_segments', value: HeaderValue.Bool(true) },
+            { key: 'segment_size', value: HeaderValue.Uint64(1073741824n) },
+            { key: 'durability', value: HeaderValue.String('persisted') }
         ]);
         assert.deepEqual(encoded, GOLDEN_OPTIONS_BLOCK);
     });

package/dist/wire/topic/create-topic.command.d.ts

@@ -1,7 +1,7 @@
 import type { CommandResponse } from '../../client/client.type.js';
 import { type Id } from '../identifier.utils.js';
 import { type OptionEntry } from '../options.utils.js';
-import { type Topic, type CompressionAlgorithm as CompressionAlgorithmT } from './topic.utils.js';
+import { Durability, type Topic, type CompressionAlgorithm as CompressionAlgorithmT } from './topic.utils.js';
 /**
  * Parameters for the create topic command.
  */
@@ -28,8 +28,9 @@ export type CreateTopic = {
     maxTopicSize?: bigint;
     /** Segment size in bytes: 512-byte multiple between 1 MiB and 1 GiB */
     segmentSize?: bigint;
-    /** Fsync every write instead of leaving it to the page cache */
-    enforceFsync?: boolean;
+    /** Message completion policy. Defaults to replicated, independently of offsets. */
+    durability?: Durability;
+    consumerOffsetDurability?: Durability;
     /** Message count that triggers a save (must be non-zero) */
     messagesRequiredToSave?: number;
     /** Accumulated message bytes that trigger a save */
@@ -52,7 +53,7 @@ export type CreateTopic = {
  */
 export declare const CREATE_TOPIC: {
     code: number;
-    serialize: ({ streamId, name, partitionCount, compressionAlgorithm, messageExpiry, maxTopicSize, segmentSize, enforceFsync, messagesRequiredToSave, sizeOfMessagesRequiredToSave, preallocateSegments, options: extraOptions }: CreateTopic) => Buffer<ArrayBuffer>;
+    serialize: ({ streamId, name, partitionCount, compressionAlgorithm, messageExpiry, maxTopicSize, segmentSize, durability, consumerOffsetDurability, messagesRequiredToSave, sizeOfMessagesRequiredToSave, preallocateSegments, options: extraOptions }: CreateTopic) => Buffer<ArrayBuffer>;
     deserialize: (r: CommandResponse) => Topic;
 };
 /**

package/dist/wire/topic/create-topic.command.js

@@ -19,7 +19,7 @@ import { wrapCommand } from '../command.utils.js';
 import { COMMAND_CODE } from '../command.code.js';
 import { dedupeOptions, serializeOptions } from '../options.utils.js';
 import { HeaderValue } from '../message/header.utils.js';
-import { isValidCompressionAlgorithm, CompressionAlgorithm, compressionAlgorithmName, deserializeTopic } from './topic.utils.js';
+import { isValidCompressionAlgorithm, CompressionAlgorithm, Durability, compressionAlgorithmName, deserializeTopic } from './topic.utils.js';
 /**
  * Create topic command definition.
  * Creates a new topic within a stream.
@@ -28,7 +28,7 @@ import { isValidCompressionAlgorithm, CompressionAlgorithm, compressionAlgorithm
  */
 export const CREATE_TOPIC = {
     code: COMMAND_CODE.CreateTopic,
-    serialize: ({ streamId, name, partitionCount, compressionAlgorithm = CompressionAlgorithm.None, messageExpiry = 0n, maxTopicSize = 0n, segmentSize, enforceFsync, messagesRequiredToSave, sizeOfMessagesRequiredToSave, preallocateSegments, options: extraOptions = [] }) => {
+    serialize: ({ streamId, name, partitionCount, compressionAlgorithm = CompressionAlgorithm.None, messageExpiry = 0n, maxTopicSize = 0n, segmentSize, durability = Durability.Replicated, consumerOffsetDurability = Durability.Replicated, messagesRequiredToSave, sizeOfMessagesRequiredToSave, preallocateSegments, options: extraOptions = [] }) => {
         // Topic ID is now auto-assigned by the server, not sent in the protocol
         const streamIdentifier = serializeIdentifier(streamId);
         const bName = Buffer.from(name);
@@ -60,10 +60,19 @@ export const CREATE_TOPIC = {
             options.push({
                 key: 'segment_size', value: HeaderValue.Uint64(segmentSize)
             });
-        if (enforceFsync !== undefined)
-            options.push({
-                key: 'enforce_fsync', value: HeaderValue.Bool(enforceFsync)
-            });
+        for (const [key, policy] of [
+            ['durability', durability],
+            ['consumer_offset_durability', consumerOffsetDurability]
+        ]) {
+            if (policy !== Durability.Replicated && policy !== Durability.Persisted)
+                throw new Error(`Invalid ${key}: ${policy}`);
+            const expected = HeaderValue.String(policy);
+            for (const entry of extraOptions) {
+                if (entry.key === key && (entry.value.kind !== expected.kind || entry.value.value !== expected.value))
+                    throw new Error(`Conflicting ${key}`);
+            }
+            options.push({ key, value: expected });
+        }
         if (messagesRequiredToSave !== undefined)
             options.push({
                 key: 'messages_required_to_save',

package/dist/wire/topic/create-topic.command.test.js

@@ -16,6 +16,7 @@
 // under the License.
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
+import { Durability } from './topic.utils.js';
 import { CREATE_TOPIC } from './create-topic.command.js';
 import { deserializeOptions } from '../options.utils.js';
 import { HeaderValue } from '../message/header.utils.js';
@@ -32,17 +33,19 @@ describe('CreateTopic', () => {
         // TLV field: [kind:u8][len:u32_le][bytes]
         const tlvSize = (bytes) => 1 + 4 + bytes;
         const identifierSize = 1 + 1 + 4; // numeric stream id
+        const defaultPolicySize = tlvSize('durability'.length) + tlvSize('replicated'.length)
+            + tlvSize('consumer_offset_durability'.length) + tlvSize('replicated'.length);
         const fixedSize = identifierSize + 4 + 1; // + partitions_count + name_len
         it('serialize name and default options into buffer', () => {
-            // Server-default sentinels are omitted, leaving an empty options block.
-            assert.deepEqual(CREATE_TOPIC.serialize(t1).length, fixedSize + t1.name.length);
+            // Durability defaults are explicit, while the other sentinels are omitted.
+            assert.deepEqual(CREATE_TOPIC.serialize(t1).length, fixedSize + t1.name.length + defaultPolicySize);
         });
         it('serialize partitionCount as a fixed u32 before the name', () => {
             const t = { ...t1, partitionCount: 7 };
             const b = CREATE_TOPIC.serialize(t);
             assert.equal(b.readUInt32LE(identifierSize), 7);
             assert.equal(b.readUInt8(identifierSize + 4), t.name.length);
-            assert.equal(b.subarray(fixedSize).toString(), t.name);
+            assert.equal(b.subarray(fixedSize, fixedSize + t.name.length).toString(), t.name);
         });
         it('serialize non-default options into buffer', () => {
             const t = {
@@ -51,7 +54,7 @@ describe('CreateTopic', () => {
                 messageExpiry: 42n,
                 maxTopicSize: 1024n
             };
-            assert.deepEqual(CREATE_TOPIC.serialize(t).length, fixedSize + t1.name.length
+            assert.deepEqual(CREATE_TOPIC.serialize(t).length, fixedSize + t1.name.length + defaultPolicySize
                 + tlvSize('compression_algorithm'.length) + tlvSize('gzip'.length)
                 + tlvSize('message_expiry'.length) + tlvSize(8)
                 + tlvSize('max_topic_size'.length) + tlvSize(8));
@@ -60,14 +63,14 @@ describe('CreateTopic', () => {
             const t = {
                 ...t1,
                 segmentSize: 1048576n,
-                enforceFsync: true,
+                durability: Durability.Persisted,
                 messagesRequiredToSave: 1000,
                 sizeOfMessagesRequiredToSave: 4096n,
                 preallocateSegments: false
             };
-            assert.deepEqual(CREATE_TOPIC.serialize(t).length, fixedSize + t1.name.length
+            assert.deepEqual(CREATE_TOPIC.serialize(t).length, fixedSize + t1.name.length + defaultPolicySize
                 + tlvSize('segment_size'.length) + tlvSize(8)
-                + tlvSize('enforce_fsync'.length) + tlvSize(1)
+                + 'persisted'.length - 'replicated'.length
                 + tlvSize('messages_required_to_save'.length) + tlvSize(4)
                 + tlvSize('size_of_messages_required_to_save'.length) + tlvSize(8)
                 + tlvSize('preallocate_segments'.length) + tlvSize(1));
@@ -77,7 +80,7 @@ describe('CreateTopic', () => {
                 ...t1,
                 maxTopicSize: 4096n,
                 options: [
-                    { key: 'enforce_fsync', value: HeaderValue.Bool(true) },
+                    { key: 'preallocate_segments', value: HeaderValue.Bool(true) },
                     // The typed field covers this key, so the caller's entry is dropped:
                     // a duplicate key makes the server refuse the whole block.
                     { key: 'max_topic_size', value: HeaderValue.String('1 GiB') }
@@ -86,10 +89,27 @@ describe('CreateTopic', () => {
             const b = CREATE_TOPIC.serialize(t);
             // The create payload runs its options block to the end, unprefixed.
             const options = deserializeOptions(b, fixedSize + t.name.length);
-            assert.deepEqual(Object.keys(options).sort(), ['enforce_fsync', 'max_topic_size']);
-            assert.equal(options.enforce_fsync, true);
+            assert.deepEqual(Object.keys(options).sort(), ['consumer_offset_durability', 'durability', 'max_topic_size', 'preallocate_segments']);
+            assert.equal(options.preallocate_segments, true);
             assert.equal(options.max_topic_size, 4096n);
         });
+        it('keeps each omitted durability policy replicated', () => {
+            for (const selected of [
+                { durability: Durability.Persisted },
+                { consumerOffsetDurability: Durability.Persisted }
+            ]) {
+                const input = { ...t1, ...selected };
+                const encoded = CREATE_TOPIC.serialize(input);
+                const options = deserializeOptions(encoded, fixedSize + input.name.length);
+                assert.equal(options.durability, selected.durability ?? 'replicated');
+                assert.equal(options.consumer_offset_durability, selected.consumerOffsetDurability ?? 'replicated');
+            }
+        });
+        it('rejects a conflicting raw durability instead of weakening it', () => {
+            assert.throws(() => CREATE_TOPIC.serialize({ ...t1, options: [
+                    { key: 'durability', value: HeaderValue.String('persisted') }
+                ] }));
+        });
         it('throw on name < 1', () => {
             const t = { ...t1, name: '' };
             assert.throws(() => CREATE_TOPIC.serialize(t));

package/dist/wire/topic/index.d.ts

@@ -5,5 +5,5 @@ export * from './get-topics.command.js';
 export * from './purge-topic.command.js';
 export * from './update-topic.command.js';
 export * from './ensure-topic.virtual.command.js';
-export { CompressionAlgorithm } from './topic.utils.js';
+export { CompressionAlgorithm, Durability } from './topic.utils.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/wire/topic/index.js

@@ -21,5 +21,5 @@ export * from './get-topics.command.js';
 export * from './purge-topic.command.js';
 export * from './update-topic.command.js';
 export * from './ensure-topic.virtual.command.js';
-export { CompressionAlgorithm } from './topic.utils.js';
+export { CompressionAlgorithm, Durability } from './topic.utils.js';
 //# sourceMappingURL=index.js.map

package/dist/wire/topic/topic.utils.d.ts

@@ -138,5 +138,10 @@ export declare const deserializeTopic: (p: Buffer, pos?: number) => TopicSeriali
  * @returns Array of deserialized topics
  */
 export declare const deserializeTopics: (p: Buffer, pos?: number) => Topic[];
+export declare const Durability: {
+    readonly Replicated: "replicated";
+    readonly Persisted: "persisted";
+};
+export type Durability = typeof Durability[keyof typeof Durability];
 export {};
 //# sourceMappingURL=topic.utils.d.ts.map

package/dist/wire/topic/topic.utils.js

@@ -146,4 +146,8 @@ export const deserializeTopics = (p, pos = 0) => {
     }
     return topics;
 };
+export const Durability = {
+    Replicated: 'replicated',
+    Persisted: 'persisted'
+};
 //# sourceMappingURL=topic.utils.js.map

package/dist/wire/vsr/header.d.ts

@@ -86,8 +86,10 @@ export type RequestHeaderFields = {
 };
 /**
  * Encodes a 256-byte request header. Only the six fields the server reads
- * are written; the checksums stay zero, matching the Rust SDK's contract
- * with the VSR server.
+ * are written. The checksums stay zero: the frame and body checksums are not
+ * read on the client request path, and `request_checksum` treats zero as
+ * unstamped, which opts out of the server's payload comparison. Stamping it is
+ * optional -- the Rust SDK does for deduped ops, this SDK does not yet.
  */
 export declare const encodeRequestHeader: (fields: RequestHeaderFields) => Buffer;
 /**

package/dist/wire/vsr/header.js

@@ -88,8 +88,10 @@ export const EvictionReason = {
 const U64_MASK = 0xffffffffffffffffn;
 /**
  * Encodes a 256-byte request header. Only the six fields the server reads
- * are written; the checksums stay zero, matching the Rust SDK's contract
- * with the VSR server.
+ * are written. The checksums stay zero: the frame and body checksums are not
+ * read on the client request path, and `request_checksum` treats zero as
+ * unstamped, which opts out of the server's payload comparison. Stamping it is
+ * optional -- the Rust SDK does for deduped ops, this SDK does not yet.
  */
 export const encodeRequestHeader = (fields) => {
     const header = Buffer.alloc(HEADER_SIZE);

package/dist/wire/vsr/index.js

@@ -18,7 +18,7 @@ import { createRequire } from 'node:module';
 import { COMMAND_CODE } from '../command.code.js';
 import { responseError } from '../error.utils.js';
 import { HEADER_SIZE, encodeRequestHeader } from './header.js';
-import { Operation, isPartition, operationForCode, } from './operation.js';
+import { Operation, operationForCode } from './operation.js';
 import { deserializeLoginRegister, serializeLoginRegister, serializeLoginRegisterWithPat, } from './register.js';
 import { decodeResponse } from './reply.js';
 import { ConsensusSession } from './session.js';
@@ -61,9 +61,10 @@ export class VsrSession {
         else {
             if (this.state.session === null)
                 throw responseError(command, UNAUTHENTICATED);
-            request = isPartition(operation)
-                ? this.state.currentRequestId()
-                : this.state.nextRequestId();
+            // Partition ops consume an id too, even though no partition-plane dedup
+            // exists yet: dedup needs each send to carry a distinct number, and the
+            // metadata watermark tolerates the gaps.
+            request = this.state.nextRequestId();
             session = this.state.session;
         }
         const header = encodeRequestHeader({

package/dist/wire/vsr/operation.d.ts

@@ -50,8 +50,6 @@ export declare const isInternal: (operation: number) => boolean;
  * `Operation::is_metadata`.
  */
 export declare const isMetadata: (operation: number) => boolean;
-/** Partition band is a bare range, mirroring `Operation::is_partition`. */
-export declare const isPartition: (operation: number) => boolean;
 /** Whether a reply body leads with a committed result section. */
 export declare const isResultFramed: (operation: number) => boolean;
 /**

package/dist/wire/vsr/operation.js

@@ -59,7 +59,6 @@ export const Operation = {
 };
 const INTERNAL_START = 64;
 const METADATA_START = 128;
-const PARTITION_START = 160;
 /**
  * Replicated command code to `Operation` mapping, the client half of the
  * dispatch table. Codes absent here are sent as non-replicated so the server
@@ -115,8 +114,6 @@ export const isMetadata = (operation) => {
     return operation >= METADATA_START &&
         operation <= Operation.LeaveConsumerGroup;
 };
-/** Partition band is a bare range, mirroring `Operation::is_partition`. */
-export const isPartition = (operation) => operation >= PARTITION_START;
 /** Whether a reply body leads with a committed result section. */
 export const isResultFramed = (operation) => isMetadata(operation) ||
     operation === Operation.StoreConsumerOffset ||

package/dist/wire/vsr/operation.test.js

@@ -17,7 +17,7 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import { COMMAND_CODE } from '../command.code.js';
-import { isInternal, isKnownOperation, isMetadata, isPartition, isResultFramed, Operation, operationForCode } from './operation.js';
+import { isInternal, isKnownOperation, isMetadata, isResultFramed, Operation, operationForCode } from './operation.js';
 const replicated = new Map([
     [COMMAND_CODE.CreateStream, Operation.CreateStream],
     [COMMAND_CODE.UpdateStream, Operation.UpdateStream],
@@ -72,8 +72,6 @@ describe('VSR operation classification', () => {
         assert.equal(isMetadata(Operation.LeaveConsumerGroup), true);
         assert.equal(isMetadata(Operation.DeleteSegments), false);
         assert.equal(isMetadata(150), false);
-        assert.equal(isPartition(Operation.SendMessages), true);
-        assert.equal(isPartition(159), false);
         assert.equal(isResultFramed(Operation.StoreConsumerOffset), true);
         assert.equal(isResultFramed(Operation.DeleteConsumerOffset), true);
         assert.equal(isResultFramed(Operation.SendMessages), false);

package/dist/wire/vsr/session.d.ts

@@ -3,9 +3,9 @@
  *
  * Each client instance generates an ephemeral random `clientId` (u128).
  * After a Register commits, the server assigns a `session` number (commit op
- * number). Replicated metadata requests advance a monotonic request watermark.
- * Non-replicated and partition-plane requests reuse the current value because
- * the server only applies request sequencing to replicated metadata.
+ * number). Every replicated request (metadata and partition) advances a
+ * monotonic request watermark; non-replicated requests reuse the current
+ * value because they bypass server-side request sequencing.
  */
 export declare class ConsensusSession {
     private _clientId;

package/dist/wire/vsr/session.js

@@ -21,9 +21,9 @@ const MAX_U64 = 0xffffffffffffffffn;
  *
  * Each client instance generates an ephemeral random `clientId` (u128).
  * After a Register commits, the server assigns a `session` number (commit op
- * number). Replicated metadata requests advance a monotonic request watermark.
- * Non-replicated and partition-plane requests reuse the current value because
- * the server only applies request sequencing to replicated metadata.
+ * number). Every replicated request (metadata and partition) advances a
+ * monotonic request watermark; non-replicated requests reuse the current
+ * value because they bypass server-side request sequencing.
  */
 export class ConsensusSession {
     _clientId;

package/dist/wire/vsr/vsr.test.js

@@ -48,17 +48,28 @@ describe('VSR custom request framing', () => {
         const frame = new VsrSession(7n).encode(prepared.command, prepared.payload);
         assert.equal(frame.readUInt8(REQUEST_OFFSET.operation), Operation.Register);
     });
-    it('does not advance for non-replicated or partition operations', () => {
+    it('does not advance for non-replicated operations', () => {
         const session = new VsrSession(7n);
         session.bind(42n);
         const custom = session.encode(60_001, Buffer.alloc(0));
         assert.equal(custom.readBigUInt64LE(REQUEST_OFFSET.request), 1n);
-        const partition = session.encode(COMMAND_CODE.SendMessages, serializeSendMessages(1, 2, [{ payload: 'x' }], Partitioning.PartitionId(3)));
-        assert.equal(partition.readUInt8(REQUEST_OFFSET.operation), Operation.SendMessages);
-        assert.equal(partition.readBigUInt64LE(REQUEST_OFFSET.request), 1n);
         const metadata = session.encode(COMMAND_CODE.CreateStream, Buffer.alloc(0));
         assert.equal(metadata.readBigUInt64LE(REQUEST_OFFSET.request), 1n);
         assert.equal(metadata.length, HEADER_SIZE);
     });
+    it('partition operations consume a distinct id per send', () => {
+        // Dedup identity requires each send to carry a distinct number, so
+        // partition ops advance the counter exactly like metadata ops and the
+        // two planes interleave on one sequence.
+        const session = new VsrSession(7n);
+        session.bind(42n);
+        const sendMessages = () => session.encode(COMMAND_CODE.SendMessages, serializeSendMessages(1, 2, [{ payload: 'x' }], Partitioning.PartitionId(3)));
+        const first = sendMessages();
+        assert.equal(first.readUInt8(REQUEST_OFFSET.operation), Operation.SendMessages);
+        assert.equal(first.readBigUInt64LE(REQUEST_OFFSET.request), 1n);
+        assert.equal(sendMessages().readBigUInt64LE(REQUEST_OFFSET.request), 2n);
+        const metadata = session.encode(COMMAND_CODE.CreateStream, Buffer.alloc(0));
+        assert.equal(metadata.readBigUInt64LE(REQUEST_OFFSET.request), 3n);
+    });
 });
 //# sourceMappingURL=vsr.test.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "apache-iggy",
   "type": "module",
-  "version": "0.10.0-edge.5",
+  "version": "0.10.0-edge.7",
   "description": "Official Apache Iggy NodeJS SDK",
   "keywords": [
     "iggy",
@@ -61,7 +61,7 @@
     "@cucumber/cucumber": "13.2.1",
     "@swc-node/register": "1.12.1",
     "@types/debug": "4.1.13",
-    "@types/node": "26.2.0",
+    "@types/node": "26.4.0",
     "c8": "^12.0.0",
     "husky": "9.1.7",
     "typescript": "6.0.3",