@actiondock/core 2.7.0 → 2.8.0

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>;
+}

package/dist/server/http-server.js

@@ -0,0 +1,304 @@
+import { createServer } from "node:http";
+import { createServer as createHttpsServer } from "node:https";
+import { readFileSync } from "node:fs";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { BAD_REQUEST, SERVER_ERROR } from "../errors.js";
+import { formatHostForUrl } from "./server.js";
+/**
+ * 将 Node.js IncomingMessage 请求转化为标准的 Web Request 对象。
+ */
+export function createWebRequest(req, options) {
+    const protocol = req.socket?.encrypted ? "https" : "http";
+    const host = req.headers.host || "127.0.0.1";
+    let baseOrigin;
+    let res;
+    if (options) {
+        if ("writableFinished" in options || typeof options.writeHead === "function") {
+            res = options;
+        }
+        else {
+            baseOrigin = options.baseOrigin;
+            res = options.res;
+        }
+    }
+    if (!res && req.res) {
+        res = req.res;
+    }
+    baseOrigin = baseOrigin || `${protocol}://${host}`;
+    const url = new URL(req.url || "/", baseOrigin).href;
+    const headers = new Headers();
+    for (const [key, val] of Object.entries(req.headers)) {
+        if (val === undefined)
+            continue;
+        if (Array.isArray(val)) {
+            for (const item of val) {
+                headers.append(key, item);
+            }
+        }
+        else {
+            headers.set(key, val);
+        }
+    }
+    const method = (req.method || "GET").toUpperCase();
+    const hasBody = method !== "GET" && method !== "HEAD";
+    const ac = new AbortController();
+    req.on("close", () => {
+        if (!req.complete) {
+            ac.abort(new Error("Request aborted by client"));
+        }
+    });
+    if (res) {
+        res.on("close", () => {
+            if (!res.writableFinished) {
+                ac.abort(new Error("Request aborted by client"));
+            }
+        });
+    }
+    const init = {
+        method,
+        headers,
+        signal: ac.signal,
+    };
+    if (hasBody) {
+        const webStream = Readable.toWeb(req);
+        init.body = webStream;
+        init.duplex = "half";
+    }
+    return new Request(url, init);
+}
+/**
+ * 将标准的 Web Response 响应流式写回 Node.js ServerResponse 客户端输出。
+ */
+export async function sendWebResponse(webResponse, res) {
+    res.statusCode = webResponse.status;
+    if (webResponse.statusText) {
+        res.statusMessage = webResponse.statusText;
+    }
+    webResponse.headers.forEach((val, key) => {
+        if (key.toLowerCase() === "set-cookie") {
+            if (typeof webResponse.headers.getSetCookie === "function") {
+                res.setHeader("set-cookie", webResponse.headers.getSetCookie());
+            }
+            else {
+                res.appendHeader("set-cookie", val);
+            }
+        }
+        else {
+            res.setHeader(key, val);
+        }
+    });
+    if (!webResponse.body) {
+        res.end();
+        return;
+    }
+    const nodeStream = Readable.fromWeb(webResponse.body);
+    try {
+        await pipeline(nodeStream, res);
+    }
+    catch (err) {
+        if (err?.code !== "ERR_STREAM_PREMATURE_CLOSE") {
+            throw err;
+        }
+    }
+}
+/**
+ * 创建适用于 Node.js 原生 http.createServer 的请求监听函数。
+ */
+export function createRequestListener(handler, options) {
+    return (req, res) => {
+        let webReq;
+        try {
+            webReq = createWebRequest(req, { ...options, res });
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                res.statusCode = 400;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({
+                    ok: false,
+                    error: {
+                        code: BAD_REQUEST,
+                        message: err?.message || String(err),
+                    },
+                }));
+            }
+            else {
+                res.destroy(err);
+            }
+            return;
+        }
+        Promise.resolve()
+            .then(() => handler(webReq))
+            .then((webRes) => sendWebResponse(webRes, res))
+            .catch((err) => {
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({
+                    ok: false,
+                    error: {
+                        code: SERVER_ERROR,
+                        message: err?.message || String(err),
+                    },
+                }));
+            }
+            else {
+                res.destroy(err);
+            }
+        });
+    };
+}
+/**
+ * 基于 Node.js node:http 的轻量级 HTTP 服务端封装。
+ * 接收 Node HTTP 请求并转化为标准 Web Request，支持 Web Response 流式输出。
+ */
+export class NodeHttpServer {
+    server;
+    listening = false;
+    portNumber = 0;
+    hostAddress = "127.0.0.1";
+    tlsOptions;
+    persistentErrorHandler;
+    constructor(optionsOrHandler) {
+        const handler = typeof optionsOrHandler === "function"
+            ? optionsOrHandler
+            : optionsOrHandler.fetch;
+        const baseOrigin = typeof optionsOrHandler === "object"
+            ? optionsOrHandler.baseOrigin
+            : undefined;
+        const tls = typeof optionsOrHandler === "object"
+            ? optionsOrHandler.tls
+            : undefined;
+        this.tlsOptions = tls;
+        const requestListener = createRequestListener(handler, { baseOrigin });
+        if (tls) {
+            let cert = tls.cert;
+            if (!cert && tls.certPath) {
+                cert = readFileSync(tls.certPath);
+            }
+            let key = tls.key;
+            if (!key && tls.keyPath) {
+                key = readFileSync(tls.keyPath);
+            }
+            const httpsOptions = { cert, key };
+            if (tls.ca)
+                httpsOptions.ca = tls.ca;
+            if (tls.passphrase)
+                httpsOptions.passphrase = tls.passphrase;
+            this.server = createHttpsServer(httpsOptions, requestListener);
+        }
+        else {
+            this.server = createServer(requestListener);
+        }
+        if (typeof optionsOrHandler === "object") {
+            if (optionsOrHandler.port !== undefined) {
+                this.portNumber = optionsOrHandler.port;
+            }
+            if (optionsOrHandler.host !== undefined) {
+                this.hostAddress = optionsOrHandler.host;
+            }
+        }
+    }
+    /**
+     * 底层原生 Node.js http.Server / https.Server 实例。
+     */
+    get rawServer() {
+        return this.server;
+    }
+    /**
+     * 绑定的监听端口号。
+     */
+    get port() {
+        return this.portNumber;
+    }
+    /**
+     * 绑定的主机地址。
+     */
+    get host() {
+        return this.hostAddress;
+    }
+    /**
+     * 完整的 HTTP 访问基础路径。
+     */
+    get url() {
+        const protocol = this.tlsOptions ? "https" : "http";
+        return `${protocol}://${formatHostForUrl(this.hostAddress)}:${this.portNumber}`;
+    }
+    /**
+     * 服务端当前是否正在监听连接。
+     */
+    get isListening() {
+        return this.listening;
+    }
+    /**
+     * 启动监听。若未显式传入端口，则默认使用实例配置或随机可用端口（0）。
+     */
+    async listen(port, host) {
+        const targetPort = port ?? this.portNumber ?? 0;
+        const targetHost = host ?? this.hostAddress ?? "127.0.0.1";
+        if (!this.persistentErrorHandler) {
+            this.persistentErrorHandler = (err) => {
+                console.error("[NodeHttpServer] unexpected server error:", err);
+            };
+            this.server.on("error", this.persistentErrorHandler);
+        }
+        return new Promise((resolve, reject) => {
+            const onListenError = (err) => {
+                this.server.removeListener("error", onListenError);
+                reject(err);
+            };
+            this.server.once("error", onListenError);
+            this.server.listen(targetPort, targetHost, () => {
+                this.server.removeListener("error", onListenError);
+                const addr = this.server.address();
+                if (addr && typeof addr === "object") {
+                    this.portNumber = addr.port;
+                    this.hostAddress = addr.address === "::" ? "127.0.0.1" : addr.address;
+                }
+                this.listening = true;
+                resolve({
+                    port: this.portNumber,
+                    host: this.hostAddress,
+                    url: this.url,
+                });
+            });
+        });
+    }
+    /**
+     * 优雅关闭服务端并释放端口与活动连接。
+     */
+    async close() {
+        if (!this.listening) {
+            return;
+        }
+        if (this.persistentErrorHandler) {
+            this.server.removeListener("error", this.persistentErrorHandler);
+            this.persistentErrorHandler = undefined;
+        }
+        return new Promise((resolve, reject) => {
+            this.server.close((err) => {
+                this.listening = false;
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+            this.server.closeAllConnections?.();
+        });
+    }
+    /**
+     * 停止服务端监听（兼容 stop 契约）。
+     */
+    async stop() {
+        return this.close();
+    }
+    /**
+     * 便捷工厂方法：创建并启动监听。
+     */
+    static async start(optionsOrHandler, port, host) {
+        const server = new NodeHttpServer(optionsOrHandler);
+        await server.listen(port, host);
+        return server;
+    }
+}

package/dist/server/index.d.ts

@@ -3,4 +3,15 @@ export * from "./security.js";
 export * from "./body.js";
 export * from "./routes/index.js";
 export * from "./server.js";
+export * from "./mcp-endpoint.js";
 export * from "./dispatcher.js";
+export * from "./http-server.js";
+export { serveParentIpc } from "../ipc/host.js";
+export { IpcActionDockService } from "../ipc/service.js";
+export type { IpcServiceOptions } from "../ipc/types.js";
+export { parseDuration } from "../utils/index.js";
+export type { ActionDockHost, ActionDockHostOptions, } from "../host/types.js";
+export { createActionDockHost, DefaultActionDockHost, } from "../host/host.js";
+export { LocalActionDockService, } from "../service/local.js";
+export { RemoteActionDockService, } from "../service/remote.js";
+export { ExitCode, StandaloneDispatcher, type StandaloneDispatcherOptions, type InvocationControl, runStandaloneProcess, } from "../runtime/standalone.js";

package/dist/server/index.js

@@ -3,4 +3,14 @@ export * from "./security.js";
 export * from "./body.js";
 export * from "./routes/index.js";
 export * from "./server.js";
+export * from "./mcp-endpoint.js";
 export * from "./dispatcher.js";
+export * from "./http-server.js";
+export { serveParentIpc } from "../ipc/host.js";
+export { IpcActionDockService } from "../ipc/service.js";
+export { parseDuration } from "../utils/index.js";
+export { createActionDockHost, DefaultActionDockHost, } from "../host/host.js";
+export { LocalActionDockService, } from "../service/local.js";
+export { RemoteActionDockService, } from "../service/remote.js";
+// 独立进程分发器与退出控制
+export { ExitCode, StandaloneDispatcher, runStandaloneProcess, } from "../runtime/standalone.js";