HTTP Server zh

HTTP 服务器

Edge 用 Cloudflare Workers 的 fetch() 替换了上游的 Node.js HTTP 服务器。

上游参考：HTTP 服务器

上游提供了什么

dsh-host-webserver 是一个 Node.js HTTP 插件，提供 ctx.webServer，支持命名路由注册、index.html 变换和 fallback 处理器。它不属于 agent loop——纯粹的浏览器 HTTP 投递。其他插件注册功能路由，包括 /api 桥接和 HMR 流。

路由匹配顺序固定：精确表优先，然后最长前缀匹配，最后 fallback。复合 /api handler 先分发给 Typert Gateway（@Remote 方法），再降级到 ApiProxy（编排操作）。

Edge 改了什么

替换件 Workers fetch() 替换 Node.js HTTP

DshEdgeInstance.fetch() 替换了上游的 ctx.webServer。请求依次经过 6 个分发点，首个匹配即短路：

#	处理器	协议	URL 示例	状态
1	handleEdgeRemote()	A: Typert	/api/commands/list	⚠️ 手写桩
2	handleTypertRpc()	A: Typert	/api/goals/edit	✅ 自动路由
3	openDownlink()	WebSocket	/api/events.mux	✅
4	apiFetch()	B: apiproxy	/api/session.prompt	⚠️ 重实现
5	parseSessionRoute()	C: Edge REST	/api/sessions/:id/prompt	✅ Edge 自有
6	Assets fallback	静态	/index.html	✅

为什么有三种协议

A: Typert Remote（斜线格式：goals/edit）— cordis Service 的 @Remote 方法，由 TypertGatewayService 自动发现。客户端调用 ctx.remote.goals.edit()。完全上游——Edge 只做 HTTP 到 gateway 的路由。

B: apiproxy（点号格式：session.prompt）— 协调多个 Service 的编排操作。上游提供 ApiProxyService（cordis 插件），但 Edge 因依赖不满足无法安装。Edge 手写了 createEdgeApi()（约 800 行）作为简化替代。这是 Edge 中最大的上游重实现。

C: Edge REST（路径参数：/sessions/:id/...）— 上游通过进程内 apiproxy 调用完成的 session 生命周期操作。Edge 需要单独的 HTTP 端点，因为这些操作跨 Worker → DO 边界。不是新业务逻辑——是两个 Cloudflare 运行时之间的传输桥。

替换件 DO 休眠 API 替换 Node.js WebSocket

Edge 用 DO 休眠 API（WebSocketPair、ctx.acceptWebSocket()、ctx.getWebSockets(channel)）替换 Node.js HTTP upgrade。Socket 按 'mux' / 'host' 标记，可跨 DO 休眠存活。

Edge 没有改什么

• 路由优先级（Typert 在 ApiProxy 之前）、信封格式、双通道推送
• 客户端连接逻辑（33 个客户端插件不变）

性能特征

分发：最多 6 次检查（正则、字符串、前缀）。亚毫秒，实际耗时取决于 handler。

WebSocket 广播：O(已连接客户端)，通常 1–3 个标签。DO 休眠保持 socket 存活无需 isolate 开销。

架构总结

组件	分类	上游对应
Workers fetch()	替换	ctx.webServer
DO 休眠 WebSocket	替换	Node.js HTTP upgrade
Typert 路由	桥接	Connection.rpc.intercept
createEdgeApi()	⚠️ 重实现	ApiProxyService 插件

关键观察：HTTP 服务器是被最彻底替换的上游组件。功能契约保留——相同的路由优先级、信封格式、双通道 WebSocket。客户端无法分辨服务端是 Node.js 还是 Workers。主要设计债是 createEdgeApi()：约 800 行重实现的 apiproxy handler，可以通过满足 ApiProxyService 的依赖来消除。

TODO

TODO: 删除 handleEdgeRemote 桩 — 阻塞于 SkillRegistry 获得 @Remote 装饰器。（#95）

TODO: 用 ApiProxyService 替换 createEdgeApi() — 阻塞于满足 4 个缺失依赖：directoryPicker、subagents、sessionQuery、userQuestions。（#96）