@actiondock/core 2.0.11 → 2.2.0

package/src/server/routes/state.ts

@@ -1,133 +0,0 @@
-import { readJsonBody } from "../body";
-import { type RouteContext, jsonResponse, resolveStorageForPackage } from "./common";
-
-/**
- * 处理状态键名列表、读取、写入、删除及清空接口。
- */
-export async function handleStateRoutes(ctx: RouteContext): Promise<Response | null> {
-  const { req, url, pathname, corsHeaders, projectRoot, customHome, runtimeRegistry, options } = ctx;
-
-  // 1. State List: GET /api/v1/state
-  if (pathname === "/api/v1/state" && req.method === "GET") {
-    try {
-      const pkgParam = url.searchParams.get("package") || undefined;
-      const nsParam = url.searchParams.get("namespace") ?? undefined;
-      const prefix = url.searchParams.get("prefix") || "";
-
-      const { packageId, storage } = resolveStorageForPackage(
-        pkgParam,
-        runtimeRegistry,
-        projectRoot,
-        customHome
-      );
-      const keys = await storage.listStateKeys(nsParam !== undefined ? nsParam : null, prefix);
-      return jsonResponse({ ok: true, packageId, keys }, 200, corsHeaders);
-    } catch (err: any) {
-      return jsonResponse(
-        { ok: false, error: { code: "STATE_LIST_ERROR", message: err.message } },
-        500,
-        corsHeaders
-      );
-    }
-  }
-
-  // 2. State Clear: POST /api/v1/state/clear
-  if (pathname === "/api/v1/state/clear" && req.method === "POST") {
-    try {
-      const body = await readJsonBody(req, { maxBytes: options.maxBodyBytes }).catch(() => ({}));
-      const pkgParam = url.searchParams.get("package") || body.package || undefined;
-      const { packageId, storage } = resolveStorageForPackage(
-        pkgParam,
-        runtimeRegistry,
-        projectRoot,
-        customHome
-      );
-      const clearedCount = await storage.clearState({
-        namespace: body.namespace ?? (url.searchParams.get("namespace") || undefined),
-        all: Boolean(body.all ?? url.searchParams.get("all") === "true"),
-        prefix: body.prefix ?? (url.searchParams.get("prefix") || undefined),
-      });
-      return jsonResponse({ ok: true, packageId, clearedCount }, 200, corsHeaders);
-    } catch (err: any) {
-      return jsonResponse(
-        { ok: false, error: { code: "STATE_CLEAR_ERROR", message: err.message } },
-        500,
-        corsHeaders
-      );
-    }
-  }
-
-  // 3. State Key CRUD: GET / PUT / POST / DELETE /api/v1/state/:key
-  const stateKeyMatch = pathname.match(/^\/api\/v1\/state\/([^/]+)$/);
-  if (stateKeyMatch) {
-    const key = decodeURIComponent(stateKeyMatch[1]);
-    const pkgParam = url.searchParams.get("package") || undefined;
-    const nsParam = url.searchParams.get("namespace") || undefined;
-
-    const { packageId, storage } = resolveStorageForPackage(
-      pkgParam,
-      runtimeRegistry,
-      projectRoot,
-      customHome
-    );
-
-    if (req.method === "GET") {
-      const entry = await storage.findState(key, nsParam);
-      if (!entry || entry.value === undefined) {
-        return jsonResponse(
-          { ok: false, error: { code: "STATE_KEY_NOT_FOUND", message: `State key '${key}' not found` } },
-          404,
-          corsHeaders
-        );
-      }
-      return jsonResponse(
-        {
-          ok: true,
-          packageId,
-          key: entry.key,
-          namespace: entry.namespace,
-          value: entry.value,
-          expiresAt: entry.expiresAt,
-        },
-        200,
-        corsHeaders
-      );
-    }
-
-    if (req.method === "PUT" || req.method === "POST") {
-      const body = await readJsonBody(req, { maxBytes: options.maxBodyBytes });
-      const val = body.value !== undefined ? body.value : body;
-      const ttl = typeof body.ttl === "number" ? body.ttl : undefined;
-      const namespace = body.namespace || nsParam || "";
-
-      let actualKey = key;
-      let ns = namespace;
-      if (!ns && key.includes(":")) {
-        const idx = key.indexOf(":");
-        ns = key.slice(0, idx);
-        actualKey = key.slice(idx + 1);
-      }
-
-      await storage.setState(ns, actualKey, val, ttl);
-      return jsonResponse(
-        { ok: true, packageId, key: actualKey, namespace: ns, message: "updated" },
-        200,
-        corsHeaders
-      );
-    }
-
-    if (req.method === "DELETE") {
-      const deleted = await storage.deleteStateSmart(key, nsParam);
-      if (!deleted) {
-        return jsonResponse(
-          { ok: false, error: { code: "STATE_KEY_NOT_FOUND", message: `State key '${key}' not found` } },
-          404,
-          corsHeaders
-        );
-      }
-      return jsonResponse({ ok: true, packageId, key, deleted: true }, 200, corsHeaders);
-    }
-  }
-
-  return null;
-}

package/src/server/runtime-registry.ts

@@ -1,115 +0,0 @@
-import { ExecutionManager } from "../runtime/execution-manager";
-import { createStorage } from "../storage";
-import type { RuntimeStorage } from "../storage/types";
-
-/**
- * 服务端运行时注册表（ServerRuntimeRegistry）。
- * 
- * 职责：
- * 1. 在长期运行的 HTTP 服务端（`ad serve` / `ad mcp serve`）中，跨请求缓存并池化管理 SQLite 数据库存储连接。
- * 2. 集中维护活跃的在途任务执行句柄（ExecutionManager）。
- * 3. 服务端停止或优雅关机（Graceful Shutdown）时，统一中断在途任务并安全关闭所有数据库连接。
- */
-export class ServerRuntimeRegistry {
-  private storages = new Map<string, RuntimeStorage>();
-  private listeners = new Map<string, Set<(event: { type: string; data: any }) => void>>();
-  public executionManager: ExecutionManager;
-
-  constructor() {
-    this.executionManager = new ExecutionManager();
-  }
-
-  /**
-   * 订阅指定 runId 的事件（用于 SSE 流式推送）。
-   */
-  public subscribe(runId: string, listener: (event: { type: string; data: any }) => void): () => void {
-    let set = this.listeners.get(runId);
-    if (!set) {
-      set = new Set();
-      this.listeners.set(runId, set);
-    }
-    set.add(listener);
-    return () => {
-      set?.delete(listener);
-      if (set && set.size === 0) {
-        this.listeners.delete(runId);
-      }
-    };
-  }
-
-  /**
-   * 向指定 runId 的订阅者广播事件。
-   */
-  public emit(runId: string, event: { type: string; data: any }): void {
-    const set = this.listeners.get(runId);
-    if (set) {
-      for (const listener of set) {
-        try {
-          listener(event);
-        } catch {
-          // 忽略单个监听器错误
-        }
-      }
-    }
-  }
-
-  /**
-   * 获取或懒加载指定 Package 和 projectRoot 的缓存 RuntimeStorage 实例。
-   * 
-   * @param packageId 所属 Package ID
-   * @param projectRoot 项目根目录（可选）
-   * @returns 缓存或新创建的 RuntimeStorage 实例
-   */
-  public getStorage(packageId: string, projectRoot?: string): RuntimeStorage {
-    const key = `${projectRoot || ""}:${packageId}`;
-    let storage = this.storages.get(key);
-    if (!storage) {
-      storage = createStorage(packageId, { projectRoot });
-      this.storages.set(key, storage);
-    }
-    return storage;
-  }
-
-  /**
-   * 获取当前缓存的所有活跃 RuntimeStorage 实例列表。
-   */
-  public getAllStorages(): RuntimeStorage[] {
-    return Array.from(this.storages.values());
-  }
-
-  /**
-   * 跨所有已建立的存储连接全局查找指定 runId 的运行记录。
-   * 
-   * @param runId 目标运行 ID
-   */
-  public findRun(runId: string) {
-    for (const storage of this.storages.values()) {
-      const run = storage.getRun(runId);
-      if (run) {
-        return { storage, run };
-      }
-    }
-    return undefined;
-  }
-
-  /**
-   * 优雅关机：中断所有在途异步任务并安全关闭所有 SQLite 存储连接。
-   */
-  public close(): void {
-    // 1. 批量向所有在途任务发送取消信号
-    for (const handle of this.executionManager.list()) {
-      handle.cancel("Server shutting down");
-    }
-    this.executionManager.clear();
-
-    // 2. 依次安全关闭所有 SQLite 数据库连接
-    for (const storage of this.storages.values()) {
-      try {
-        storage.close();
-      } catch {
-        // 忽略关机过程中的单个存储关闭异常
-      }
-    }
-    this.storages.clear();
-  }
-}

package/src/server/security.ts

@@ -1,115 +0,0 @@
-import { timingSafeEqual } from "node:crypto";
-
-/**
- * 恒定时间字符串比较（Constant-time comparison）。
- * 使用底层的 `crypto.timingSafeEqual` 防范时序攻击（Timing Attack）。
- * 
- * @param a 字符串 A
- * @param b 字符串 B
- * @returns 两个字符串内容是否完全一致
- */
-export function safeEqual(a: string, b: string): boolean {
-  const aa = Buffer.from(a);
-  const bb = Buffer.from(b);
-
-  if (aa.length !== bb.length) {
-    return false;
-  }
-
-  return timingSafeEqual(aa, bb);
-}
-
-/**
- * 检查指定的主机地址是否为本地回环接口（Loopback Host）。
- * 支持 127.0.0.1, localhost, ::1 等形式。
- * 
- * @param host 主机名或 IP 字符串
- */
-export function isLoopbackHost(host: string): boolean {
-  const trimmed = host.trim().toLowerCase();
-  return (
-    trimmed === "127.0.0.1" ||
-    trimmed === "::1" ||
-    trimmed === "localhost" ||
-    trimmed === "0:0:0:0:0:0:0:1"
-  );
-}
-
-/**
- * 校验 HTTP 请求中的鉴权令牌是否有效。
- * 
- * 支持两种凭证携带模式（均通过恒定时间对比）：
- * 1. HTTP 请求头: `Authorization: Bearer <token>`
- * 2. URL 查询参数: `?token=<token>`（便于浏览器/Web 调试）
- * 
- * @param req 传入的 HTTP Request 对象
- * @param expectedToken 服务端预期的正确 Token（若未配置 Token 则默认放行）
- * @returns 是否鉴权成功
- */
-export function verifyBearerToken(req: Request, expectedToken?: string): boolean {
-  if (!expectedToken || !expectedToken.trim()) {
-    return true;
-  }
-
-  const trimmedExpected = expectedToken.trim();
-
-  // 1. 请求头 Authorization: Bearer <token>
-  const authHeader = req.headers.get("authorization");
-  if (authHeader && authHeader.startsWith("Bearer ")) {
-    const token = authHeader.slice(7).trim();
-    if (safeEqual(token, trimmedExpected)) {
-      return true;
-    }
-  }
-
-  // 2. URL 查询参数: ?token=<token>
-  try {
-    const url = new URL(req.url);
-    const tokenParam = url.searchParams.get("token");
-    if (tokenParam && safeEqual(tokenParam.trim(), trimmedExpected)) {
-      return true;
-    }
-  } catch {
-    // 畸形 URL 视作鉴权失败
-  }
-
-  return false;
-}
-
-/**
- * 根据配置的 CORS 白名单解析并返回跨域响应头。
- * 默认情况下若未配置 corsOrigins，返回空对象（即默认关闭跨域访问，防范 CSRF）。
- * 
- * @param origin 请求头中的 Origin 字段
- * @param allowedOrigins 允许跨域的白名单来源数组
- * @returns 包含 Access-Control-* 的响应头对象
- */
-export function resolveCorsHeaders(
-  origin: string | null,
-  allowedOrigins?: string[]
-): Record<string, string> {
-  if (!allowedOrigins || allowedOrigins.length === 0) {
-    return {};
-  }
-
-  const hasWildcard = allowedOrigins.includes("*");
-  if (hasWildcard) {
-    return {
-      "Access-Control-Allow-Origin": "*",
-      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-      "Access-Control-Allow-Headers": "Content-Type, Authorization",
-      Vary: "Origin",
-    };
-  }
-
-  if (origin && allowedOrigins.includes(origin)) {
-    return {
-      "Access-Control-Allow-Origin": origin,
-      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-      "Access-Control-Allow-Headers": "Content-Type, Authorization",
-      Vary: "Origin",
-    };
-  }
-
-  return {};
-}

package/src/server/server.ts

@@ -1,251 +0,0 @@
-import { createServer as createNodeHttpServer, type IncomingMessage, type ServerResponse } from "node:http";
-import { resolve } from "node:path";
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
-import { findProjectRoot } from "../project/loader";
-import {
-  handleActionsRoutes,
-  handleConfigRoutes,
-  handleDoctorRoute,
-  handleHealthRoute,
-  handleInfoRoute,
-  handlePlaybooksRoutes,
-  handleRunsRoutes,
-  handleStateRoutes,
-  jsonResponse,
-  type RouteContext,
-} from "./routes";
-import { ServerRuntimeRegistry } from "./runtime-registry";
-import { isLoopbackHost, resolveCorsHeaders, verifyBearerToken } from "./security";
-import type { ActionDockServerInstance, CoreHttpServerFactory, CoreHttpServerInstance, ServerOptions } from "./types";
-
-let customHttpServerFactory: CoreHttpServerFactory | undefined;
-
-/**
- * 注册自定义 HTTP 服务端工厂（用于 Node.js / Bun 运行时环境适配）。
- */
-export function setHttpServerFactory(factory: CoreHttpServerFactory): void {
-  customHttpServerFactory = factory;
-}
-
-/**
- * 根据当前运行时环境启动标准 Web Request/Response 兼容的 HTTP 服务。
- */
-export function launchHttpServer(
-  port: number,
-  host: string,
-  fetchHandler: (req: Request) => Promise<Response>
-): CoreHttpServerInstance {
-  if (customHttpServerFactory) {
-    return customHttpServerFactory({ port, host, fetch: fetchHandler }) as CoreHttpServerInstance;
-  }
-
-  // 若处于原生 Bun 运行时
-  if (typeof (globalThis as any).Bun !== "undefined" && typeof (globalThis as any).Bun.serve === "function") {
-    const bunServer = (globalThis as any).Bun.serve({
-      port,
-      hostname: host,
-      fetch: fetchHandler,
-    });
-    return {
-      port: bunServer.port,
-      stop: (closeActive?: boolean) => bunServer.stop(closeActive),
-    };
-  }
-
-  // Node.js 原生 node:http 兜底实现
-  const srv = createNodeHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
-    try {
-      const protocol = (req.socket as any)?.encrypted ? "https" : "http";
-      const hostHeader = req.headers.host || "127.0.0.1";
-      const url = new URL(req.url || "/", `${protocol}://${hostHeader}`).href;
-
-      const headers = new Headers();
-      for (const [k, v] of Object.entries(req.headers)) {
-        if (v === undefined) continue;
-        if (Array.isArray(v)) {
-          for (const item of v) headers.append(k, item);
-        } else {
-          headers.set(k, v);
-        }
-      }
-
-      const method = (req.method || "GET").toUpperCase();
-      const hasBody = method !== "GET" && method !== "HEAD";
-      const init: RequestInit = { method, headers };
-      if (hasBody) {
-        (init as any).body = Readable.toWeb(req);
-        (init as any).duplex = "half";
-      }
-
-      const webReq = new Request(url, init);
-      const webRes = await fetchHandler(webReq);
-
-      res.statusCode = webRes.status;
-      if (webRes.statusText) res.statusMessage = webRes.statusText;
-      webRes.headers.forEach((v, k) => res.setHeader(k, v));
-
-      if (!webRes.body) {
-        res.end();
-        return;
-      }
-      await pipeline(Readable.fromWeb(webRes.body as any), res);
-    } catch (err: any) {
-      if (!res.headersSent) {
-        res.statusCode = 500;
-        res.end(JSON.stringify({ error: err?.message || String(err) }));
-      } else {
-        res.destroy(err);
-      }
-    }
-  });
-
-  srv.listen(port, host);
-  const addr = srv.address();
-  const actualPort = typeof addr === "object" && addr ? addr.port : port;
-
-  return {
-    port: actualPort,
-    stop: () => {
-      srv.close();
-      (srv as any).closeAllConnections?.();
-    },
-  };
-}
-
-/**
- * 启动 ActionDock 2.0 原生轻量级 HTTP 服务装配中枢。
- * 
- * 仅负责中间件流转、认证拦截、路由分发与服务生命周期管理。
- */
-export function startActionDockServer(
-  options: ServerOptions = {}
-): ActionDockServerInstance {
-  const port = options.port ?? 5177;
-  const host = options.host ?? "127.0.0.1";
-  const token = options.token;
-  const customHome = options.customHome;
-  const projectRoot = options.projectRoot
-    ? resolve(options.projectRoot)
-    : findProjectRoot(process.cwd());
-
-  // 非回环地址强制要求配置 Token 鉴权（防裸奔）
-  if (!isLoopbackHost(host) && !token && !options.allowInsecureNoAuth) {
-    throw new Error(
-      "Authentication token is required when binding to a non-loopback address. Use --allow-insecure-no-auth to override."
-    );
-  }
-
-  const runtimeRegistry = new ServerRuntimeRegistry();
-
-  const server = launchHttpServer(port, host, async (req) => {
-    const origin = req.headers.get("origin");
-    const corsHeaders = resolveCorsHeaders(origin, options.corsOrigins);
-
-    if (req.method === "OPTIONS") {
-      return new Response(null, {
-        status: 204,
-        headers: corsHeaders,
-      });
-    }
-
-    const url = new URL(req.url);
-    const pathname = url.pathname;
-
-    const ctx: RouteContext = {
-      req,
-      url,
-      pathname,
-      corsHeaders,
-      projectRoot,
-      customHome,
-      runtimeRegistry,
-      options,
-    };
-
-    // 1. 健康检查路由（内部处理独立鉴权逻辑）
-    const healthResponse = await handleHealthRoute(ctx);
-    if (healthResponse) {
-      return healthResponse;
-    }
-
-    // 2. MCP 统一网关端点
-    if (
-      options.enableMcp !== false &&
-      options.mcpHandler &&
-      (pathname === "/mcp" || pathname.startsWith("/mcp/"))
-    ) {
-      if (!verifyBearerToken(req, token)) {
-        return jsonResponse(
-          {
-            ok: false,
-            error: {
-              code: "UNAUTHORIZED",
-              message: "Invalid or missing Bearer token",
-            },
-          },
-          401,
-          corsHeaders
-        );
-      }
-      const mcpRes = await options.mcpHandler(req);
-      if (mcpRes) return mcpRes;
-    }
-
-    // 3. 全局 API 认证鉴权拦截
-    if (!verifyBearerToken(req, token)) {
-      return jsonResponse(
-        {
-          ok: false,
-          error: {
-            code: "UNAUTHORIZED",
-            message: "Invalid or missing Bearer token",
-          },
-        },
-        401,
-        corsHeaders
-      );
-    }
-
-    // 4. 业务领域路由分发
-    const routeResponse =
-      (await handleInfoRoute(ctx)) ||
-      (await handleDoctorRoute(ctx)) ||
-      (await handleActionsRoutes(ctx)) ||
-      (await handlePlaybooksRoutes(ctx)) ||
-      (await handleRunsRoutes(ctx)) ||
-      (await handleStateRoutes(ctx)) ||
-      (await handleConfigRoutes(ctx));
-
-    if (routeResponse) {
-      return routeResponse;
-    }
-
-    // 5. 404 路由兜底
-    return jsonResponse(
-      {
-        ok: false,
-        error: {
-          code: "NOT_FOUND",
-          message: `Route not found: ${req.method} ${pathname}`,
-        },
-      },
-      404,
-      corsHeaders
-    );
-  });
-
-  const actualHost = host === "0.0.0.0" ? "127.0.0.1" : host;
-  const url = `http://${actualHost}:${server.port}`;
-
-  return {
-    port: server.port ?? port,
-    host,
-    url,
-    runtimeRegistry,
-    stop: () => {
-      runtimeRegistry.close();
-      server.stop(true);
-    },
-  };
-}

package/src/server/types.ts

@@ -1,57 +0,0 @@
-import type { ServerRuntimeRegistry } from "./runtime-registry";
-
-export interface CoreHttpServerInstance {
-  port: number;
-  stop: (closeActiveConnections?: boolean) => void | Promise<void>;
-}
-
-export type CoreHttpServerFactory = (options: {
-  port: number;
-  host: string;
-  fetch: (req: Request) => Promise<Response>;
-}) => CoreHttpServerInstance | Promise<CoreHttpServerInstance>;
-
-/**
- * 启动 ActionDock HTTP Runner 服务端的配置选项。
- */
-export interface ServerOptions {
-  /** 监听端口号（默认 5177） */
-  port?: number;
-  /** 绑定监听的主机地址（默认 "127.0.0.1"） */
-  host?: string;
-  /** 用于 HTTP Bearer Token 鉴权的密钥令牌 */
-  token?: string;
-  /** 服务的项目根目录（可选，若未指定则自动向上查找或进入全局 Registry 模式） */
-  projectRoot?: string;
-  /** 自定义 ActionDock 用户家目录 */
-  customHome?: string;
-  /** 是否允许非回环地址（如 0.0.0.0）在未配置 Token 的情况下启动（不安全） */
-  allowInsecureNoAuth?: boolean;
-  /** 允许跨域请求的 CORS Origin 白名单列表 */
-  corsOrigins?: string[];
-  /** 最大允许的请求体字节限制（默认 1MB，防 DoS） */
-  maxBodyBytes?: number;
-  /** 是否在 health 和 info 接口中透传本地 projectRoot 等调试路径 */
-  exposeDebugInfo?: boolean;
-  /** 是否启用一体化 MCP 协议支持（默认开启） */
-  enableMcp?: boolean;
-  /** 自定义 MCP 请求处理器钩子（若挂载则 /mcp 路由交由其处理） */
-  mcpHandler?: (req: Request) => Promise<Response | null | undefined> | Response | null | undefined;
-}
-
-/**
- * 已启动的 ActionDock HTTP Runner 实例句柄。
- */
-export interface ActionDockServerInstance {
-  /** 实际监听的端口号 */
-  port: number;
-  /** 实际绑定的主机地址 */
-  host: string;
-  /** 服务端可访问的基础 URL（如 "http://127.0.0.1:5177"） */
-  url: string;
-  /** 关联的 ServerRuntimeRegistry 运行时注册表 */
-  runtimeRegistry?: ServerRuntimeRegistry;
-  /** 优雅关闭服务端并释放所有存储连接 */
-  stop: () => Promise<void> | void;
-}
-