apache-iggy 0.6.0 → 0.7.0

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

@@ -16,176 +16,303 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import { boolToBuf, int8ToBuf, int16ToBuf, int32ToBuf, int64ToBuf, uint8ToBuf, uint16ToBuf, uint32ToBuf, uint64ToBuf, floatToBuf, doubleToBuf } from '../number.utils.js';
-import { HeaderKind, ReverseHeaderKind } from './header.type.js';
+import { boolToBuf, int8ToBuf, int16ToBuf, int32ToBuf, int64ToBuf, uint8ToBuf, uint16ToBuf, uint32ToBuf, uint64ToBuf, floatToBuf, doubleToBuf, } from "../number.utils.js";
+import { HeaderKind, ReverseHeaderKind, expectedSize, } from "./header.type.js";
+/**
+ * Serializes a header value to a Buffer based on its kind.
+ *
+ * @param header - Header value to serialize
+ * @returns Serialized value as Buffer
+ */
 export const serializeHeaderValue = (header) => {
     const { kind, value } = header;
     switch (kind) {
-        case HeaderKind.Raw: return value;
-        case HeaderKind.String: return Buffer.from(value);
-        case HeaderKind.Bool: return boolToBuf(value);
-        case HeaderKind.Int8: return int8ToBuf(value);
-        case HeaderKind.Int16: return int16ToBuf(value);
-        case HeaderKind.Int32: return int32ToBuf(value);
-        case HeaderKind.Int64: return int64ToBuf(value);
-        case HeaderKind.Int128: return value;
-        case HeaderKind.Uint8: return uint8ToBuf(value);
-        case HeaderKind.Uint16: return uint16ToBuf(value);
-        case HeaderKind.Uint32: return uint32ToBuf(value);
-        case HeaderKind.Uint64: return uint64ToBuf(value);
-        case HeaderKind.Uint128: return value;
-        case HeaderKind.Float: return floatToBuf(value);
-        case HeaderKind.Double: return doubleToBuf(value);
+        case HeaderKind.Raw:
+            return value;
+        case HeaderKind.String:
+            return Buffer.from(value);
+        case HeaderKind.Bool:
+            return boolToBuf(value);
+        case HeaderKind.Int8:
+            return int8ToBuf(value);
+        case HeaderKind.Int16:
+            return int16ToBuf(value);
+        case HeaderKind.Int32:
+            return int32ToBuf(value);
+        case HeaderKind.Int64:
+            return int64ToBuf(value);
+        case HeaderKind.Int128:
+            return value;
+        case HeaderKind.Uint8:
+            return uint8ToBuf(value);
+        case HeaderKind.Uint16:
+            return uint16ToBuf(value);
+        case HeaderKind.Uint32:
+            return uint32ToBuf(value);
+        case HeaderKind.Uint64:
+            return uint64ToBuf(value);
+        case HeaderKind.Uint128:
+            return value;
+        case HeaderKind.Float:
+            return floatToBuf(value);
+        case HeaderKind.Double:
+            return doubleToBuf(value);
+    }
+};
+/**
+ * Serializes a header key to a Buffer based on its kind.
+ *
+ * @param key - Header key to serialize
+ * @returns Serialized key as Buffer
+ */
+export const serializeHeaderKey = (key) => {
+    const { kind, value } = key;
+    switch (kind) {
+        case HeaderKind.Raw:
+            return value;
+        case HeaderKind.String:
+            return Buffer.from(value);
+        case HeaderKind.Int32:
+            return int32ToBuf(value);
     }
 };
+/**
+ * Serializes a single header key-value pair to wire format.
+ * Format: [key_kind][key_length][key][value_kind][value_length][value]
+ *
+ * @param key - Header key
+ * @param v - Binary header value
+ * @returns Serialized header as Buffer
+ */
 export const serializeHeader = (key, v) => {
-    const bKey = Buffer.from(key);
-    const b1 = uint32ToBuf(bKey.length);
-    const b2 = Buffer.alloc(5);
-    b2.writeUInt8(v.kind);
-    b2.writeUInt32LE(v.value.length, 1);
-    // @TODO debug
-    // console.log(
-    //   'SERIALIZE\n',
-    //   'KEY-LEN', b1.length, b1.toString('hex'), '=', b1.readUInt32LE(0), '\n',
-    //   'KEY', bKey.length, bKey.toString('hex'), '\n',
-    //   'KIND', b2.readUInt8(0), b2.subarray(0, 1).toString('hex'), '\n',
-    //   'V-LEN', b2.readUInt32LE(1), b2.subarray(1, 5).toString('hex'), '\n',
-    //   'V', v.value.length, v.value.toString('hex')
-    // );
-    return Buffer.concat([
-        b1,
-        bKey,
-        b2,
-        v.value
-    ]);
+    const bKey = serializeHeaderKey(key);
+    const keyHeader = Buffer.alloc(5);
+    keyHeader.writeUInt8(key.kind);
+    keyHeader.writeUInt32LE(bKey.length, 1);
+    const valueHeader = Buffer.alloc(5);
+    valueHeader.writeUInt8(v.kind);
+    valueHeader.writeUInt32LE(v.value.length, 1);
+    return Buffer.concat([keyHeader, bKey, valueHeader, v.value]);
 };
+/** Empty headers buffer constant */
 export const EMPTY_HEADERS = Buffer.alloc(0);
+/**
+ * Creates a binary header value from a typed header value.
+ *
+ * @param header - Typed header value
+ * @returns Binary header value
+ */
 const createHeaderValue = (header) => ({
     kind: header.kind,
-    value: serializeHeaderValue(header)
+    value: serializeHeaderValue(header),
 });
+/**
+ * Serializes all headers to a single buffer.
+ *
+ * @param headers - Optional headers array
+ * @returns Serialized headers buffer (empty if no headers)
+ */
 export const serializeHeaders = (headers) => {
-    if (!headers)
+    if (!headers || headers.length === 0)
         return EMPTY_HEADERS;
-    return Buffer.concat(Object.keys(headers).map((c) => serializeHeader(c, createHeaderValue(headers[c]))));
+    return Buffer.concat(headers.map((entry) => serializeHeader(entry.key, createHeaderValue(entry.value))));
 };
+/**
+ * Maps a numeric header kind to its string identifier.
+ *
+ * @param k - Numeric header kind value
+ * @returns Header kind identifier string
+ * @throws Error if the header kind is unknown
+ */
 export const mapHeaderKind = (k) => {
     if (!ReverseHeaderKind[k])
         throw new Error(`unknow header kind: ${k}`);
     return ReverseHeaderKind[k];
 };
+/**
+ * Deserializes a header value buffer based on its kind.
+ *
+ * @param kind - Numeric header kind
+ * @param value - Raw value buffer
+ * @returns Deserialized value
+ * @throws Error if the header kind is invalid
+ */
 export const deserializeHeaderValue = (kind, value) => {
     switch (kind) {
         case HeaderKind.Int128:
         case HeaderKind.Uint128:
-        case HeaderKind.Raw: return value;
-        case HeaderKind.String: return value.toString();
-        case HeaderKind.Int8: return value.readInt8();
-        case HeaderKind.Int16: return value.readInt16LE();
-        case HeaderKind.Int32: return value.readInt32LE();
-        case HeaderKind.Int64: return value.readBigInt64LE();
-        case HeaderKind.Uint8: return value.readUint8();
-        case HeaderKind.Uint16: return value.readUint16LE();
-        case HeaderKind.Uint32: return value.readUInt32LE();
-        case HeaderKind.Uint64: return value.readBigUInt64LE();
-        case HeaderKind.Bool: return value.readUInt8() === 1;
-        case HeaderKind.Float: return value.readFloatLE();
-        case HeaderKind.Double: return value.readDoubleLE();
-        default: throw new Error(`deserializeHeaderValue: invalid HeaderKind ${kind}`);
+        case HeaderKind.Raw:
+            return value;
+        case HeaderKind.String:
+            return value.toString();
+        case HeaderKind.Int8:
+            return value.readInt8();
+        case HeaderKind.Int16:
+            return value.readInt16LE();
+        case HeaderKind.Int32:
+            return value.readInt32LE();
+        case HeaderKind.Int64:
+            return value.readBigInt64LE();
+        case HeaderKind.Uint8:
+            return value.readUint8();
+        case HeaderKind.Uint16:
+            return value.readUint16LE();
+        case HeaderKind.Uint32:
+            return value.readUInt32LE();
+        case HeaderKind.Uint64:
+            return value.readBigUInt64LE();
+        case HeaderKind.Bool:
+            return value.readUInt8() === 1;
+        case HeaderKind.Float:
+            return value.readFloatLE();
+        case HeaderKind.Double:
+            return value.readDoubleLE();
+        default:
+            throw new Error(`deserializeHeaderValue: invalid HeaderKind ${kind}`);
     }
 };
+/**
+ * Deserializes a single header from a buffer.
+ * Format: [key_kind][key_length][key][value_kind][value_length][value]
+ *
+ * @param p - Buffer containing serialized headers
+ * @param pos - Starting position in the buffer
+ * @returns Object with bytes read and deserialized header data
+ * @throws Error if header key or value length is invalid (must be 1-255)
+ */
 export const deserializeHeader = (p, pos = 0) => {
-    const keyLength = p.readUInt32LE(pos);
-    const key = p.subarray(pos + 4, pos + 4 + keyLength).toString();
-    pos += keyLength + 4;
-    const rawKind = p.readUInt8(pos);
-    // @TODO ?
-    // const kind = mapHeaderKind(rawKind); 
+    const keyKind = p.readUInt8(pos);
+    const keyLength = p.readUInt32LE(pos + 1);
+    if (keyLength < 1 || keyLength > 255) {
+        throw new Error(`Invalid header key length: ${keyLength}, must be between 1 and 255`);
+    }
+    const keyExpected = expectedSize(keyKind);
+    if (keyExpected !== -1 && keyLength !== keyExpected) {
+        throw new Error(`Invalid header key size for kind ${keyKind}: expected ${keyExpected}, got ${keyLength}`);
+    }
+    const keyValue = deserializeHeaderValue(keyKind, p.subarray(pos + 5, pos + 5 + keyLength));
+    pos += 5 + keyLength;
+    const valueKind = p.readUInt8(pos);
     const valueLength = p.readUInt32LE(pos + 1);
-    const value = deserializeHeaderValue(rawKind, p.subarray(pos + 5, pos + 5 + valueLength));
+    if (valueLength < 1 || valueLength > 255) {
+        throw new Error(`Invalid header value length: ${valueLength}, must be between 1 and 255`);
+    }
+    const valueExpected = expectedSize(valueKind);
+    if (valueExpected !== -1 && valueLength !== valueExpected) {
+        throw new Error(`Invalid header value size for kind ${valueKind}: expected ${valueExpected}, got ${valueLength}`);
+    }
+    const value = deserializeHeaderValue(valueKind, p.subarray(pos + 5, pos + 5 + valueLength));
     return {
-        bytesRead: 4 + 4 + 1 + keyLength + valueLength,
+        bytesRead: 5 + keyLength + 5 + valueLength,
         data: {
-            key,
-            kind: rawKind,
-            value
-        }
+            key: { kind: keyKind, value: keyValue },
+            value: { kind: valueKind, value },
+        },
     };
 };
+/**
+ * Deserializes all headers from a buffer.
+ *
+ * @param p - Buffer containing serialized headers
+ * @param pos - Starting position in the buffer
+ * @returns Array of parsed header entries
+ */
 export const deserializeHeaders = (p, pos = 0) => {
-    const headers = {};
+    const headers = [];
     const len = p.length;
     while (pos < len) {
-        const { bytesRead, data: { kind, key, value } } = deserializeHeader(p, pos);
-        headers[key] = { kind, value };
+        const { bytesRead, data } = deserializeHeader(p, pos);
+        headers.push(data);
         pos += bytesRead;
     }
     return headers;
 };
-/** HeaderValue Helper */
+/**
+ * HeaderValue factory functions and utilities.
+ * Provides type-safe constructors for each header value type.
+ */
+/** Creates a raw binary header value */
 const Raw = (value) => ({
     kind: HeaderKind.Raw,
-    value
+    value,
 });
+/** Creates a string header value */
 const String = (value) => ({
     kind: HeaderKind.String,
-    value
+    value,
 });
+/** Creates a boolean header value */
 const Bool = (value) => ({
     kind: HeaderKind.Bool,
-    value
+    value,
 });
+/** Creates an Int8 header value */
 const Int8 = (value) => ({
     kind: HeaderKind.Int8,
-    value
+    value,
 });
+/** Creates an Int16 header value */
 const Int16 = (value) => ({
     kind: HeaderKind.Int16,
-    value
+    value,
 });
+/** Creates an Int32 header value */
 const Int32 = (value) => ({
     kind: HeaderKind.Int32,
-    value
+    value,
 });
+/** Creates an Int64 header value */
 const Int64 = (value) => ({
     kind: HeaderKind.Int64,
-    value
+    value,
 });
+/** Creates an Int128 header value */
 const Int128 = (value) => ({
     kind: HeaderKind.Int128,
-    value
+    value,
 });
+/** Creates a Uint8 header value */
 const Uint8 = (value) => ({
     kind: HeaderKind.Uint8,
-    value
+    value,
 });
+/** Creates a Uint16 header value */
 const Uint16 = (value) => ({
     kind: HeaderKind.Uint16,
-    value
+    value,
 });
+/** Creates a Uint32 header value */
 const Uint32 = (value) => ({
     kind: HeaderKind.Uint32,
-    value
+    value,
 });
+/** Creates a Uint64 header value */
 const Uint64 = (value) => ({
     kind: HeaderKind.Uint64,
-    value
+    value,
 });
+/** Creates a Uint128 header value */
 const Uint128 = (value) => ({
     kind: HeaderKind.Uint128,
-    value
+    value,
 });
+/** Creates a Float header value */
 const Float = (value) => ({
     kind: HeaderKind.Float,
-    value
+    value,
 });
+/** Creates a Double header value */
 const Double = (value) => ({
     kind: HeaderKind.Double,
-    value
+    value,
 });
+/** Gets the kind identifier string of a header value */
 const getKind = (h) => mapHeaderKind(h.kind);
+/** Gets the value from a header value */
 const getValue = (h) => h.value;
+/**
+ * HeaderValue factory object with constructors for all header types.
+ */
 export const HeaderValue = {
     Raw,
     String,
@@ -203,7 +330,27 @@ export const HeaderValue = {
     Float,
     Double,
     getKind,
-    getValue
+    getValue,
+};
+/** Creates a raw binary header key */
+const keyRaw = (value) => ({
+    kind: HeaderKind.Raw,
+    value,
+});
+/** Creates a string header key */
+const keyString = (value) => ({
+    kind: HeaderKind.String,
+    value,
+});
+/** Creates an Int32 header key */
+const keyInt32 = (value) => ({
+    kind: HeaderKind.Int32,
+    value,
+});
+export const HeaderKeyFactory = {
+    Raw: keyRaw,
+    String: keyString,
+    Int32: keyInt32,
 };
 // export type InputHeaderValue = boolean | number | string | bigint | Buffer;
 // export type InputHeaders = Record<string, InputHeaderValue>;

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

@@ -16,24 +16,47 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import { uuidv7, uuidv4 } from 'uuidv7';
-import { serializeHeaders, deserializeHeaders, HeaderValue } from './header.utils.js';
-describe('Headers', () => {
-    const headers = {
-        'p': HeaderValue.Bool(true),
-        'x': HeaderValue.Uint32(123),
-        'y': HeaderValue.Uint64(42n),
-        'z': HeaderValue.Float(42.20000076293945),
-        'a': HeaderValue.Double(1 / 3),
-        'ID': HeaderValue.String(uuidv7()),
-        'val': HeaderValue.Raw(Buffer.from(uuidv4()))
-    };
-    it('serialize/deserialize', () => {
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { uuidv7, uuidv4 } from "uuidv7";
+import { serializeHeaders, deserializeHeaders, HeaderValue, HeaderKeyFactory, } from "./header.utils.js";
+import { HeaderKind } from "./header.type.js";
+describe("Headers", () => {
+    const headers = [
+        { key: HeaderKeyFactory.String("p"), value: HeaderValue.Bool(true) },
+        { key: HeaderKeyFactory.String("x"), value: HeaderValue.Uint32(123) },
+        { key: HeaderKeyFactory.String("y"), value: HeaderValue.Uint64(42n) },
+        {
+            key: HeaderKeyFactory.String("z"),
+            value: HeaderValue.Float(42.20000076293945),
+        },
+        { key: HeaderKeyFactory.String("a"), value: HeaderValue.Double(1 / 3) },
+        { key: HeaderKeyFactory.String("ID"), value: HeaderValue.String(uuidv7()) },
+        {
+            key: HeaderKeyFactory.String("val"),
+            value: HeaderValue.Raw(Buffer.from(uuidv4())),
+        },
+    ];
+    it("serialize/deserialize string keys", () => {
         const s = serializeHeaders(headers);
         const d = deserializeHeaders(s);
-        assert.deepEqual(headers, d);
+        assert.equal(d.length, headers.length);
+        for (let i = 0; i < headers.length; i++) {
+            assert.equal(d[i].key.kind, headers[i].key.kind);
+            assert.equal(d[i].value.kind, headers[i].value.kind);
+        }
+    });
+    it("serialize/deserialize int32 key", () => {
+        const int32Headers = [
+            { key: HeaderKeyFactory.Int32(42), value: HeaderValue.String("test") },
+        ];
+        const s = serializeHeaders(int32Headers);
+        const d = deserializeHeaders(s);
+        assert.equal(d.length, 1);
+        assert.equal(d[0].key.kind, HeaderKind.Int32);
+        assert.equal(d[0].key.value, 42);
+        assert.equal(d[0].value.kind, HeaderKind.String);
+        assert.equal(d[0].value.value, "test");
     });
 });
 //# sourceMappingURL=header.utils.test.js.map

package/dist/wire/message/iggy-header.utils.d.ts

@@ -16,17 +16,55 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+/**
+ * Iggy message header containing metadata for each message.
+ */
 export type IggyMessageHeader = {
+    /** Message checksum for integrity verification */
     checksum: bigint;
-    id: string | BigInt;
+    /** Unique message identifier (UUID or numeric) */
+    id: string | bigint;
+    /** Message offset within the partition */
     offset: bigint;
+    /** Server-assigned timestamp */
     timestamp: Date;
+    /** Client-provided origin timestamp */
     originTimestamp: Date;
+    /** Length of user-defined headers in bytes */
     userHeadersLength: number;
+    /** Length of message payload in bytes */
     payloadLength: number;
+    /** Reserved for future use */
+    reserved: bigint;
 };
+/**
+ * Size of the Iggy message header in bytes.
+ * Layout: u64 (checksum) + u128 (id) + u64 (offset) + u64 (timestamp) + u64 (originTimestamp) + u32 (userHeadersLength) + u32 (payloadLength) + u64 (reserved)
+ */
 export declare const IGGY_MESSAGE_HEADER_SIZE: number;
+/**
+ * Serializes an Iggy message header to wire format.
+ * Sets checksum, offset, and timestamp to zero (filled by server).
+ *
+ * @param id - Message ID as 16-byte buffer
+ * @param payload - Message payload
+ * @param userHeaders - Serialized user headers
+ * @returns Serialized header buffer
+ */
 export declare const serializeIggyMessageHeader: (id: Buffer, payload: Buffer, userHeaders: Buffer) => Buffer<ArrayBuffer>;
+/**
+ * Deserializes a message ID from a 16-byte buffer to BigInt.
+ *
+ * @param b - 16-byte buffer containing the message ID
+ * @returns Message ID as BigInt
+ */
 export declare const deserialiseMessageId: (b: Buffer) => bigint;
+/**
+ * Deserializes Iggy message headers from a buffer.
+ *
+ * @param b - Buffer containing the serialized header
+ * @returns Parsed IggyMessageHeader object
+ * @throws Error if buffer length doesn't match expected header size
+ */
 export declare const deserializeIggyMessageHeaders: (b: Buffer) => IggyMessageHeader;
 //# sourceMappingURL=iggy-header.utils.d.ts.map

package/dist/wire/message/iggy-header.utils.js

@@ -18,8 +18,20 @@
  */
 import { toDate } from "../serialize.utils.js";
 import { u128LEBufToBigint } from "../number.utils.js";
-// u64 + u128 + u64 + u64 + u64 + u32 + u32
-export const IGGY_MESSAGE_HEADER_SIZE = 8 + 16 + 8 + 8 + 8 + 4 + 4;
+/**
+ * Size of the Iggy message header in bytes.
+ * Layout: u64 (checksum) + u128 (id) + u64 (offset) + u64 (timestamp) + u64 (originTimestamp) + u32 (userHeadersLength) + u32 (payloadLength) + u64 (reserved)
+ */
+export const IGGY_MESSAGE_HEADER_SIZE = 8 + 16 + 8 + 8 + 8 + 4 + 4 + 8;
+/**
+ * Serializes an Iggy message header to wire format.
+ * Sets checksum, offset, and timestamp to zero (filled by server).
+ *
+ * @param id - Message ID as 16-byte buffer
+ * @param payload - Message payload
+ * @param userHeaders - Serialized user headers
+ * @returns Serialized header buffer
+ */
 export const serializeIggyMessageHeader = (id, payload, userHeaders) => {
     const b = Buffer.allocUnsafe(IGGY_MESSAGE_HEADER_SIZE);
     b.writeBigUInt64LE(0n, 0); // checksum u64
@@ -29,9 +41,23 @@ export const serializeIggyMessageHeader = (id, payload, userHeaders) => {
     b.writeBigUint64LE(BigInt(new Date().getTime()), 40); // originTimestamp u64
     b.writeUInt32LE(userHeaders.length, 48); // userHeaders len u32
     b.writeUInt32LE(payload.length, 52); // payload len u32
+    b.writeBigUInt64LE(0n, 56); // reserved u64
     return b;
 };
+/**
+ * Deserializes a message ID from a 16-byte buffer to BigInt.
+ *
+ * @param b - 16-byte buffer containing the message ID
+ * @returns Message ID as BigInt
+ */
 export const deserialiseMessageId = (b) => u128LEBufToBigint(b);
+/**
+ * Deserializes Iggy message headers from a buffer.
+ *
+ * @param b - Buffer containing the serialized header
+ * @returns Parsed IggyMessageHeader object
+ * @throws Error if buffer length doesn't match expected header size
+ */
 export const deserializeIggyMessageHeaders = (b) => {
     if (b.length !== IGGY_MESSAGE_HEADER_SIZE)
         throw new Error(`deserialize message headers error, length = ${b.length} ` +
@@ -43,7 +69,8 @@ export const deserializeIggyMessageHeaders = (b) => {
         timestamp: toDate(b.readBigUInt64LE(32)),
         originTimestamp: toDate(b.readBigUInt64LE(40)),
         userHeadersLength: b.readUInt32LE(48),
-        payloadLength: b.readUInt32LE(52)
+        payloadLength: b.readUInt32LE(52),
+        reserved: b.readBigUInt64LE(56),
     };
     return headers;
 };

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

@@ -16,10 +16,10 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-export * from './poll-messages.command.js';
-export * from './send-messages.command.js';
-export * from './message.utils.js';
+export * from "./poll-messages.command.js";
+export * from "./send-messages.command.js";
+export * from "./message.utils.js";
 export * from "./poll.utils.js";
-export { Partitioning } from './partitioning.utils.js';
-export { HeaderValue } from './header.utils.js';
+export { Partitioning } from "./partitioning.utils.js";
+export { HeaderValue, HeaderKeyFactory } from "./header.utils.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/wire/message/index.js

@@ -16,10 +16,10 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-export * from './poll-messages.command.js';
-export * from './send-messages.command.js';
-export * from './message.utils.js';
+export * from "./poll-messages.command.js";
+export * from "./send-messages.command.js";
+export * from "./message.utils.js";
 export * from "./poll.utils.js";
-export { Partitioning } from './partitioning.utils.js';
-export { HeaderValue } from './header.utils.js';
+export { Partitioning } from "./partitioning.utils.js";
+export { HeaderValue, HeaderKeyFactory } from "./header.utils.js";
 //# sourceMappingURL=index.js.map