@actiondock/core 2.2.2 → 2.3.0

package/dist/process/driver.d.ts

@@ -0,0 +1,214 @@
+import type { Capabilities, LaunchSpec } from "@actiondock/sdk";
+/**
+ * 进程驱动实例底层控制句柄接口。
+ */
+export interface ProcessDriverHandle {
+    /**
+     * 向受管进程标准输入通道写入原始字节数据。
+     *
+     * @param data 原始字节切片
+     */
+    write(data: Uint8Array): Promise<void>;
+    /**
+     * 关闭标准输入流发送 EOF 信号。
+     */
+    sendInputEOF?(): Promise<void>;
+    /**
+     * 向进程前台作业组发送中断信号。
+     */
+    interruptForeground?(): Promise<void>;
+    /**
+     * 动态调整伪终端窗口尺寸。
+     *
+     * @param cols 列数
+     * @param rows 行数
+     */
+    resize?(cols: number, rows: number): Promise<void>;
+    /**
+     * 优雅终止或强制终止底层进程。
+     *
+     * @param graceMs 优雅退出宽限时限（毫秒）
+     */
+    terminate(graceMs: number): Promise<{
+        code: number | null;
+        signal: string | null;
+    } | void>;
+}
+/**
+ * 进程驱动底层事件回调接口。
+ */
+export interface ProcessDriverCallbacks {
+    /**
+     * 接收来自进程的原始输出字节切片。
+     *
+     * @param stream 输出流来源标签
+     * @param data 原始字节切片
+     */
+    onOutput(stream: "stdout" | "stderr" | "pty", data: Uint8Array): void;
+    /**
+     * 进程退出时触发。
+     *
+     * @param exit 退出状态码与信号
+     */
+    onExit(exit: {
+        code: number | null;
+        signal: string | null;
+    }): void;
+    /**
+     * 输出通道彻底关闭时触发。
+     *
+     * @param reason 关闭原因：自然关闭、drain 超时或宿主丢失
+     */
+    onOutputClosed?(reason: "natural" | "drain-timeout" | "host-lost"): void;
+    /**
+     * 进程发生底层错误时触发。
+     *
+     * @param err 异常对象
+     */
+    onError(err: Error): void;
+}
+/**
+ * 默认允许继承的环境变量白名单。
+ */
+export declare const DEFAULT_ENV_ALLOWLIST: readonly string[];
+/**
+ * 解析并生成子进程生效环境变量集合。
+ *
+ * @param envConfig 启动规范中的环境变量配置
+ * @param hostEnv 宿主环境变量字典，默认为 process.env
+ */
+export declare function resolveProcessEnv(envConfig?: LaunchSpec["env"], hostEnv?: Record<string, string | undefined>): Record<string, string>;
+/**
+ * 进程观察者接口，接收来自底层驱动的流输出与生命周期通知。
+ */
+export interface ProcessObserver {
+    /**
+     * 接收来自进程的输出数据。
+     *
+     * @param stream 输出流类型
+     * @param data 原始字节切片
+     */
+    output(stream: "stdout" | "stderr" | "pty", data: Uint8Array): void;
+    /**
+     * 进程退出通知。
+     *
+     * @param result 退出状态码与信号
+     */
+    exited(result: {
+        code: number | null;
+        signal: string | null;
+    }): void;
+    /**
+     * 输出流彻底关闭通知。
+     *
+     * @param reason 关闭原因：自然关闭、drain 超时或宿主丢失
+     */
+    outputClosed(reason: "natural" | "drain-timeout" | "host-lost"): void;
+    /**
+     * 底层驱动故障通知。
+     *
+     * @param error 故障异常对象
+     */
+    fault?(error: Error): void;
+}
+/**
+ * 进程驱动句柄接口。
+ */
+export interface ProcessHandle {
+    /** 句柄唯一标识 */
+    readonly id: string;
+    /** 操作系统进程标识符（若可用） */
+    readonly pid?: number;
+}
+/**
+ * 受管进程底层执行驱动接口。
+ */
+export interface ProcessDriver {
+    /**
+     * 查询当前驱动支持的运行时能力集快照。
+     */
+    getCapabilities(): Capabilities;
+    /**
+     * 依据《Managed Process 设计 v2》标准接口派生新进程。
+     *
+     * @param spec 进程启动规范
+     * @param observer 进程生命周期与输出观察者
+     */
+    spawn(spec: LaunchSpec, observer: ProcessObserver): Promise<ProcessHandle>;
+    /**
+     * 兼容旧版基于 processId 派生新进程签名。
+     */
+    spawn(processId: string, spec: LaunchSpec, callbacks: ProcessDriverCallbacks): Promise<ProcessDriverHandle>;
+    /**
+     * 向受管进程标准输入写入字节数据。
+     *
+     * @param handle 进程句柄
+     * @param data 原始字节数据
+     */
+    write?(handle: ProcessHandle, data: Uint8Array): Promise<void>;
+    /**
+     * 关闭标准输入流发送 EOF 信号。
+     */
+    inputEOF?(handle: ProcessHandle): Promise<void>;
+    /**
+     * 向进程前台作业组发送中断信号。
+     */
+    interruptForeground?(handle: ProcessHandle): Promise<void>;
+    /**
+     * 动态调整终端窗口尺寸。
+     */
+    resize?(handle: ProcessHandle, cols: number, rows: number): Promise<void>;
+    /**
+     * 优雅终止或强制终止底层进程。
+     */
+    terminate(handle: ProcessHandle, graceMs: number): Promise<void>;
+    terminate(processId: string, graceMs: number): Promise<void>;
+    /**
+     * 销毁进程句柄并清理关联资源。
+     */
+    dispose?(handle: ProcessHandle): Promise<void>;
+}
+/**
+ * 内存模拟进程驱动实现，专用于确定性测试与离线环境。
+ */
+export declare class MemoryProcessDriver implements ProcessDriver {
+    private capabilities;
+    handles: Map<string, MemoryProcessDriverHandle>;
+    spawnHook?: (processId: string, spec: LaunchSpec, callbacks: ProcessDriverCallbacks) => Promise<MemoryProcessDriverHandle | void> | MemoryProcessDriverHandle | void;
+    constructor(capabilities?: Partial<Capabilities>);
+    getCapabilities(): Capabilities;
+    setCapabilities(caps: Partial<Capabilities>): void;
+    spawn(specOrProcessId: LaunchSpec | string, observerOrSpec: ProcessObserver | LaunchSpec, maybeCallbacks?: ProcessDriverCallbacks): Promise<any>;
+    terminate(handleOrId: ProcessHandle | string, graceMs: number): Promise<void>;
+}
+/**
+ * 内存模拟进程驱动句柄实现。
+ */
+export declare class MemoryProcessDriverHandle implements ProcessDriverHandle, ProcessHandle {
+    readonly id: string;
+    readonly processId: string;
+    readonly spec: LaunchSpec;
+    readonly callbacks: ProcessDriverCallbacks;
+    writtenChunks: Uint8Array[];
+    eofSent: boolean;
+    interrupted: boolean;
+    currentSize?: {
+        cols: number;
+        rows: number;
+    };
+    terminated: boolean;
+    writeFailureError?: Error;
+    constructor(processId: string, spec: LaunchSpec, callbacks: ProcessDriverCallbacks);
+    write(data: Uint8Array): Promise<void>;
+    sendInputEOF(): Promise<void>;
+    interruptForeground(): Promise<void>;
+    resize(cols: number, rows: number): Promise<void>;
+    terminate(graceMs: number): Promise<{
+        code: number | null;
+        signal: string | null;
+    }>;
+    emitOutput(stream: "stdout" | "stderr" | "pty", textOrBytes: string | Uint8Array): void;
+    emitExit(code?: number | null, signal?: string | null): void;
+    emitOutputClosed(reason?: "natural" | "drain-timeout" | "host-lost"): void;
+    emitError(err: Error): void;
+}

package/dist/process/driver.js

@@ -0,0 +1,197 @@
+/**
+ * 默认允许继承的环境变量白名单。
+ */
+export const DEFAULT_ENV_ALLOWLIST = Object.freeze([
+    "PATH",
+    "PATHEXT",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TERM",
+    "TZ",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+    "SYSTEMROOT",
+    "SYSTEMDRIVE",
+    "COMSPEC",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "USERPROFILE",
+    "HOMEDRIVE",
+    "HOMEPATH",
+    "WINDIR",
+]);
+/**
+ * 解析并生成子进程生效环境变量集合。
+ *
+ * @param envConfig 启动规范中的环境变量配置
+ * @param hostEnv 宿主环境变量字典，默认为 process.env
+ */
+export function resolveProcessEnv(envConfig, hostEnv = process.env) {
+    const inherit = envConfig?.inherit ?? "allowlisted";
+    const result = {};
+    if (inherit === "allowlisted") {
+        const isWin = process.platform === "win32";
+        const allowSet = new Set(DEFAULT_ENV_ALLOWLIST.map((key) => (isWin ? key.toUpperCase() : key)));
+        for (const [key, value] of Object.entries(hostEnv)) {
+            if (value === undefined)
+                continue;
+            const lookupKey = isWin ? key.toUpperCase() : key;
+            if (allowSet.has(lookupKey)) {
+                result[key] = value;
+            }
+        }
+    }
+    if (envConfig?.set) {
+        for (const [key, value] of Object.entries(envConfig.set)) {
+            result[key] = value;
+        }
+    }
+    if (envConfig?.unset) {
+        const isWin = process.platform === "win32";
+        for (const unsetKey of envConfig.unset) {
+            if (isWin) {
+                const unsetUpper = unsetKey.toUpperCase();
+                for (const existingKey of Object.keys(result)) {
+                    if (existingKey.toUpperCase() === unsetUpper) {
+                        delete result[existingKey];
+                    }
+                }
+            }
+            else {
+                delete result[unsetKey];
+            }
+        }
+    }
+    return result;
+}
+/**
+ * 内存模拟进程驱动实现，专用于确定性测试与离线环境。
+ */
+export class MemoryProcessDriver {
+    capabilities;
+    handles = new Map();
+    spawnHook;
+    constructor(capabilities) {
+        this.capabilities = {
+            pty: true,
+            resize: true,
+            inputEOF: true,
+            interruptForeground: true,
+            terminationScope: "process-tree",
+            ...capabilities,
+        };
+    }
+    getCapabilities() {
+        return { ...this.capabilities };
+    }
+    setCapabilities(caps) {
+        this.capabilities = { ...this.capabilities, ...caps };
+    }
+    async spawn(specOrProcessId, observerOrSpec, maybeCallbacks) {
+        if (typeof specOrProcessId === "string") {
+            const processId = specOrProcessId;
+            const spec = observerOrSpec;
+            const callbacks = maybeCallbacks;
+            if (this.spawnHook) {
+                const customHandle = await this.spawnHook(processId, spec, callbacks);
+                if (customHandle) {
+                    this.handles.set(processId, customHandle);
+                    return customHandle;
+                }
+            }
+            const handle = new MemoryProcessDriverHandle(processId, spec, callbacks);
+            this.handles.set(processId, handle);
+            return handle;
+        }
+        const spec = specOrProcessId;
+        const observer = observerOrSpec;
+        const processId = `mem-${Math.random().toString(36).slice(2, 10)}`;
+        const callbacks = {
+            onOutput(stream, data) {
+                observer.output(stream, data);
+            },
+            onExit(exit) {
+                observer.exited(exit);
+            },
+            onOutputClosed(reason) {
+                observer.outputClosed(reason ?? "natural");
+            },
+            onError(err) {
+                observer.fault?.(err);
+            },
+        };
+        const handle = new MemoryProcessDriverHandle(processId, spec, callbacks);
+        this.handles.set(processId, handle);
+        return handle;
+    }
+    async terminate(handleOrId, graceMs) {
+        const id = typeof handleOrId === "string" ? handleOrId : handleOrId.id;
+        const handle = this.handles.get(id);
+        if (handle) {
+            await handle.terminate(graceMs);
+        }
+    }
+}
+/**
+ * 内存模拟进程驱动句柄实现。
+ */
+export class MemoryProcessDriverHandle {
+    id;
+    processId;
+    spec;
+    callbacks;
+    writtenChunks = [];
+    eofSent = false;
+    interrupted = false;
+    currentSize;
+    terminated = false;
+    writeFailureError;
+    constructor(processId, spec, callbacks) {
+        this.id = processId;
+        this.processId = processId;
+        this.spec = spec;
+        this.callbacks = callbacks;
+    }
+    async write(data) {
+        if (this.writeFailureError) {
+            throw this.writeFailureError;
+        }
+        this.writtenChunks.push(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+    }
+    async sendInputEOF() {
+        this.eofSent = true;
+    }
+    async interruptForeground() {
+        this.interrupted = true;
+    }
+    async resize(cols, rows) {
+        this.currentSize = { cols, rows };
+    }
+    async terminate(graceMs) {
+        this.terminated = true;
+        const exitResult = { code: null, signal: "SIGTERM" };
+        this.callbacks.onExit(exitResult);
+        return exitResult;
+    }
+    emitOutput(stream, textOrBytes) {
+        const bytes = typeof textOrBytes === "string"
+            ? new TextEncoder().encode(textOrBytes)
+            : textOrBytes;
+        this.callbacks.onOutput(stream, bytes);
+    }
+    emitExit(code = 0, signal = null) {
+        this.callbacks.onExit({ code, signal });
+    }
+    emitOutputClosed(reason = "natural") {
+        this.callbacks.onOutputClosed?.(reason);
+    }
+    emitError(err) {
+        this.callbacks.onError(err);
+    }
+}

package/dist/process/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./cursor.js";
+export * from "./output-log.js";
+export * from "./metadata-store.js";
+export * from "./driver.js";
+export * from "./process-manager.js";
+export * from "./context-process.js";

package/dist/process/index.js

@@ -0,0 +1,6 @@
+export * from "./cursor.js";
+export * from "./output-log.js";
+export * from "./metadata-store.js";
+export * from "./driver.js";
+export * from "./process-manager.js";
+export * from "./context-process.js";

package/dist/process/metadata-store.d.ts

@@ -0,0 +1,205 @@
+import type { SqliteDriver } from "../storage/types.js";
+/**
+ * 受管进程运行状态。
+ */
+export type ProcessState = "starting" | "running" | "stopping" | "stopped" | "failed" | "lost" | "killed" | "completed" | string;
+/**
+ * 受管进程控制通道状态。
+ */
+export type ProcessControlState = "open" | "closing" | "closed" | string;
+/**
+ * 进程终止原因。
+ */
+export type ProcessEndReason = "exit" | "host-lost" | "timeout" | "signal" | "error" | "killed" | string;
+/**
+ * 进程输入输出配置。
+ */
+export interface ProcessIOConfig {
+    [key: string]: unknown;
+}
+/**
+ * 进程能力集定义。
+ */
+export interface ProcessCapabilities {
+    [key: string]: unknown;
+}
+/**
+ * 进程生效资源限制配置。
+ */
+export interface ProcessEffectiveLimits {
+    [key: string]: unknown;
+}
+/**
+ * 受管进程核心模型信息。
+ */
+export interface ProcessInfo {
+    processId: string;
+    hostEpoch: string;
+    state: ProcessState;
+    controlState?: ProcessControlState;
+    control?: ProcessControlState;
+    ioConfig?: ProcessIOConfig;
+    capabilities?: ProcessCapabilities;
+    createdAt?: string;
+    exitCode?: number | null;
+    exitSignal?: string | null;
+    endReason?: ProcessEndReason | null;
+    outputClosed?: boolean;
+    outputEndReason?: string | null;
+    /** 输入通道是否已发送 EOF 彻底关闭 */
+    inputClosed?: boolean;
+    effectiveLimits?: ProcessEffectiveLimits;
+}
+/**
+ * 带有归属所有者与请求凭据的持久化进程记录。
+ */
+export type StoredProcessRecord = ProcessInfo & {
+    tenantId: string;
+    principalId: string;
+    packageInstanceId: string;
+    generationId: string;
+    startRequestId?: string;
+};
+/**
+ * 进程所有者过滤条件。
+ */
+export interface ProcessOwnerFilter {
+    tenantId: string;
+    principalId: string;
+    packageInstanceId: string;
+    generationId: string;
+}
+/**
+ * 操作请求去重查询键。
+ */
+export interface ProcessRequestKey {
+    hostEpoch: string;
+    scope: string;
+    processId?: string;
+    requestId: string;
+}
+/**
+ * 操作回执凭证。
+ */
+export interface OperationReceipt {
+    status?: string;
+    result?: unknown;
+    error?: unknown;
+    timestamp?: string;
+    [key: string]: unknown;
+}
+/**
+ * 操作请求记录项。
+ */
+export interface RequestRecord {
+    receipt: OperationReceipt;
+    payloadHash?: string;
+    createdAt?: string;
+}
+/**
+ * 受管进程元数据存储契约接口。
+ */
+export interface ProcessMetadataStore {
+    /**
+     * 保存或替换受管进程元数据。
+     */
+    saveProcess(process: StoredProcessRecord): Promise<void>;
+    /**
+     * 按进程标识获取受管进程元数据详情。
+     */
+    getProcess(processId: string): Promise<StoredProcessRecord | undefined>;
+    /**
+     * 分页列出指定所有者归属下的受管进程列表。
+     */
+    listProcesses(owner: ProcessOwnerFilter, pageToken?: string, limit?: number): Promise<{
+        processes: ProcessInfo[];
+        nextPageToken?: string;
+    }>;
+    /**
+     * 局部更新受管进程状态字段。
+     */
+    updateProcessState(processId: string, patch: Partial<ProcessInfo>): Promise<void>;
+    /**
+     * 记录幂等请求与操作凭据。
+     */
+    recordRequest(key: ProcessRequestKey, receipt: OperationReceipt, payloadHash?: string): Promise<void>;
+    /**
+     * 获取幂等请求已记录的操作凭据。
+     */
+    getRequest(key: ProcessRequestKey): Promise<{
+        receipt: OperationReceipt;
+        payloadHash?: string;
+    } | undefined>;
+    /**
+     * 宿主生命周期初始化与故障收敛：
+     * 将所有不属于当前 hostEpoch 且处于非终态（starting/running/stopping）的旧进程状态更新为 lost。
+     */
+    initializeHost(hostEpoch: string): Promise<number>;
+    /**
+     * 释放存储资源（如关闭数据库连接）。
+     */
+    close?(): Promise<void> | void;
+}
+/**
+ * 内存型受管进程元数据存储实现。
+ * 适用于确定性测试与无持久化文件系统运行场景。
+ */
+export declare class MemoryProcessMetadataStore implements ProcessMetadataStore {
+    private processes;
+    private requests;
+    private formatRequestKey;
+    saveProcess(process: StoredProcessRecord): Promise<void>;
+    getProcess(processId: string): Promise<StoredProcessRecord | undefined>;
+    listProcesses(owner: ProcessOwnerFilter, pageToken?: string, limit?: number): Promise<{
+        processes: ProcessInfo[];
+        nextPageToken?: string;
+    }>;
+    updateProcessState(processId: string, patch: Partial<ProcessInfo>): Promise<void>;
+    recordRequest(key: ProcessRequestKey, receipt: OperationReceipt, payloadHash?: string): Promise<void>;
+    getRequest(key: ProcessRequestKey): Promise<{
+        receipt: OperationReceipt;
+        payloadHash?: string;
+    } | undefined>;
+    initializeHost(hostEpoch: string): Promise<number>;
+    clear(): void;
+}
+/**
+ * SQLite 存储选项。
+ */
+export interface SqliteProcessMetadataStoreOptions {
+    dbPath?: string;
+    driver?: SqliteDriver;
+}
+/**
+ * 基于 SQLite 的受管进程元数据持久化存储实现。
+ */
+export declare class SqliteProcessMetadataStore implements ProcessMetadataStore {
+    private driver;
+    private statementCache;
+    private isClosed;
+    constructor(options?: SqliteProcessMetadataStoreOptions);
+    private initTables;
+    /**
+     * 旧库结构迁移：逐列探测并补充新增字段，重复执行安全（幂等）。
+     */
+    private migrateSchema;
+    /**
+     * 枚举指定表的全部列定义。
+     */
+    private listTableColumns;
+    private getStatement;
+    saveProcess(process: StoredProcessRecord): Promise<void>;
+    getProcess(processId: string): Promise<StoredProcessRecord | undefined>;
+    listProcesses(owner: ProcessOwnerFilter, pageToken?: string, limit?: number): Promise<{
+        processes: ProcessInfo[];
+        nextPageToken?: string;
+    }>;
+    updateProcessState(processId: string, patch: Partial<ProcessInfo>): Promise<void>;
+    recordRequest(key: ProcessRequestKey, receipt: OperationReceipt, payloadHash?: string): Promise<void>;
+    getRequest(key: ProcessRequestKey): Promise<{
+        receipt: OperationReceipt;
+        payloadHash?: string;
+    } | undefined>;
+    initializeHost(hostEpoch: string): Promise<number>;
+    close(): void;
+}