@xyagent/cli 0.0.1

package/src/tunnel_proxy.mjs

@@ -0,0 +1,913 @@
+// tunnel.mjs 拆分:tunnel-agent 长轮询 + HTTP/WS/TCP 代理。
+//
+// 这层只做"作为 agent 在 relay 和本地服务之间转发流量",不知道 CLI、不知道
+// state 文件,只接受参数(relayUrl/tunnelID/tunnelToken/targetBaseUrl/protocol)
+// 然后跑 long-poll 循环 / 心跳 / 会话维护。
+
+import net from "node:net";
+
+import { trimSlash } from "./core.mjs";
+import {
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  DEFAULT_HEARTBEAT_INTERVAL_MS,
+  DEFAULT_HEARTBEAT_TIMEOUT_MS,
+  DEFAULT_POLL_WAIT_SECONDS,
+  DEFAULT_STREAM_WAIT_TIMEOUT_MS,
+  TUNNEL_PROTOCOL_HTTP,
+  TUNNEL_PROTOCOL_WS,
+  TUNNEL_PROTOCOL_TCP,
+  TUNNEL_IDLE_LOG_EVERY,
+  TUNNEL_HEARTBEAT_ERROR_LOG_EVERY,
+  TUNNEL_STREAM_IDLE_LOG_EVERY,
+  fetchJson,
+  withServerToken,
+  extractJsonError,
+  isHopByHopHeader,
+  joinTunnelTargetUrl,
+  parseTunnelTCPAddress,
+  normalizeWebSocketPayload,
+  summarizeTunnelRequest,
+  decodeBase64Length,
+  sleep,
+  normalizeTunnelProtocol,
+} from "./tunnel_state.mjs";
+
+// ---- 远端 tunnel CRUD ----
+
+export async function createTunnel({ relayUrl, localPort, protocol, targetBaseUrl, serverToken, fail }) {
+  const response = await fetchJson(`${relayUrl}/v1/tunnels`, {
+    method: "POST",
+    headers: withServerToken(serverToken),
+    body: JSON.stringify({ protocol, localPort, targetBaseUrl }),
+  });
+  if (!response.ok) {
+    fail(extractJsonError(response.body, `create tunnel failed (HTTP ${response.status})`));
+  }
+  const tunnel = response.body?.tunnel;
+  if (!tunnel?.id || !tunnel?.agentToken || !tunnel?.publicUrl) {
+    fail("create tunnel returned incomplete payload");
+  }
+  tunnel.protocol = normalizeTunnelProtocol(tunnel.protocol || protocol, fail);
+  return tunnel;
+}
+
+export async function safeDeleteRemoteTunnel(state) {
+  if (!state?.id || !state?.token || !state?.relayUrl) return;
+  try {
+    await fetchJson(`${trimSlash(state.relayUrl)}/v1/tunnels/${encodeURIComponent(state.id)}`, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${state.token}` },
+    });
+  } catch { /* best effort */ }
+}
+
+// ---- agent 长轮询 ----
+
+export async function readNextTunnelRequest({ relayUrl, tunnelID, tunnelToken }) {
+  const response = await fetchJson(
+    `${relayUrl}/v1/tunnels/${encodeURIComponent(tunnelID)}/requests/next`,
+    { method: "GET", headers: { Authorization: `Bearer ${tunnelToken}` } },
+    DEFAULT_REQUEST_TIMEOUT_MS + DEFAULT_POLL_WAIT_SECONDS * 1000,
+  );
+  if (response.status === 204) return null;
+  if (!response.ok) {
+    throw new Error(extractJsonError(response.body, `read tunnel request failed (HTTP ${response.status})`));
+  }
+  return response.body?.request ?? null;
+}
+
+export async function publishTunnelResponse({ relayUrl, tunnelID, tunnelToken, requestID, response }) {
+  const result = await fetchJson(
+    `${relayUrl}/v1/tunnels/${encodeURIComponent(tunnelID)}/responses/${encodeURIComponent(requestID)}/publish`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${tunnelToken}` },
+      body: JSON.stringify(response),
+    },
+  );
+  if (!result.ok) {
+    throw new Error(extractJsonError(result.body, `publish tunnel response failed (HTTP ${result.status})`));
+  }
+}
+
+export async function readNextTunnelStreamEvent({ relayUrl, tunnelID, tunnelToken }) {
+  const response = await fetchJson(
+    `${relayUrl}/v1/tunnels/${encodeURIComponent(tunnelID)}/streams/next`,
+    { method: "GET", headers: { Authorization: `Bearer ${tunnelToken}` } },
+    DEFAULT_STREAM_WAIT_TIMEOUT_MS + DEFAULT_POLL_WAIT_SECONDS * 1000,
+  );
+  if (response.status === 204) return null;
+  if (!response.ok) {
+    throw new Error(extractJsonError(response.body, `read tunnel stream event failed (HTTP ${response.status})`));
+  }
+  return response.body?.event ?? null;
+}
+
+export async function publishTunnelSessionEvent({ relayUrl, tunnelID, tunnelToken, sessionID, event }) {
+  const result = await fetchJson(
+    `${relayUrl}/v1/tunnels/${encodeURIComponent(tunnelID)}/sessions/${encodeURIComponent(sessionID)}/publish`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${tunnelToken}` },
+      body: JSON.stringify(event),
+    },
+  );
+  if (!result.ok) {
+    throw new Error(extractJsonError(result.body, `publish tunnel session event failed (HTTP ${result.status})`));
+  }
+}
+
+// ---- agent 心跳 ----
+
+async function sendTunnelHeartbeat({ relayUrl, tunnelID, tunnelToken }) {
+  const result = await fetchJson(
+    `${relayUrl}/v1/tunnels/${encodeURIComponent(tunnelID)}/heartbeat`,
+    { method: "POST", headers: { Authorization: `Bearer ${tunnelToken}` } },
+    DEFAULT_HEARTBEAT_TIMEOUT_MS,
+  );
+  if (!result.ok) {
+    throw new Error(extractJsonError(result.body, `heartbeat failed (HTTP ${result.status})`));
+  }
+}
+
+export function startTunnelHeartbeat({ relayUrl, tunnelID, tunnelToken, logger }) {
+  let stopped = false;
+  let failureCount = 0;
+  const tick = async (phase) => {
+    if (stopped) return;
+    try {
+      await sendTunnelHeartbeat({ relayUrl, tunnelID, tunnelToken });
+      if (failureCount > 0) {
+        logger.info("heartbeat recovered", { failures: failureCount, phase });
+      }
+      failureCount = 0;
+    } catch (error) {
+      failureCount += 1;
+      if (failureCount === 1 || failureCount % TUNNEL_HEARTBEAT_ERROR_LOG_EVERY === 0) {
+        logger.error("heartbeat failed", {
+          phase, failures: failureCount,
+          error: String(error instanceof Error ? error.message : error),
+        });
+      }
+      throw error;
+    }
+  };
+  const timer = setInterval(() => { tick("interval").catch(() => {}); }, DEFAULT_HEARTBEAT_INTERVAL_MS);
+  if (typeof timer.unref === "function") timer.unref();
+  return {
+    sendNow(phase = "manual") { return tick(phase); },
+    stop() { stopped = true; clearInterval(timer); },
+  };
+}
+
+// ---- HTTP 代理 ----
+
+// ---------------------------------------------------------------------------
+// Tunnel path rewriting & runtime shim injection
+// ---------------------------------------------------------------------------
+// 被代理应用 (Next.js / Vite / 任何带前端构建产物的 SPA) 不知道自己挂在
+// `/t/<slug>/` 下。它产的 absolute path 资源 (`/_next/...`)、Location 头、
+// CSS url()、JS 里 `fetch("/api/...")`、SPA router 写 history 时调 pushState、
+// 等等,都会落到 origin 根上,绕过 tunnel 路由直接 404。
+//
+// 两层补丁:
+//   1. 静态层: 扫文本改写 HTML 属性 / CSS url() / Link / Location 等所有能
+//      用 regex 安全匹配的 absolute path。这层零运行时副作用。
+//   2. 运行时层: 往 HTML 注一段 inline shim,hook fetch / XHR / WebSocket /
+//      EventSource / sendBeacon / history.pushState/replaceState /
+//      Location.pathname/href getter,以及 MutationObserver 跟踪后续 DOM。
+//      shim 保证 JS 在运行时拼出来的 absolute path / SPA 路由也带前缀。
+
+// 静态属性扫描覆盖的 URL 属性集合 —— 引导 HTML rewriter 一次性命中所有
+// 单值 URL 属性。`srcset` / `imagesrcset` 是逗号分隔的多值,走单独的 regex。
+const SINGLE_URL_ATTRS = [
+  "href", "src", "action", "formaction",
+  "data-href", "data-src", "poster",
+  "cite", "data", "manifest", "longdesc", "background",
+];
+const URL_ATTR_RE = new RegExp(
+  `\\b(${SINGLE_URL_ATTRS.join("|")})=(['"])\\/(?!\\/)`,
+  "gi",
+);
+// srcset / imagesrcset 形如 `"/a.jpg 1x, /b.jpg 2x, /c.jpg"`,
+// 抓整个属性值后逐项处理。
+const SRCSET_ATTR_RE = /\b(srcset|imagesrcset)=(['"])([^'"]*)\2/gi;
+// `<meta http-equiv="refresh" content="0;url=/foo">` —— content 里嵌的 URL。
+const META_REFRESH_RE =
+  /(<meta\b[^>]*\bhttp-equiv\s*=\s*['"]?refresh['"]?[^>]*\bcontent\s*=\s*['"][^'"]*\burl\s*=\s*)\/(?!\/)/gi;
+// CSS url(/foo) / url('/foo') / url("/foo) —— `(?!\/)` 排除 protocol-relative。
+const CSS_URL_RE = /\burl\(\s*(['"]?)\/(?!\/)/gi;
+// CSS @import "/foo" (不带 url() 的裸引号形式)。
+const CSS_IMPORT_RE = /(@import\s+)(['"])\/(?!\/)/gi;
+
+function trimTrailingSlash(s) {
+  return String(s || "").replace(/\/+$/, "");
+}
+
+// rewriteSrcsetValue 改写 srcset / imagesrcset 属性值。逗号分隔多 URL,
+// 每段允许追加 descriptor (`1x` / `300w`),descriptor 后再带逗号或结束。
+function rewriteSrcsetValue(value, prefix) {
+  return value
+    .split(",")
+    .map((part) => {
+      const trimmed = part.trim();
+      if (!trimmed) return part;
+      const m = trimmed.match(/^(\S+)(\s.*)?$/);
+      if (!m) return part;
+      const url = m[1];
+      const rest = m[2] || "";
+      const leading = part.slice(0, part.length - trimmed.length);
+      if (url.startsWith("/") && !url.startsWith("//") &&
+        url !== prefix && !url.startsWith(prefix + "/")
+      ) {
+        return `${leading}${prefix}${url}${rest}`;
+      }
+      return part;
+    })
+    .join(",");
+}
+
+export function rewriteHtmlAbsolutePaths(html, prefix) {
+  const prefixSafe = trimTrailingSlash(prefix);
+  if (!prefixSafe) return html;
+  return html
+    .replace(URL_ATTR_RE, (_full, attr, quote) =>
+      `${attr}=${quote}${prefixSafe}/`,
+    )
+    .replace(SRCSET_ATTR_RE, (_full, attr, quote, val) =>
+      `${attr}=${quote}${rewriteSrcsetValue(val, prefixSafe)}${quote}`,
+    )
+    .replace(META_REFRESH_RE, (_full, head) => `${head}${prefixSafe}/`)
+    .replace(CSS_URL_RE, (_match, quote) => `url(${quote}${prefixSafe}/`)
+    .replace(CSS_IMPORT_RE, (_full, head, quote) => `${head}${quote}${prefixSafe}/`);
+}
+
+// CSS 文件 (`text/css` 响应) 的改写。HTML rewriter 只扫 HTML 里的 inline
+// `<style>` 和 url() —— 外链 `.css` 文件里写的 url() 和 @import 不在它的覆盖范围
+// (响应不是 text/html),所以这里单独跑一遍。
+export function rewriteCssAbsolutePaths(css, prefix) {
+  const prefixSafe = trimTrailingSlash(prefix);
+  if (!prefixSafe) return css;
+  return css
+    .replace(CSS_URL_RE, (_match, quote) => `url(${quote}${prefixSafe}/`)
+    .replace(CSS_IMPORT_RE, (_full, head, quote) => `${head}${quote}${prefixSafe}/`);
+}
+
+// 3xx 响应的 Location 头。`/login` → `/t/<slug>/login`;跨域 / protocol-relative
+// 不动 (浏览器自己跳走,不归 tunnel 管)。
+export function rewriteLocationHeader(value, prefix) {
+  const prefixSafe = trimTrailingSlash(prefix);
+  if (!prefixSafe) return value;
+  const v = String(value || "");
+  if (!v.startsWith("/") || v.startsWith("//")) return v;
+  if (v === prefixSafe || v.startsWith(prefixSafe + "/")) return v;
+  return prefixSafe + v;
+}
+
+// 运行时 shim —— 注入到 HTML 顶端,patch 所有运行时 URL 入口。
+// 占位 `__HTTP_PREFIX__` / `__WS_PREFIX__` 由 buildShimScript 替换。
+const TUNNEL_SHIM_TEMPLATE = `
+(function(){
+  if (window.__BUBBO_TUNNEL_SHIM__) return;
+  window.__BUBBO_TUNNEL_SHIM__ = true;
+
+  var HTTP_PREFIX = "__HTTP_PREFIX__";
+  var WS_PREFIX   = "__WS_PREFIX__";
+
+  function isAbsPath(u){
+    return typeof u === "string" && u.length > 0 && u.charAt(0) === "/" && u.charAt(1) !== "/";
+  }
+  function hasHttpPrefix(u){
+    return u === HTTP_PREFIX || u.indexOf(HTTP_PREFIX + "/") === 0;
+  }
+  function fixHttp(u){
+    if (!isAbsPath(u)) return u;
+    if (hasHttpPrefix(u)) return u;
+    return HTTP_PREFIX + u;
+  }
+  function stripHttp(p){
+    if (typeof p !== "string") return p;
+    if (p === HTTP_PREFIX) return "/";
+    if (p.indexOf(HTTP_PREFIX + "/") === 0) return p.slice(HTTP_PREFIX.length);
+    return p;
+  }
+  function sameOrigin(u){
+    try { return u.host === location.host; } catch(e){ return false; }
+  }
+  function fixHttpUrl(s){
+    if (typeof s !== "string") return s;
+    if (isAbsPath(s)) return fixHttp(s);
+    try {
+      var u = new URL(s, location.href);
+      if (sameOrigin(u) && !hasHttpPrefix(u.pathname)) {
+        u.pathname = HTTP_PREFIX + (u.pathname === "" ? "/" : u.pathname);
+        return u.toString();
+      }
+    } catch(e){}
+    return s;
+  }
+  function fixWs(u){
+    if (typeof u !== "string") return u;
+    if (isAbsPath(u)) {
+      if (u === WS_PREFIX || u.indexOf(WS_PREFIX + "/") === 0) return u;
+      return WS_PREFIX + u;
+    }
+    try {
+      var parsed = new URL(u, location.href);
+      if ((parsed.protocol === "ws:" || parsed.protocol === "wss:") && sameOrigin(parsed)) {
+        if (parsed.pathname !== WS_PREFIX && parsed.pathname.indexOf(WS_PREFIX + "/") !== 0) {
+          parsed.pathname = WS_PREFIX + (parsed.pathname === "" ? "/" : parsed.pathname);
+          return parsed.toString();
+        }
+      }
+    } catch(e){}
+    return u;
+  }
+
+  // 1) fetch
+  if (typeof window.fetch === "function") {
+    var origFetch = window.fetch.bind(window);
+    window.fetch = function(input, init){
+      try {
+        if (typeof input === "string") {
+          return origFetch(fixHttpUrl(input), init);
+        }
+        if (typeof Request !== "undefined" && input instanceof Request) {
+          var url = new URL(input.url);
+          if (sameOrigin(url) && !hasHttpPrefix(url.pathname)) {
+            url.pathname = HTTP_PREFIX + url.pathname;
+            return origFetch(new Request(url.toString(), input), init);
+          }
+        }
+      } catch(e){}
+      return origFetch(input, init);
+    };
+  }
+
+  // 2) XMLHttpRequest
+  if (typeof XMLHttpRequest !== "undefined") {
+    var xhrOpen = XMLHttpRequest.prototype.open;
+    XMLHttpRequest.prototype.open = function(method, url){
+      try { arguments[1] = fixHttpUrl(url); } catch(e){}
+      return xhrOpen.apply(this, arguments);
+    };
+  }
+
+  // 3) WebSocket
+  if (typeof window.WebSocket === "function") {
+    var OrigWS = window.WebSocket;
+    function PatchedWS(url, protocols){
+      return arguments.length >= 2 ? new OrigWS(fixWs(url), protocols) : new OrigWS(fixWs(url));
+    }
+    PatchedWS.prototype = OrigWS.prototype;
+    PatchedWS.CONNECTING = OrigWS.CONNECTING;
+    PatchedWS.OPEN       = OrigWS.OPEN;
+    PatchedWS.CLOSING    = OrigWS.CLOSING;
+    PatchedWS.CLOSED     = OrigWS.CLOSED;
+    window.WebSocket = PatchedWS;
+  }
+
+  // 4) EventSource (SSE)
+  if (typeof window.EventSource === "function") {
+    var OrigES = window.EventSource;
+    function PatchedES(url, init){
+      return arguments.length >= 2 ? new OrigES(fixHttpUrl(url), init) : new OrigES(fixHttpUrl(url));
+    }
+    PatchedES.prototype = OrigES.prototype;
+    window.EventSource = PatchedES;
+  }
+
+  // 5) sendBeacon
+  if (navigator && typeof navigator.sendBeacon === "function") {
+    var origBeacon = navigator.sendBeacon.bind(navigator);
+    navigator.sendBeacon = function(url, data){
+      return origBeacon(fixHttpUrl(url), data);
+    };
+  }
+
+  // 6) history.pushState / replaceState
+  ["pushState","replaceState"].forEach(function(name){
+    var orig = history[name];
+    if (typeof orig !== "function") return;
+    history[name] = function(state, title, url){
+      if (typeof url === "string") url = fixHttpUrl(url);
+      return orig.call(this, state, title, url);
+    };
+  });
+
+  // 7) Location.pathname / href getter — 让 SPA router 看到剥掉前缀的 path,
+  //    否则 router 把 /t/<slug>/foo 当成路由的一部分,根本匹配不到 /foo。
+  //    setter 同样兜底:app 写 location.pathname = "/foo" 时自动补前缀。
+  try {
+    var Loc = Location.prototype;
+    var pathDesc = Object.getOwnPropertyDescriptor(Loc, "pathname");
+    if (pathDesc && pathDesc.configurable && pathDesc.get) {
+      var origPathGet = pathDesc.get, origPathSet = pathDesc.set;
+      Object.defineProperty(Loc, "pathname", {
+        configurable: true,
+        enumerable: pathDesc.enumerable,
+        get: function(){ return stripHttp(origPathGet.call(this)); },
+        set: function(v){ return origPathSet.call(this, fixHttp(v)); },
+      });
+    }
+    var hrefDesc = Object.getOwnPropertyDescriptor(Loc, "href");
+    if (hrefDesc && hrefDesc.configurable && hrefDesc.get) {
+      var origHrefGet = hrefDesc.get, origHrefSet = hrefDesc.set;
+      Object.defineProperty(Loc, "href", {
+        configurable: true,
+        enumerable: hrefDesc.enumerable,
+        get: function(){
+          var real = origHrefGet.call(this);
+          try {
+            var u = new URL(real);
+            if (u.pathname === HTTP_PREFIX) { u.pathname = "/"; return u.toString(); }
+            if (u.pathname.indexOf(HTTP_PREFIX + "/") === 0) {
+              u.pathname = u.pathname.slice(HTTP_PREFIX.length);
+              return u.toString();
+            }
+          } catch(e){}
+          return real;
+        },
+        set: function(v){ return origHrefSet.call(this, fixHttpUrl(v)); },
+      });
+    }
+    // toString() 等价 href getter
+    if (typeof Loc.toString === "function") {
+      var origToString = Loc.toString;
+      Loc.toString = function(){ return this.href; };
+      // 保留旧 origToString 引用避免被 GC,但用 hrefGet 输出。
+      void origToString;
+    }
+  } catch(e){ /* Safari / 古浏览器 patch 失败,降级:SPA 路由可能不工作 */ }
+
+  // 8) MutationObserver —— 跟踪 JS 后续 inject 的 <a>/<img>/<link>/<script> 等
+  //    与已有元素的 attribute 动态变化。
+  var DYN_ATTRS = ["href","src","action","formaction","poster","data","cite","manifest","longdesc","background"];
+  function rewriteAttrs(el){
+    if (!el || el.nodeType !== 1) return;
+    for (var i = 0; i < DYN_ATTRS.length; i++) {
+      var a = DYN_ATTRS[i];
+      if (!el.hasAttribute || !el.hasAttribute(a)) continue;
+      var v = el.getAttribute(a);
+      if (isAbsPath(v) && !hasHttpPrefix(v)) el.setAttribute(a, HTTP_PREFIX + v);
+    }
+    if (el.hasAttribute && el.hasAttribute("srcset")) {
+      el.setAttribute("srcset", rewriteSrcsetAttr(el.getAttribute("srcset")));
+    }
+    if (el.hasAttribute && el.hasAttribute("imagesrcset")) {
+      el.setAttribute("imagesrcset", rewriteSrcsetAttr(el.getAttribute("imagesrcset")));
+    }
+    if (el.children) {
+      for (var j = 0; j < el.children.length; j++) rewriteAttrs(el.children[j]);
+    }
+  }
+  function rewriteSrcsetAttr(v){
+    if (!v) return v;
+    return v.split(",").map(function(part){
+      var trimmed = part.trim();
+      if (!trimmed) return part;
+      var m = trimmed.match(/^(\\S+)(\\s.*)?$/);
+      if (!m) return part;
+      var url = m[1], rest = m[2] || "";
+      var leading = part.slice(0, part.length - trimmed.length);
+      if (isAbsPath(url) && !hasHttpPrefix(url)) return leading + HTTP_PREFIX + url + rest;
+      return part;
+    }).join(",");
+  }
+  function startObserver(){
+    if (!document.body) {
+      var pre = new MutationObserver(function(){ if (document.body) { pre.disconnect(); startObserver(); } });
+      pre.observe(document.documentElement, { childList: true });
+      return;
+    }
+    new MutationObserver(function(records){
+      for (var i = 0; i < records.length; i++) {
+        var r = records[i];
+        if (r.type === "childList") {
+          for (var k = 0; k < r.addedNodes.length; k++) rewriteAttrs(r.addedNodes[k]);
+        } else if (r.type === "attributes") {
+          rewriteAttrs(r.target);
+        }
+      }
+    }).observe(document.documentElement, {
+      childList: true, subtree: true, attributes: true,
+      attributeFilter: ["href","src","srcset","imagesrcset","action","formaction","poster","data","cite","manifest","longdesc","background"],
+    });
+  }
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", startObserver, { once: true });
+  } else {
+    startObserver();
+  }
+})();
+`.trim();
+
+export function buildShimScript(httpPrefix, wsPrefix) {
+  const safeHttp = trimTrailingSlash(httpPrefix);
+  const safeWs = trimTrailingSlash(wsPrefix || "");
+  // 占位符替换 —— 直接字符串替换,不参与 JS 语义,前缀里只允许 URL-safe 字符
+  // (本仓库 slug 形如 `p<port>-<hex>`,符合 `[A-Za-z0-9_-]`)。
+  return TUNNEL_SHIM_TEMPLATE
+    .replace("__HTTP_PREFIX__", safeHttp)
+    .replace("__WS_PREFIX__", safeWs || safeHttp);
+}
+
+// injectHtmlShim 把 <script>shim</script> 塞到 HTML 最前面。优先紧跟 `<head>`
+// 开标签插入(保证在被代理 app 任何 JS 之前执行);若没有 `<head>`,退而求其次
+// 紧跟 `<html>`;两者都没有则直接 prepend。
+export function injectHtmlShim(html, httpPrefix, wsPrefix) {
+  const script = buildShimScript(httpPrefix, wsPrefix);
+  const tag = `<script>${script}</script>`;
+  const headMatch = html.match(/<head\b[^>]*>/i);
+  if (headMatch) {
+    const idx = headMatch.index + headMatch[0].length;
+    return html.slice(0, idx) + tag + html.slice(idx);
+  }
+  const htmlMatch = html.match(/<html\b[^>]*>/i);
+  if (htmlMatch) {
+    const idx = htmlMatch.index + htmlMatch[0].length;
+    return html.slice(0, idx) + tag + html.slice(idx);
+  }
+  return tag + html;
+}
+
+export async function proxyTunnelRequest({ request, targetBaseUrl, publicPathPrefix = "", publicWsPathPrefix = "" }) {
+  const pathName = typeof request.path === "string" && request.path.trim() ? request.path : "/";
+  const url = new URL(trimSlash(targetBaseUrl) + pathName);
+  if (typeof request.rawQuery === "string" && request.rawQuery) {
+    url.search = request.rawQuery;
+  }
+
+  const headers = new Headers();
+  for (const [name, values] of Object.entries(request.headers ?? {})) {
+    if (isHopByHopHeader(name) || name.toLowerCase() === "host") continue;
+    // 跳过浏览器的 Accept-Encoding —— 它会让 origin 返回 gzip 压缩 body,
+    // 但我们要做 HTML 路径改写必须拿到 plain text。如果改写 gzip 字节,
+    // 浏览器 gzip 解码会得到 ERR_CONTENT_DECODING_FAILED。强制 identity
+    // 让 origin 返回未压缩 body。
+    if (publicPathPrefix && name.toLowerCase() === "accept-encoding") continue;
+    for (const value of Array.isArray(values) ? values : [values]) {
+      headers.append(name, String(value));
+    }
+  }
+  if (publicPathPrefix) {
+    headers.set("accept-encoding", "identity");
+  }
+  if (request.originalHost) {
+    headers.set("x-forwarded-host", String(request.originalHost));
+  }
+
+  let body;
+  if (typeof request.bodyBase64 === "string" && request.bodyBase64) {
+    body = Buffer.from(request.bodyBase64, "base64");
+  }
+
+  let response;
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), DEFAULT_REQUEST_TIMEOUT_MS);
+    try {
+      response = await fetch(url, {
+        method: request.method || "GET",
+        headers, body,
+        signal: controller.signal,
+        redirect: "manual",
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  } catch (error) {
+    return {
+      statusCode: 502,
+      headers: { "content-type": ["text/plain; charset=utf-8"] },
+      bodyBase64: Buffer.from(String(error instanceof Error ? error.message : error), "utf8").toString("base64"),
+    };
+  }
+
+  let payload = Buffer.from(await response.arrayBuffer());
+  const contentType = response.headers.get("content-type") || "";
+
+  // text/html: 改写 absolute-path 属性 + 注入运行时 shim。两步合在一起做,
+  // 避免对同一份 body 反复 toString。
+  if (publicPathPrefix && /^text\/html\b/i.test(contentType)) {
+    try {
+      const html = payload.toString("utf8");
+      const rewritten = rewriteHtmlAbsolutePaths(html, publicPathPrefix);
+      const injected = injectHtmlShim(rewritten, publicPathPrefix, publicWsPathPrefix);
+      if (injected !== html) {
+        payload = Buffer.from(injected, "utf8");
+      }
+    } catch { /* 改写失败回退到原 payload */ }
+  }
+  // text/css: 外链 CSS 文件里写的 url()/@import 走单独一遍扫描;HTML rewriter
+  // 不看这些响应。
+  if (publicPathPrefix && /^text\/css\b/i.test(contentType)) {
+    try {
+      const css = payload.toString("utf8");
+      const rewritten = rewriteCssAbsolutePaths(css, publicPathPrefix);
+      if (rewritten !== css) {
+        payload = Buffer.from(rewritten, "utf8");
+      }
+    } catch { /* same */ }
+  }
+
+  const outHeaders = responseHeadersToObject(response.headers);
+
+  if (publicPathPrefix) {
+    // 1) Link 头 preload hints (Next.js / Nuxt / etc.) —— 已有逻辑。
+    if (Array.isArray(outHeaders["link"])) {
+      outHeaders["link"] = outHeaders["link"].map((v) =>
+        rewriteLinkHeaderValue(v, publicPathPrefix),
+      );
+    }
+    // 2) 3xx Location 头 —— `/login` → `/t/<slug>/login`,绝对 URL 不动。
+    if (response.status >= 300 && response.status < 400 && Array.isArray(outHeaders["location"])) {
+      outHeaders["location"] = outHeaders["location"].map((v) =>
+        rewriteLocationHeader(v, publicPathPrefix),
+      );
+    }
+    // 3) Content-Encoding —— Node fetch 已自动解压,客户端看到这个 header 会
+    //    去 decode 已解压的 body 必然失败,删掉。
+    delete outHeaders["content-encoding"];
+    // 4) CSP —— inline shim 在 strict CSP (`script-src 'self'`) 下会被拒。
+    //    tunnel 自身是受信代理,直接把 CSP 头干掉,让 shim 能跑。
+    //    Report-Only 同样删除,避免产生误导性违规日志。
+    delete outHeaders["content-security-policy"];
+    delete outHeaders["content-security-policy-report-only"];
+  }
+
+  return {
+    statusCode: response.status,
+    headers: outHeaders,
+    bodyBase64: payload.toString("base64"),
+  };
+}
+
+// 改写 Link header 里的 absolute path。Link header 形如:
+//   </foo.css>; rel=preload; as=style, </bar.woff2>; rel=preload; as=font
+// 里面的 `<URL>` 部分若以 `/` 开头(非 protocol-relative `//`)则加前缀。
+export function rewriteLinkHeaderValue(value, prefix) {
+  const prefixSafe = String(prefix || "").replace(/\/+$/, "");
+  if (!prefixSafe) return value;
+  return String(value).replace(/<\s*(\/(?!\/)[^>]*)>/g, (_match, urlPath) => `<${prefixSafe}${urlPath}>`);
+}
+
+function responseHeadersToObject(headers) {
+  const out = {};
+  for (const [name, value] of headers.entries()) {
+    if (isHopByHopHeader(name) || name.toLowerCase() === "content-length") continue;
+    if (!out[name]) out[name] = [];
+    out[name].push(value);
+  }
+  if (typeof headers.getSetCookie === "function") {
+    const cookies = headers.getSetCookie();
+    if (cookies.length > 0) out["set-cookie"] = cookies;
+  }
+  return out;
+}
+
+// ---- WebSocket / TCP session pool ----
+
+const tunnelStreamSessions = new Map();
+
+export async function handleTunnelStreamEvent({
+  event, protocol, targetBaseUrl, relayUrl, tunnelID, tunnelToken, logger,
+}) {
+  const sessionID = String(event?.sessionId ?? "").trim();
+  if (!sessionID) throw new Error("missing session id");
+  switch (event.kind) {
+    case "open":
+      if (protocol === TUNNEL_PROTOCOL_WS) {
+        await openLocalWebSocketSession({ event, targetBaseUrl, relayUrl, tunnelID, tunnelToken, logger });
+        return;
+      }
+      if (protocol === TUNNEL_PROTOCOL_TCP) {
+        await openLocalTCPSession({ event, targetBaseUrl, relayUrl, tunnelID, tunnelToken, logger });
+        return;
+      }
+      throw new Error(`unsupported stream protocol: ${protocol}`);
+    case "client_data":
+      await writeTunnelStreamSession({ sessionID, event });
+      return;
+    case "client_close":
+      await closeTunnelStreamSession(sessionID);
+      return;
+    default:
+      logger.info("stream event ignored", { sessionId: sessionID, kind: event.kind ?? "-" });
+  }
+}
+
+async function openLocalWebSocketSession({ event, targetBaseUrl, relayUrl, tunnelID, tunnelToken, logger }) {
+  const sessionID = event.sessionId;
+  const targetUrl = joinTunnelTargetUrl(targetBaseUrl, event.path, event.rawQuery);
+  const ws = new WebSocket(targetUrl);
+  ws.binaryType = "arraybuffer";
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("websocket open timeout")), DEFAULT_REQUEST_TIMEOUT_MS);
+    ws.addEventListener("open", () => { clearTimeout(timer); resolve(true); }, { once: true });
+    ws.addEventListener("error", (error) => {
+      clearTimeout(timer);
+      reject(error?.error ?? new Error("websocket open failed"));
+    }, { once: true });
+  });
+  tunnelStreamSessions.set(sessionID, {
+    protocol: TUNNEL_PROTOCOL_WS,
+    send(payload, eventType) {
+      ws.send(eventType === "binary" ? Buffer.from(payload) : payload.toString("utf8"));
+    },
+    close() {
+      try { ws.close(); } catch { /* noop */ }
+    },
+  });
+  logger.info("stream open", { sessionId: sessionID, protocol: TUNNEL_PROTOCOL_WS, target: targetUrl });
+
+  ws.addEventListener("message", async (message) => {
+    const payload = await normalizeWebSocketPayload(message.data);
+    await publishTunnelSessionEvent({
+      relayUrl, tunnelID, tunnelToken, sessionID,
+      event: {
+        sessionId: sessionID, protocol: TUNNEL_PROTOCOL_WS,
+        kind: "server_data",
+        messageType: typeof message.data === "string" ? "text" : "binary",
+        payloadBase64: payload.toString("base64"),
+        createdAt: new Date().toISOString(),
+      },
+    });
+  });
+  ws.addEventListener("close", async () => {
+    tunnelStreamSessions.delete(sessionID);
+    await publishTunnelSessionEvent({
+      relayUrl, tunnelID, tunnelToken, sessionID,
+      event: { sessionId: sessionID, protocol: TUNNEL_PROTOCOL_WS, kind: "server_close", createdAt: new Date().toISOString() },
+    }).catch(() => {});
+  });
+  ws.addEventListener("error", async (error) => {
+    await publishTunnelSessionEvent({
+      relayUrl, tunnelID, tunnelToken, sessionID,
+      event: {
+        sessionId: sessionID, protocol: TUNNEL_PROTOCOL_WS,
+        kind: "server_error",
+        error: String(error?.message ?? error?.error?.message ?? "websocket error"),
+        createdAt: new Date().toISOString(),
+      },
+    }).catch(() => {});
+  });
+}
+
+async function openLocalTCPSession({ event, targetBaseUrl, relayUrl, tunnelID, tunnelToken, logger }) {
+  const sessionID = event.sessionId;
+  const { host, port } = parseTunnelTCPAddress(targetBaseUrl);
+  const socket = net.createConnection({ host, port });
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("tcp open timeout")), DEFAULT_REQUEST_TIMEOUT_MS);
+    socket.once("connect", () => { clearTimeout(timer); resolve(); });
+    socket.once("error", (error) => { clearTimeout(timer); reject(error); });
+  });
+  tunnelStreamSessions.set(sessionID, {
+    protocol: TUNNEL_PROTOCOL_TCP,
+    send(payload) { socket.write(payload); },
+    close() { socket.destroy(); },
+  });
+  logger.info("stream open", { sessionId: sessionID, protocol: TUNNEL_PROTOCOL_TCP, target: `${host}:${port}` });
+
+  socket.on("data", async (chunk) => {
+    await publishTunnelSessionEvent({
+      relayUrl, tunnelID, tunnelToken, sessionID,
+      event: {
+        sessionId: sessionID, protocol: TUNNEL_PROTOCOL_TCP,
+        kind: "server_data",
+        payloadBase64: Buffer.from(chunk).toString("base64"),
+        createdAt: new Date().toISOString(),
+      },
+    });
+  });
+  socket.on("close", async () => {
+    tunnelStreamSessions.delete(sessionID);
+    await publishTunnelSessionEvent({
+      relayUrl, tunnelID, tunnelToken, sessionID,
+      event: { sessionId: sessionID, protocol: TUNNEL_PROTOCOL_TCP, kind: "server_close", createdAt: new Date().toISOString() },
+    }).catch(() => {});
+  });
+  socket.on("error", async (error) => {
+    await publishTunnelSessionEvent({
+      relayUrl, tunnelID, tunnelToken, sessionID,
+      event: {
+        sessionId: sessionID, protocol: TUNNEL_PROTOCOL_TCP,
+        kind: "server_error",
+        error: String(error instanceof Error ? error.message : error),
+        createdAt: new Date().toISOString(),
+      },
+    }).catch(() => {});
+  });
+}
+
+async function writeTunnelStreamSession({ sessionID, event }) {
+  const session = tunnelStreamSessions.get(sessionID);
+  if (!session) return;
+  const payload = Buffer.from(String(event.payloadBase64 ?? ""), "base64");
+  session.send(payload, event.messageType);
+}
+
+async function closeTunnelStreamSession(sessionID) {
+  const session = tunnelStreamSessions.get(sessionID);
+  if (!session) return;
+  tunnelStreamSessions.delete(sessionID);
+  session.close();
+}
+
+// ---- agent 主循环 (HTTP 模式 long-poll, WS/TCP 模式 stream-poll) ----
+
+export async function runHttpAgentLoop({ stopState, relayUrl, tunnelID, tunnelToken, targetBaseUrl, logger, publicPathPrefix = "", publicWsPathPrefix = "" }) {
+  let idlePolls = 0;
+  while (!stopState.stopping) {
+    let request;
+    try {
+      request = await readNextTunnelRequest({ relayUrl, tunnelID, tunnelToken });
+    } catch (error) {
+      logger.error("poll failed", { error: String(error instanceof Error ? error.message : error) });
+      await sleep(1000);
+      continue;
+    }
+    if (!request) {
+      idlePolls += 1;
+      if (idlePolls === 1 || idlePolls % TUNNEL_IDLE_LOG_EVERY === 0) {
+        logger.info("poll idle", { count: idlePolls });
+      }
+      continue;
+    }
+    idlePolls = 0;
+    const requestSummary = summarizeTunnelRequest(request);
+    logger.info("request start", requestSummary);
+    const startedAt = Date.now();
+    let response;
+    try {
+      response = await proxyTunnelRequest({ request, targetBaseUrl, publicPathPrefix, publicWsPathPrefix });
+    } catch (error) {
+      logger.error("proxy failed", {
+        ...requestSummary,
+        error: String(error instanceof Error ? error.message : error),
+      });
+      throw error;
+    }
+    logger.info("request proxied", {
+      ...requestSummary,
+      status: response.statusCode,
+      bytes: decodeBase64Length(response.bodyBase64),
+      durationMs: Date.now() - startedAt,
+    });
+    try {
+      await publishTunnelResponse({ relayUrl, tunnelID, tunnelToken, requestID: request.requestId, response });
+      logger.info("response published", {
+        requestId: request.requestId,
+        status: response.statusCode,
+        durationMs: Date.now() - startedAt,
+      });
+    } catch (error) {
+      logger.error("publish failed", {
+        requestId: request.requestId,
+        error: String(error instanceof Error ? error.message : error),
+      });
+      throw error;
+    }
+  }
+}
+
+export async function runStreamAgentLoop({
+  stopState, protocol, relayUrl, tunnelID, tunnelToken, targetBaseUrl, logger,
+}) {
+  let idlePolls = 0;
+  while (!stopState.stopping) {
+    let event;
+    try {
+      event = await readNextTunnelStreamEvent({ relayUrl, tunnelID, tunnelToken });
+    } catch (error) {
+      logger.error("poll failed", { error: String(error instanceof Error ? error.message : error) });
+      await sleep(1000);
+      continue;
+    }
+    if (!event) {
+      idlePolls += 1;
+      if (idlePolls === 1 || idlePolls % TUNNEL_STREAM_IDLE_LOG_EVERY === 0) {
+        logger.info("stream idle", { count: idlePolls });
+      }
+      continue;
+    }
+    idlePolls = 0;
+    try {
+      await handleTunnelStreamEvent({
+        event, protocol, targetBaseUrl,
+        relayUrl, tunnelID, tunnelToken, logger,
+      });
+    } catch (error) {
+      logger.error("stream event failed", {
+        sessionId: event?.sessionId ?? "-",
+        kind: event?.kind ?? "-",
+        error: String(error instanceof Error ? error.message : error),
+      });
+      throw error;
+    }
+  }
+}
+
+// 协议常量在调用方需要,re-export 便于 tunnel.mjs 引用。
+export { TUNNEL_PROTOCOL_HTTP, TUNNEL_PROTOCOL_WS, TUNNEL_PROTOCOL_TCP };