@actiondock/core 2.6.0 → 2.8.0

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";

package/dist/server/mcp-endpoint.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 共享 MCP 端点处理器工厂配置选项。
+ *
+ * 覆盖 core 网关与 mcp 独立 HTTP 服务双方共同消费的配置面：
+ * - token 与 allowQueryToken 决定 Bearer 鉴权（含查询参数放行开关）；
+ * - corsOrigins 决定跨域响应头解析；
+ * - maxBodyBytes 决定请求体有界读取上限（防 DoS）；
+ * - corsApplyMode 决定 MCP 响应的 CORS 头部应用方式。
+ */
+export interface McpEndpointHandlerOptions {
+    /** 服务端预期的 Bearer Token（未配置时默认放行） */
+    token?: string;
+    /** 是否允许通过 URL 查询参数携带 Token（默认 false） */
+    allowQueryToken?: boolean;
+    /** 允许跨域请求的 CORS Origin 白名单列表 */
+    corsOrigins?: string[];
+    /** 最大允许的请求体字节限制（默认 1 MiB，防 DoS） */
+    maxBodyBytes?: number;
+    /** MCP 响应的 CORS 头部应用模式（默认 inherit 透传响应原头部） */
+    corsApplyMode?: McpCorsApplyMode;
+}
+/**
+ * MCP 委托处理器契约。
+ * 接收经限流重建后的标准 Request，返回 MCP 协议响应；
+ * 返回 null / undefined 表示委托方未处理，交回调用方继续后续路由。
+ */
+export type McpDelegateHandler = (req: Request) => Promise<Response | null | undefined> | Response | null | undefined;
+/**
+ * 构造 MCP 响应的 CORS 头部回写规则。
+ * - inherit：透传 MCP 响应自身头部（core 网关行为）；
+ * - merge：将解析出的 CORS 头部合并覆盖到 MCP 响应（mcp 独立服务行为）。
+ */
+export type McpCorsApplyMode = "inherit" | "merge";
+/**
+ * 共享 MCP 端点处理器契约。
+ *
+ * 返回 Response 表示已完整处理；返回 null / undefined 表示委托方未处理，
+ * 交回调用方继续后续路由分发。
+ */
+export type McpEndpointHandler = (req: Request) => Promise<Response | null | undefined>;
+/**
+ * 构造可复用的 MCP 端点处理器。
+ *
+ * 统一承载 core 网关端点与 mcp 独立 HTTP 服务共同遵循的请求处理子序列：
+ * verifyBearerToken 鉴权（401 标准 JSON）→ readBodyWithLimit 有界读取
+ * （413 处理）→ 委托 MCP 处理器 → 按 corsApplyMode 应用 CORS 头部。
+ *
+ * CORS 头部解析与 OPTIONS 预检由外层路由分发统一承担（两端点在健康检查、
+ * 全局鉴权等前置路由上存在形态差异，不宜在此收敛）；本处理器聚焦 MCP
+ * 端点自身的鉴权与请求体防护序列。
+ *
+ * 鉴权失败响应默认产出 core 网关标准错误形态；需要 JSON-RPC 错误形态的
+ * 调用方（如 mcp 独立服务）可通过 unauthorizedResponse 定制。
+ *
+ * @param delegate MCP 委托处理器（接收限流重建后的 Request）
+ * @param options 端点配置选项
+ */
+export declare function createMcpEndpointHandler(delegate: McpDelegateHandler, options?: McpEndpointHandlerOptions & {
+    /** 鉴权失败响应构造（默认产出 core 网关标准 401 JSON） */
+    unauthorizedResponse?: (corsHeaders: Record<string, string>) => Response;
+}): McpEndpointHandler;

package/dist/server/mcp-endpoint.js

@@ -0,0 +1,118 @@
+import { UNAUTHORIZED, REQUEST_TOO_LARGE } from "../errors.js";
+import { jsonResponse } from "./routes/common.js";
+import { DEFAULT_MAX_BODY_BYTES, readBodyWithLimit, RequestTooLargeError } from "./body.js";
+import { resolveCorsHeaders, verifyBearerToken } from "./security.js";
+/**
+ * 构造 413 Payload Too Large JSON 响应。
+ */
+function requestTooLargeResponse(corsHeaders) {
+    return jsonResponse({
+        ok: false,
+        error: {
+            code: REQUEST_TOO_LARGE,
+            message: "Request body exceeds maximum allowed size",
+        },
+    }, 413, corsHeaders);
+}
+/**
+ * 有界读取请求体并重建 Request。
+ *
+ * 读取与超限判定统一复用 body 域的 readBodyWithLimit 单一事实源；
+ * 超限时返回 null 表示应回退 413 响应，由调用方构造错误响应。
+ * 空请求体保持 body 为 undefined，与 core 网关历史行为逐字节一致。
+ *
+ * @param req 原始请求
+ * @param maxBytes 单次请求体允许的最大字节数
+ * @returns 重建后的请求；体积超限时返回 null
+ */
+async function rebuildRequestWithLimit(req, maxBytes) {
+    let merged;
+    try {
+        merged = await readBodyWithLimit(req, { maxBytes });
+    }
+    catch (err) {
+        if (err instanceof RequestTooLargeError) {
+            return null;
+        }
+        throw err;
+    }
+    const bodyInit = merged.byteLength > 0 ? new Blob([merged]) : undefined;
+    return new Request(req.url, {
+        method: req.method,
+        headers: req.headers,
+        body: bodyInit,
+        signal: req.signal,
+    });
+}
+/**
+ * 按指定模式为 MCP 响应附加 CORS 头部。
+ *
+ * @param response MCP 委托处理器返回的原始响应
+ * @param corsHeaders 本次请求解析出的 CORS 响应头
+ * @param mode CORS 头部应用模式（默认 inherit 透传）
+ */
+function applyCorsToResponse(response, corsHeaders, mode) {
+    if (mode !== "merge" || Object.keys(corsHeaders).length === 0) {
+        return response;
+    }
+    const newHeaders = new Headers(response.headers);
+    for (const [k, v] of Object.entries(corsHeaders)) {
+        newHeaders.set(k, String(v));
+    }
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: newHeaders,
+    });
+}
+/**
+ * 构造可复用的 MCP 端点处理器。
+ *
+ * 统一承载 core 网关端点与 mcp 独立 HTTP 服务共同遵循的请求处理子序列：
+ * verifyBearerToken 鉴权（401 标准 JSON）→ readBodyWithLimit 有界读取
+ * （413 处理）→ 委托 MCP 处理器 → 按 corsApplyMode 应用 CORS 头部。
+ *
+ * CORS 头部解析与 OPTIONS 预检由外层路由分发统一承担（两端点在健康检查、
+ * 全局鉴权等前置路由上存在形态差异，不宜在此收敛）；本处理器聚焦 MCP
+ * 端点自身的鉴权与请求体防护序列。
+ *
+ * 鉴权失败响应默认产出 core 网关标准错误形态；需要 JSON-RPC 错误形态的
+ * 调用方（如 mcp 独立服务）可通过 unauthorizedResponse 定制。
+ *
+ * @param delegate MCP 委托处理器（接收限流重建后的 Request）
+ * @param options 端点配置选项
+ */
+export function createMcpEndpointHandler(delegate, options = {}) {
+    const { token, allowQueryToken, corsOrigins, maxBodyBytes, unauthorizedResponse, } = options;
+    const maxBytes = maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const verifyOptions = { allowQueryToken };
+    return async (req) => {
+        const origin = req.headers.get("origin");
+        const corsHeaders = resolveCorsHeaders(origin, corsOrigins);
+        // Bearer Token 鉴权拦截
+        if (!verifyBearerToken(req, token, verifyOptions)) {
+            return (unauthorizedResponse?.(corsHeaders) ??
+                jsonResponse({
+                    ok: false,
+                    error: {
+                        code: UNAUTHORIZED,
+                        message: "Invalid or missing Bearer token",
+                    },
+                }, 401, corsHeaders));
+        }
+        // 请求体体积限制保护（复用 body 域有界读取单一事实源）
+        let mcpReq = req;
+        if (req.body && req.method !== "GET" && req.method !== "HEAD") {
+            const rebuilt = await rebuildRequestWithLimit(req, maxBytes);
+            if (!rebuilt) {
+                return requestTooLargeResponse(corsHeaders);
+            }
+            mcpReq = rebuilt;
+        }
+        const mcpRes = await delegate(mcpReq);
+        if (mcpRes) {
+            return applyCorsToResponse(mcpRes, corsHeaders, options.corsApplyMode ?? "inherit");
+        }
+        return mcpRes;
+    };
+}