apache-iggy 0.10.0 → 0.10.1-edge.2

package/dist/wire/system/snapshot.command.js

@@ -0,0 +1,76 @@
+// 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';
+export const SnapshotCompression = {
+    Stored: 1,
+    Deflated: 2,
+    Bzip2: 3,
+    Zstd: 4,
+    Lzma: 5,
+    Xz: 6,
+};
+export const SystemSnapshotType = {
+    FilesystemOverview: 1,
+    ProcessList: 2,
+    ResourceUsage: 3,
+    Test: 4,
+    ServerLogs: 5,
+    ServerConfig: 6,
+    All: 100,
+};
+export const SNAPSHOT_COMPRESSION = SnapshotCompression;
+export const SYSTEM_SNAPSHOT_TYPE = SystemSnapshotType;
+const serializeSnapshot = (payload) => {
+    const compression = payload && payload.compression ? payload.compression : SnapshotCompression.Deflated;
+    const snapshotTypes = payload && payload.snapshotTypes ? payload.snapshotTypes : [SystemSnapshotType.All];
+    if (snapshotTypes.length > 255) {
+        throw new Error('snapshotTypes count cannot exceed 255');
+    }
+    if (snapshotTypes.length > 1 && snapshotTypes.includes(SystemSnapshotType.All)) {
+        throw new Error('SystemSnapshotType.All cannot be combined with specific snapshot types');
+    }
+    const buf = Buffer.allocUnsafe(2 + snapshotTypes.length);
+    buf.writeUInt8(compression, 0);
+    buf.writeUInt8(snapshotTypes.length, 1);
+    for (let i = 0; i < snapshotTypes.length; i++) {
+        buf.writeUInt8(snapshotTypes[i], 2 + i);
+    }
+    return buf;
+};
+export const SNAPSHOT = {
+    code: COMMAND_CODE.GetSnapshot,
+    serialize: serializeSnapshot,
+    deserialize: (r) => r.data
+};
+/**
+ * Captures and packages the current system state as a raw ZIP archive.
+ *
+ * @param options - Optional configuration for snapshot compression and section types.
+ * Defaults to Deflated compression and `SystemSnapshotType.All` (code 100), capturing all
+ * available diagnostic sections (filesystem overview, process list, resource usage, server
+ * logs, and server configuration) for complete debugging.
+ * @returns A Buffer containing the raw ZIP archive bytes.
+ *
+ * @remarks
+ * - Authentication is required, and the caller must have administrative permissions.
+ * - The server enforces a single-flight mutex guard: only one snapshot can be collected
+ *   at a time across the cluster.
+ * - Subject to the client's default 30-second socket timeout budget.
+ */
+export const snapshot = wrapCommand(SNAPSHOT);
+//# sourceMappingURL=snapshot.command.js.map

package/dist/wire/system/snapshot.command.test.d.ts

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

package/dist/wire/system/snapshot.command.test.js

@@ -0,0 +1,86 @@
+// 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 { COMMAND_CODE } from '../command.code.js';
+import { SNAPSHOT, SnapshotCompression, SystemSnapshotType, SNAPSHOT_COMPRESSION, SYSTEM_SNAPSHOT_TYPE } from './snapshot.command.js';
+describe('SnapshotCommand', () => {
+    it('has correct command code', () => {
+        assert.equal(SNAPSHOT.code, COMMAND_CODE.GetSnapshot);
+        assert.equal(SNAPSHOT.code, 11);
+    });
+    describe('serialize', () => {
+        it('serializes default options (Deflated compression and All snapshot type)', () => {
+            const buf = SNAPSHOT.serialize();
+            assert.equal(buf.length, 3);
+            assert.equal(buf.readUInt8(0), SnapshotCompression.Deflated);
+            assert.equal(buf.readUInt8(1), 1);
+            assert.equal(buf.readUInt8(2), SystemSnapshotType.All);
+        });
+        it('serializes custom compression and snapshot types', () => {
+            const buf = SNAPSHOT.serialize({
+                compression: SnapshotCompression.Stored,
+                snapshotTypes: [
+                    SystemSnapshotType.FilesystemOverview,
+                    SystemSnapshotType.ServerLogs
+                ]
+            });
+            assert.equal(buf.length, 4);
+            assert.equal(buf.readUInt8(0), SnapshotCompression.Stored);
+            assert.equal(buf.readUInt8(1), 2);
+            assert.equal(buf.readUInt8(2), SystemSnapshotType.FilesystemOverview);
+            assert.equal(buf.readUInt8(3), SystemSnapshotType.ServerLogs);
+        });
+        it('serializes empty snapshot types', () => {
+            const buf = SNAPSHOT.serialize({
+                compression: SnapshotCompression.Bzip2,
+                snapshotTypes: []
+            });
+            assert.equal(buf.length, 2);
+            assert.equal(buf.readUInt8(0), SnapshotCompression.Bzip2);
+            assert.equal(buf.readUInt8(1), 0);
+        });
+        it('throws when snapshotTypes count exceeds 255', () => {
+            const oversizedTypes = new Array(256).fill(SystemSnapshotType.Test);
+            assert.throws(() => SNAPSHOT.serialize({ snapshotTypes: oversizedTypes }), /snapshotTypes count cannot exceed 255/);
+        });
+        it('throws when SystemSnapshotType.All is mixed with other types', () => {
+            assert.throws(() => SNAPSHOT.serialize({
+                snapshotTypes: [
+                    SystemSnapshotType.All,
+                    SystemSnapshotType.ProcessList
+                ]
+            }), /SystemSnapshotType\.All cannot be combined with specific snapshot types/);
+        });
+        it('supports backwards-compatible enum aliases', () => {
+            assert.equal(SNAPSHOT_COMPRESSION.Deflated, SnapshotCompression.Deflated);
+            assert.equal(SYSTEM_SNAPSHOT_TYPE.All, SystemSnapshotType.All);
+        });
+    });
+    describe('deserialize', () => {
+        it('returns raw payload buffer', () => {
+            const rawData = Buffer.from([0x50, 0x4B, 0x03, 0x04, 1, 2, 3]);
+            const res = SNAPSHOT.deserialize({
+                status: 0,
+                length: rawData.length,
+                data: rawData
+            });
+            assert.deepEqual(res, rawData);
+        });
+    });
+});
+//# sourceMappingURL=snapshot.command.test.js.map

package/dist/wire/system/update-resource.command.d.ts

@@ -0,0 +1,53 @@
+import { type Id } from '../identifier.utils.js';
+import { type OptionEntry } from '../options.utils.js';
+import { OptionsScope } from './describe-options.command.js';
+/** The resource an update patches, tagged by its options scope. */
+export type ResourceTarget = {
+    scope: typeof OptionsScope.Topic;
+    streamId: Id;
+    topicId: Id;
+} | {
+    scope: typeof OptionsScope.Stream;
+    streamId: Id;
+} | {
+    scope: typeof OptionsScope.User;
+    userId: Id;
+};
+/**
+ * Parameters for the generic update: the keys to set, the keys to reset to
+ * their defaults. Every other key keeps its stored value.
+ *
+ * Typed keys are checked here with the category and in the order the server
+ * admits them. A patch carrying any raw entry or raw reset name gets only the
+ * structural checks, because the server catalog may know keys or flags this
+ * build does not, so the server decides the rest.
+ */
+export type UpdateResource = {
+    target: ResourceTarget;
+    /** Keys set through typed fields. A later entry for a key wins */
+    options?: OptionEntry[];
+    /** Keys reset through typed members */
+    reset?: readonly string[];
+    /** Entries with no typed field. A typed entry of the same key wins */
+    rawOptions?: OptionEntry[];
+    /** Reset names with no typed member */
+    rawReset?: readonly string[];
+};
+/**
+ * Update resource command definition, the one update for streams, topics and
+ * users. Layout: `[scope:u8][identifiers][reset_count:u8][reset_key:name]*`
+ * followed by the options block running to the end of the payload. Reset
+ * names and set entries are both written in ascending name byte order.
+ */
+export declare const UPDATE_RESOURCE: {
+    code: number;
+    serialize: ({ target, options, reset, rawOptions, rawReset }: UpdateResource) => Buffer<ArrayBuffer>;
+    deserialize: (r: import("../../index.js").CommandResponse) => boolean;
+};
+/**
+ * A typed column value as an option entry. Text no header value can carry
+ * travels as a bool, a kind the column never accepts, so the refusal is the
+ * column's own error on either side.
+ */
+export declare const columnOption: (key: string, text: string) => OptionEntry;
+//# sourceMappingURL=update-resource.command.d.ts.map

package/dist/wire/system/update-resource.command.js

@@ -0,0 +1,130 @@
+// 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 { deserializeVoidResponse } from '../../client/client.utils.js';
+import { COMMAND_CODE } from '../command.code.js';
+import { responseError } from '../error.utils.js';
+import { serializeIdentifier } from '../identifier.utils.js';
+import { uint8ToBuf } from '../number.utils.js';
+import { HeaderKind } from '../message/header.type.js';
+import { HeaderValue } from '../message/header.utils.js';
+import { OPTION_CATALOG, dedupeOptions, serializeOptions, sortOptions } from '../options.utils.js';
+import { OptionFlag, OptionsScope } from './describe-options.command.js';
+const INVALID_COMMAND = 3;
+const INVALID_USERNAME = 43;
+const INVALID_USER_STATUS = 45;
+const INVALID_STREAM_NAME = 1013;
+const INVALID_TOPIC_NAME = 2014;
+const UNSUPPORTED_OPTION_KEY = 4041;
+const OPTION_NOT_UPDATABLE = 4103;
+const OPTION_NOT_RESETTABLE = 4104;
+const READ_ONLY_OPTION = 4105;
+const MAX_NAME_LENGTH = 255;
+const MAX_RESET_KEYS = 255;
+const KEY_PREVIEW_LENGTH = 64;
+const MIN_USERNAME_LENGTH = 3;
+const MAX_USERNAME_LENGTH = 50;
+/**
+ * Update resource command definition, the one update for streams, topics and
+ * users. Layout: `[scope:u8][identifiers][reset_count:u8][reset_key:name]*`
+ * followed by the options block running to the end of the payload. Reset
+ * names and set entries are both written in ascending name byte order.
+ */
+export const UPDATE_RESOURCE = {
+    code: COMMAND_CODE.UpdateResource,
+    serialize: ({ target, options = [], reset = [], rawOptions = [], rawReset = [] }) => {
+        const set = sortOptions(dedupeOptions([...rawOptions, ...options]));
+        const resetKeys = [...new Set([...reset, ...rawReset])]
+            .sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+        checkPatch(target.scope, set, resetKeys, rawOptions.length > 0 || rawReset.length > 0);
+        const identifiers = target.scope === OptionsScope.Topic
+            ? [serializeIdentifier(target.streamId), serializeIdentifier(target.topicId)]
+            : [serializeIdentifier(target.scope === OptionsScope.Stream ? target.streamId : target.userId)];
+        return Buffer.concat([
+            uint8ToBuf(target.scope),
+            ...identifiers,
+            uint8ToBuf(resetKeys.length),
+            ...resetKeys.map((key) => {
+                const name = Buffer.from(key);
+                return Buffer.concat([uint8ToBuf(name.length), name]);
+            }),
+            serializeOptions(set)
+        ]);
+    },
+    deserialize: deserializeVoidResponse
+};
+/**
+ * A typed column value as an option entry. Text no header value can carry
+ * travels as a bool, a kind the column never accepts, so the refusal is the
+ * column's own error on either side.
+ */
+export const columnOption = (key, text) => {
+    const length = Buffer.byteLength(text);
+    return {
+        key,
+        value: length >= 1 && length <= MAX_NAME_LENGTH ? HeaderValue.String(text) : HeaderValue.Bool(false)
+    };
+};
+/** Refuses a patch with the category and in the order the server admits it. */
+const checkPatch = (scope, set, reset, raw) => {
+    const refuse = (code, detail) => {
+        throw responseError(COMMAND_CODE.UpdateResource, code, detail);
+    };
+    if (set.length === 0 && reset.length === 0)
+        refuse(INVALID_COMMAND, 'the update sets and resets nothing');
+    const conflict = reset.find((key) => set.some((entry) => entry.key === key));
+    if (conflict !== undefined)
+        refuse(INVALID_COMMAND, `key '${conflict}' is both set and reset`);
+    const nameLength = (key) => Buffer.byteLength(key);
+    // The catalog is far smaller than the count byte, so an overlong list always
+    // names a key admission would refuse.
+    const unwritable = reset.find((key) => nameLength(key) < 1 || nameLength(key) > MAX_NAME_LENGTH)
+        ?? (reset.length > MAX_RESET_KEYS
+            ? reset.find((key) => !OPTION_CATALOG.get(key)?.scopes.includes(scope))
+            : undefined);
+    if (unwritable !== undefined)
+        refuse(UNSUPPORTED_OPTION_KEY, `reset of '${unwritable.slice(0, KEY_PREVIEW_LENGTH)}'`);
+    if (raw)
+        return;
+    const keys = [...set.map((entry) => entry.key), ...reset];
+    const outOfScope = keys.find((key) => !OPTION_CATALOG.get(key)?.scopes.includes(scope));
+    if (outOfScope !== undefined)
+        refuse(UNSUPPORTED_OPTION_KEY, `key '${outOfScope}'`);
+    const first = (candidates, refused) => candidates.find((key) => {
+        const descriptor = OPTION_CATALOG.get(key);
+        return descriptor !== undefined && refused(descriptor);
+    });
+    const readOnly = first(keys, ({ flags, internal }) => internal || (flags & OptionFlag.ReadOnly) !== 0);
+    if (readOnly !== undefined)
+        refuse(READ_ONLY_OPTION, `key '${readOnly}'`);
+    const createOnly = first(keys, ({ flags }) => (flags & OptionFlag.Updatable) === 0);
+    if (createOnly !== undefined)
+        refuse(OPTION_NOT_UPDATABLE, `key '${createOnly}'`);
+    const fixed = first(reset, ({ flags }) => (flags & OptionFlag.Resettable) === 0);
+    if (fixed !== undefined)
+        refuse(OPTION_NOT_RESETTABLE, `reset of '${fixed}'`);
+    for (const { key, value } of set) {
+        const text = value.kind === HeaderKind.String ? value.value : undefined;
+        const length = text === undefined ? 0 : Buffer.byteLength(text);
+        if (key === 'name' && (length < 1 || length > MAX_NAME_LENGTH))
+            refuse(scope === OptionsScope.Topic ? INVALID_TOPIC_NAME : INVALID_STREAM_NAME, 'name');
+        if (key === 'username' && (length < MIN_USERNAME_LENGTH || length > MAX_USERNAME_LENGTH))
+            refuse(INVALID_USERNAME, 'username');
+        if (key === 'status' && text !== 'active' && text !== 'inactive')
+            refuse(INVALID_USER_STATUS, 'status');
+    }
+};
+//# sourceMappingURL=update-resource.command.js.map

package/dist/wire/system/update-resource.command.test.d.ts

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