dsh-mobile-plugin 0.0.0-stage → 0.1.57

package/lib/relay/port-allocator.cjs

@@ -0,0 +1,60 @@
+'use strict'
+
+/**
+ * 局域网代理端口的自适应分配。
+ *
+ * 背景：默认端口 18787 是个「谁都能想到」的数字，于是同一台机器上只要还有别的
+ * 服务先占了它（这台开发机就被 `billion-context start --port 18787` 占着），
+ * 局域网代理的 `listen` 就会 EADDRINUSE，整条 LAN 直连链路直接死掉——而
+ * `/api/relay/status` 只会说 `lan.state='error'`，用户看到的现象是「手机配不上对」，
+ * 和真正的原因（端口被占）隔了十万八千里。
+ *
+ * 这里把「挑端口」从配置里解耦出来：先探测首选端口，空闲就用它；被占就让内核
+ * 分配一个空闲端口，并把实际端口回传（由调用方写进状态、状态接口和配对二维码，
+ * 否则二维码里带的会是那个根本没在监听的死端口）。
+ */
+
+const net = require('node:net')
+
+/** 试绑一次端口确认它可用。占用/权限等一切失败都算「不可用」。 */
+function canListen(port, host) {
+  return new Promise(resolve => {
+    const probe = net.createServer()
+    probe.unref()
+    probe.once('error', () => resolve(false))
+    probe.once('listening', () => probe.close(() => resolve(true)))
+    try {
+      probe.listen(port, host)
+    } catch {
+      resolve(false)
+    }
+  })
+}
+
+/** 让内核分配一个当前空闲的端口（bind(0) 后立刻释放）。 */
+function freePort(host) {
+  return new Promise(resolve => {
+    const probe = net.createServer()
+    probe.unref()
+    probe.once('error', () => resolve(0))
+    probe.listen(0, host, () => {
+      const address = probe.address()
+      const port = address && typeof address.port === 'number' ? address.port : 0
+      probe.close(() => resolve(port))
+    })
+  })
+}
+
+/**
+ * 解析出本次真正要监听的端口。
+ * @returns {Promise<{port: number, adjusted: boolean, requested: number}>}
+ *   `adjusted=true` 表示首选端口被占、换了一个。
+ */
+async function resolvePort(requested, host = '0.0.0.0') {
+  const wanted = Number.isInteger(requested) && requested >= 1024 && requested <= 65535 ? requested : 18787
+  if (await canListen(wanted, host)) return { port: wanted, adjusted: false, requested: wanted }
+  const port = await freePort(host)
+  return { port: port > 0 ? port : wanted, adjusted: true, requested: wanted }
+}
+
+module.exports = { canListen, freePort, resolvePort }

package/lib/relay/preview.js

@@ -0,0 +1,374 @@
+'use strict';
+
+/**
+ * 预览字节管道（宿主侧）。
+ *
+ * 手机 App 的内置浏览器要能看到桌面机上「开发中的网页」，而那些 dev server 只监听
+ * 宿主机的 127.0.0.1:<port>。手机、中转、局域网代理都够不着它，所以链路上必须有一
+ * 段跑在宿主进程里的搬运工——就是这里。
+ *
+ * 为什么是**字节管道**而不是又一个 HTTP 代理：
+ * 一个页面不是「一次请求」而是「几百次请求」——ES 模块、CSS、图片、XHR、还有 HMR
+ * 那条活着的 WebSocket。浏览器引擎自己发这些请求，App 侧的 JS 拦不住。所以端口只在
+ * 建立管道时协商一次，之后这管道对内容一无所知，只搬字节。
+ *
+ * 这么做的收益是结构性的：内置浏览器地址栏里是 `http://localhost:3001/`，宿主机上
+ * 的 dev server 看到的 Host 也是 `localhost:3001`——两边对「我在哪」的认知完全一致。
+ * 于是 dev server 生成的一切绝对地址（资源路径、接口地址、跳转 Location、HMR 连接
+ * 地址）都自动闭环，**dev server 零配置**。反过来说，如果这里做半吊子的路径改写，
+ * `/assets/app.js` 这类绝对路径立刻全 404。
+ *
+ * 这一层刻意「不认识」HTTP 与 WebSocket：
+ *
+ *   - 手机侧的原生模块把 WebView 写下的原始字节塞进 WebSocket 的二进制帧；
+ *   - 这里 `net.connect(<环回地址>, port)` 之后双向对搬。环回地址要**双栈**试：macOS 上
+ *     不少 dev server（Vite 等）默认只监听 `::1`，只拨 `127.0.0.1` 会连不上；
+ *   - 中间任何一层都不解析、不改写，所以 WS 升级、SSE、分块传输、自定义子协议全都
+ *     原样穿过（HMR 不用砍也不用绕——浏览器和 Vite 自己完成握手与分帧）。
+ *
+ * 代价要说清楚：正因为宿主无法审查内容，**端口就是这里唯一的边界**，所以下面有
+ * `protectedPorts()` 那道按身份的拒绝（DSH 自身的 web 端口永远不许从预览进来）。
+ *
+ * 与仓库里 `dsh-mobile-server/scripts/adb-ws-bridge.cjs` 是同一个套路（原始 TCP 流包进 WebSocket 帧），
+ * 那个先例证明这条路在本项目里走得通。
+ */
+
+const net = require('node:net');
+const { WebSocketServer } = require('ws');
+
+/**
+ * 同一个宿主上同时在跑的预览连接上限。
+ *
+ * 浏览器对单个源本就有 6 条左右的并发连接限制（HTTP 与 WebSocket 各算），所以一个
+ * 正常页面根本到不了这个数；这个上限只是防止某个页面失控时把宿主的 fd 吃光。
+ */
+const MAX_PREVIEW_STREAMS = 32;
+
+/** 单条 WS 消息上限，与中转侧 MAX_WS_MESSAGE_BYTES / MAX_FRAME_BYTES 对齐。 */
+const MAX_PREVIEW_MESSAGE_BYTES = 8 * 1024 * 1024;
+
+/** 往手机方向的水位：缓冲超了就把 dev server 那头按住，落下来再放开。 */
+const SEND_HIGH_WATER_BYTES = 4 * 1024 * 1024;
+const SEND_LOW_WATER_BYTES = 1 * 1024 * 1024;
+const SEND_RESUME_POLL_MS = 20;
+
+/** 连上游的一发超时：只覆盖「还没握上」这一段；握上之后是长连接，不能有读超时。 */
+const UPSTREAM_CONNECT_TIMEOUT_MS = 10_000;
+
+/**
+ * WS 握手已成、但上游 `net.connect` 还没连上的那几百微秒里，手机已经发出来的字节
+ * 最多攒这么多。浏览器不会等我们连好上游才发请求，所以这段字节必须存住；攒过头说明
+ * 上游根本连不上，这时宁可断掉这条管道，也不能无限吃内存。
+ */
+const MAX_PREVIEW_PENDING_BYTES = 1024 * 1024;
+
+/**
+ * 从升级请求的查询串里取 port。
+ *
+ * 中转的升级分发（`server.js` 的 `server.on('upgrade')`）不看路径，只做鉴权后把
+ * `req.url` 原样交给隧道；宿主的 webServer 又只按 pathname 匹配升级路由、忽略查询串
+ * ——所以端口只能这么带，也只能这么读。
+ *
+ * @returns {number|null} 合法端口，或 null（缺参数、非数字、越界都算非法）
+ */
+function parsePreviewPort(req) {
+  let params;
+  try {
+    params = new URL(req && req.url ? req.url : '/', 'http://preview.invalid').searchParams;
+  } catch {
+    return null;
+  }
+  const raw = params.get('port');
+  if (raw === null || !/^[0-9]{1,5}$/.test(raw)) return null;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+  return port;
+}
+
+const HTML_HEAD = '<!doctype html><html lang="zh-CN"><head><meta charset="utf-8">'
+  + '<meta name="viewport" content="width=device-width,initial-scale=1">'
+  + '<title>预览未建立</title><style>'
+  + 'body{margin:0;padding:28px 20px;font:15px/1.7 -apple-system,"PingFang SC","Noto Sans CJK SC",sans-serif;'
+  + 'background:#14161a;color:#e6e8ec}'
+  + 'h1{margin:0 0 10px;font-size:17px;font-weight:600}'
+  + 'p{margin:0 0 10px;color:#a9b0bb}'
+  + 'code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;color:#f0b849}'
+  + '</style></head><body>';
+
+/**
+ * 失败页。由**宿主**生成再借这条字节管道发给内置浏览器——手机原生模块只是个哑管道，
+ * 它没有能力编出人话；而原因只有宿主知道（端口没人监听？被拒？）。
+ */
+function renderFailureHtml({ title, detail, port }) {
+  return `${HTML_HEAD}<h1>${title}</h1><p>${detail}</p>`
+    + `<p>端口：<code>${port}</code></p>`
+    + '</body></html>';
+}
+
+/** 升级**之前**的拒绝：握手还没成，所以按普通 HTTP 应答，对方的 WS 客户端会看到状态码。 */
+function refuseUpgrade(socket, status, reason, text) {
+  if (!socket || socket.destroyed) return;
+  const body = Buffer.from(renderFailureHtml({ title: text, detail: '', port: '' }), 'utf8');
+  socket.write(
+    `HTTP/1.1 ${status} ${reason}\r\n`
+    + 'Content-Type: text/html; charset=utf-8\r\n'
+    + `Content-Length: ${body.length}\r\n`
+    + 'Connection: close\r\n\r\n',
+  );
+  socket.end(body);
+}
+
+/**
+ * @param {object} deps
+ * @param {(req: object) => boolean} deps.authorized 移动端鉴权（lib/mobile/auth.js 的 authorized）
+ * @param {() => Set<number>} deps.protectedPorts DSH 自身占用的端口，永远不许从预览进来
+ * @param {(message: string) => void} [deps.onLog]
+ */
+function createPreviewService({ authorized, protectedPorts, onLog }) {
+  const wss = new WebSocketServer({
+    noServer: true,
+    perMessageDeflate: false,
+    maxPayload: MAX_PREVIEW_MESSAGE_BYTES,
+  });
+
+  /**
+   * 走过这道门的端口。这张表是「预览到底碰过什么」的唯一记录，内存态、随宿主重启清空
+   * ——端口本身不是长期授权，是一次使用留下的痕迹，用于手机端展示与排查。
+   */
+  const grants = new Map();
+  let activeStreams = 0;
+  let closed = false;
+
+  const log = (message) => { try { onLog?.(message); } catch { /* 日志失败不该影响搬运 */ } };
+
+  function noteGrant(port) {
+    const now = Date.now();
+    const grant = grants.get(port);
+    if (grant) {
+      grant.streams += 1;
+      grant.lastUsedAt = now;
+    } else {
+      grants.set(port, { port, firstUsedAt: now, lastUsedAt: now, streams: 1 });
+    }
+  }
+
+  /**
+   * 一条管道：完成 WebSocket 握手，然后把它与 `127.0.0.1:<port>` 对搬。
+   */
+  function openPipe(ws, port) {
+    activeStreams += 1;
+    noteGrant(port);
+
+    let upstream = null;
+    let finished = false;
+    let resumeTimer = null;
+    let upstreamReady = false;
+    let pendingBytes = 0;
+    /** 上游还没连上时手机先发过来的字节，见 MAX_PREVIEW_PENDING_BYTES。 */
+    const pending = [];
+
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      activeStreams -= 1;
+      if (resumeTimer) { clearInterval(resumeTimer); resumeTimer = null; }
+      pending.length = 0;
+      pendingBytes = 0;
+      try { ws.close(); } catch { /* 可能已经关了 */ }
+      if (upstream && !upstream.destroyed) upstream.destroy();
+    };
+
+    /** 手机 → dev server；`write` 返回 false 表示内核缓冲满了，此时按住 WS 的读端。 */
+    const writeToUpstream = (chunk) => {
+      if (finished || !upstream || upstream.destroyed) return;
+      if (!upstream.write(chunk)) ws.pause();
+    };
+
+    /** 发往手机方向的水位控制：`ws` 没有 drain 事件，只能轮询 bufferedAmount。 */
+    const startResumePoll = () => {
+      if (resumeTimer || finished) return;
+      resumeTimer = setInterval(() => {
+        if (finished || ws.readyState !== ws.OPEN) {
+          clearInterval(resumeTimer); resumeTimer = null; return;
+        }
+        if (ws.bufferedAmount <= SEND_LOW_WATER_BYTES) {
+          clearInterval(resumeTimer); resumeTimer = null;
+          if (upstream && !upstream.destroyed) upstream.resume();
+        }
+      }, SEND_RESUME_POLL_MS);
+      if (typeof resumeTimer.unref === 'function') resumeTimer.unref();
+    };
+
+    // 这两个监听必须**立刻**挂上，不能等 `upstream.on('connect')`：手机在 WS 握手一
+    // 完成就会把 HTTP 请求字节发出来，而上游 TCP 往往还在路上。挂晚了这几百微秒内的
+    // 字节会被直接丢掉——表现就是「页面时好时坏、偶尔整页空白」，且只在真机上偶发。
+    ws.on('message', (data) => {
+      if (finished) return;
+      const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data);
+      if (chunk.length === 0) return;
+      if (upstreamReady) { writeToUpstream(chunk); return; }
+      pending.push(chunk);
+      pendingBytes += chunk.length;
+      if (pendingBytes > MAX_PREVIEW_PENDING_BYTES) finish();
+    });
+    ws.on('close', finish);
+    ws.on('error', finish);
+
+    // 上游必须**双栈**拨号：macOS 上 Vite 之类的 dev server 默认只监听 `::1`，只连
+    // `127.0.0.1` 必然是 ECONNREFUSED，用户看到的就是「电脑上这个端口没有服务」。
+    // 两个地址都是环回，谁在听就用谁；只有在前一个「还没连上就失败」时才换下一个。
+    const upstreamHosts = ['127.0.0.1', '::1'];
+    let hostIndex = 0;
+    let connectTimer = null;
+    let lastError = 'ECONNREFUSED';
+
+    const clearConnectTimer = () => {
+      if (connectTimer) { clearTimeout(connectTimer); connectTimer = null; }
+    };
+
+    /** 两个环回地址都连不上：握手已经成了，没法再用 HTTP 状态码，只能借管道送失败页。 */
+    const failUpstream = () => {
+      log(`preview port ${port}: ${lastError}`);
+      // 这条管道本来就是透明的，索性由宿主写一段 502 响应借它送进内置浏览器——比让
+      // WebView 显示系统错误页清楚得多。
+      if (ws.readyState === ws.OPEN) {
+        const body = Buffer.from(renderFailureHtml({
+          title: '电脑上这个端口没有服务',
+          detail: lastError === 'ECONNREFUSED'
+            ? '开发服务可能已经停了。回到 DSH 重新启动它，再刷新这个页面。'
+            : `宿主连不上 127.0.0.1:${port}，也连不上 [::1]:${port}（${lastError}）。`,
+          port,
+        }), 'utf8');
+        const head = Buffer.from(
+          'HTTP/1.1 502 Bad Gateway\r\n'
+          + 'Content-Type: text/html; charset=utf-8\r\n'
+          + `Content-Length: ${body.length}\r\n`
+          + 'Connection: close\r\n\r\n',
+          'utf8',
+        );
+        try { ws.send(Buffer.concat([head, body]), { binary: true }); } catch { /* 已经断了 */ }
+      }
+      finish();
+    };
+
+    /** 换下一个环回地址；都试过了就按失败收场。 */
+    const advanceHost = () => {
+      if (finished) return;
+      hostIndex += 1;
+      if (hostIndex < upstreamHosts.length) { dialUpstream(); return; }
+      failUpstream();
+    };
+
+    function dialUpstream() {
+      const host = upstreamHosts[hostIndex];
+      const socketToUpstream = net.connect({ host, port });
+      upstream = socketToUpstream;
+
+      // 握上手之前给一发超时；连上之后这条 TCP 就是长连接（SSE、HMR 都从它过），
+      // 不能再有任何读超时。
+      connectTimer = setTimeout(() => {
+        connectTimer = null;
+        if (finished || upstreamReady || socketToUpstream !== upstream) return;
+        lastError = 'ETIMEDOUT';
+        log(`preview port ${port}: ${host} 连接超时`);
+        try { socketToUpstream.destroy(); } catch { /* 可能已经断了 */ }
+        advanceHost();
+      }, UPSTREAM_CONNECT_TIMEOUT_MS);
+      if (typeof connectTimer.unref === 'function') connectTimer.unref();
+
+      socketToUpstream.on('error', (error) => {
+        if (finished || socketToUpstream !== upstream) return;
+        lastError = (error && error.code) || (error && error.message) || 'unknown';
+        clearConnectTimer();
+        if (!upstreamReady) {
+          log(`preview port ${port}: ${host} 连不上（${lastError}）`);
+          advanceHost();
+          return;
+        }
+        failUpstream();
+      });
+
+      socketToUpstream.on('connect', () => {
+        clearConnectTimer();
+        log(`preview port ${port}: 管道已接通（${host}）`);
+        upstreamReady = true;
+
+        socketToUpstream.on('drain', () => { if (!finished && ws.readyState === ws.OPEN) ws.resume(); });
+
+        // dev server → 手机。
+        socketToUpstream.on('data', (chunk) => {
+          if (finished || ws.readyState !== ws.OPEN) return;
+          if (ws.bufferedAmount > SEND_HIGH_WATER_BYTES) {
+            socketToUpstream.pause();
+            startResumePoll();
+          }
+          ws.send(chunk, { binary: true });
+        });
+
+        socketToUpstream.on('close', finish);
+
+        // 冲掉「连上之前」攒下的字节（顺序不变）。
+        for (const chunk of pending) {
+          if (finished) break;
+          writeToUpstream(chunk);
+        }
+        pending.length = 0;
+        pendingBytes = 0;
+      });
+    }
+
+    dialUpstream();
+  }
+
+  /**
+   * 宿主 webServer 的升级处理器（`ctx.webServer.registerUpgrade`）。
+   *
+   * 拒绝一定要发生在 `handleUpgrade` **之前**：那时 socket 还是一条普通 HTTP 连接，
+   * 可以老实回 401/403；一旦完成握手，就只能靠管道里塞失败页了。
+   */
+  function handleUpgrade(req, socket, head) {
+    if (closed) return refuseUpgrade(socket, 503, 'Service Unavailable', '预览管道已关闭');
+
+    const port = parsePreviewPort(req);
+    if (port === null) return refuseUpgrade(socket, 400, 'Bad Request', '缺少或非法的 port 参数');
+
+    let allowed = false;
+    try { allowed = Boolean(authorized(req)); } catch { allowed = false; }
+    if (!allowed) return refuseUpgrade(socket, 401, 'Unauthorized', '移动端凭据无效');
+
+    // DSH 自身的端口按**身份**拒绝，不是按数字拉黑。3080 是宿主 web 服务的实际端口
+    // （`ctx.webServer.port`，可能被配置改过），从预览进来等于把桌面端 GUI/API 搬到了
+    // 手机内置浏览器里——那条路刻意不做，所以在这里用同一个真值掐掉。
+    if (protectedPorts().has(port)) {
+      return refuseUpgrade(socket, 403, 'Forbidden', `端口 ${port} 属于 DSH 自身，不允许预览`);
+    }
+
+    if (activeStreams >= MAX_PREVIEW_STREAMS) {
+      return refuseUpgrade(socket, 503, 'Service Unavailable', '预览连接数已达上限');
+    }
+
+    wss.handleUpgrade(req, socket, head, (ws) => openPipe(ws, port));
+  }
+
+  return {
+    handleUpgrade,
+    /** 「预览碰过哪些端口」的快照，供状态接口展示。 */
+    grants: () => [...grants.values()].sort((a, b) => a.port - b.port).map((grant) => ({ ...grant })),
+    stats: () => ({ activeStreams, maxStreams: MAX_PREVIEW_STREAMS }),
+    close: () => {
+      closed = true;
+      for (const client of wss.clients) {
+        try { client.terminate(); } catch { /* 已经断了 */ }
+      }
+      wss.close();
+    },
+  };
+}
+
+module.exports = {
+  MAX_PREVIEW_STREAMS,
+  MAX_PREVIEW_MESSAGE_BYTES,
+  createPreviewService,
+  parsePreviewPort,
+  renderFailureHtml,
+};

package/lib/relay/protocol.js

@@ -0,0 +1,177 @@
+'use strict';
+
+/**
+ * dsh-mobile-server 隧道协议 v2 编解码（取代 v1 的 JSON/base64 文本帧）。
+ *
+ * 每条隧道消息 = 一个 WS binary 帧：
+ *   [type: 1B][id: 4B 大端][length: 4B 大端][payload: length B]
+ *
+ * - 数据通道（httpBody / httpChunk / wsText / wsBinary）的 payload 为
+ *   原始字节，不再 base64（消除 ~33% 体积膨胀）；
+ * - 控制消息（register / httpHead 等）payload 为 UTF-8 JSON；
+ * - ping/pong 为应用层心跳（经代理/负载均衡时比 WS 原生 ping 更可靠）。
+ *
+ * 协议语义见 ../../../dsh-mobile-server/PROTOCOL.md（v2 章节）。
+ *
+ * 本文件是 dsh-mobile-server/lib/protocol.js 的自包含副本
+ * （插件包不能跨目录引用中转仓库的文件），唯一允许的差异是上面那行路径注释。
+ * 改动权威实现的 T 表后，必须同步修改本文件。
+ */
+
+const T = {
+  register: 0x01,      // id=0  JSON {instanceId, pairingCode, name, lanUrls?, lanCandidates?}
+  registered: 0x02,    // id=0  JSON {}
+  updatePairing: 0x03, // id=0  JSON {pairingCode}
+  httpRequest: 0x04,   // id=N  JSON {method, path, headers}；body 随后以 httpBody 流式发送
+  httpBody: 0x05,      // id=N  raw bytes（空 payload = body 结束）
+  httpHead: 0x06,      // id=N  JSON {status, headers}
+  httpChunk: 0x07,     // id=N  raw bytes
+  httpEnd: 0x08,       // id=N  空
+  httpError: 0x09,     // id=N  JSON {message}
+  wsUpgrade: 0x0A,     // id=N  JSON {path, headers}
+  wsOpen: 0x0B,        // id=N  空
+  wsError: 0x0C,       // id=N  JSON {message}
+  wsText: 0x0D,        // id=N  raw bytes（上游 WS 文本帧数据）
+  wsBinary: 0x0E,      // id=N  raw bytes（上游 WS 二进制帧数据）
+  wsClose: 0x0F,       // id=N  2B 大端 close code
+  ping: 0x10,          // id=0  空
+  pong: 0x11,          // id=0  空
+  pairRequest: 0x12,   // id=0  JSON {requestId, device:{id?, deviceId?, name?, platform?, osVersion?, appVersion?, ip?}}（手机配对 → 请求桌面授权；ip 由中转注入）
+  pairConfirm: 0x13,   // id=0  JSON {requestId, approved, token?}（桌面授权结果 → 中转 → 手机）
+  httpCancel: 0x14,     // id=N  空；取消上游 HTTP 请求/响应
+  httpPause: 0x15,      // id=N  空；暂停向中转发送响应数据
+  httpResume: 0x16,     // id=N  空；恢复向中转发送响应数据
+  sync: 0x17,          // id=0  JSON {kind, ...}；桌面→中转主动推送（移动端镜像缓存）
+  revokeAll: 0x18,     // id=0  JSON {at}；桌面请求中转清空本实例全部设备授权
+  revokeAllAck: 0x19,  // id=0  JSON {ok, revoked}；中转确认已清空
+};
+
+const TYPE_NAME = {};
+for (const [name, code] of Object.entries(T)) TYPE_NAME[code] = name;
+
+const HEADER_LEN = 9;
+
+/** 编码一帧；字符串/JSON 直接写入最终帧，避免中间 Buffer 与整段复制。 */
+function encodeFrame(type, id, payload) {
+  let body = null;
+  let text = null;
+  if (Buffer.isBuffer(payload)) {
+    body = payload;
+  } else if (typeof payload === 'string') {
+    text = payload;
+  } else if (payload !== undefined && payload !== null) {
+    text = JSON.stringify(payload);
+  }
+  const bodyLength = body ? body.length : (text === null ? 0 : Buffer.byteLength(text, 'utf8'));
+  const buf = Buffer.allocUnsafe(HEADER_LEN + bodyLength);
+  buf.writeUInt8(type, 0);
+  buf.writeUInt32BE(id >>> 0, 1);
+  buf.writeUInt32BE(bodyLength, 5);
+  if (body) body.copy(buf, HEADER_LEN);
+  else if (bodyLength) buf.write(text, HEADER_LEN, bodyLength, 'utf8');
+  return buf;
+}
+
+/** JSON 帧编码助手。 */
+function jsonFrame(type, id, obj) {
+  return encodeFrame(type, id, JSON.stringify(obj));
+}
+
+/**
+ * 创建流式帧解码器：WS 消息可能包含多帧或半帧（send 大 buffer 时 TCP 层
+ * 分片，ws 库会重组为一个 message；此处仍做拼接防御）。
+ * 用法：const push = createFrameDecoder(onFrame); push(chunk);
+ */
+function createFrameDecoder(onFrame, options = {}) {
+  const maxFrameBytes = options.maxFrameBytes == null ? 64 * 1024 * 1024 : options.maxFrameBytes;
+  const onError = options.onError || (() => {});
+  let buf = Buffer.alloc(0);
+  return function push(chunk) {
+    if (!Buffer.isBuffer(chunk)) chunk = Buffer.from(chunk);
+    if (chunk.length > maxFrameBytes + HEADER_LEN || buf.length + chunk.length > maxFrameBytes + HEADER_LEN) {
+      onError(new Error('frame too large'));
+      buf = Buffer.alloc(0);
+      return false;
+    }
+    buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+    while (buf.length >= HEADER_LEN) {
+      const type = buf.readUInt8(0);
+      const id = buf.readUInt32BE(1);
+      const len = buf.readUInt32BE(5);
+      if (len > maxFrameBytes) {
+        onError(new Error('frame too large'));
+        buf = Buffer.alloc(0);
+        return false;
+      }
+      if (buf.length < HEADER_LEN + len) break;
+      const payload = buf.subarray(HEADER_LEN, HEADER_LEN + len);
+      buf = buf.subarray(HEADER_LEN + len);
+      onFrame({ type, id, payload });
+    }
+  };
+}
+
+/** 解析控制帧 payload 为对象（失败返回空对象）。 */
+function parseJson(buf) {
+  try {
+    return JSON.parse(buf.toString('utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/** 按字节截断字符串，且不切断 UTF-8 码点（ws 会拒绝非法 reason）。 */
+function truncateUtf8(text, maxBytes) {
+  const bytes = Buffer.from(text, 'utf8');
+  let end = Math.min(maxBytes, bytes.length);
+  while (end > 0) {
+    const last = bytes[end - 1];
+    if ((last & 0x80) === 0) return bytes.subarray(0, end);
+    let start = end - 1;
+    while (start > 0 && (bytes[start] & 0xc0) === 0x80) start -= 1;
+    const lead = bytes[start];
+    const width = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : lead >= 0xc0 ? 2 : 1;
+    if ((lead & 0xc0) !== 0x80 && start + width <= end) return bytes.subarray(0, end);
+    end = start;
+  }
+  return Buffer.alloc(0);
+}
+
+// WS 关闭帧：reason 上限 123 字节（RFC 6455 控制帧 125 字节减去 2 字节 code）。
+const MAX_CLOSE_REASON_BYTES = 123;
+// 1005/1006/1015 是保留值，不得出现在线上；1004 语义不明，ws 同样拒绝。
+const RESERVED_CLOSE_CODES = [1004, 1005, 1006, 1015];
+/** close code 是否可出现在线上（ws 对保留值/越界值会直接抛错）。 */
+function validCloseCode(code) {
+  return Number.isInteger(code) && code >= 1000 && code <= 4999 && !RESERVED_CLOSE_CODES.includes(code);
+}
+/** 编码 wsClose payload：2B 大端 close code + 不切断码点的 UTF-8 reason。
+ *  reason 可能是 string，也可能是 ws 'close' 事件给的 Buffer。Buffer 不需要单独
+ *  分支：String(buf) 走的是 Buffer.prototype.toString()，本身就按 UTF-8 解码
+ *  （'<Buffer e5 86 8d …>' 只是 util.inspect / console.log 的显示形式，不是
+ *  String() 的结果）。 */
+function encodeClosePayload(code, reason) {
+  const c = validCloseCode(code) ? code : 1000;
+  return Buffer.concat([Buffer.from([(c >> 8) & 255, c & 255]), truncateUtf8(String(reason || ''), MAX_CLOSE_REASON_BYTES)]);
+}
+/** 解码 wsClose payload。code 可直接交给 ws.close()；raw 是线上原值（供日志）。 */
+function decodeClosePayload(payload) {
+  const raw = payload && payload.length >= 2 ? payload.readUInt16BE(0) : 1000;
+  const ok = validCloseCode(raw);
+  const reason = payload && payload.length > 2 ? truncateUtf8(payload.subarray(2), MAX_CLOSE_REASON_BYTES).toString('utf8') : '';
+  return { code: ok ? raw : 1000, raw, validCode: ok, reason };
+}
+
+module.exports = {
+  T,
+  TYPE_NAME,
+  HEADER_LEN,
+  encodeFrame,
+  jsonFrame,
+  createFrameDecoder,
+  parseJson,
+  truncateUtf8,
+  encodeClosePayload,
+  decodeClosePayload,
+  MAX_CLOSE_REASON_BYTES,
+};