@actiondock/core 2.0.11 → 2.2.0

package/dist/ipc/target.js

@@ -0,0 +1,297 @@
+import { randomUUID } from "node:crypto";
+import { fork } from "node:child_process";
+import { DiagnosticForwarder } from "./diagnostic.js";
+import { EXECUTION_ABORTED, HOST_PROCESS_EXITED } from "../errors.js";
+/**
+ * 基于 Node IPC 监督进程通信通道的 ActionDockTarget 实现。
+ *
+ * 职责：
+ * 1. 监督并隔离子进程的生命周期与标准输出，保证父进程标准输入输出通道 100% 纯净。
+ * 2. 将子进程标准输出/错误通过 DiagnosticForwarder 进行受控排空与诊断流限流转发。
+ * 3. 当子进程异常终止时，立即将当前活跃调用转换为结构化 HOST_PROCESS_EXITED 错误，防止调用方死锁。
+ */
+export class IpcActionDockTarget {
+    child;
+    forwarder;
+    pendingCalls = new Map();
+    isClosed = false;
+    exitError;
+    readyPromise;
+    constructor(options) {
+        this.forwarder = new DiagnosticForwarder({
+            maxBytes: options.maxDiagnosticBytes,
+            maxRateBytesPerSec: options.maxDiagnosticRate,
+            target: options.diagnosticTarget,
+        });
+        if (options.childProcess) {
+            this.child = options.childProcess;
+        }
+        else if (options.scriptPath) {
+            this.child = fork(options.scriptPath, options.scriptArgs || [], {
+                cwd: options.cwd || process.cwd(),
+                env: options.env || process.env,
+                stdio: ["pipe", "pipe", "pipe", "ipc"],
+            });
+        }
+        else {
+            throw new Error("IpcActionDockTarget requires either 'childProcess' or 'scriptPath'");
+        }
+        // 绑定子进程输出至受控限流排空器，绝不泄露至 process.stdout
+        if (this.child.stdout) {
+            this.forwarder.attach(this.child.stdout, "stdout");
+        }
+        if (this.child.stderr) {
+            this.forwarder.attach(this.child.stderr, "stderr");
+        }
+        let resolveReady;
+        this.readyPromise = new Promise((r) => {
+            resolveReady = r;
+        });
+        this.child.on("message", (msg) => {
+            if (!msg || typeof msg !== "object")
+                return;
+            if (msg.type === "ready") {
+                resolveReady();
+            }
+            else if (msg.type === "response") {
+                const resp = msg;
+                const pending = this.pendingCalls.get(resp.id);
+                if (pending) {
+                    this.pendingCalls.delete(resp.id);
+                    if (resp.ok) {
+                        pending.resolve(resp.data);
+                    }
+                    else {
+                        const err = new Error(resp.error?.message || "IPC Target call failed");
+                        if (resp.error?.code)
+                            err.code = resp.error.code;
+                        if (resp.error?.details)
+                            err.details = resp.error.details;
+                        pending.reject(err);
+                    }
+                }
+            }
+        });
+        this.child.on("exit", (code, signal) => {
+            const exitMsg = `Host process exited prematurely with code ${code ?? signal ?? "unknown"}`;
+            const err = new Error(exitMsg);
+            err.code = "HOST_PROCESS_EXITED";
+            this.exitError = err;
+            this.isClosed = true;
+            // 快速失败所有待处理调用
+            for (const pending of this.pendingCalls.values()) {
+                if (pending.method === "runAction") {
+                    pending.resolve({
+                        ok: false,
+                        runId: randomUUID(),
+                        error: {
+                            code: HOST_PROCESS_EXITED,
+                            message: exitMsg,
+                        },
+                    });
+                }
+                else {
+                    pending.reject(err);
+                }
+            }
+            this.pendingCalls.clear();
+            resolveReady(); // 避免就绪死锁
+        });
+        this.child.on("error", (err) => {
+            this.exitError = err;
+        });
+    }
+    /**
+     * 等待宿主子进程初始化就绪。
+     */
+    async waitReady(timeoutMs = 5000) {
+        if (this.exitError)
+            throw this.exitError;
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Timeout waiting for host process ready after ${timeoutMs}ms`)), timeoutMs);
+        });
+        try {
+            await Promise.race([this.readyPromise, timeout]);
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
+    }
+    /**
+     * 获取底层子进程实例。
+     */
+    get process() {
+        return this.child;
+    }
+    async callRemote(method, args) {
+        if (this.isClosed || this.exitError) {
+            if (method === "runAction") {
+                return {
+                    ok: false,
+                    runId: randomUUID(),
+                    error: {
+                        code: HOST_PROCESS_EXITED,
+                        message: this.exitError?.message || "Host process is already closed",
+                    },
+                };
+            }
+            throw this.exitError || new Error("Host process is already closed");
+        }
+        const id = randomUUID();
+        const msg = {
+            id,
+            type: "call",
+            method,
+            args,
+        };
+        return new Promise((resolve, reject) => {
+            this.pendingCalls.set(id, { resolve, reject, method });
+            try {
+                if (this.child.send) {
+                    this.child.send(msg);
+                }
+                else {
+                    this.pendingCalls.delete(id);
+                    reject(new Error("IPC channel unavailable on child process"));
+                }
+            }
+            catch (err) {
+                this.pendingCalls.delete(id);
+                reject(err);
+            }
+        });
+    }
+    async info() {
+        return this.callRemote("info", []);
+    }
+    async listPackages() {
+        return this.callRemote("listPackages", []);
+    }
+    async listActions(options) {
+        return this.callRemote("listActions", [options]);
+    }
+    async describeAction(ref) {
+        return this.callRemote("describeAction", [ref]);
+    }
+    async listPlaybooks(options) {
+        return this.callRemote("listPlaybooks", [options]);
+    }
+    async describePlaybook(id) {
+        return this.callRemote("describePlaybook", [id]);
+    }
+    async runAction(ref, input, options) {
+        const { signal, ...serializableOptions } = options || {};
+        if (signal?.aborted) {
+            return {
+                ok: false,
+                runId: randomUUID(),
+                error: {
+                    code: EXECUTION_ABORTED,
+                    message: "Execution was aborted before starting",
+                },
+            };
+        }
+        return this.callRemote("runAction", [ref, input, serializableOptions]);
+    }
+    async startAction(ref, input, options) {
+        const { signal, ...serializableOptions } = options || {};
+        return this.callRemote("startAction", [ref, input, serializableOptions]);
+    }
+    async getRun(runId) {
+        const res = await this.callRemote("getRun", [runId]);
+        return res ?? undefined;
+    }
+    async cancelRun(runId) {
+        return this.callRemote("cancelRun", [runId]);
+    }
+    async listRuns(options) {
+        return this.callRemote("listRuns", [options]);
+    }
+    async *events(_runId, _options) {
+        // 基础 IPC 通道暂不流式下发历史事件
+    }
+    async listConfig(packageId) {
+        return this.callRemote("listConfig", [packageId]);
+    }
+    async getConfig(packageId, key) {
+        return this.callRemote("getConfig", [packageId, key]);
+    }
+    async setConfig(packageId, key, value) {
+        return this.callRemote("setConfig", [packageId, key, value]);
+    }
+    async deleteConfig(packageId, key) {
+        return this.callRemote("deleteConfig", [packageId, key]);
+    }
+    async getState(packageId, actionId, key, options) {
+        return this.callRemote("getState", [
+            packageId,
+            actionId,
+            key,
+            options,
+        ]);
+    }
+    async setState(packageId, actionId, key, value, options) {
+        return this.callRemote("setState", [packageId, actionId, key, value, options]);
+    }
+    async deleteState(packageId, actionId, key, options) {
+        return this.callRemote("deleteState", [packageId, actionId, key, options]);
+    }
+    async listStateKeys(packageId, actionId, options) {
+        return this.callRemote("listStateKeys", [packageId, actionId, options]);
+    }
+    async clearState(packageId, actionId, options) {
+        return this.callRemote("clearState", [packageId, actionId, options]);
+    }
+    async close() {
+        if (this.isClosed)
+            return;
+        if (this.child.exitCode !== null) {
+            this.forwarder.detachAll();
+            return;
+        }
+        const exitPromise = new Promise((resolve) => {
+            if (this.child.exitCode !== null) {
+                resolve();
+            }
+            else {
+                this.child.once("exit", () => resolve());
+            }
+        });
+        try {
+            if (this.child.connected) {
+                this.child.send({ type: "close" });
+            }
+        }
+        catch {
+            // 忽略发送关闭消息异常
+        }
+        // 若子进程超时未退出，先 SIGTERM 再 SIGKILL
+        const termTimer = setTimeout(() => {
+            if (this.child.exitCode === null) {
+                try {
+                    this.child.kill("SIGTERM");
+                }
+                catch { }
+            }
+        }, 1500);
+        const killTimer = setTimeout(() => {
+            if (this.child.exitCode === null) {
+                try {
+                    this.child.kill("SIGKILL");
+                }
+                catch { }
+            }
+        }, 3000);
+        try {
+            await exitPromise;
+        }
+        finally {
+            clearTimeout(termTimer);
+            clearTimeout(killTimer);
+            this.forwarder.detachAll();
+        }
+    }
+}

package/dist/ipc/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 监督进程与宿主子进程间调用的 IPC 请求消息。
+ */
+export interface IpcCallMessage {
+    id: string;
+    type: "call";
+    method: string;
+    args: unknown[];
+}
+/**
+ * 宿主子进程回复给监督进程的 IPC 响应消息。
+ */
+export interface IpcResponseMessage {
+    id: string;
+    type: "response";
+    ok: boolean;
+    data?: unknown;
+    error?: {
+        code?: string;
+        message: string;
+        stack?: string;
+        details?: unknown;
+    };
+}
+/**
+ * 宿主子进程向监督进程流式推送的执行事件。
+ */
+export interface IpcEventMessage {
+    type: "event";
+    runId: string;
+    event: unknown;
+}
+/**
+ * 宿主子进程初始化就绪通知。
+ */
+export interface IpcReadyMessage {
+    type: "ready";
+}
+/**
+ * 联合 IPC 消息类型。
+ */
+export type IpcMessage = IpcCallMessage | IpcResponseMessage | IpcEventMessage | IpcReadyMessage;

package/dist/ipc/types.js

@@ -0,0 +1 @@
+export {};

package/dist/platform/default.d.ts

@@ -0,0 +1,32 @@
+import type { ProcessAPI } from "@actiondock/sdk";
+import { type Clock } from "../runtime/clock.js";
+import { type ModuleLoader } from "../runtime/module-loader.js";
+import type { FileSystem, RuntimePlatform, StorageFactory } from "./types.js";
+/**
+ * 默认运行时平台构建选项。
+ */
+export interface DefaultPlatformOptions {
+    /** 平台名称覆盖（默认使用 node） */
+    name?: "node" | "test";
+    /** 自定义文件系统实现（默认使用 NodeFileSystem） */
+    files?: FileSystem;
+    /** 自定义时间与时钟驱动（默认使用 SystemClock） */
+    clock?: Clock;
+    /** 自定义进程执行驱动（默认使用 DefaultProcessExecutor） */
+    process?: ProcessAPI;
+    /** 自定义源码加载驱动（默认使用 DefaultModuleLoader） */
+    modules?: ModuleLoader;
+    /** 自定义存储工厂（默认基于 core/storage 构造） */
+    storage?: StorageFactory;
+    /** 自定义 ActionDock 家目录 */
+    customHome?: string;
+    /** 自定义全局数据存储目录 */
+    dataDir?: string;
+    /** 文件系统沙箱根目录 */
+    rootDir?: string;
+}
+/**
+ * 创建默认 RuntimePlatform 平台实例。
+ * 直接基于 Node 原生与 Core 内核能力组装平台，禁止任何全局单例状态。
+ */
+export declare function createDefaultPlatform(options?: DefaultPlatformOptions): RuntimePlatform;

package/dist/platform/default.js

@@ -0,0 +1,40 @@
+import { SystemClock } from "../runtime/clock.js";
+import { DefaultModuleLoader } from "../runtime/module-loader.js";
+import { DefaultProcessExecutor } from "../runtime/process.js";
+import { createGlobalStorage as coreCreateGlobalStorage, createStorage as coreCreateStorage, } from "../storage/index.js";
+import { NodeFileSystem } from "./node-fs.js";
+/**
+ * 创建默认 RuntimePlatform 平台实例。
+ * 直接基于 Node 原生与 Core 内核能力组装平台，禁止任何全局单例状态。
+ */
+export function createDefaultPlatform(options = {}) {
+    const platformName = options.name ?? "node";
+    const clock = options.clock ?? new SystemClock();
+    const files = options.files ?? new NodeFileSystem({ rootDir: options.rootDir });
+    const modules = options.modules ?? new DefaultModuleLoader();
+    const process = options.process ?? new DefaultProcessExecutor();
+    const storage = options.storage ?? {
+        createStorage(packageId, opts) {
+            return coreCreateStorage(packageId, {
+                customHome: options.customHome,
+                dataDir: options.dataDir,
+                ...opts,
+            });
+        },
+        createGlobalStorage(opts) {
+            return coreCreateGlobalStorage({
+                customHome: options.customHome,
+                dataDir: options.dataDir,
+                ...opts,
+            });
+        },
+    };
+    return {
+        name: platformName,
+        clock,
+        files,
+        modules,
+        process,
+        storage,
+    };
+}

package/dist/platform/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./node-fs.js";
+export * from "./default.js";

package/dist/platform/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./node-fs.js";
+export * from "./default.js";

package/dist/platform/node-fs.d.ts

@@ -0,0 +1,37 @@
+import type { FileStat, FileSystem } from "./types.js";
+/**
+ * NodeFileSystem 配置选项。
+ */
+export interface NodeFileSystemOptions {
+    /**
+     * 安全沙箱根路径。
+     * 若指定，则所有文件系统操作将被强制约束在 rootDir 边界内，防止路径遍历逃逸。
+     */
+    rootDir?: string;
+}
+/**
+ * 基于 node:fs 和 node:path 的安全受限文件系统实现。
+ */
+export declare class NodeFileSystem implements FileSystem {
+    private readonly rootDir?;
+    constructor(options?: NodeFileSystemOptions);
+    /**
+     * 安全解析并校验路径边界。
+     */
+    private resolvePath;
+    readFile(path: string, encoding?: string): Promise<string>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    readdir(dir: string): Promise<string[]>;
+    stat(path: string): Promise<FileStat>;
+    exists(path: string): Promise<boolean>;
+    mkdir(dir: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    copy(src: string, dest: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+}

package/dist/platform/node-fs.js

@@ -0,0 +1,81 @@
+import { promises as fs } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { assertPathWithinRoot } from "../utils/index.js";
+/**
+ * 基于 node:fs 和 node:path 的安全受限文件系统实现。
+ */
+export class NodeFileSystem {
+    rootDir;
+    constructor(options = {}) {
+        if (options.rootDir) {
+            this.rootDir = resolve(options.rootDir);
+        }
+    }
+    /**
+     * 安全解析并校验路径边界。
+     */
+    resolvePath(targetPath) {
+        if (typeof targetPath !== "string" || targetPath.includes("\0")) {
+            throw new Error("Invalid path: contains null byte or non-string argument");
+        }
+        if (this.rootDir) {
+            const resolved = isAbsolute(targetPath)
+                ? resolve(targetPath)
+                : resolve(this.rootDir, targetPath);
+            assertPathWithinRoot(this.rootDir, resolved);
+            return resolved;
+        }
+        return resolve(targetPath);
+    }
+    async readFile(path, encoding = "utf-8") {
+        const resolved = this.resolvePath(path);
+        return await fs.readFile(resolved, { encoding: (encoding || "utf-8") });
+    }
+    async writeFile(path, content) {
+        const resolved = this.resolvePath(path);
+        const parentDir = dirname(resolved);
+        await fs.mkdir(parentDir, { recursive: true });
+        await fs.writeFile(resolved, content);
+    }
+    async readdir(dir) {
+        const resolved = this.resolvePath(dir);
+        return await fs.readdir(resolved);
+    }
+    async stat(path) {
+        const resolved = this.resolvePath(path);
+        const s = await fs.stat(resolved);
+        return {
+            isDirectory: () => s.isDirectory(),
+            isFile: () => s.isFile(),
+            size: s.size,
+        };
+    }
+    async exists(path) {
+        try {
+            const resolved = this.resolvePath(path);
+            await fs.access(resolved);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async mkdir(dir, options) {
+        const resolved = this.resolvePath(dir);
+        await fs.mkdir(resolved, { recursive: options?.recursive ?? true });
+    }
+    async rm(path, options) {
+        const resolved = this.resolvePath(path);
+        await fs.rm(resolved, {
+            recursive: options?.recursive ?? true,
+            force: options?.force ?? true,
+        });
+    }
+    async copy(src, dest, options) {
+        const resolvedSrc = this.resolvePath(src);
+        const resolvedDest = this.resolvePath(dest);
+        const parentDir = dirname(resolvedDest);
+        await fs.mkdir(parentDir, { recursive: true });
+        await fs.cp(resolvedSrc, resolvedDest, { recursive: options?.recursive ?? true });
+    }
+}

package/dist/platform/types.d.ts

@@ -0,0 +1,104 @@
+import type { ProcessAPI } from "@actiondock/sdk";
+import type { Clock } from "../runtime/clock.js";
+import type { ModuleLoader } from "../runtime/module-loader.js";
+import type { RuntimeStorage } from "../storage/types.js";
+/**
+ * 文件元数据信息契约。
+ */
+export interface FileStat {
+    /** 是否为目录 */
+    isDirectory(): boolean;
+    /** 是否为普通文件 */
+    isFile(): boolean;
+    /** 文件字节大小 */
+    size: number;
+}
+/**
+ * 跨运行时统一文件系统抽象契约。
+ */
+export interface FileSystem {
+    /** 读取文件内容 */
+    readFile(path: string, encoding?: string): Promise<string> | string;
+    /** 写入文件内容 */
+    writeFile(path: string, content: string | Uint8Array): Promise<void> | void;
+    /** 读取目录下的所有条目名称 */
+    readdir(dir: string): Promise<string[]> | string[];
+    /** 获取路径对应条目的元数据状态 */
+    stat(path: string): Promise<{
+        isDirectory(): boolean;
+        isFile(): boolean;
+        size: number;
+    }>;
+    /** 检查路径是否存在 */
+    exists(path: string): Promise<boolean> | boolean;
+    /** 创建目录 */
+    mkdir(dir: string, options?: {
+        recursive?: boolean;
+    }): Promise<void> | void;
+    /** 删除文件或目录 */
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void> | void;
+    /** 拷贝文件或目录 */
+    copy(src: string, dest: string, options?: {
+        recursive?: boolean;
+    }): Promise<void> | void;
+}
+/**
+ * 跨运行时持久化存储工厂配置选项。
+ */
+export interface StorageFactoryOptions {
+    projectRoot?: string;
+    dataDir?: string;
+    inMemory?: boolean;
+    customHome?: string;
+}
+/**
+ * 跨运行时全局存储工厂配置选项。
+ */
+export interface GlobalStorageFactoryOptions {
+    dataDir?: string;
+    inMemory?: boolean;
+    customHome?: string;
+}
+/**
+ * 跨运行时持久化存储工厂契约。
+ */
+export interface StorageFactory {
+    /**
+     * 为指定 Package 创建或连接运行时存储。
+     */
+    createStorage(packageId: string, options?: StorageFactoryOptions): RuntimeStorage;
+    /**
+     * 创建或连接跨 Package 共享的全局存储。
+     */
+    createGlobalStorage(options?: GlobalStorageFactoryOptions): RuntimeStorage;
+}
+/**
+ * 跨运行时 HTTP 服务启动工厂契约。
+ */
+export interface HttpServerFactory {
+    /**
+     * 启动 HTTP 服务端实例。
+     */
+    launchHttpServer(options: any): Promise<any>;
+}
+/**
+ * 运行时底层环境核心标准契约。
+ * 提供统一的运行时契约，屏蔽宿主平台与测试沙箱环境的实现差异。
+ */
+export interface RuntimePlatform {
+    /** 运行时平台名称标识 */
+    readonly name: "node" | "test";
+    /** 统一时间与时钟驱动 */
+    readonly clock: Clock;
+    /** 统一文件系统操作驱动 */
+    readonly files: FileSystem;
+    /** 动态源码模块加载驱动 */
+    readonly modules: ModuleLoader;
+    /** 子进程衍生与执行驱动 */
+    readonly process: ProcessAPI;
+    /** 持久化数据库存储驱动工厂 */
+    readonly storage: StorageFactory;
+}

package/dist/platform/types.js

@@ -0,0 +1 @@
+export {};