@actiondock/core 2.0.12 → 2.2.0

package/dist/schema/validator.js

@@ -0,0 +1,116 @@
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+// 初始化全局 Ajv 实例，预载所有标准 format 格式校验器
+const ajv = new Ajv({
+    allErrors: true,
+    strict: false,
+    coerceTypes: false,
+});
+addFormats(ajv);
+// 缓存已编译的 ValidateFunction，提升性能并支持同对象引用复用
+const validatorCache = new WeakMap();
+/**
+ * 递归检查数据中是否包含危险的原型污染属性键名（__proto__、constructor、prototype）。
+ */
+export function hasDangerousKeys(data) {
+    if (data === null || typeof data !== "object") {
+        return false;
+    }
+    if (Array.isArray(data)) {
+        for (const item of data) {
+            if (hasDangerousKeys(item))
+                return true;
+        }
+        return false;
+    }
+    const obj = data;
+    const keys = Object.getOwnPropertyNames(obj);
+    for (const key of keys) {
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+            return true;
+        }
+        if (hasDangerousKeys(obj[key])) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * 校验指定数据是否符合给定的 JSON Schema 契约。
+ *
+ * 行为与策略约定：
+ * 1. 严格契约校验：当 Schema 中定义 additionalProperties: false 时，包含未声明属性的输入将被直接拒绝（返回 valid: false），系统不会静默过滤或篡改用户输入。
+ * 2. 危险原型键硬拦截：输入数据或其任意嵌套对象中若出现 __proto__、constructor 或 prototype 键名，即使 Schema 允许亦立即拒绝，彻底杜绝原型污染。
+ * 3. 布尔 Schema：false 显式拒绝所有输入；true 或未定义时允许所有合法非污染数据。
+ * 4. 无原型对象支持：完全支持 Object.create(null) 创建的无原型对象校验。
+ *
+ * @param schema 期望匹配的 JSON Schema 对象（未提供或为空对象/true 时默认通过；为 false 时拒绝所有数据）
+ * @param data 待校验的原始数据
+ * @returns 包含 valid 状态与错误信息列表的 ValidationResult
+ */
+export function validateSchema(schema, data) {
+    // 1. 布尔 Schema 支持：false 拒绝一切输入；true/undefined 允许一切输入
+    if (schema === false) {
+        return {
+            valid: false,
+            errors: ["Schema is false, rejecting all data"],
+        };
+    }
+    if (schema === true || !schema) {
+        if (hasDangerousKeys(data)) {
+            return {
+                valid: false,
+                errors: ["Data contains prohibited prototype pollution keys (__proto__, constructor, or prototype)"],
+            };
+        }
+        return { valid: true };
+    }
+    if (typeof schema !== "object" || Object.keys(schema).length === 0) {
+        if (hasDangerousKeys(data)) {
+            return {
+                valid: false,
+                errors: ["Data contains prohibited prototype pollution keys (__proto__, constructor, or prototype)"],
+            };
+        }
+        return { valid: true };
+    }
+    // 2. 危险原型键拦截
+    if (hasDangerousKeys(data)) {
+        return {
+            valid: false,
+            errors: ["Data contains prohibited prototype pollution keys (__proto__, constructor, or prototype)"],
+        };
+    }
+    try {
+        let validate = validatorCache.get(schema);
+        if (!validate) {
+            // 避免因相同 $id 误用全局旧验证器，剥离 $id 进行独立编译
+            if ("$id" in schema) {
+                const { $id, ...cleanSchema } = schema;
+                validate = ajv.compile(cleanSchema);
+            }
+            else {
+                validate = ajv.compile(schema);
+            }
+            validatorCache.set(schema, validate);
+        }
+        const valid = validate(data);
+        if (valid) {
+            return { valid: true };
+        }
+        const errors = (validate.errors || []).map((err) => {
+            const path = err.instancePath ? `at '${err.instancePath}' ` : "";
+            return `${path}${err.message || "failed validation"}`.trim();
+        });
+        return {
+            valid: false,
+            errors: errors.length > 0 ? errors : ["Schema validation failed"],
+        };
+    }
+    catch (err) {
+        return {
+            valid: false,
+            errors: [`Schema compilation error: ${err.message || String(err)}`],
+        };
+    }
+}

package/dist/server/body.js

@@ -0,0 +1,93 @@
+/**
+ * 默认单次 HTTP 请求体最大字节上限（1 MiB）。
+ */
+export const DEFAULT_MAX_BODY_BYTES = 1024 * 1024; // 1 MiB
+/**
+ * 请求体超出最大允许体积时抛出的异常（对应 HTTP 413 Payload Too Large）。
+ */
+export class RequestTooLargeError extends Error {
+    code = "REQUEST_TOO_LARGE";
+    constructor(message = "Request body exceeds maximum allowed size") {
+        super(message);
+        this.name = "RequestTooLargeError";
+    }
+}
+/**
+ * 请求体非合法 JSON 格式时抛出的异常（对应 HTTP 400 Bad Request）。
+ */
+export class InvalidJsonError extends Error {
+    code = "INVALID_JSON";
+    constructor(message = "Failed to parse request body as JSON") {
+        super(message);
+        this.name = "InvalidJsonError";
+    }
+}
+/**
+ * 流式安全地读取 HTTP 请求体并解析为 JSON 对象。
+ *
+ * 防护机制：
+ * 1. 快速拒绝（Fast-path）：若请求头中存在 `Content-Length` 且超过 `maxBytes`，立即抛出 RequestTooLargeError，不进行内存分配。
+ * 2. 流式计数器（Chunk Streaming）：在读取 ReadableStream 过程中实时累计字节数，中途超出上限即刻截断并释放流锁，防止大文件 DoS 与内存耗尽（OOM）。
+ * 3. 安全解码：处理空请求体与 UTF-8 字符集解码。
+ *
+ * @param req 传入的 Request 对象
+ * @param options 读取配置选项
+ * @returns 解析后的 JSON 对象
+ * @throws {RequestTooLargeError} 若请求体体积超限
+ * @throws {InvalidJsonError} 若请求体非合法 JSON
+ */
+export async function readJsonBody(req, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BODY_BYTES;
+    // 1. 快速检查 Content-Length 头部
+    const contentLengthHeader = req.headers.get("content-length");
+    if (contentLengthHeader) {
+        const parsedLength = parseInt(contentLengthHeader, 10);
+        if (!isNaN(parsedLength) && parsedLength > maxBytes) {
+            throw new RequestTooLargeError();
+        }
+    }
+    // 2. 流式读取并实时统计字节数
+    if (!req.body) {
+        return {};
+    }
+    const reader = req.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                totalBytes += value.byteLength;
+                if (totalBytes > maxBytes) {
+                    throw new RequestTooLargeError();
+                }
+                chunks.push(value);
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    if (chunks.length === 0 || totalBytes === 0) {
+        return {};
+    }
+    // 3. 拼接字节数组并进行 UTF-8 解码
+    const merged = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    const text = new TextDecoder("utf-8").decode(merged);
+    if (!text.trim()) {
+        return {};
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new InvalidJsonError(`Failed to parse request body: ${err.message}`);
+    }
+}

package/dist/server/index.d.ts

@@ -1,6 +1,5 @@
-export * from "./types";
-export * from "./security";
-export * from "./body";
-export * from "./runtime-registry";
-export * from "./routes";
-export * from "./server";
+export * from "./types.js";
+export * from "./security.js";
+export * from "./body.js";
+export * from "./routes/index.js";
+export * from "./server.js";

package/dist/server/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./security.js";
+export * from "./body.js";
+export * from "./routes/index.js";
+export * from "./server.js";

package/dist/server/routes/actions.d.ts

@@ -1,5 +1,5 @@
-import { type RouteContext } from "./common";
+import { type RouteContext } from "./common.js";
 /**
- * 处理 Action 列表、详情查询及同步/异步运行接口。
+ * 处理 Action 相关的 HTTP 路由（列表、规范查询、同步执行与异步启动）。
  */
 export declare function handleActionsRoutes(ctx: RouteContext): Promise<Response | null>;

package/dist/server/routes/actions.js

@@ -0,0 +1,298 @@
+import { randomUUID } from "node:crypto";
+import { ActionResolver } from "../../catalog/action-resolver.js";
+import { filterByIntent } from "../../filter/index.js";
+import { ACTION_NOT_FOUND, ACTION_TIMEOUT, IDEMPOTENCY_CONFLICT, INPUT_VALIDATION_FAILED, PACKAGE_NOT_FOUND } from "../../errors.js";
+import { InvalidJsonError, readJsonBody, RequestTooLargeError } from "../body.js";
+import { getSubPath, jsonResponse } from "./common.js";
+/**
+ * 处理 Action 相关的 HTTP 路由（列表、规范查询、同步执行与异步启动）。
+ */
+export async function handleActionsRoutes(ctx) {
+    const { req, url, pathname, corsHeaders, options, target } = ctx;
+    const subpath = getSubPath(pathname);
+    // 1. Actions List: GET /api/v2/actions, GET /actions
+    if (subpath === "/actions" && req.method === "GET") {
+        try {
+            const intent = url.searchParams.get("intent") || undefined;
+            const query = url.searchParams.get("query") || intent;
+            const targetPkg = url.searchParams.get("package") || url.searchParams.get("packageId") || undefined;
+            const prefix = url.searchParams.get("prefix") || undefined;
+            const tags = url.searchParams.getAll("tag");
+            let actions = await target.listActions({
+                query,
+                prefix,
+                tags: tags.length > 0 ? tags : undefined,
+            });
+            if (targetPkg) {
+                actions = actions.filter((a) => a.packageId === targetPkg || a.id.startsWith(`${targetPkg}/`));
+            }
+            if (options.packageAllowlist && options.packageAllowlist.length > 0) {
+                actions = actions.filter((a) => a.packageId && options.packageAllowlist.includes(a.packageId));
+            }
+            if (intent) {
+                actions = filterByIntent(actions, intent, [(a) => a.id, (a) => a.description || "", (a) => a.packageId || ""], false);
+            }
+            return jsonResponse(actions, 200, corsHeaders);
+        }
+        catch (err) {
+            return jsonResponse({
+                ok: false,
+                error: { code: "ACTIONS_LIST_ERROR", message: err.message },
+            }, 500, corsHeaders);
+        }
+    }
+    // 2. Multi-package Action Show: GET /api/v2/packages/:packageId/actions/:actionId
+    const pkgActionShowMatch = subpath.match(/^\/packages\/([^/]+)\/actions\/([^/]+)$/);
+    if (pkgActionShowMatch && req.method === "GET") {
+        const packageId = decodeURIComponent(pkgActionShowMatch[1]);
+        const actionId = decodeURIComponent(pkgActionShowMatch[2]);
+        if (options.packageAllowlist && options.packageAllowlist.length > 0) {
+            if (!options.packageAllowlist.includes(packageId)) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        code: "PACKAGE_FORBIDDEN",
+                        message: `Package '${packageId}' is not in the allowed package list`,
+                    },
+                }, 403, corsHeaders);
+            }
+        }
+        const ref = `${packageId}/${actionId}`;
+        try {
+            const spec = await target.describeAction(ref);
+            return jsonResponse(spec, 200, corsHeaders);
+        }
+        catch (err) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: ACTION_NOT_FOUND,
+                    message: err.message || `Action '${actionId}' not found in package '${packageId}'`,
+                },
+            }, 404, corsHeaders);
+        }
+    }
+    // 3. Short Action Show: GET /api/v2/actions/:actionId, GET /actions/:actionId
+    const actionShowMatch = subpath.match(/^\/actions\/(.+)$/);
+    if (actionShowMatch && req.method === "GET") {
+        const actionId = decodeURIComponent(actionShowMatch[1]);
+        try {
+            const parsed = ActionResolver.parseRef(actionId);
+            if (parsed.packageId && options.packageAllowlist && options.packageAllowlist.length > 0) {
+                if (!options.packageAllowlist.includes(parsed.packageId)) {
+                    return jsonResponse({
+                        ok: false,
+                        error: {
+                            code: "PACKAGE_FORBIDDEN",
+                            message: `Package '${parsed.packageId}' is not in the allowed package list`,
+                        },
+                    }, 403, corsHeaders);
+                }
+            }
+        }
+        catch { }
+        try {
+            const spec = await target.describeAction(actionId);
+            if (options.packageAllowlist &&
+                options.packageAllowlist.length > 0 &&
+                (!spec.packageId || !options.packageAllowlist.includes(spec.packageId))) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        code: "PACKAGE_FORBIDDEN",
+                        message: `Package '${spec.packageId}' is not in the allowed package list`,
+                    },
+                }, 403, corsHeaders);
+            }
+            return jsonResponse(spec, 200, corsHeaders);
+        }
+        catch (err) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: ACTION_NOT_FOUND,
+                    message: err.message || `Action '${actionId}' not found`,
+                },
+            }, 404, corsHeaders);
+        }
+    }
+    // 4. Execution Routes (Run & Start)
+    // Match patterns:
+    // - /packages/:packageId/actions/:actionId/run
+    // - /packages/:packageId/actions/:actionId/start
+    // - /actions/:actionId/run
+    // - /actions/:actionId/start
+    const pkgRunMatch = subpath.match(/^\/packages\/([^/]+)\/actions\/([^/]+)\/(run|start)$/);
+    const shortRunMatch = subpath.match(/^\/actions\/(.+)\/(run|start)$/);
+    if ((pkgRunMatch || shortRunMatch) && req.method === "POST") {
+        let actionRef;
+        let endpointMode;
+        let pkgId;
+        if (pkgRunMatch) {
+            pkgId = decodeURIComponent(pkgRunMatch[1]);
+            const actId = decodeURIComponent(pkgRunMatch[2]);
+            endpointMode = pkgRunMatch[3];
+            actionRef = `${pkgId}/${actId}`;
+        }
+        else {
+            actionRef = decodeURIComponent(shortRunMatch[1]);
+            endpointMode = shortRunMatch[2];
+            try {
+                const parsed = ActionResolver.parseRef(actionRef);
+                pkgId = parsed.packageId;
+            }
+            catch { }
+        }
+        // 校验 Package 允许白名单
+        if (options.packageAllowlist && options.packageAllowlist.length > 0) {
+            if (!pkgId) {
+                try {
+                    const spec = await target.describeAction(actionRef);
+                    pkgId = spec?.packageId;
+                }
+                catch { }
+            }
+            if (!pkgId || !options.packageAllowlist.includes(pkgId)) {
+                return jsonResponse({
+                    ok: false,
+                    runId: randomUUID(),
+                    error: {
+                        code: "PACKAGE_FORBIDDEN",
+                        message: pkgId
+                            ? `Package '${pkgId}' is not in the allowed package list`
+                            : `Action '${actionRef}' does not belong to any allowed package`,
+                    },
+                }, 403, corsHeaders);
+            }
+        }
+        let body = {};
+        try {
+            body = await readJsonBody(req, { maxBytes: options.maxBodyBytes });
+        }
+        catch (err) {
+            if (err instanceof RequestTooLargeError) {
+                return jsonResponse({
+                    ok: false,
+                    runId: randomUUID(),
+                    error: { code: "REQUEST_TOO_LARGE", message: err.message },
+                }, 413, corsHeaders);
+            }
+            if (err instanceof InvalidJsonError) {
+                return jsonResponse({
+                    ok: false,
+                    runId: randomUUID(),
+                    error: { code: "INVALID_JSON", message: err.message },
+                }, 400, corsHeaders);
+            }
+            return jsonResponse({
+                ok: false,
+                runId: randomUUID(),
+                error: { code: "INVALID_JSON", message: `Failed to parse request body: ${err.message}` },
+            }, 400, corsHeaders);
+        }
+        const isAsync = endpointMode === "start" ||
+            body?.execution?.mode === "async" ||
+            body?.async === true;
+        const timeoutMs = typeof body?.execution?.timeoutMs === "number" && body.execution.timeoutMs > 0
+            ? body.execution.timeoutMs
+            : undefined;
+        const input = body && "input" in body ? body.input : {};
+        const configOverrides = body?.config;
+        const requestId = req.headers.get("Idempotency-Key") ||
+            req.headers.get("idempotency-key") ||
+            req.headers.get("X-Request-Id") ||
+            req.headers.get("x-request-id") ||
+            body?.requestId ||
+            body?.execution?.requestId ||
+            undefined;
+        if (isAsync) {
+            try {
+                const ticket = await target.startAction(actionRef, input, {
+                    timeoutMs,
+                    config: configOverrides,
+                    requestId,
+                });
+                if (ticket.status === "failed") {
+                    const res = await ticket.result;
+                    return jsonResponse(res, 400, corsHeaders);
+                }
+                return jsonResponse({
+                    ok: true,
+                    runId: ticket.runId,
+                    status: ticket.status || "running",
+                    streamUrl: `/api/v2/runs/${ticket.runId}/events`,
+                }, 202, corsHeaders);
+            }
+            catch (err) {
+                if (err?.code === IDEMPOTENCY_CONFLICT) {
+                    return jsonResponse({
+                        ok: false,
+                        error: {
+                            code: IDEMPOTENCY_CONFLICT,
+                            message: err.message,
+                            details: err.details,
+                        },
+                    }, 409, corsHeaders);
+                }
+                return jsonResponse({
+                    ok: false,
+                    runId: randomUUID(),
+                    error: {
+                        code: "ACTION_START_FAILED",
+                        message: err.message || String(err),
+                    },
+                }, 500, corsHeaders);
+            }
+        }
+        // 同步执行模式
+        try {
+            const result = await target.runAction(actionRef, input, {
+                signal: req.signal,
+                timeoutMs,
+                config: configOverrides,
+                requestId,
+            });
+            let status = 200;
+            if (!result.ok) {
+                if (result.error?.code === INPUT_VALIDATION_FAILED) {
+                    status = 400;
+                }
+                else if (result.error?.code === IDEMPOTENCY_CONFLICT) {
+                    status = 409;
+                }
+                else if (result.error?.code === ACTION_NOT_FOUND ||
+                    result.error?.code === PACKAGE_NOT_FOUND) {
+                    status = 404;
+                }
+                else if (result.error?.code === ACTION_TIMEOUT) {
+                    status = 504;
+                }
+                else {
+                    status = 500;
+                }
+            }
+            return jsonResponse(result, status, corsHeaders);
+        }
+        catch (err) {
+            if (err?.code === IDEMPOTENCY_CONFLICT) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        code: IDEMPOTENCY_CONFLICT,
+                        message: err.message,
+                        details: err.details,
+                    },
+                }, 409, corsHeaders);
+            }
+            return jsonResponse({
+                ok: false,
+                runId: randomUUID(),
+                error: {
+                    code: "ACTION_EXECUTION_ERROR",
+                    message: err.message || String(err),
+                },
+            }, 500, corsHeaders);
+        }
+    }
+    return null;
+}

package/dist/server/routes/common.d.ts

@@ -1,7 +1,7 @@
-import type { RuntimeStorage } from "../../storage/types";
-import type { RunRecord } from "@actiondock/sdk";
-import type { ServerRuntimeRegistry } from "../runtime-registry";
-import type { ServerOptions } from "../types";
+import type { ActionDockApp } from "../../app/types.js";
+import type { ActionDockHost } from "../../host/types.js";
+import type { ActionDockTarget } from "../../target/types.js";
+import type { ServerOptions } from "../types.js";
 /**
  * 路由处理统一上下文对象。
  */
@@ -12,25 +12,36 @@ export interface RouteContext {
     corsHeaders: Record<string, string>;
     projectRoot: string | null;
     customHome?: string;
-    runtimeRegistry: ServerRuntimeRegistry;
+    host?: ActionDockHost;
+    target: ActionDockTarget;
     options: ServerOptions;
 }
 /**
- * 辅助函数：构造带 CORS 头的标准 JSON HTTP 响应。
+ * 构造带 CORS 头的标准 JSON HTTP 响应。
  */
 export declare function jsonResponse(data: unknown, status?: number, corsHeaders?: Record<string, string>): Response;
 /**
- * 依据 package 参数或项目上下文解析目标 Storage 实例与根目录。
+ * 剥离标准版本前缀 (/api/v2/ 与兼容的 /api/v1/)，获取相对路由子路径。
  */
-export declare function resolveStorageForPackage(packageIdOrPath: string | undefined, runtimeRegistry: ServerRuntimeRegistry, projectRoot?: string | null, customHome?: string): {
-    packageId: string;
-    storage: RuntimeStorage;
-    projectRoot?: string;
-};
+export declare function getSubPath(pathname: string): string;
 /**
- * 跨活跃连接与所有已知持久化存储全局检索指定 runId 的运行记录。
+ * 包未列入白名单拒绝访问异常。
  */
-export declare function findRunAcrossStorages(runId: string, runtimeRegistry: ServerRuntimeRegistry, projectRoot?: string | null, customHome?: string): {
-    storage: RuntimeStorage;
-    run: RunRecord;
-} | null;
+export declare class PackageNotAllowedError extends Error {
+    status: number;
+    statusCode: number;
+    code: string;
+    constructor(packageId: string);
+}
+/**
+ * 校验目标 packageId 是否属于允许包白名单。
+ * 当 options.packageAllowlist 存在且目标 packageId 不在白名单中时抛出 403 PACKAGE_NOT_ALLOWED 异常。
+ */
+export declare function assertPackageAllowed(packageId: string | undefined | null, options?: {
+    packageAllowlist?: string[];
+}): void;
+/**
+ * 从 Host 或 Target 中依据 packageId 解析对应的 ActionDockApp 实例。
+ * 若提供了 options，过滤或优先选择白名单内的 app。
+ */
+export declare function resolveAppForPackage(packageIdOrPath: string | undefined, host?: ActionDockHost, target?: ActionDockTarget, options?: ServerOptions): ActionDockApp;