@rex0220/ksql-flownet 1.0.0

package/dist/bundle/zip-store.js

@@ -0,0 +1,175 @@
+const LOCAL_SIGNATURE = 0x04034b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const END_SIGNATURE = 0x06054b50;
+const UTF8_FLAG = 0x0800;
+export class StoreZipError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StoreZipError";
+    }
+}
+/** Store-only ZIP with fixed zero DOS timestamps and caller-defined entry order. */
+export function createStoreZip(entries) {
+    if (entries.length === 0) {
+        throw new StoreZipError("ZIP requires at least one entry");
+    }
+    if (entries.length > 0xffff) {
+        throw new StoreZipError("ZIP64 entry counts are not supported");
+    }
+    const localParts = [];
+    const centralParts = [];
+    const names = new Set();
+    let offset = 0;
+    for (const entry of entries) {
+        if (names.has(entry.name)) {
+            throw new StoreZipError(`duplicate ZIP entry '${entry.name}'`);
+        }
+        names.add(entry.name);
+        const name = Buffer.from(entry.name, "utf8");
+        const data = Buffer.from(entry.data);
+        if (name.length === 0 || name.length > 0xffff || name.includes(0)) {
+            throw new StoreZipError("ZIP entry name length is invalid");
+        }
+        if (data.length > 0xffffffff) {
+            throw new StoreZipError("ZIP64 entry sizes are not supported");
+        }
+        const crc = crc32(data);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(LOCAL_SIGNATURE, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(UTF8_FLAG, 6);
+        local.writeUInt16LE(0, 8);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(data.length, 18);
+        local.writeUInt32LE(data.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        localParts.push(local, name, data);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(CENTRAL_SIGNATURE, 0);
+        central.writeUInt16LE(20, 4);
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(UTF8_FLAG, 8);
+        central.writeUInt16LE(0, 10);
+        central.writeUInt32LE(crc, 16);
+        central.writeUInt32LE(data.length, 20);
+        central.writeUInt32LE(data.length, 24);
+        central.writeUInt16LE(name.length, 28);
+        central.writeUInt32LE(offset, 42);
+        centralParts.push(central, name);
+        offset += local.length + name.length + data.length;
+        if (offset > 0xffffffff) {
+            throw new StoreZipError("ZIP64 archive sizes are not supported");
+        }
+    }
+    const centralDirectory = Buffer.concat(centralParts);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(END_SIGNATURE, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(centralDirectory.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...localParts, centralDirectory, end]);
+}
+export function readStoreZip(input) {
+    const zip = Buffer.from(input);
+    if (zip.length < 22 || zip.readUInt32LE(zip.length - 22) !== END_SIGNATURE) {
+        throw new StoreZipError("ZIP end of central directory was not found");
+    }
+    const endOffset = zip.length - 22;
+    const diskNumber = zip.readUInt16LE(endOffset + 4);
+    const centralDisk = zip.readUInt16LE(endOffset + 6);
+    const diskCount = zip.readUInt16LE(endOffset + 8);
+    const count = zip.readUInt16LE(endOffset + 10);
+    const centralSize = zip.readUInt32LE(endOffset + 12);
+    const centralOffset = zip.readUInt32LE(endOffset + 16);
+    const commentLength = zip.readUInt16LE(endOffset + 20);
+    if (diskNumber !== 0 ||
+        centralDisk !== 0 ||
+        diskCount !== count ||
+        commentLength !== 0 ||
+        centralOffset + centralSize !== endOffset) {
+        throw new StoreZipError("unsupported or malformed ZIP directory");
+    }
+    const entries = [];
+    const names = new Set();
+    let cursor = centralOffset;
+    for (let index = 0; index < count; index += 1) {
+        assertRange(zip, cursor, 46, "ZIP central directory");
+        if (zip.readUInt32LE(cursor) !== CENTRAL_SIGNATURE) {
+            throw new StoreZipError("ZIP central directory signature is invalid");
+        }
+        const flags = zip.readUInt16LE(cursor + 8);
+        const method = zip.readUInt16LE(cursor + 10);
+        const expectedCrc = zip.readUInt32LE(cursor + 16);
+        const compressedSize = zip.readUInt32LE(cursor + 20);
+        const size = zip.readUInt32LE(cursor + 24);
+        const nameLength = zip.readUInt16LE(cursor + 28);
+        const extraLength = zip.readUInt16LE(cursor + 30);
+        const entryCommentLength = zip.readUInt16LE(cursor + 32);
+        const localOffset = zip.readUInt32LE(cursor + 42);
+        const centralEntryLength = 46 + nameLength + extraLength + entryCommentLength;
+        assertRange(zip, cursor, centralEntryLength, "ZIP central entry");
+        const nameBytes = zip.subarray(cursor + 46, cursor + 46 + nameLength);
+        const name = nameBytes.toString("utf8");
+        if (method !== 0 || compressedSize !== size || flags !== UTF8_FLAG) {
+            throw new StoreZipError("only deterministic UTF-8 store-only ZIP is supported");
+        }
+        if (names.has(name))
+            throw new StoreZipError(`duplicate ZIP entry '${name}'`);
+        names.add(name);
+        assertRange(zip, localOffset, 30, "ZIP local header");
+        if (zip.readUInt32LE(localOffset) !== LOCAL_SIGNATURE) {
+            throw new StoreZipError("ZIP local header signature is invalid");
+        }
+        const localFlags = zip.readUInt16LE(localOffset + 6);
+        const localMethod = zip.readUInt16LE(localOffset + 8);
+        const localCrc = zip.readUInt32LE(localOffset + 14);
+        const localCompressedSize = zip.readUInt32LE(localOffset + 18);
+        const localSize = zip.readUInt32LE(localOffset + 22);
+        const localNameLength = zip.readUInt16LE(localOffset + 26);
+        const localExtraLength = zip.readUInt16LE(localOffset + 28);
+        const localNameOffset = localOffset + 30;
+        const dataOffset = localNameOffset + localNameLength + localExtraLength;
+        assertRange(zip, localNameOffset, localNameLength, "ZIP local entry name");
+        assertRange(zip, dataOffset, size, "ZIP entry data");
+        const localName = zip.subarray(localNameOffset, localNameOffset + localNameLength);
+        if (!localName.equals(nameBytes) ||
+            localFlags !== flags ||
+            localMethod !== method ||
+            localCrc !== expectedCrc ||
+            localCompressedSize !== compressedSize ||
+            localSize !== size) {
+            throw new StoreZipError(`ZIP entry '${name}' headers do not agree`);
+        }
+        const data = zip.subarray(dataOffset, dataOffset + size);
+        if (crc32(data) !== expectedCrc) {
+            throw new StoreZipError(`ZIP entry '${name}' CRC does not match`);
+        }
+        entries.push({ name, data: Buffer.from(data), crc32: expectedCrc });
+        cursor += centralEntryLength;
+    }
+    if (cursor !== endOffset) {
+        throw new StoreZipError("ZIP central directory length does not match");
+    }
+    return entries;
+}
+export function crc32(input) {
+    let crc = 0xffffffff;
+    for (const byte of input) {
+        crc ^= byte;
+        for (let bit = 0; bit < 8; bit += 1) {
+            crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+        }
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function assertRange(buffer, offset, length, label) {
+    if (!Number.isSafeInteger(offset) ||
+        !Number.isSafeInteger(length) ||
+        offset < 0 ||
+        length < 0 ||
+        offset + length > buffer.length) {
+        throw new StoreZipError(`${label} is out of bounds`);
+    }
+}
+//# sourceMappingURL=zip-store.js.map

package/dist/cli/archive-run-command.d.ts

@@ -0,0 +1,12 @@
+import { type ArchiveRunOutcome } from "../orchestration/archive-run.js";
+export interface ArchiveRunCommandDependencies {
+    readonly execute: (input: {
+        networkPath: string;
+        runId: string;
+        reason: string;
+        profile?: string;
+    }) => Promise<ArchiveRunOutcome>;
+    readonly readFile?: (path: string) => string;
+}
+export declare function runArchiveRunCommand(args: readonly string[], dependencies?: ArchiveRunCommandDependencies): Promise<number>;
+//# sourceMappingURL=archive-run-command.d.ts.map

package/dist/cli/archive-run-command.js

@@ -0,0 +1,131 @@
+import { readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { loadNetworkDefinition } from "../domain/load-network.js";
+import { archiveRun, } from "../orchestration/archive-run.js";
+import { LeaseMonitor, NetworkLockManager, } from "../persistence/network-lock.js";
+import { repositoryFromEnvironment, requiredEnvironment, } from "./resolve-node-command.js";
+export async function runArchiveRunCommand(args, dependencies) {
+    const parsed = parseArguments(args);
+    if (parsed.errors.length > 0) {
+        process.stderr.write(`Invalid archive-run arguments:\n${parsed.errors.map((x) => `- ${x}`).join("\n")}\n`);
+        return 1;
+    }
+    try {
+        const reason = (dependencies?.readFile ?? ((path) => readFileSync(path, "utf8")))(parsed.reasonFile);
+        const outcome = dependencies === undefined
+            ? await productionArchive(parsed.networkPath, parsed.runId, reason, parsed.profile)
+            : await dependencies.execute({
+                networkPath: parsed.networkPath,
+                runId: parsed.runId,
+                reason,
+                ...(parsed.profile === undefined
+                    ? {}
+                    : { profile: parsed.profile }),
+            });
+        process.stdout.write(`${JSON.stringify(outcome)}\n`);
+        // 仕様 §5.3: exit 0 は ARCHIVED+RECORDED+解放済み、または ALREADY_ARCHIVED+解放済みのときだけ。
+        const success = (outcome.outcome === "ARCHIVED" &&
+            outcome.audit === "RECORDED" &&
+            outcome.lock_released) ||
+            (outcome.outcome === "ALREADY_ARCHIVED" && outcome.lock_released);
+        if (success)
+            process.stderr.write(`${outcome.outcome}: ${outcome.run_id} (revision ${outcome.run_revision})\n`);
+        else
+            process.stderr.write(`Error [${outcomeCode(outcome)}]: archive-run did not complete cleanly\n`);
+        return success ? 0 : 1;
+    }
+    catch (error) {
+        const code = typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            typeof error.code === "string"
+            ? error.code
+            : "ARCHIVE_RUN_FAILED";
+        process.stderr.write(`Error [${code}]: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+async function productionArchive(networkPath, runId, reason, profileOption) {
+    const loaded = loadNetworkDefinition(networkPath);
+    if (loaded.definition === undefined || loaded.errors.length > 0)
+        throw new Error("network definition is invalid");
+    const profile = profileOption ?? requiredEnvironment("KSQL_FLOWNET_PROFILE");
+    const baseUrl = requiredEnvironment("KSQL_FLOWNET_BASE_URL").replace(/\/$/u, "");
+    const appId = Number(requiredEnvironment("KSQL_FLOWNET_STATE_APP_ID"));
+    const token = requiredEnvironment("KSQL_FLOWNET_STATE_API_TOKEN");
+    const leaseDuration = loaded.definition.network_lock.lease_duration_sec;
+    return archiveRun({
+        repository: repositoryFromEnvironment(),
+        runId,
+        requestedBy: requiredEnvironment("KSQL_FLOWNET_REQUESTED_BY"),
+        reason,
+        // ポーラー経由(cron 環境)では未設定のことがあるため、ホスト識別へフォールバックする。
+        servicePrincipal: process.env.KSQL_FLOWNET_SERVICE_PRINCIPAL?.trim() ||
+            process.env.KSQL_FLOWNET_HOST?.trim() ||
+            hostname(),
+        lockManagerFactory: (owner) => new NetworkLockManager({
+            baseUrl,
+            appId,
+            apiToken: token,
+            profile,
+            networkId: loaded.definition.network_id,
+            ownerInvocationId: owner,
+            ownerInstanceId: process.env.KSQL_FLOWNET_HOST ?? hostname(),
+            leaseDurationSec: leaseDuration,
+        }),
+        leaseMonitorFactory: (manager, reference) => new LeaseMonitor(manager, reference, {
+            leaseDurationSec: leaseDuration,
+            heartbeatIntervalSec: loaded.definition.network_lock.heartbeat_interval_sec,
+        }),
+    });
+}
+function outcomeCode(value) {
+    if ("code" in value)
+        return value.code;
+    if (value.outcome === "ALREADY_ARCHIVED")
+        return "ALREADY_ARCHIVED";
+    return value.lock_released
+        ? "ARCHIVE_RUN_FAILED"
+        : "RUN_ARCHIVED_LOCK_UNRELEASED";
+}
+function parseArguments(args) {
+    const result = { errors: [] };
+    const seen = new Set();
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg.startsWith("--")) {
+            if (result.networkPath !== undefined)
+                result.errors.push("exactly one <network.yaml> path is required");
+            else
+                result.networkPath = arg;
+            continue;
+        }
+        if (!["--run-id", "--reason-file", "--profile"].includes(arg)) {
+            result.errors.push(`unknown option '${arg}'`);
+            continue;
+        }
+        const value = args[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            result.errors.push(`${arg} requires a value`);
+            continue;
+        }
+        if (seen.has(arg))
+            result.errors.push(`${arg} was specified more than once`);
+        seen.add(arg);
+        index += 1;
+        if (arg === "--run-id")
+            result.runId = value;
+        else if (arg === "--reason-file")
+            result.reasonFile = value;
+        else
+            result.profile = value;
+    }
+    if (result.networkPath === undefined)
+        result.errors.push("<network.yaml> is required");
+    if (result.runId === undefined)
+        result.errors.push("--run-id is required");
+    if (result.reasonFile === undefined)
+        result.errors.push("--reason-file is required");
+    return result;
+}
+//# sourceMappingURL=archive-run-command.js.map

package/dist/cli/cancel-run-command.d.ts

@@ -0,0 +1,9 @@
+import type { PersistenceRepository } from "../persistence/repository.js";
+export interface CancelRunCommandDependencies {
+    readonly repository: PersistenceRepository;
+    readonly requestedBy: string;
+    readonly readFile?: (path: string) => string;
+    readonly now?: () => Date;
+}
+export declare function runCancelRunCommand(args: readonly string[], dependencies?: CancelRunCommandDependencies): Promise<number>;
+//# sourceMappingURL=cancel-run-command.d.ts.map

package/dist/cli/cancel-run-command.js

@@ -0,0 +1,77 @@
+import { readFileSync } from "node:fs";
+import { changeCancelRequest } from "../orchestration/cancel-request.js";
+import { repositoryFromEnvironment, requiredEnvironment, } from "./resolve-node-command.js";
+export async function runCancelRunCommand(args, dependencies) {
+    const parsed = parseArguments(args);
+    if (parsed.errors.length > 0) {
+        process.stderr.write(`Invalid cancel-run arguments:\n${parsed.errors.map((error) => `- ${error}`).join("\n")}\n`);
+        return 1;
+    }
+    try {
+        const runtime = dependencies ?? {
+            repository: repositoryFromEnvironment(),
+            requestedBy: requiredEnvironment("KSQL_FLOWNET_REQUESTED_BY"),
+        };
+        const reason = (runtime.readFile ?? ((path) => readFileSync(path, "utf8")))(parsed.reasonFile);
+        const result = await changeCancelRequest({
+            repository: runtime.repository,
+            runId: parsed.runId,
+            requestedBy: runtime.requestedBy,
+            reason,
+            release: parsed.release,
+            ...(runtime.now === undefined ? {} : { now: runtime.now }),
+        });
+        const state = result?.value.state ?? "RELEASED";
+        const revision = result === null ? "none" : String(result.revision);
+        process.stdout.write(`${state}: CANCEL:${parsed.runId} (revision ${revision}).\n`);
+        return 0;
+    }
+    catch (error) {
+        const code = typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            typeof error.code === "string"
+            ? error.code
+            : "CANCEL_RUN_FAILED";
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`Error [${code}]: ${message}\n`);
+        return 1;
+    }
+}
+function parseArguments(args) {
+    const result = { release: false, errors: [] };
+    const values = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--release") {
+            if (result.release)
+                result.errors.push("--release was specified more than once");
+            result.release = true;
+            continue;
+        }
+        if (argument !== "--run-id" && argument !== "--reason-file") {
+            result.errors.push(`unknown option '${argument}'`);
+            continue;
+        }
+        const value = args[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            result.errors.push(`${argument} requires a value`);
+            continue;
+        }
+        if (values.has(argument))
+            result.errors.push(`${argument} was specified more than once`);
+        values.set(argument, value);
+        index += 1;
+    }
+    for (const option of ["--run-id", "--reason-file"])
+        if (!values.has(option))
+            result.errors.push(`${option} is required`);
+    return {
+        ...result,
+        ...(values.has("--run-id") ? { runId: values.get("--run-id") } : {}),
+        ...(values.has("--reason-file")
+            ? { reasonFile: values.get("--reason-file") }
+            : {}),
+    };
+}
+//# sourceMappingURL=cancel-run-command.js.map

package/dist/cli/force-unlock-network-command.d.ts

@@ -0,0 +1,8 @@
+import { type NetworkLockRecoveryDependencies } from "../persistence/network-lock-recovery.js";
+export interface ForceUnlockNetworkCommandDependencies extends NetworkLockRecoveryDependencies {
+    readonly servicePrincipal: string;
+    readonly requestedBy: string;
+    readonly readFile?: (path: string) => string;
+}
+export declare function runForceUnlockNetworkCommand(args: readonly string[], dependencies?: ForceUnlockNetworkCommandDependencies): Promise<number>;
+//# sourceMappingURL=force-unlock-network-command.d.ts.map

package/dist/cli/force-unlock-network-command.js

@@ -0,0 +1,129 @@
+import { readFileSync } from "node:fs";
+import { forceUnlockNetwork, } from "../persistence/network-lock-recovery.js";
+import { repositoryFromEnvironment, requiredEnvironment, } from "./resolve-node-command.js";
+export async function runForceUnlockNetworkCommand(args, dependencies) {
+    const parsed = parseArguments(args);
+    if (parsed.errors.length > 0) {
+        process.stderr.write(`Invalid force-unlock-network arguments:\n${parsed.errors.map((error) => `- ${error}`).join("\n")}\n`);
+        return 1;
+    }
+    try {
+        const runtime = dependencies ?? productionDependencies();
+        const reason = (runtime.readFile ?? ((path) => readFileSync(path, "utf8")))(parsed.reasonFile);
+        const result = await forceUnlockNetwork({
+            networkId: parsed.networkId,
+            profile: parsed.profile,
+            expectedOwnerInvocationId: parsed.expectedOwnerInvocationId,
+            reason,
+            evidenceRef: parsed.evidenceRef,
+            stopConfirmedBy: parsed.stopConfirmedBy,
+            stopEvidenceRef: parsed.stopEvidenceRef,
+            stopMethod: parsed.stopMethod,
+            servicePrincipal: runtime.servicePrincipal,
+            requestedBy: runtime.requestedBy,
+        }, runtime);
+        process.stdout.write(`RELEASED: ${result.lockKey} (previous owner ${result.previousOwnerInvocationId}, post revision ${result.postReleaseRevision}).\n`);
+        process.stdout.write("If a Node was running, use resolve-node to resolve it as UNKNOWN before resume.\n");
+        return 0;
+    }
+    catch (error) {
+        const code = errorCode(error, "FORCE_UNLOCK_NETWORK_FAILED");
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`Error [${code}]: ${message}\n`);
+        return 1;
+    }
+}
+function parseArguments(args) {
+    const errors = [];
+    const positional = [];
+    const values = new Map();
+    const allowed = new Set([
+        "--profile",
+        "--expected-owner-invocation-id",
+        "--reason-file",
+        "--evidence-ref",
+        "--stop-confirmed-by",
+        "--stop-evidence-ref",
+        "--stop-method",
+    ]);
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (!argument.startsWith("--")) {
+            positional.push(argument);
+            continue;
+        }
+        const value = args[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            errors.push(`${argument} requires a value`);
+            continue;
+        }
+        if (!allowed.has(argument))
+            errors.push(`unknown option '${argument}'`);
+        if (values.has(argument))
+            errors.push(`${argument} was specified more than once`);
+        values.set(argument, value);
+        index += 1;
+    }
+    if (positional.length === 0)
+        errors.push("<network_id> is required");
+    if (positional.length > 1) {
+        for (const argument of positional.slice(1))
+            errors.push(`unexpected argument '${argument}'`);
+    }
+    for (const option of allowed) {
+        if (!values.has(option))
+            errors.push(`${option} is required`);
+    }
+    return {
+        ...(positional[0] === undefined ? {} : { networkId: positional[0] }),
+        ...(values.get("--profile") === undefined
+            ? {}
+            : { profile: values.get("--profile") }),
+        ...(values.get("--expected-owner-invocation-id") === undefined
+            ? {}
+            : {
+                expectedOwnerInvocationId: values.get("--expected-owner-invocation-id"),
+            }),
+        ...(values.get("--reason-file") === undefined
+            ? {}
+            : { reasonFile: values.get("--reason-file") }),
+        ...(values.get("--evidence-ref") === undefined
+            ? {}
+            : { evidenceRef: values.get("--evidence-ref") }),
+        ...(values.get("--stop-confirmed-by") === undefined
+            ? {}
+            : { stopConfirmedBy: values.get("--stop-confirmed-by") }),
+        ...(values.get("--stop-evidence-ref") === undefined
+            ? {}
+            : { stopEvidenceRef: values.get("--stop-evidence-ref") }),
+        ...(values.get("--stop-method") === undefined
+            ? {}
+            : { stopMethod: values.get("--stop-method") }),
+        errors,
+    };
+}
+function productionDependencies() {
+    return {
+        baseUrl: requiredEnvironment("KSQL_FLOWNET_BASE_URL").replace(/\/$/u, ""),
+        stateAppId: positiveIntegerEnvironment("KSQL_FLOWNET_STATE_APP_ID"),
+        stateApiToken: requiredEnvironment("KSQL_FLOWNET_STATE_API_TOKEN"),
+        repository: repositoryFromEnvironment(),
+        servicePrincipal: requiredEnvironment("KSQL_FLOWNET_SERVICE_PRINCIPAL"),
+        requestedBy: requiredEnvironment("KSQL_FLOWNET_REQUESTED_BY"),
+    };
+}
+function positiveIntegerEnvironment(name) {
+    const value = Number(requiredEnvironment(name));
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`${name} must be a positive integer`);
+    return value;
+}
+function errorCode(error, fallback) {
+    return typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string"
+        ? error.code
+        : fallback;
+}
+//# sourceMappingURL=force-unlock-network-command.js.map

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map