@taole/dd-playwright 0.0.0-stage → 0.1.1

package/src/whistle-proxy.mjs

@@ -0,0 +1,232 @@
+/**
+ * Whistle 隔离代理管理器（进程内启动）。
+ *
+ * 与 CLI `run` 不同（CLI 内部还会 spawn 二级 bootstrap 子进程，kill 后易留孤儿），
+ * 这里直接调用 whistle 的 programmatic API，在当前 Node 进程内监听端口：
+ *   - 无子进程，MCP 进程退出即代理消失，无孤儿
+ *   - WHISTLE_PATH 指向独立临时目录，绝不污染用户本机 ~/.WhistleAppData
+ *   - 仅监听 127.0.0.1，不对外暴露
+ *   - 域名后缀限制可声明规则；启用后浏览器流量均经代理转发
+ */
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+
+let startWhistleFn = null;
+function getStartWhistle() {
+  if (!startWhistleFn) {
+    const require = createRequire(import.meta.url);
+    startWhistleFn = require("whistle");
+  }
+  return startWhistleFn;
+}
+async function waitReady(port, timeoutMs = 25_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/cgi-bin/status`);
+      if (res.ok) return true;
+    } catch {}
+    await new Promise((r) => setTimeout(r, 300));
+  }
+  return false;
+}
+
+export class WhistleProxyManager {
+  /**
+   * @param {{domainRegex: RegExp}} options 域名白名单正则，不匹配的规则域名会被拒绝
+   */
+  constructor({ domainRegex } = {}) {
+    if (!(domainRegex instanceof RegExp)) {
+      throw new Error("WhistleProxyManager 需要 domainRegex (RegExp)");
+    }
+    this.domainRegex = domainRegex;
+    this.port = null;
+    this.proxyEvents = null; // whistle 内部 EventEmitter，含 .server
+    this.workDir = null;
+    this.started = false;
+  }
+
+  /**
+   * 启动隔离 whistle 实例。
+   * @param {number} [preferredPort] 代理监听端口，默认自动分配
+   * @returns {Promise<number>} 实际监听的代理端口
+   */
+  async start(preferredPort) {
+    if (this.started) return this.port;
+
+    const port = preferredPort ?? (await this._findFreePort());
+
+    // 创建隔离数据目录（必须在 require 配置生效前设置环境变量）
+    this.workDir = mkdtempSync(join(tmpdir(), "whistle-proxy-"));
+    process.env.WHISTLE_PATH = this.workDir;
+
+    const rulesDir = join(this.workDir, ".whistle", "rules");
+    const filesDir = join(rulesDir, "files");
+    mkdirSync(filesDir, { recursive: true });
+
+    // 写入空规则文件（selectedList 必须存在，否则规则不生效）
+    writeFileSync(join(filesDir, "0.default"), "");
+    writeFileSync(
+      join(rulesDir, "properties"),
+      JSON.stringify({ filesOrder: ["default"], selectedList: ["default"] }),
+    );
+
+    // 进程内启动（callback this 指向 server，参数为 proxyEvents）
+    const startWhistle = getStartWhistle();
+    this.proxyEvents = await new Promise((resolve, reject) => {
+      try {
+        startWhistle(
+          {
+            host: "127.0.0.1",
+            port,
+            mode: "capture",
+            noGlobalPlugins: true,
+          },
+          function (proxyEvents) {
+            resolve(proxyEvents);
+          },
+        );
+      } catch (err) {
+        reject(err);
+      }
+    });
+
+    // 等待就绪
+    const ready = await waitReady(port);
+    if (!ready) {
+      await this._closeServer();
+      rmSync(this.workDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+      this.workDir = null;
+      throw new Error(
+        `Whistle proxy failed to start on port ${port} within 25s`,
+      );
+    }
+
+    this.port = port;
+    this.started = true;
+    return port;
+  }
+
+  /**
+   * 声明一条域名映射规则。
+   * @param {string} domain 目标域名，必须匹配 domainRegex
+   * @param {number} port 本地 dev server 端口
+   * @param {"http"|"https"} protocol 本地 dev server 协议，默认 http
+   * @returns {Promise<{url: string, rule: string}>} 浏览器应访问的干净 URL
+   */
+  async setRule(domain, port, protocol = "http") {
+    if (!this.started) {
+      throw new Error("Whistle proxy not started. Call start() first.");
+    }
+    if (!this.domainRegex.test(domain)) {
+      throw new Error(
+        `Domain ${domain} not allowed; must match ${this.domainRegex}`,
+      );
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error(`Invalid port: ${port}`);
+    }
+    if (protocol !== "http" && protocol !== "https") {
+      throw new Error(`Protocol must be http or https, got: ${protocol}`);
+    }
+
+    const ruleText = `${domain} ${protocol}://127.0.0.1:${port}`;
+
+    // 通过 whistle WebUI CGI 运行期写入并启用规则（比写文件可靠，立即生效）
+    const res = await fetch(
+      `http://127.0.0.1:${this.port}/cgi-bin/rules/select`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          name: "default",
+          value: ruleText,
+        }).toString(),
+      },
+    );
+    if (!res.ok) {
+      throw new Error(`Failed to set whistle rule: HTTP ${res.status}`);
+    }
+    const result = await res.json();
+    if (result.ec !== 0) {
+      throw new Error(`Failed to set whistle rule: ${JSON.stringify(result)}`);
+    }
+
+    // 验证规则已生效
+    const listRes = await fetch(
+      `http://127.0.0.1:${this.port}/cgi-bin/rules/list`,
+    );
+    const listData = await listRes.json();
+    const active = listData.list?.find((r) => r.name === "default");
+    if (!active?.selected || !active.data?.includes(domain)) {
+      throw new Error(
+        "Whistle rule set but not active. Verify via /cgi-bin/rules/list.",
+      );
+    }
+
+    const url = protocol === "https" ? `https://${domain}/` : `http://${domain}/`;
+    return { url, rule: ruleText };
+  }
+
+  /**
+   * 浏览器应使用的 Chromium 启动参数。
+   * @returns {string[]}
+   */
+  getBrowserArgs() {
+    if (!this.started) return [];
+    return [
+      `--proxy-server=http://127.0.0.1:${this.port}`,
+      "--ignore-certificate-errors",
+    ];
+  }
+
+  /**
+   * 浏览器 context 选项（HTTPS 场景需要忽略证书错误）。
+   * @returns {{ignoreHTTPSErrors: boolean}}
+   */
+  getContextOptions() {
+    return { ignoreHTTPSErrors: true };
+  }
+
+  async _closeServer() {
+    const server = this.proxyEvents?.server;
+    if (server && typeof server.close === "function") {
+      await new Promise((resolve) => {
+        // 强制断开已建立连接，避免 close 挂起
+        if (typeof server.closeAllConnections === "function") {
+          try {
+            server.closeAllConnections();
+          } catch {}
+        }
+        server.close(() => resolve());
+        // 兜底：server 未在监听时 close 回调可能不触发
+        setTimeout(resolve, 3000).unref?.();
+      });
+    }
+    this.proxyEvents = null;
+  }
+
+  async close() {
+    await this._closeServer();
+    if (this.workDir) {
+      rmSync(this.workDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+      this.workDir = null;
+    }
+    this.started = false;
+    this.port = null;
+  }
+
+  async _findFreePort() {
+    const net = await import("node:net");
+    return new Promise((resolve, reject) => {
+      const server = net.createServer();
+      server.listen(0, "127.0.0.1", () => {
+        const { port } = server.address();
+        server.close(() => resolve(port));
+      });
+      server.on("error", reject);
+    });
+  }
+}