@actiondock/core 2.2.2 → 2.3.0

package/dist/process/metadata-store.js

@@ -0,0 +1,462 @@
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { createDefaultSqliteDriver } from "../storage/driver.js";
+/**
+ * 解析分页游标偏移量。
+ */
+function parsePageToken(pageToken) {
+    if (!pageToken) {
+        return 0;
+    }
+    const parsed = parseInt(pageToken, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+        return parsed;
+    }
+    return 0;
+}
+/**
+ * 内存型受管进程元数据存储实现。
+ * 适用于确定性测试与无持久化文件系统运行场景。
+ */
+export class MemoryProcessMetadataStore {
+    processes = new Map();
+    requests = new Map();
+    formatRequestKey(key) {
+        return `${key.hostEpoch}:${key.scope}:${key.processId ?? ""}:${key.requestId}`;
+    }
+    async saveProcess(process) {
+        const createdAt = process.createdAt ?? new Date().toISOString();
+        const ctrl = process.controlState ?? process.control;
+        const cloned = {
+            ...process,
+            createdAt,
+            controlState: ctrl,
+            control: ctrl,
+            outputClosed: Boolean(process.outputClosed),
+            inputClosed: Boolean(process.inputClosed),
+        };
+        this.processes.set(process.processId, cloned);
+    }
+    async getProcess(processId) {
+        const record = this.processes.get(processId);
+        if (!record) {
+            return undefined;
+        }
+        return { ...record };
+    }
+    async listProcesses(owner, pageToken, limit) {
+        const actualLimit = typeof limit === "number" && limit > 0 ? limit : 50;
+        const offset = parsePageToken(pageToken);
+        const matched = Array.from(this.processes.values()).filter((p) => p.tenantId === owner.tenantId &&
+            p.principalId === owner.principalId &&
+            p.packageInstanceId === owner.packageInstanceId &&
+            p.generationId === owner.generationId);
+        matched.sort((a, b) => {
+            const timeA = new Date(a.createdAt || 0).getTime();
+            const timeB = new Date(b.createdAt || 0).getTime();
+            if (timeA !== timeB) {
+                return timeB - timeA;
+            }
+            return a.processId.localeCompare(b.processId);
+        });
+        const sliced = matched.slice(offset, offset + actualLimit + 1);
+        const hasMore = sliced.length > actualLimit;
+        const resultRows = hasMore ? sliced.slice(0, actualLimit) : sliced;
+        const processes = resultRows.map((p) => ({ ...p }));
+        const nextPageToken = hasMore ? String(offset + actualLimit) : undefined;
+        return { processes, nextPageToken };
+    }
+    async updateProcessState(processId, patch) {
+        const target = this.processes.get(processId);
+        if (!target) {
+            throw new Error(`Process '${processId}' not found`);
+        }
+        const ctrl = patch.controlState !== undefined ? patch.controlState : patch.control;
+        const updated = {
+            ...target,
+            ...patch,
+            controlState: ctrl !== undefined ? ctrl : target.controlState,
+            control: ctrl !== undefined ? ctrl : target.control,
+        };
+        this.processes.set(processId, updated);
+    }
+    async recordRequest(key, receipt, payloadHash) {
+        const k = this.formatRequestKey(key);
+        this.requests.set(k, {
+            receipt: JSON.parse(JSON.stringify(receipt)),
+            payloadHash,
+            createdAt: new Date().toISOString(),
+        });
+    }
+    async getRequest(key) {
+        const k = this.formatRequestKey(key);
+        const item = this.requests.get(k);
+        if (!item) {
+            return undefined;
+        }
+        return {
+            receipt: JSON.parse(JSON.stringify(item.receipt)),
+            payloadHash: item.payloadHash,
+        };
+    }
+    async initializeHost(hostEpoch) {
+        let recoveredCount = 0;
+        for (const [id, proc] of Array.from(this.processes.entries())) {
+            if (proc.hostEpoch !== hostEpoch &&
+                (proc.state === "starting" || proc.state === "running" || proc.state === "stopping")) {
+                this.processes.set(id, {
+                    ...proc,
+                    state: "lost",
+                    controlState: "closed",
+                    control: "closed",
+                    endReason: "host-lost",
+                    outputClosed: true,
+                    outputEndReason: "host-lost",
+                });
+                recoveredCount += 1;
+            }
+        }
+        return recoveredCount;
+    }
+    clear() {
+        this.processes.clear();
+        this.requests.clear();
+    }
+}
+/**
+ * 将数据库行反序列化为进程模型。
+ */
+function mapRowToStoredProcess(row) {
+    return {
+        processId: row.process_id,
+        tenantId: row.tenant_id,
+        principalId: row.principal_id,
+        packageInstanceId: row.package_instance_id,
+        generationId: row.generation_id,
+        hostEpoch: row.host_epoch,
+        state: row.state,
+        controlState: row.control_state ?? undefined,
+        control: row.control_state ?? undefined,
+        ioConfig: row.io_config_json ? JSON.parse(row.io_config_json) : undefined,
+        capabilities: row.capabilities_json ? JSON.parse(row.capabilities_json) : undefined,
+        createdAt: row.created_at,
+        exitCode: row.exit_code !== null && row.exit_code !== undefined ? Number(row.exit_code) : undefined,
+        exitSignal: row.exit_signal ?? undefined,
+        endReason: row.end_reason ?? undefined,
+        outputClosed: Boolean(row.output_closed),
+        outputEndReason: row.output_end_reason ?? undefined,
+        inputClosed: Boolean(row.input_closed),
+        effectiveLimits: row.effective_limits_json ? JSON.parse(row.effective_limits_json) : undefined,
+        startRequestId: row.start_request_id ?? undefined,
+    };
+}
+/**
+ * 基于 SQLite 的受管进程元数据持久化存储实现。
+ */
+export class SqliteProcessMetadataStore {
+    driver;
+    statementCache = new Map();
+    isClosed = false;
+    constructor(options = {}) {
+        const dbPath = options.dbPath || ":memory:";
+        if (dbPath !== ":memory:") {
+            const dir = dirname(dbPath);
+            if (!existsSync(dir)) {
+                try {
+                    mkdirSync(dir, { recursive: true, mode: 0o700 });
+                    chmodSync(dir, 0o700);
+                }
+                catch {
+                    // 忽略系统权限配置失败
+                }
+            }
+        }
+        this.driver = options.driver ?? createDefaultSqliteDriver(dbPath);
+        if (dbPath !== ":memory:" && existsSync(dbPath)) {
+            try {
+                chmodSync(dbPath, 0o600);
+            }
+            catch {
+                // 忽略文件权限配置异常
+            }
+        }
+        this.initTables();
+    }
+    initTables() {
+        this.driver.exec("PRAGMA journal_mode = WAL;");
+        this.driver.exec("PRAGMA synchronous = NORMAL;");
+        this.driver.exec(`
+      CREATE TABLE IF NOT EXISTS managed_processes (
+        process_id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL,
+        principal_id TEXT NOT NULL,
+        package_instance_id TEXT NOT NULL,
+        generation_id TEXT NOT NULL,
+        host_epoch TEXT NOT NULL,
+        state TEXT NOT NULL,
+        control_state TEXT,
+        io_config_json TEXT,
+        capabilities_json TEXT,
+        created_at TEXT NOT NULL,
+        exit_code INTEGER,
+        exit_signal TEXT,
+        end_reason TEXT,
+        output_closed INTEGER NOT NULL DEFAULT 0,
+        output_end_reason TEXT,
+        input_closed INTEGER NOT NULL DEFAULT 0,
+        effective_limits_json TEXT,
+        start_request_id TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_processes_owner_created
+        ON managed_processes(tenant_id, principal_id, package_instance_id, generation_id, created_at DESC, process_id ASC);
+
+      CREATE INDEX IF NOT EXISTS idx_processes_host_state
+        ON managed_processes(host_epoch, state);
+
+      CREATE INDEX IF NOT EXISTS idx_processes_start_req
+        ON managed_processes(start_request_id);
+
+      CREATE TABLE IF NOT EXISTS process_requests (
+        host_epoch TEXT NOT NULL,
+        scope TEXT NOT NULL,
+        process_id TEXT NOT NULL DEFAULT '',
+        request_id TEXT NOT NULL,
+        receipt_json TEXT NOT NULL,
+        payload_hash TEXT,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (host_epoch, scope, process_id, request_id)
+      );
+    `);
+        this.migrateSchema();
+    }
+    /**
+     * 旧库结构迁移：逐列探测并补充新增字段，重复执行安全（幂等）。
+     */
+    migrateSchema() {
+        const columns = new Set();
+        for (const row of this.listTableColumns("managed_processes")) {
+            columns.add(String(row.name));
+        }
+        if (!columns.has("input_closed")) {
+            this.driver.exec("ALTER TABLE managed_processes ADD COLUMN input_closed INTEGER NOT NULL DEFAULT 0;");
+        }
+    }
+    /**
+     * 枚举指定表的全部列定义。
+     */
+    listTableColumns(tableName) {
+        try {
+            const stmt = this.driver.prepare(`PRAGMA table_info(${tableName})`);
+            return stmt.all() ?? [];
+        }
+        catch {
+            return [];
+        }
+    }
+    getStatement(sql) {
+        let stmt = this.statementCache.get(sql);
+        if (!stmt) {
+            stmt = this.driver.prepare(sql);
+            this.statementCache.set(sql, stmt);
+        }
+        return stmt;
+    }
+    async saveProcess(process) {
+        if (this.isClosed) {
+            throw new Error("SqliteProcessMetadataStore is closed");
+        }
+        const stmt = this.getStatement(`
+      INSERT INTO managed_processes (
+        process_id, tenant_id, principal_id, package_instance_id, generation_id,
+        host_epoch, state, control_state, io_config_json, capabilities_json,
+        created_at, exit_code, exit_signal, end_reason, output_closed,
+        output_end_reason, input_closed, effective_limits_json, start_request_id
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(process_id) DO UPDATE SET
+        tenant_id = excluded.tenant_id,
+        principal_id = excluded.principal_id,
+        package_instance_id = excluded.package_instance_id,
+        generation_id = excluded.generation_id,
+        host_epoch = excluded.host_epoch,
+        state = excluded.state,
+        control_state = excluded.control_state,
+        io_config_json = excluded.io_config_json,
+        capabilities_json = excluded.capabilities_json,
+        created_at = excluded.created_at,
+        exit_code = excluded.exit_code,
+        exit_signal = excluded.exit_signal,
+        end_reason = excluded.end_reason,
+        output_closed = excluded.output_closed,
+        output_end_reason = excluded.output_end_reason,
+        input_closed = excluded.input_closed,
+        effective_limits_json = excluded.effective_limits_json,
+        start_request_id = excluded.start_request_id
+    `);
+        const createdAt = process.createdAt ?? new Date().toISOString();
+        const ctrlState = process.controlState ?? process.control ?? null;
+        const ioConfigJson = process.ioConfig !== undefined ? JSON.stringify(process.ioConfig) : null;
+        const capabilitiesJson = process.capabilities !== undefined ? JSON.stringify(process.capabilities) : null;
+        const effectiveLimitsJson = process.effectiveLimits !== undefined ? JSON.stringify(process.effectiveLimits) : null;
+        const outputClosed = process.outputClosed ? 1 : 0;
+        const inputClosed = process.inputClosed ? 1 : 0;
+        stmt.run(process.processId, process.tenantId, process.principalId, process.packageInstanceId, process.generationId, process.hostEpoch, process.state, ctrlState, ioConfigJson, capabilitiesJson, createdAt, process.exitCode !== undefined && process.exitCode !== null ? process.exitCode : null, process.exitSignal !== undefined ? process.exitSignal : null, process.endReason !== undefined ? process.endReason : null, outputClosed, process.outputEndReason !== undefined ? process.outputEndReason : null, inputClosed, effectiveLimitsJson, process.startRequestId !== undefined ? process.startRequestId : null);
+    }
+    async getProcess(processId) {
+        if (this.isClosed) {
+            throw new Error("SqliteProcessMetadataStore is closed");
+        }
+        const stmt = this.getStatement("SELECT * FROM managed_processes WHERE process_id = ?");
+        const row = stmt.get(processId);
+        if (!row) {
+            return undefined;
+        }
+        return mapRowToStoredProcess(row);
+    }
+    async listProcesses(owner, pageToken, limit) {
+        if (this.isClosed) {
+            throw new Error("SqliteProcessMetadataStore is closed");
+        }
+        const actualLimit = typeof limit === "number" && limit > 0 ? limit : 50;
+        const offset = parsePageToken(pageToken);
+        const stmt = this.getStatement(`
+      SELECT * FROM managed_processes
+      WHERE tenant_id = ? AND principal_id = ? AND package_instance_id = ? AND generation_id = ?
+      ORDER BY created_at DESC, process_id ASC
+      LIMIT ? OFFSET ?
+    `);
+        const rows = stmt.all(owner.tenantId, owner.principalId, owner.packageInstanceId, owner.generationId, actualLimit + 1, offset);
+        const hasMore = rows.length > actualLimit;
+        const resultRows = hasMore ? rows.slice(0, actualLimit) : rows;
+        const processes = resultRows.map(mapRowToStoredProcess);
+        const nextPageToken = hasMore ? String(offset + actualLimit) : undefined;
+        return { processes, nextPageToken };
+    }
+    async updateProcessState(processId, patch) {
+        if (this.isClosed) {
+            throw new Error("SqliteProcessMetadataStore is closed");
+        }
+        const sets = [];
+        const params = [];
+        if (patch.state !== undefined) {
+            sets.push("state = ?");
+            params.push(patch.state);
+        }
+        const ctrl = patch.controlState !== undefined ? patch.controlState : patch.control;
+        if (ctrl !== undefined) {
+            sets.push("control_state = ?");
+            params.push(ctrl);
+        }
+        if (patch.exitCode !== undefined) {
+            sets.push("exit_code = ?");
+            params.push(patch.exitCode !== null ? patch.exitCode : null);
+        }
+        if (patch.exitSignal !== undefined) {
+            sets.push("exit_signal = ?");
+            params.push(patch.exitSignal);
+        }
+        if (patch.endReason !== undefined) {
+            sets.push("end_reason = ?");
+            params.push(patch.endReason);
+        }
+        if (patch.outputClosed !== undefined) {
+            sets.push("output_closed = ?");
+            params.push(patch.outputClosed ? 1 : 0);
+        }
+        if (patch.outputEndReason !== undefined) {
+            sets.push("output_end_reason = ?");
+            params.push(patch.outputEndReason);
+        }
+        if (patch.inputClosed !== undefined) {
+            sets.push("input_closed = ?");
+            params.push(patch.inputClosed ? 1 : 0);
+        }
+        if (patch.effectiveLimits !== undefined) {
+            sets.push("effective_limits_json = ?");
+            params.push(patch.effectiveLimits !== null ? JSON.stringify(patch.effectiveLimits) : null);
+        }
+        if (patch.ioConfig !== undefined) {
+            sets.push("io_config_json = ?");
+            params.push(patch.ioConfig !== null ? JSON.stringify(patch.ioConfig) : null);
+        }
+        if (patch.capabilities !== undefined) {
+            sets.push("capabilities_json = ?");
+            params.push(patch.capabilities !== null ? JSON.stringify(patch.capabilities) : null);
+        }
+        if (patch.hostEpoch !== undefined) {
+            sets.push("host_epoch = ?");
+            params.push(patch.hostEpoch);
+        }
+        if (sets.length === 0) {
+            return;
+        }
+        params.push(processId);
+        const sql = `UPDATE managed_processes SET ${sets.join(", ")} WHERE process_id = ?`;
+        const stmt = this.getStatement(sql);
+        const res = stmt.run(...params);
+        if (res.changes === 0) {
+            throw new Error(`Process '${processId}' not found`);
+        }
+    }
+    async recordRequest(key, receipt, payloadHash) {
+        if (this.isClosed) {
+            throw new Error("SqliteProcessMetadataStore is closed");
+        }
+        const stmt = this.getStatement(`
+      INSERT INTO process_requests (
+        host_epoch, scope, process_id, request_id, receipt_json, payload_hash, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(host_epoch, scope, process_id, request_id) DO UPDATE SET
+        receipt_json = excluded.receipt_json,
+        payload_hash = excluded.payload_hash,
+        created_at = excluded.created_at
+    `);
+        const processId = key.processId ?? "";
+        const receiptJson = JSON.stringify(receipt);
+        const createdAt = new Date().toISOString();
+        stmt.run(key.hostEpoch, key.scope, processId, key.requestId, receiptJson, payloadHash ?? null, createdAt);
+    }
+    async getRequest(key) {
+        if (this.isClosed) {
+            throw new Error("SqliteProcessMetadataStore is closed");
+        }
+        const stmt = this.getStatement(`
+      SELECT receipt_json, payload_hash FROM process_requests
+      WHERE host_epoch = ? AND scope = ? AND process_id = ? AND request_id = ?
+    `);
+        const processId = key.processId ?? "";
+        const row = stmt.get(key.hostEpoch, key.scope, processId, key.requestId);
+        if (!row) {
+            return undefined;
+        }
+        return {
+            receipt: JSON.parse(row.receipt_json),
+            payloadHash: row.payload_hash ?? undefined,
+        };
+    }
+    async initializeHost(hostEpoch) {
+        if (this.isClosed) {
+            return 0;
+        }
+        const stmt = this.getStatement(`
+      UPDATE managed_processes
+      SET state = 'lost',
+          control_state = 'closed',
+          end_reason = 'host-lost',
+          output_closed = 1,
+          output_end_reason = 'host-lost'
+      WHERE host_epoch != ?
+        AND state IN ('starting', 'running', 'stopping')
+    `);
+        const res = stmt.run(hostEpoch);
+        return res.changes;
+    }
+    close() {
+        if (this.isClosed) {
+            return;
+        }
+        this.isClosed = true;
+        this.statementCache.clear();
+        this.driver.close();
+    }
+}

package/dist/process/output-log.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 外部输出分块数据。
+ */
+export interface OutputChunk {
+    /** 输出流标识 */
+    stream: "stdout" | "stderr" | "pty";
+    /** 原始字节数据 */
+    data: Uint8Array;
+}
+/**
+ * 游标读取返回结果快照。
+ */
+export interface OutputReadResult {
+    /** 本次读取到的数据切片列表 */
+    chunks: OutputChunk[];
+    /** 下次读取应使用的推进游标 */
+    nextCursor: string;
+    /** 当前保留窗口的最早游标 */
+    earliestCursor: string;
+    /** 当前日志末尾的最新游标 */
+    tailCursor: string;
+    /** 是否由于淘汰跳过了缺口数据 */
+    truncated: boolean;
+    /** 发生缺口跳过时的跨度信息 */
+    gap?: {
+        fromCursor: string;
+        toCursor: string;
+    };
+    /** 是否已在输出通道关闭后读尽全部数据 */
+    eof: boolean;
+}
+/**
+ * 输出日志配置选项。
+ */
+export interface ProcessOutputLogOptions {
+    /** 缓冲区最大保留字节数，默认 4 MiB */
+    maxBufferBytes?: number;
+    /** 单个进程最大并发等待者上限，默认 8 */
+    maxWaiters?: number;
+    /** 初始日志序号，默认 0 */
+    initialSequence?: number;
+}
+/**
+ * 读取长轮询等待配置选项。
+ */
+export interface OutputReadOptions {
+    /** 单次读取最大原始字节数，默认 64 KiB */
+    maxBytes?: number;
+    /** 遇到淘汰缺口时的处理策略，error 抛出异常，skip 自动跳过缺口 */
+    onGap?: "error" | "skip";
+}
+/**
+ * 基于内存有界环形缓冲区的受管进程原始字节输出日志。
+ *
+ * 职责与不变量：
+ * - 保留原始字节流，不做字符集猜测与跨流重排序。
+ * - 维护单调推进的游标系统，支持按记录切分与不透明游标寻址。
+ * - 缓冲区超额时淘汰最旧数据并更新最早保留游标。
+ * - 长轮询等待机制保证状态检查与等待者注册处于同一同步边界，杜绝漏唤醒。
+ * - 严格遵循等待者配额，超额抛出配额超限异常。
+ */
+export declare class ProcessOutputLog {
+    readonly hostEpoch: string;
+    readonly processId: string;
+    readonly maxBufferBytes: number;
+    readonly maxWaiters: number;
+    private records;
+    private totalBytes;
+    private nextSequence;
+    private earliestCursorState;
+    private tailCursorState;
+    private outputClosedState;
+    private outputEndReasonState?;
+    private waiters;
+    constructor(hostEpoch: string, processId: string, options?: ProcessOutputLogOptions);
+    /**
+     * 当前保留日志的最早可用游标。
+     */
+    get earliestCursor(): string;
+    /**
+     * 当前日志尾部的下一写入游标。
+     */
+    get tailCursor(): string;
+    /**
+     * 输出通道是否已关闭。
+     */
+    get outputClosed(): boolean;
+    /**
+     * 输出通道关闭原因。
+     */
+    get outputEndReason(): "natural" | "drain-timeout" | "host-lost" | undefined;
+    /**
+     * 当前缓冲区占用的原始字节总数。
+     */
+    get currentBytes(): number;
+    /**
+     * 当前正在挂起等待的读取者数量。
+     */
+    get waiterCount(): number;
+    /**
+     * 向输出日志追加新的原始字节数据。
+     *
+     * 行为约束：
+     * - 记录新数据并更新日志尾部游标。
+     * - 若总字节数超出缓冲区上限，淘汰最旧记录并更新最早保留游标。
+     * - 同步唤醒所有挂起等待者。
+     */
+    append(stream: "stdout" | "stderr" | "pty", data: Uint8Array): void;
+    /**
+     * 标记输出通道关闭并唤醒所有等待者。
+     */
+    closeOutput(reason?: "natural" | "drain-timeout" | "host-lost"): void;
+    /**
+     * 从指定游标处读取输出数据。
+     *
+     * 行为约束：
+     * - 校验游标是否超出当前日志末尾，超出则抛出 INVALID_CURSOR 异常。
+     * - 检查游标是否落后于最早保留游标：
+     *   - 若落后且 onGap 为 error，抛出 OUTPUT_GAP 异常并附带当前最早游标。
+     *   - 若落后且 onGap 为 skip，从最早可用游标开始读取，标记 truncated 为 true 并提供缺口范围。
+     * - 支持记录切分并生成带有内部偏移量的不透明推进游标。
+     */
+    read(cursor: string, maxBytes?: number, onGap?: "error" | "skip"): OutputReadResult;
+    /**
+     * 长轮询等待输出数据或通道关闭。
+     *
+     * 行为约束：
+     * - 状态检查与等待者登记位于同一同步边界，杜绝漏唤醒竞态。
+     * - 若已有数据、通道已关闭或超时时长小于等于 0，立即返回读取结果。
+     * - 严格校验等待者配额，超额抛出 QUOTA_EXCEEDED 异常。
+     * - 外部信号中止时立即清理等待者并不修改日志游标状态。
+     * - 等待超时且无新数据时返回空分块结果。
+     */
+    waitForData(cursor: string, waitMs: number, signal?: AbortSignal, options?: OutputReadOptions): Promise<OutputReadResult>;
+    private notifyWaiters;
+}