@actiondock/core 2.6.0 → 2.8.0

package/dist/schema/validator.d.ts

@@ -10,8 +10,18 @@ export interface ValidationResult {
 }
 /**
  * 递归检查数据中是否包含危险的原型污染属性键名（__proto__、constructor、prototype）。
+ * 内部委托 validateActionInputValue 执行迭代遍历，确保环路安全、有向无环图安全且无调用栈溢出风险。
  */
 export declare function hasDangerousKeys(data: unknown): boolean;
+/**
+ * 内部纯 Schema 校验器。
+ * 仅处理布尔 Schema 与 Ajv 规则校验，严禁执行 dangerous-key 遍历。
+ *
+ * @param schema 期望匹配的 JSON Schema 对象
+ * @param data 待校验的原始数据
+ * @returns 包含 valid 状态与错误信息列表的 ValidationResult
+ */
+export declare function validateSchemaOnly(schema: JsonSchema | undefined, data: unknown): ValidationResult;
 /**
  * 校验指定数据是否符合给定的 JSON Schema 契约。
  *

package/dist/schema/validator.js

@@ -18,75 +18,36 @@ const validatorCache = new WeakMap();
 /**
  * 递归检查数据中是否包含危险的原型污染属性键名（__proto__、constructor、prototype）。
  */
+import { validateActionInputValue } from "../json/value-validator.js";
+/**
+ * 递归检查数据中是否包含危险的原型污染属性键名（__proto__、constructor、prototype）。
+ * 内部委托 validateActionInputValue 执行迭代遍历，确保环路安全、有向无环图安全且无调用栈溢出风险。
+ */
 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;
+    const result = validateActionInputValue(data);
+    return !result.valid && result.kind === "input-policy";
 }
 /**
- * 校验指定数据是否符合给定的 JSON Schema 契约。
+ * 内部纯 Schema 校验器。
+ * 仅处理布尔 Schema 与 Ajv 规则校验，严禁执行 dangerous-key 遍历。
  *
- * 行为与策略约定：
- * 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 schema 期望匹配的 JSON Schema 对象
  * @param data 待校验的原始数据
  * @returns 包含 valid 状态与错误信息列表的 ValidationResult
  */
-export function validateSchema(schema, data) {
-    // 1. 布尔 Schema 支持：false 拒绝一切输入；true/undefined 允许一切输入
+export function validateSchemaOnly(schema, data) {
     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)"],
-            };
-        }
+    if (schema === true ||
+        !schema ||
+        typeof schema !== "object" ||
+        Object.keys(schema).length === 0) {
         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) {
@@ -120,3 +81,36 @@ export function validateSchema(schema, data) {
         };
     }
 }
+/**
+ * 校验指定数据是否符合给定的 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 拒绝一切输入
+    if (schema === false) {
+        return {
+            valid: false,
+            errors: ["Schema is false, rejecting all data"],
+        };
+    }
+    // 2. 危险原型键拦截（保持历史兼容，包含 schema 为 true / undefined / {} 的场景）
+    if (hasDangerousKeys(data)) {
+        return {
+            valid: false,
+            errors: [
+                "Data contains prohibited prototype pollution keys (__proto__, constructor, or prototype)",
+            ],
+        };
+    }
+    // 3. 委托纯 Schema 校验器处理其余规则校验
+    return validateSchemaOnly(schema, data);
+}

package/dist/server/body.d.ts

@@ -1,3 +1,4 @@
+import { ActionDockError } from "../errors.js";
 /**
  * 默认单次 HTTP 请求体最大字节上限（1 MiB）。
  */
@@ -5,15 +6,13 @@ export declare const DEFAULT_MAX_BODY_BYTES: number;
 /**
  * 请求体超出最大允许体积时抛出的异常（对应 HTTP 413 Payload Too Large）。
  */
-export declare class RequestTooLargeError extends Error {
-    code: string;
+export declare class RequestTooLargeError extends ActionDockError {
     constructor(message?: string);
 }
 /**
  * 请求体非合法 JSON 格式时抛出的异常（对应 HTTP 400 Bad Request）。
  */
-export declare class InvalidJsonError extends Error {
-    code: string;
+export declare class InvalidJsonError extends ActionDockError {
     constructor(message?: string);
 }
 /**
@@ -24,12 +23,21 @@ export interface ReadJsonBodyOptions {
     maxBytes?: number;
 }
 /**
- * 流式安全地读取 HTTP 请求体并解析为 JSON 对象。
+ * 流式安全地读取 HTTP 请求体为原始字节数组（有界读取单一事实源）。
  *
  * 防护机制：
- * 1. 快速拒绝（Fast-path）：若请求头中存在 `Content-Length` 且超过 `maxBytes`，立即抛出 RequestTooLargeError，不进行内存分配。
- * 2. 流式计数器（Chunk Streaming）：在读取 ReadableStream 过程中实时累计字节数，中途超出上限即刻截断并释放流锁，防止大文件 DoS 与内存耗尽（OOM）。
- * 3. 安全解码：处理空请求体与 UTF-8 字符集解码。
+ * 1. 快速拒绝（Fast-path）：若请求头中存在 Content-Length 且超过 maxBytes，立即抛出 RequestTooLargeError，不进行内存分配。
+ * 2. 流式计数器（Chunk Streaming）：读取 ReadableStream 过程中实时累计字节数，中途超出上限即刻截断并释放流锁，防止大文件 DoS 与内存耗尽（OOM）。
+ *
+ * @param req 传入的 Request 对象
+ * @param options 读取配置选项
+ * @returns 原始字节数组（空请求体返回空数组）
+ * @throws {RequestTooLargeError} 若请求体体积超限
+ */
+export declare function readBodyWithLimit(req: Request, options?: ReadJsonBodyOptions): Promise<Uint8Array>;
+/**
+ * 流式安全地读取 HTTP 请求体并解析为 JSON 对象。
+ * 防护机制见 readBodyWithLimit；此外处理空请求体与 UTF-8 字符集解码。
  *
  * @param req 传入的 Request 对象
  * @param options 读取配置选项

package/dist/server/body.js

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

package/dist/server/dispatcher.d.ts

@@ -4,8 +4,6 @@
 export type FetchDispatcherProvider = () => unknown;
 /**
  * 注册全局用于忽略服务端证书校验的调度器提供者。
- * 唯一注册通道：平台适配层（如 @actiondock/runtime-node 的
- * installInsecureDispatcher）显式调用完成注册，不再读取全局符号注入。
  */
 export declare function setInsecureDispatcherProvider(provider?: FetchDispatcherProvider): void;
 /**
@@ -13,17 +11,15 @@ export declare function setInsecureDispatcherProvider(provider?: FetchDispatcher
  */
 export declare function getInsecureDispatcherProvider(): FetchDispatcherProvider | undefined;
 /**
- * 获取用于忽略服务端证书校验的调度器实例。
- * 纯粹解耦设计：
- * 1. 优先调用显式注册的提供者（如由 @actiondock/runtime-node 显式安装）；
- * 2. 若在 Node 环境下且无注册提供者，动态加载 @actiondock/runtime-node
- *    （其入口聚合点会显式完成安装），绝不让 core 包产生静态硬编译依赖；
- * 3. 仍不可得时返回 undefined，由调用方回退默认 fetch，绝不在 core 内
- *    直接探测加载 undici，避免与平台适配层形成层次倒置与隐藏依赖环。
+ * 获取用于忽略服务端证书校验的全局单例 Undici Agent 调度器。
+ * 显式配置 bodyTimeout: 0 以防止 SSE 长连接与流式事件读取出现 UND_ERR_BODY_TIMEOUT 空闲超时断流。
  */
 export declare function getInsecureDispatcher(): unknown;
+/**
+ * 显式安装平台调度器：向 core 注册本模块的提供者函数。
+ */
+export declare function installInsecureDispatcher(): void;
 /**
  * 显式强制重置并销毁调度器连接池（仅用于单元测试重置或进程退出）。
- * core 自身不再持有任何兜底连接池，关闭语义完全委托已注册的平台提供者宿主。
  */
 export declare function closeInsecureDispatcher(): Promise<void>;

package/dist/server/dispatcher.js

@@ -1,9 +1,8 @@
-import { createRequire } from "node:module";
+import { Agent } from "undici";
 let insecureDispatcherProvider;
+let globalInsecureAgent;
 /**
  * 注册全局用于忽略服务端证书校验的调度器提供者。
- * 唯一注册通道：平台适配层（如 @actiondock/runtime-node 的
- * installInsecureDispatcher）显式调用完成注册，不再读取全局符号注入。
  */
 export function setInsecureDispatcherProvider(provider) {
     insecureDispatcherProvider = provider;
@@ -15,48 +14,41 @@ export function getInsecureDispatcherProvider() {
     return insecureDispatcherProvider;
 }
 /**
- * 获取用于忽略服务端证书校验的调度器实例。
- * 纯粹解耦设计：
- * 1. 优先调用显式注册的提供者（如由 @actiondock/runtime-node 显式安装）；
- * 2. 若在 Node 环境下且无注册提供者，动态加载 @actiondock/runtime-node
- *    （其入口聚合点会显式完成安装），绝不让 core 包产生静态硬编译依赖；
- * 3. 仍不可得时返回 undefined，由调用方回退默认 fetch，绝不在 core 内
- *    直接探测加载 undici，避免与平台适配层形成层次倒置与隐藏依赖环。
+ * 获取用于忽略服务端证书校验的全局单例 Undici Agent 调度器。
+ * 显式配置 bodyTimeout: 0 以防止 SSE 长连接与流式事件读取出现 UND_ERR_BODY_TIMEOUT 空闲超时断流。
  */
 export function getInsecureDispatcher() {
     if (insecureDispatcherProvider) {
         return insecureDispatcherProvider();
     }
-    if (typeof process !== "undefined" && process.versions?.node) {
-        try {
-            const req = createRequire(import.meta.url);
-            const runtimeNode = req("@actiondock/runtime-node");
-            if (typeof runtimeNode?.getInsecureDispatcher === "function") {
-                return runtimeNode.getInsecureDispatcher();
-            }
-        }
-        catch {
-            // 忽略未安装 @actiondock/runtime-node 的情况
-        }
+    if (!globalInsecureAgent || globalInsecureAgent.closed || globalInsecureAgent.destroyed) {
+        globalInsecureAgent = new Agent({
+            connect: {
+                rejectUnauthorized: false,
+            },
+            bodyTimeout: 0,
+        });
     }
-    return undefined;
+    return globalInsecureAgent;
+}
+/**
+ * 显式安装平台调度器：向 core 注册本模块的提供者函数。
+ */
+export function installInsecureDispatcher() {
+    setInsecureDispatcherProvider(getInsecureDispatcher);
 }
 /**
  * 显式强制重置并销毁调度器连接池（仅用于单元测试重置或进程退出）。
- * core 自身不再持有任何兜底连接池，关闭语义完全委托已注册的平台提供者宿主。
  */
 export async function closeInsecureDispatcher() {
-    if (insecureDispatcherProvider) {
-        // 提供者由平台层注册：优先委托提供者宿主的关闭语义（如可用）
+    if (globalInsecureAgent) {
+        const agent = globalInsecureAgent;
+        globalInsecureAgent = undefined;
         try {
-            const req = createRequire(import.meta.url);
-            const runtimeNode = req("@actiondock/runtime-node");
-            if (typeof runtimeNode?.closeInsecureDispatcher === "function") {
-                await runtimeNode.closeInsecureDispatcher();
-            }
+            await agent.close();
         }
-        catch {
-            // 忽略未安装 @actiondock/runtime-node 的情况
+        catch (err) {
+            console.warn("[actiondock] closeInsecureDispatcher failed to close agent:", err);
         }
     }
 }

package/dist/server/http-server.d.ts

@@ -0,0 +1,87 @@
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { type Server as HttpsServer } from "node:https";
+import type { ServerTlsOptions } from "./types.js";
+/**
+ * Web 标准 Request 处理函数。
+ */
+export type WebRequestHandler = (request: Request) => Promise<Response> | Response;
+/**
+ * Node HTTP 服务端配置选项。
+ */
+export interface NodeHttpServerOptions {
+    port?: number;
+    host?: string;
+    fetch: WebRequestHandler;
+    baseOrigin?: string;
+    tls?: ServerTlsOptions;
+}
+/**
+ * 将 Node.js IncomingMessage 请求转化为标准的 Web Request 对象。
+ */
+export declare function createWebRequest(req: IncomingMessage, options?: {
+    baseOrigin?: string;
+    res?: ServerResponse;
+} | ServerResponse): Request;
+/**
+ * 将标准的 Web Response 响应流式写回 Node.js ServerResponse 客户端输出。
+ */
+export declare function sendWebResponse(webResponse: Response, res: ServerResponse): Promise<void>;
+/**
+ * 创建适用于 Node.js 原生 http.createServer 的请求监听函数。
+ */
+export declare function createRequestListener(handler: WebRequestHandler, options?: {
+    baseOrigin?: string;
+}): (req: IncomingMessage, res: ServerResponse) => void;
+/**
+ * 基于 Node.js node:http 的轻量级 HTTP 服务端封装。
+ * 接收 Node HTTP 请求并转化为标准 Web Request，支持 Web Response 流式输出。
+ */
+export declare class NodeHttpServer {
+    private server;
+    private listening;
+    private portNumber;
+    private hostAddress;
+    private tlsOptions?;
+    private persistentErrorHandler?;
+    constructor(optionsOrHandler: WebRequestHandler | NodeHttpServerOptions);
+    /**
+     * 底层原生 Node.js http.Server / https.Server 实例。
+     */
+    get rawServer(): Server | HttpsServer;
+    /**
+     * 绑定的监听端口号。
+     */
+    get port(): number;
+    /**
+     * 绑定的主机地址。
+     */
+    get host(): string;
+    /**
+     * 完整的 HTTP 访问基础路径。
+     */
+    get url(): string;
+    /**
+     * 服务端当前是否正在监听连接。
+     */
+    get isListening(): boolean;
+    /**
+     * 启动监听。若未显式传入端口，则默认使用实例配置或随机可用端口（0）。
+     */
+    listen(port?: number, host?: string): Promise<{
+        port: number;
+        host: string;
+        url: string;
+    }>;
+    /**
+     * 优雅关闭服务端并释放端口与活动连接。
+     */
+    close(): Promise<void>;
+    /**
+     * 停止服务端监听（兼容 stop 契约）。
+     */
+    stop(): Promise<void>;
+    /**
+     * 便捷工厂方法：创建并启动监听。
+     */
+    static start(optionsOrHandler: WebRequestHandler | NodeHttpServerOptions, port?: number, host?: string): Promise<NodeHttpServer>;
+}