@actiondock/core 2.6.0 → 2.8.0

package/dist/ipc/service.js

@@ -0,0 +1,349 @@
+import { randomUUID } from "node:crypto";
+import { fork } from "node:child_process";
+import { DiagnosticForwarder } from "./diagnostic.js";
+import { ActionDockError, CAPABILITY_UNAVAILABLE, EXECUTION_ABORTED, HOST_PROCESS_EXITED, IPC_ERROR, SERVICE_CLOSED, } from "../errors.js";
+/**
+ * 跨进程取消信号占位标记字段名。
+ * AbortSignal 不可序列化，序列化 options 时把 signal 字段替换为该标记，
+ * 宿主侧识别后重建 AbortController 并接入 abort 消息通知链路。
+ */
+export const IPC_SIGNAL_MARKER = "__ipcSignal";
+/**
+ * 判断执行选项中是否携带跨进程取消信号占位标记。
+ */
+export function hasIpcSignalMarker(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[IPC_SIGNAL_MARKER] === true);
+}
+/**
+ * 序列化执行选项：剥离不可序列化的 AbortSignal 并写入占位标记。
+ */
+function markIpcSignal(options) {
+    if (!options)
+        return undefined;
+    const clean = {};
+    if (options.timeoutMs !== undefined)
+        clean.timeoutMs = options.timeoutMs;
+    if (options.config !== undefined)
+        clean.config = options.config;
+    if (options.requestId !== undefined)
+        clean.requestId = options.requestId;
+    if (options.signal) {
+        clean[IPC_SIGNAL_MARKER] = true;
+    }
+    return clean;
+}
+/**
+ * 基于 Node IPC 监督进程通信通道的 ActionDockService 实现。
+ * 遵循标准 Service Ports 体系，隔离子进程生命周期并暴露结构化服务端口。
+ */
+export class IpcActionDockService {
+    child;
+    forwarder;
+    pendingCalls = new Map();
+    isClosed = false;
+    exitError;
+    readyPromise;
+    discovery;
+    execution;
+    runs;
+    management;
+    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("IpcActionDockService requires either 'childProcess' or 'scriptPath'");
+        }
+        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 ActionDockError(resp.error?.code || IPC_ERROR, resp.error?.message || "IPC Service call failed", 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 ActionDockError(HOST_PROCESS_EXITED, exitMsg);
+            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();
+            this.forwarder.detachAll();
+            resolveReady();
+        });
+        const self = this;
+        /**
+         * 生成方法级端口转发器：把端口方法调用映射为 callRemote 远端调用。
+         * 方法名与参数列表的对应关系即唯一事实源，杜绝手写转发样板膨胀。
+         */
+        const forward = (method, args) => self.callRemote(method, args);
+        this.discovery = {
+            async listPackages() {
+                return forward("listPackages", []);
+            },
+            async listActions(opts) {
+                return forward("listActions", [opts]);
+            },
+            async describeAction(ref) {
+                return forward("describeAction", [ref]);
+            },
+            async listPlaybooks(opts) {
+                return forward("listPlaybooks", [opts]);
+            },
+            async describePlaybook(id) {
+                return forward("describePlaybook", [id]);
+            },
+        };
+        this.execution = {
+            async run(ref, input, opts) {
+                if (opts?.signal?.aborted) {
+                    return {
+                        ok: false,
+                        runId: randomUUID(),
+                        error: {
+                            code: EXECUTION_ABORTED,
+                            message: "Execution was aborted before starting",
+                        },
+                    };
+                }
+                const serializableOptions = markIpcSignal(opts);
+                return self.callRemote("runAction", [ref, input ?? {}, serializableOptions], opts?.signal);
+            },
+            async start(ref, input, opts) {
+                if (opts?.signal?.aborted) {
+                    throw new ActionDockError(EXECUTION_ABORTED, "Execution was aborted before starting");
+                }
+                const serializableOptions = markIpcSignal(opts);
+                return self.callRemote("startAction", [ref, input ?? {}, serializableOptions], opts?.signal);
+            },
+        };
+        this.runs = {
+            async list(query) {
+                return forward("listRuns", [query]);
+            },
+            async get(runId) {
+                const res = await forward("getRun", [runId]);
+                return res ?? undefined;
+            },
+            async cancel(runId, reason) {
+                return forward("cancelRun", [runId, reason]);
+            },
+            async clear(opts) {
+                return forward("clearRuns", [opts]);
+            },
+        };
+        if (options.enableManagement !== false) {
+            this.management = {
+                config: {
+                    async get(packageId, key) {
+                        return forward("getConfig", [packageId, key]);
+                    },
+                    async set(packageId, key, value) {
+                        return forward("setConfig", [packageId, key, value]);
+                    },
+                    async delete(packageId, key) {
+                        return forward("deleteConfig", [packageId, key]);
+                    },
+                    async list(packageId) {
+                        return forward("listConfig", [packageId]);
+                    },
+                },
+                state: {
+                    async get(packageId, actionId, key, opts) {
+                        return forward("getState", [packageId, actionId, key, opts]);
+                    },
+                    async set(packageId, actionId, key, value, opts) {
+                        return forward("setState", [packageId, actionId, key, value, opts]);
+                    },
+                    async delete(packageId, actionId, key, opts) {
+                        return forward("deleteState", [packageId, actionId, key, opts]);
+                    },
+                    async list(packageId, actionId, opts) {
+                        return forward("listStateKeys", [packageId, actionId, opts]);
+                    },
+                    async clear(packageId, actionId, opts) {
+                        return forward("clearState", [packageId, actionId, opts]);
+                    },
+                    async listEntries(packageId, opts) {
+                        return forward("listStateEntries", [packageId, opts]);
+                    },
+                },
+            };
+        }
+    }
+    async callRemote(method, args, signal) {
+        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 ActionDockError(SERVICE_CLOSED, `IpcActionDockService is closed: cannot call '${method}'`);
+        }
+        await this.readyPromise;
+        if (signal?.aborted) {
+            const err = new Error(signal.reason ? String(signal.reason) : "Operation aborted");
+            err.name = "AbortError";
+            throw err;
+        }
+        const id = randomUUID();
+        const message = {
+            id,
+            type: "call",
+            method,
+            args,
+        };
+        let onAbort;
+        if (signal && !signal.aborted) {
+            onAbort = () => {
+                this.sendAbort(id);
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+        return new Promise((resolve, reject) => {
+            this.pendingCalls.set(id, { resolve, reject, method });
+            try {
+                if (!this.child.send) {
+                    throw new ActionDockError(CAPABILITY_UNAVAILABLE, "ChildProcess IPC channel is not available");
+                }
+                this.child.send(message, (err) => {
+                    if (err) {
+                        this.pendingCalls.delete(id);
+                        reject(err);
+                    }
+                });
+            }
+            catch (err) {
+                this.pendingCalls.delete(id);
+                reject(err);
+            }
+        }).finally(() => {
+            if (onAbort && signal) {
+                signal.removeEventListener("abort", onAbort);
+            }
+        });
+    }
+    sendAbort(id) {
+        if (this.isClosed)
+            return;
+        try {
+            const abortMsg = { id, type: "abort" };
+            if (this.child.send) {
+                this.child.send(abortMsg);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[IPC Service] Failed to send abort for call '${id}': ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    async info() {
+        return this.discovery.listPackages();
+    }
+    get process() {
+        return this.child;
+    }
+    async waitReady() {
+        return this.readyPromise;
+    }
+    async close() {
+        if (this.isClosed)
+            return;
+        if (this.child.exitCode !== null) {
+            this.forwarder.detachAll();
+            return;
+        }
+        const exitPromise = new Promise((resolve) => {
+            this.child.once("exit", () => resolve());
+        });
+        try {
+            if (this.child.connected) {
+                this.child.send({ type: "close" });
+            }
+        }
+        catch {
+            // 忽略发送关闭消息异常
+        }
+        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

@@ -32,20 +32,26 @@ export interface IpcResponseMessage {
     };
 }
 /**
- * 宿主子进程向监督进程流式推送的执行事件。
+ * 监督进程 IPC 服务初始化选项。
  */
-export interface IpcEventMessage {
-    type: "event";
-    runId: string;
-    event: unknown;
+export interface IpcServiceOptions {
+    type?: "ipc";
+    /** 已启动的子进程实例（需具备 IPC 通道） */
+    childProcess?: any;
+    /** 待启动的脚本物理路径 */
+    scriptPath?: string;
+    /** 启动参数 */
+    scriptArgs?: string[];
+    /** 工作目录 */
+    cwd?: string;
+    /** 环境变量 */
+    env?: NodeJS.ProcessEnv;
+    /** 诊断流最大缓冲字节数 */
+    maxDiagnosticBytes?: number;
+    /** 诊断流每秒最大字节速率 */
+    maxDiagnosticRate?: number;
+    /** 诊断流目标输出 */
+    diagnosticTarget?: any;
+    /** 是否启用管理端口（默认 true） */
+    enableManagement?: boolean;
 }
-/**
- * 宿主子进程初始化就绪通知。
- */
-export interface IpcReadyMessage {
-    type: "ready";
-}
-/**
- * 联合 IPC 消息类型。
- */
-export type IpcMessage = IpcCallMessage | IpcResponseMessage | IpcAbortMessage | IpcEventMessage | IpcReadyMessage;

package/dist/json/index.d.ts

@@ -0,0 +1 @@
+export * from "./value-validator.js";

package/dist/json/index.js

@@ -0,0 +1 @@
+export * from "./value-validator.js";

package/dist/json/value-validator.d.ts

@@ -0,0 +1,88 @@
+import type { JsonValue } from "@actiondock/sdk";
+/** 默认 JSON 最大嵌套深度限制（防止恶意超深结构） */
+export declare const DEFAULT_MAX_JSON_DEPTH = 256;
+/**
+ * JSON 结构校验选项。
+ */
+export interface ValidateJsonOptions {
+    /** 最大允许嵌套深度（默认 256） */
+    maxDepth?: number;
+}
+/**
+ * Action 输入校验选项。
+ */
+export interface ValidateActionInputOptions extends ValidateJsonOptions {
+}
+/**
+ * JSON 值校验错误码类型。
+ */
+export type JsonValueValidationErrorCode = "NON_FINITE_NUMBER" | "MAX_JSON_DEPTH" | "CIRCULAR_REFERENCE" | "UNSUPPORTED_JSON_TYPE" | "INVALID_JSON_OBJECT" | "UNDEFINED_JSON_VALUE";
+/**
+ * Canonical JsonValue 校验结果。
+ */
+export type JsonValueValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    code: JsonValueValidationErrorCode;
+    reason: string;
+    path?: string;
+};
+/**
+ * Action 输入值校验结果（包含策略违规分支）。
+ */
+export type ActionInputValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    kind: "json-value";
+    code: JsonValueValidationErrorCode;
+    reason: string;
+    path?: string;
+} | {
+    valid: false;
+    kind: "input-policy";
+    code: "FORBIDDEN_PROPERTY";
+    property: string;
+    path: string;
+    reason: string;
+};
+/**
+ * 按照 RFC 6901 转义单个 JSON Pointer 路径段。
+ *
+ * @param segment 路径段（属性名或数组索引）
+ * @returns 转义后的路径段
+ */
+export declare function escapeJsonPointerSegment(segment: string | number): string;
+/**
+ * 将路径段追加到基础 RFC 6901 JSON Pointer 路径后。
+ *
+ * @param basePath 基础路径
+ * @param segment 待追加的路径段
+ * @returns 拼接后的 JSON Pointer
+ */
+export declare function appendJsonPointer(basePath: string, segment: string | number): string;
+/**
+ * 校验值是否为合法的 Canonical JSON 兼容结构。
+ *
+ * @param value 待校验的目标值
+ * @param options 校验配置选项
+ * @returns 校验结果对象
+ */
+export declare function validateJsonValue(value: unknown, options?: ValidateJsonOptions): JsonValueValidationResult;
+/**
+ * 校验 Action 输入值是否满足 Canonical JsonValue 规范且符合 ActionDock 安全策略。
+ * 在遍历过程中递归检查是否存在禁止属性（__proto__、constructor、prototype）。
+ *
+ * @param value 待校验的 Action 输入值
+ * @param options 校验配置选项
+ * @returns 校验结果对象
+ */
+export declare function validateActionInputValue(value: unknown, options?: ValidateActionInputOptions): ActionInputValidationResult;
+/**
+ * 断言值必须为合法的 Canonical JSON 兼容结构，若非法则抛出 TypeError。
+ *
+ * @param value 待断言的目标值
+ * @param options 校验配置选项
+ */
+export declare function assertJsonValue(value: unknown, options?: ValidateJsonOptions): asserts value is JsonValue;