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

package/README.md

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

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

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

package/dist/client/client.config.js

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

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

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

package/dist/client/client.socket.js

@@ -519,6 +519,9 @@ export class CommandResponseStream extends EventEmitter {
                 }
             }
         }, interval);
+        // A pending heartbeat must not be the reason the process stays up: a script
+        // that never calls destroy() would otherwise hang on exit.
+        this.heartbeatIntervalHandler.unref();
     }
     /**
      * Returns the underlying socket as a readable stream.

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

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

package/dist/debug.js

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

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

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

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

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

package/dist/wire/command-set.js

@@ -53,6 +53,7 @@ import { ensureStream } from './stream/ensure-stream.virtual.command.js';
 import { createPartition } from './partition/create-partition.command.js';
 import { deletePartition } from './partition/delete-partition.command.js';
 import { deleteSegments } from './segment/delete-segments.command.js';
+import { describeOptions } from './system/describe-options.command.js';
 import { getStats } from './system/get-stats.command.js';
 import { ping } from './system/ping.command.js';
 import { getClusterMetadata } from './cluster/get-cluster-metadata.command.js';
@@ -137,7 +138,8 @@ const messageAPI = (c) => ({
 });
 const systemAPI = (c) => ({
     ping: ping(c),
-    getStats: getStats(c)
+    getStats: getStats(c),
+    describeOptions: describeOptions(c)
 });
 const clusterAPI = (c) => ({
     getClusterMetadata: getClusterMetadata(c)

package/dist/wire/command.code.d.ts

@@ -3,6 +3,7 @@ export declare const COMMAND_CODE: {
     GetStats: number;
     GetSnapshot: number;
     GetClusterMetadata: number;
+    DescribeOptions: number;
     GetMe: number;
     GetClient: number;
     GetClients: number;

package/dist/wire/command.code.js

@@ -21,6 +21,7 @@ export const COMMAND_CODE = {
     GetStats: 10,
     GetSnapshot: 11, // @TODO GET_SNAPSHOT_FILE_CODE: u32 = 11
     GetClusterMetadata: 12,
+    DescribeOptions: 13,
     GetMe: 20,
     GetClient: 21,
     GetClients: 22,

package/dist/wire/message/header.type.d.ts

@@ -27,7 +27,7 @@ export type HeaderKindId = keyof HeaderKind;
 /** Numeric values of header kinds */
 export type HeaderKindValue = ValueOf<HeaderKind>;
 /** Reverse mapping from numeric value to header kind name */
-export declare const ReverseHeaderKind: Record<2 | 1 | 10 | 11 | 12 | 5 | 8 | 13 | 3 | 4 | 6 | 7 | 9 | 14 | 15, "Raw" | "String" | "Bool" | "Int8" | "Int16" | "Int32" | "Int64" | "Int128" | "Uint8" | "Uint16" | "Uint32" | "Uint64" | "Uint128" | "Float" | "Double">;
+export declare const ReverseHeaderKind: Record<2 | 1 | 10 | 11 | 12 | 13 | 5 | 8 | 3 | 4 | 6 | 7 | 9 | 14 | 15, "Raw" | "String" | "Bool" | "Int8" | "Int16" | "Int32" | "Int64" | "Int128" | "Uint8" | "Uint16" | "Uint32" | "Uint64" | "Uint128" | "Float" | "Double">;
 /** Returns expected byte size for a header kind, or -1 for variable-size kinds */
 export declare const expectedSize: (kind: number) => number;
 /** Raw binary header value */

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

@@ -0,0 +1,62 @@
+import { type HeaderValue, type ParsedHeaderValue } from './message/header.utils.js';
+/** Maximum number of key-value entries in one options block. */
+export declare const MAX_OPTIONS = 1024;
+/**
+ * Maximum total byte length of an encoded options block.
+ *
+ * Mirrors the Rust `MAX_OPTIONS_BYTES`, which in turn mirrors the user-headers
+ * budget: options ride that codec and inherit its limit.
+ */
+export declare const MAX_OPTIONS_BYTES: number;
+/** A resource option entry: UTF-8 string key with a typed value. */
+export type OptionEntry = {
+    key: string;
+    value: HeaderValue;
+};
+/** Deserialized options block keyed by option name. */
+export type ParsedOptions = Record<string, ParsedHeaderValue>;
+/** Result of deserializing a length-prefixed options block. */
+export type OptionsDeserialized = {
+    /** Number of bytes consumed, length prefix included */
+    bytesRead: number;
+    /** Deserialized options */
+    options: ParsedOptions;
+};
+/**
+ * Keeps the last entry for each key, preserving first-seen order.
+ *
+ * A block carrying a key twice is refused whole by wire validation, so callers
+ * that append their own entries ahead of the typed ones rely on this to let the
+ * typed value win.
+ */
+export declare const dedupeOptions: (options: OptionEntry[]) => OptionEntry[];
+/**
+ * Serializes resource options into a TLV block.
+ * Reuses the user-headers TLV encoding: each field is
+ * `[kind:u8][len:u32_le][bytes]`, alternating key, value.
+ * Empty options serialize to zero bytes.
+ *
+ * @param options - Option entries to serialize
+ * @returns Serialized options block
+ * @throws Error if an options constraint is violated
+ */
+export declare const serializeOptions: (options: OptionEntry[]) => Buffer;
+/**
+ * Deserializes a bare options TLV block spanning `[pos, end)`.
+ *
+ * @param p - Buffer containing the options block
+ * @param pos - Starting position of the block
+ * @param end - End position of the block (exclusive)
+ * @returns Deserialized options keyed by option name
+ * @throws Error if a key is not a string or the block is malformed
+ */
+export declare const deserializeOptions: (p: Buffer, pos?: number, end?: number) => ParsedOptions;
+/**
+ * Deserializes a `u32_le`-length-prefixed options block at `pos`.
+ *
+ * @param p - Buffer containing `[options_len:u32_le][options TLV]`
+ * @param pos - Starting position of the length prefix
+ * @returns Bytes consumed (prefix included) and deserialized options
+ */
+export declare const deserializePrefixedOptions: (p: Buffer, pos?: number) => OptionsDeserialized;
+//# sourceMappingURL=options.utils.d.ts.map

package/dist/wire/options.utils.js

@@ -0,0 +1,144 @@
+// 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 { HeaderKind } from './message/header.type.js';
+import { serializeHeaders, serializeHeaderValue, deserializeHeaderValue, HeaderKeyFactory, } from './message/header.utils.js';
+/** Maximum number of key-value entries in one options block. */
+export const MAX_OPTIONS = 1024;
+/**
+ * Maximum total byte length of an encoded options block.
+ *
+ * Mirrors the Rust `MAX_OPTIONS_BYTES`, which in turn mirrors the user-headers
+ * budget: options ride that codec and inherit its limit.
+ */
+export const MAX_OPTIONS_BYTES = 100 * 1000;
+/**
+ * Key and value length bound, in encoded bytes rather than characters.
+ * Inherited from the header-field codec rather than being an options-specific
+ * rule: the server refuses a block carrying a field outside this range.
+ */
+const MAX_HEADER_FIELD_LENGTH = 255;
+/**
+ * Keeps the last entry for each key, preserving first-seen order.
+ *
+ * A block carrying a key twice is refused whole by wire validation, so callers
+ * that append their own entries ahead of the typed ones rely on this to let the
+ * typed value win.
+ */
+export const dedupeOptions = (options) => {
+    const byKey = new Map();
+    for (const entry of options)
+        byKey.set(entry.key, entry);
+    return [...byKey.values()];
+};
+/**
+ * Rejects a key or value the codec cannot express.
+ *
+ * `serializeHeaders` writes whatever field length it is handed, so without
+ * this the block leaves here well-formed and comes back as a generic server
+ * error naming neither the key nor the bound it broke.
+ */
+const checkFieldLength = (length, field) => {
+    if (length < 1 || length > MAX_HEADER_FIELD_LENGTH)
+        throw new Error(`Invalid option ${field} length: ${length} bytes, ` +
+            `must be between 1 and ${MAX_HEADER_FIELD_LENGTH}`);
+};
+/**
+ * Serializes resource options into a TLV block.
+ * Reuses the user-headers TLV encoding: each field is
+ * `[kind:u8][len:u32_le][bytes]`, alternating key, value.
+ * Empty options serialize to zero bytes.
+ *
+ * @param options - Option entries to serialize
+ * @returns Serialized options block
+ * @throws Error if an options constraint is violated
+ */
+export const serializeOptions = (options) => {
+    if (options.length > MAX_OPTIONS)
+        throw new Error(`Options block has ${options.length} entries, exceeds maximum ${MAX_OPTIONS}`);
+    for (const { key, value } of options) {
+        checkFieldLength(Buffer.byteLength(key), `key '${key}'`);
+        checkFieldLength(serializeHeaderValue(value).length, `value for key '${key}'`);
+    }
+    const block = serializeHeaders(options.map(({ key, value }) => ({ key: HeaderKeyFactory.String(key), value })));
+    if (block.length > MAX_OPTIONS_BYTES)
+        throw new Error(`Options block is ${block.length} bytes, exceeds maximum ${MAX_OPTIONS_BYTES}`);
+    return block;
+};
+/**
+ * Deserializes a bare options TLV block spanning `[pos, end)`.
+ *
+ * @param p - Buffer containing the options block
+ * @param pos - Starting position of the block
+ * @param end - End position of the block (exclusive)
+ * @returns Deserialized options keyed by option name
+ * @throws Error if a key is not a string or the block is malformed
+ */
+export const deserializeOptions = (p, pos = 0, end = p.length) => {
+    const options = {};
+    while (pos < end) {
+        const keyKind = p.readUInt8(pos);
+        if (keyKind !== HeaderKind.String)
+            throw new Error(`Option key kind ${keyKind} is not a string`);
+        const keyLength = p.readUInt32LE(pos + 1);
+        if (keyLength < 1 || keyLength > MAX_HEADER_FIELD_LENGTH)
+            throw new Error(`Invalid option key length: ${keyLength}, ` +
+                `must be between 1 and ${MAX_HEADER_FIELD_LENGTH}`);
+        if (pos + 5 + keyLength > end)
+            throw new Error('Option key overruns the block');
+        const key = p.subarray(pos + 5, pos + 5 + keyLength).toString();
+        pos += 5 + keyLength;
+        const valueKind = p.readUInt8(pos);
+        const valueLength = p.readUInt32LE(pos + 1);
+        if (pos + 5 + valueLength > end)
+            throw new Error(`Option value for key '${key}' overruns the block`);
+        const valueBytes = p.subarray(pos + 5, pos + 5 + valueLength);
+        pos += 5 + valueLength;
+        let value;
+        try {
+            value = deserializeHeaderValue(valueKind, valueBytes);
+        }
+        catch {
+            // Unknown value kinds stay raw bytes, mirroring the wire
+            // forward-compatibility contract for options.
+            value = valueBytes;
+        }
+        options[key] = value;
+    }
+    return options;
+};
+/**
+ * Deserializes a `u32_le`-length-prefixed options block at `pos`.
+ *
+ * @param p - Buffer containing `[options_len:u32_le][options TLV]`
+ * @param pos - Starting position of the length prefix
+ * @returns Bytes consumed (prefix included) and deserialized options
+ */
+export const deserializePrefixedOptions = (p, pos = 0) => {
+    const length = p.readUInt32LE(pos);
+    const end = pos + 4 + length;
+    // Without this, `subarray` clamps a truncated block silently: a known-kind
+    // value throws inside `deserializeHeaderValue`, the forward-compat catch
+    // swallows it and hands back raw bytes, and `bytesRead` over-reports so every
+    // later field decodes from the wrong offset.
+    if (end > p.length)
+        throw new Error(`Options block overruns the payload: ${length} bytes declared at ${pos}, ` +
+            `${p.length - pos - 4} available`);
+    const options = deserializeOptions(p, pos + 4, end);
+    return { bytesRead: 4 + length, options };
+};
+//# sourceMappingURL=options.utils.js.map

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

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

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

@@ -0,0 +1,102 @@
+// 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 { serializeOptions, deserializePrefixedOptions } from './options.utils.js';
+import { HeaderValue } from './message/header.utils.js';
+const prefixed = (block) => {
+    const length = Buffer.alloc(4);
+    length.writeUInt32LE(block.length, 0);
+    return Buffer.concat([length, block]);
+};
+/**
+ * The cross-SDK golden vector for an options 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.
+ */
+const GOLDEN_OPTIONS_BLOCK = Buffer.from([
+    2, 13, 0, 0, 0,
+    ...Buffer.from('enforce_fsync'),
+    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
+]);
+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) }
+        ]);
+        assert.deepEqual(encoded, GOLDEN_OPTIONS_BLOCK);
+    });
+    it('refuses an empty key', () => {
+        assert.throws(() => serializeOptions([{ key: '', value: HeaderValue.Bool(true) }]), /Invalid option key '' length: 0 bytes/);
+    });
+    it('refuses a key past the field bound', () => {
+        assert.throws(() => serializeOptions([
+            { key: 'k'.repeat(256), value: HeaderValue.Bool(true) }
+        ]), /length: 256 bytes, must be between 1 and 255/);
+    });
+    it('bounds the key on encoded bytes, not characters', () => {
+        // 128 two-byte characters: a character count reads 128 and lets this
+        // through, leaving the server to refuse the whole block.
+        assert.throws(() => serializeOptions([
+            { key: 'ключ'.repeat(32), value: HeaderValue.Bool(true) }
+        ]), /length: 256 bytes/);
+    });
+    it('accepts a key exactly at the field bound', () => {
+        const encoded = serializeOptions([
+            { key: 'k'.repeat(255), value: HeaderValue.Bool(true) }
+        ]);
+        assert.equal(encoded.readUInt32LE(1), 255);
+    });
+    it('refuses a value past the field bound', () => {
+        assert.throws(() => serializeOptions([
+            { key: 'segment_size', value: HeaderValue.String('v'.repeat(256)) }
+        ]), /Invalid option value for key 'segment_size' length: 256 bytes/);
+    });
+    it('refuses an empty value', () => {
+        assert.throws(() => serializeOptions([
+            { key: 'segment_size', value: HeaderValue.Raw(Buffer.alloc(0)) }
+        ]), /Invalid option value for key 'segment_size' length: 0 bytes/);
+    });
+});
+describe('deserializePrefixedOptions', () => {
+    it('reads a whole block and reports the bytes it consumed', () => {
+        const block = prefixed(serializeOptions([
+            { key: 'segment_size', value: HeaderValue.Uint64(1048576n) }
+        ]));
+        const { bytesRead, options } = deserializePrefixedOptions(block);
+        assert.equal(bytesRead, block.length);
+        assert.deepEqual(options, { segment_size: 1048576n });
+    });
+    it('rejects a block whose declared length runs past the payload', () => {
+        // `subarray` clamps instead of throwing, so without the bounds check the
+        // truncated value comes back as raw bytes through the forward-compat catch
+        // and `bytesRead` over-reports, shifting every later field.
+        const block = prefixed(serializeOptions([
+            { key: 'segment_size', value: HeaderValue.Uint64(1048576n) }
+        ]));
+        assert.throws(() => deserializePrefixedOptions(block.subarray(0, block.length - 4)), /overruns the payload/);
+    });
+});
+//# sourceMappingURL=options.utils.test.js.map

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

@@ -1,3 +1,4 @@
+import { type ParsedOptions } from '../options.utils.js';
 /**
  * Stream information returned from the server.
  */
@@ -14,6 +15,8 @@ export type Stream = {
     messagesCount: bigint;
     /** Stream creation timestamp */
     createdAt: Date;
+    /** Options the client explicitly sent at create */
+    options: ParsedOptions;
 };
 /**
  * Result of deserializing a stream.

package/dist/wire/stream/stream.utils.js

@@ -16,6 +16,7 @@
 // under the License.
 //
 import { toDate } from '../serialize.utils.js';
+import { deserializePrefixedOptions } from '../options.utils.js';
 /**
  * Deserializes a stream from a buffer.
  *
@@ -34,10 +35,11 @@ export const deserializeToStream = (r, pos = 0) => {
     const messagesCount = r.readBigUint64LE(pos + 24);
     const nameLength = r.readUInt8(pos + 32);
     const name = r.subarray(pos + 33, pos + 33 + nameLength).toString();
+    const { bytesRead: optionsBytes, options } = deserializePrefixedOptions(r, pos + 33 + nameLength);
     return {
-        bytesRead: 33 + nameLength,
+        bytesRead: 33 + nameLength + optionsBytes,
         data: {
-            id, name, topicsCount, messagesCount, sizeBytes, createdAt
+            id, name, topicsCount, messagesCount, sizeBytes, createdAt, options
         }
     };
 };

package/dist/wire/system/describe-options.command.d.ts

@@ -0,0 +1,33 @@
+import type { CommandResponse } from '../../client/index.js';
+/** Resource whose option catalog the server serves. */
+export declare const OptionsScope: {
+    readonly Topic: 1;
+    readonly Stream: 2;
+    readonly User: 3;
+};
+export type OptionsScope = typeof OptionsScope[keyof typeof OptionsScope];
+/**
+ * One catalog entry: the key a create command accepts, the kind the server
+ * encodes its default under, that default, and what the option does.
+ *
+ * `kind` is this key's canonical kind: what the server encodes its default
+ * under, and what a value set at create is stored as whatever kind it was sent
+ * in, since create admission re-encodes the block from its own parse. An update
+ * stores the client's bytes verbatim and is the exception.
+ */
+export type OptionSpec = {
+    key: string;
+    kind: number;
+    defaultValue: Buffer;
+    description: string;
+};
+export type DescribeOptions = {
+    scope: OptionsScope;
+};
+export declare const DESCRIBE_OPTIONS: {
+    code: number;
+    serialize: ({ scope }: DescribeOptions) => Buffer<ArrayBuffer>;
+    deserialize: (r: CommandResponse) => OptionSpec[];
+};
+export declare const describeOptions: (getClient: import("../../client/client.type.js").ClientProvider) => (arg: DescribeOptions) => Promise<OptionSpec[]>;
+//# sourceMappingURL=describe-options.command.d.ts.map

package/dist/wire/system/describe-options.command.js

@@ -0,0 +1,63 @@
+// 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 { COMMAND_CODE } from '../command.code.js';
+import { wrapCommand } from '../command.utils.js';
+/** Resource whose option catalog the server serves. */
+export const OptionsScope = {
+    Topic: 1,
+    Stream: 2,
+    User: 3
+};
+const deserializeDescribeOptions = (b) => {
+    const count = b.readUInt32LE(0);
+    let position = 4;
+    const specs = [];
+    for (let i = 0; i < count; i++) {
+        const keyLength = b.readUInt8(position);
+        position += 1;
+        if (position + keyLength > b.length)
+            throw new Error(`Option key overruns the response at offset ${position}`);
+        const key = b.subarray(position, position + keyLength).toString();
+        position += keyLength;
+        const kind = b.readUInt8(position);
+        position += 1;
+        const defaultLength = b.readUInt32LE(position);
+        position += 4;
+        if (position + defaultLength > b.length)
+            throw new Error(`Default value for '${key}' overruns the response`);
+        const defaultValue = Buffer.from(b.subarray(position, position + defaultLength));
+        position += defaultLength;
+        const descriptionLength = b.readUInt32LE(position);
+        position += 4;
+        if (position + descriptionLength > b.length)
+            throw new Error(`Description for '${key}' overruns the response`);
+        const description = b.subarray(position, position + descriptionLength).toString();
+        position += descriptionLength;
+        specs.push({ key, kind, defaultValue, description });
+    }
+    return specs;
+};
+export const DESCRIBE_OPTIONS = {
+    code: COMMAND_CODE.DescribeOptions,
+    serialize: ({ scope }) => {
+        return Buffer.from([scope]);
+    },
+    deserialize: (r) => deserializeDescribeOptions(r.data)
+};
+export const describeOptions = wrapCommand(DESCRIBE_OPTIONS);
+//# sourceMappingURL=describe-options.command.js.map