@mzzsfy/dsh-tunnel 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# dsh-tunnel
+
+穿透隧道插件: 在 dsh 宿主进程内把本地 TCP 端口反向代理出来, 并向 ai 注册 `tunnel_open` / `tunnel_list` / `tunnel_close` 三个工具, 赋予 ai 主动开关隧道的能力。代理逻辑全在插件进程内, 不引入 nginx/caddy 等外部反代。
+
+## 双入口形态
+
+### path(默认)——子路径模式
+
+`http://<host>:<port>/p/<name>/` → 本机 targetPort:
+
+- HTTP 前缀 strip 纯字节转发, 保留原 Host, 附 `x-forwarded-host/for/proto`; 3xx 同源根绝对路径的 `Location` 单头补前缀
+- WebSocket: 创建时声明 `wsPaths`(相对隧道根), 每值注册带/不带尾斜杠两形态 exact upgrade 路由; 缺省 = 纯 HTTP
+- 应用需支持子路径部署(vite `--base` / jupyter `base_url` / gradio `root_path` / streamlit `baseUrlPath`), 由 ai 以正确 base 参数启动
+
+### subdomain——子域名模式
+
+`http://<name>.<任意泛解析到本机的域名>:<port>/` → 本机 targetPort(本机浏览器直接 `<name>.localhost:<port>`):
+
+- 全路径全协议透传: 无 strip、不改写 Location、WebSocket 任意路径可用(动态内核通道如 jupyter 无需枚举)
+- 应用按根路径正常启动, 无需 base 参数
+- 实现: wrap+shadow 分流(与 dsh-auto-trust-all 同构), 隧道 Host 命中即转发, 隧道域名上与宿主路由完全隔离; Host 信任依赖 dsh-auto-trust-all
+- 限制: 隧道名避开入口域名首标签(如 GUI 经 `dsh.example.com` 访问则别用隧道名 `dsh`)
+
+## 使用
+
+- ai 通道: 会话内直接让 ai 开隧道 `tunnel_open`(name, targetPort, entry?, wsPaths?) / `tunnel_list` / `tunnel_close`; 「允许 ai 使用」开关(默认开)关闭即向 ai 注销三件工具, 看板与 REST 管理不受影响
+- GUI 通道: 侧边栏「穿透隧道」面板手动添加/删除/复制访问地址(与 ai 同表); 设置卡两枚开关——「允许 ai 使用隧道工具」与「看板移入 better-sidebar 侧边栏」(设置 > 插件页 / 0.1.7+ 插件管理页包详情)
+- 设置面: legacy(≤0.1.6) 设置 > 插件页独立配置节; 0.1.7+ Config volatile 字段自动配置节(connectTimeoutMs / aiTools / sidebarTab 均支持原地热更, dataDir 为环境路径不进 UI)。`connectTimeoutMs`(响应头等待超时, 改动即时生效, 无需重启)
+- 持久化 `~/.dsh/dsh-tunnel/tunnels.json`(随 `DSH_HOME`), 重启自动恢复; 目标拒连 502, 响应头等待超时(默认 10s, 头到即解除, SSE 不受影响)504
+- REST: `/api/tunnel/tunnels`(GET/POST/DELETE `/api/tunnel/tunnels/:name`) + `/api/tunnel/status` + `/api/tunnel/ui-settings`(PATCH: aiTools / sidebarTab), 与 GUI/ai 同一入口
+
+## 验证
+
+- `node --test "test/*.test.mjs"`: 36 场景 + 8 api 用例 + 11 ai 开关注册面 + 12 守卫断言(mock webServer + 真实 http/net 端到端)
+- `node scripts/compat/tunnel-fullchain.mjs`: 隔离 dsh 实例全链路(真实激活/恢复/分发面七项探针)
+
+## 设计文档
+
+`docs/调研-路径穿透插件.md`(「方案设计」两节为本包实施规格, 含已知限制); `docs/设计-隧道GUI.md`(GUI/设置/侧边栏注入实施规格)。

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-tunnel bundle patch: 把本包 host 平面行注册进 profile 根
+# (`dsh plugin add @mzzsfy/dsh-tunnel` 应用):
+#   - 路径穿透隧道: /p/<name> 前缀路由 + 声明式 WS upgrade + /api/tunnel REST 面 + ai 工具三件。
+#   - client 半区(隧道看板 + 设置页卡片)随宿主条目进入客户端模块表(dsh.client.platform=web)。
+# 隧道表存自有文件 ~/.dsh/dsh-tunnel/tunnels.json; 设置偏好(侧边栏开关/超时)经宿主 settings 服务。
+
+- insert:
+    - id: dsh-tunnel
+      name: '@mzzsfy/dsh-tunnel'

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@mzzsfy/dsh-tunnel",
+  "description": "路径穿透隧道:在 dsh 宿主进程内把 /p/<name> 反向代理到本地 TCP 端口(HTTP strip 转发 + 声明式 WS upgrade + 3xx Location 单头改写),支持 <name>.* 子域名全路径透传(任意 WS 路径);GUI 看板手动管理隧道,设置页独立配置节与侧边栏注入开关;向 ai 注册 tunnel_open/tunnel_list/tunnel_close 工具且「允许 ai 使用」可开关(关闭即注销);代理逻辑全在插件进程内,不引入 nginx/caddy 等外部反代",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "npmPublish": "npm publish --access public --provenance=false --registry=https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mzzsfy/dsh-plugin.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": ">=3.18.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.5-rc.2"
+  },
+  "files": [
+    "src",
+    "test",
+    "cordis.patch.yml",
+    "README.md"
+  ]
+}

package/src/api.mjs

@@ -0,0 +1,116 @@
+// api: REST 路由 /api/tunnel/*。宿主 webServer 仅支持 exact/prefix 注册,
+// 本插件注册一条 prefix, handler 内按 method + 路径段表驱动分发(:name 路径段捕获);
+// 隧道增删改查直通宿主半区 tunnelsApi(open/list/close 同一入口, 与 ai 工具面同表);
+// 错误语义对齐仓内惯例: 业务错误中文透传, 系统级错误收敛固定文案并落服务端日志。
+
+const BODY_MAX_BYTES = 64 * 1024
+
+export const ROUTE_PREFIX = '/api/tunnel'
+
+export const MESSAGES = {
+  notFound: '接口不存在',
+  badJsonBody: '请求体不是合法 JSON',
+  bodyTooLarge: '请求体超过上限',
+  systemError: '操作失败(系统级错误, 详见服务端日志)',
+}
+
+function sendJson(res, status, payload) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(payload))
+}
+
+function respondError(res, error, logSystem) {
+  const isSystem = Boolean(error && typeof error.code === 'string' && error.code !== '')
+  if (isSystem && logSystem) logSystem(String(error && error.stack || error))
+  const message = isSystem ? MESSAGES.systemError : (error && error.message ? error.message : String(error))
+  sendJson(res, 400, { error: message })
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > BODY_MAX_BYTES) {
+        reject(new Error(MESSAGES.bodyTooLarge))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+async function readJsonBody(req) {
+  let body
+  try {
+    body = JSON.parse(await readBody(req))
+  } catch (error) {
+    if (error && error.message === MESSAGES.bodyTooLarge) throw error
+    throw new Error(MESSAGES.badJsonBody)
+  }
+  return body && typeof body === 'object' ? body : {}
+}
+
+// readUi/updateUi: 设置读写在宿主半区(settings 服务语义归属 index.js), 此处仅路由
+export function createApi({ tunnelsApi, readUi, updateUi, logSystem }) {
+  const routes = [
+    { method: 'GET', segments: ['tunnels'], handler: () => ({ items: tunnelsApi.list().tunnels }) },
+    { method: 'POST', segments: ['tunnels'], handler: ({ body }) => {
+      const outcome = tunnelsApi.open(body)
+      if (!outcome.ok) throw new Error(outcome.error)
+      return outcome
+    } },
+    { method: 'DELETE', segments: ['tunnels', ':name'], handler: ({ params }) => tunnelsApi.close({ name: params.name }) },
+    { method: 'GET', segments: ['status'], handler: () => ({ ui: readUi(), total: tunnelsApi.list().tunnels.length }) },
+    { method: 'POST', segments: ['ui-settings'], handler: ({ body }) => updateUi(body) },
+  ]
+
+  function matchRoute(method, segments) {
+    for (const route of routes) {
+      if (route.method !== method || route.segments.length !== segments.length) continue
+      const params = {}
+      let matched = true
+      for (let i = 0; i < segments.length && matched; i++) {
+        const expected = route.segments[i]
+        if (expected.startsWith(':')) {
+          try {
+            params[expected.slice(1)] = decodeURIComponent(segments[i])
+          } catch {
+            matched = false
+          }
+        } else matched = expected === segments[i]
+      }
+      if (matched) return { route, params }
+    }
+    return null
+  }
+
+  return {
+    async handle(req, res) {
+      const url = new URL(req.url, 'http://localhost')
+      const pathname = url.pathname.startsWith(ROUTE_PREFIX + '/')
+        ? url.pathname.slice(ROUTE_PREFIX.length)
+        : url.pathname === ROUTE_PREFIX ? '/' : null
+      if (pathname === null) {
+        sendJson(res, 404, { error: MESSAGES.notFound })
+        return
+      }
+      const segments = pathname.split('/').filter(Boolean)
+      try {
+        const matched = matchRoute(req.method, segments)
+        if (!matched) {
+          sendJson(res, 404, { error: MESSAGES.notFound })
+          return
+        }
+        const body = req.method === 'POST' ? await readJsonBody(req) : undefined
+        sendJson(res, 200, await matched.route.handler({ req, res, url, params: matched.params, body }))
+      } catch (error) {
+        respondError(res, error, logSystem)
+      }
+    },
+  }
+}