4.5 KiB
@deepseek-ai/dsh-host-webserver
English | 中文
Web HTTP 与 upgrade route 注册插件（默认导出 WebServer，配置为 {host, port, compression?, compressionLevel?, compressionThresholdBytes?}）：一个在激活时开始监听的 node:http 服务器，提供 ctx.webServer。register(route) 添加具名的 exact／prefix HTTP route；registerUpgrade(route) 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为 route 模式是组合层约定，冲突即配置错误；两者返回的 disposer 都会移除注册。registerFallback(handler) 注册一个 handler，处理所有未被具名 route 命中的请求。第二次注册会抛错；随附的 SPA dist 服务器 dsh-host-frontend-static 是该 handler 的所有者，没有注册 handler 时服务器返回 404。index 的启动输入是结构化行：collectIndexInjections() 每次调用经一次 webserver/index-inject emit 现收一张全新的 IndexInjection 表，renderIndex(html) 先把行渲染进 index.html 响应体，再按注册顺序应用原始的 tapIndex(transform) 转换（applyIndexTaps(html)，行无法表达的标记的逃生口）；script-preload 行渲染为 classic script 的提示性预加载链接。fallback handler 在每次 index 响应时调用 renderIndex，静态部署则把同一批行经 boot 载荷下发。port 读取正在监听的端口（当 port 为 0 时读取 OS 分配的值），host 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给 fallback handler。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不影响请求处理。
compression: 'gzip' 会包装基于 socket 的 HTTP 响应，而不改变 route API。客户端必须偏好 gzip，且媒体类型必须可压缩；已知长度低于 compressionThresholdBytes 的响应保持 identity，未知长度的 stream 则直接具备压缩资格。compressionLevel 控制 DEFLATE 强度。已有内容编码、Cache-Control: no-transform、范围响应、SSE、ZIP 与打包后的 .gz Worker 镜像均保持原样。随附的 Web 组合启用 level 1 和 1024 字节阈值；其他组合默认使用 compression: 'none'。Web Worker 隧道不携带浏览器管理的 Accept-Encoding 请求头，因此其合成响应仍为 identity 字节。
该包不了解任何 harness 概念，也不提供任何文件服务：/api HTTP 桥接与下行 WebSocket 是 connection 插件的 route，插件 bundle 与 HMR（热模块替换）事件流是 modules／hmr 插件的 route，dist 服务则属于 fallback 持有者。upgrade handler 拥有协议握手与连接内容；webserver 只交付原始 socket 与 request。host 只接受 127.0.0.1（默认安全姿态）和 0.0.0.0（有意向网络开放）。该服务器只服务浏览器；Electron 通过 file:// 加载 dist，并经 IPC 桥接承载 fetch。该包从不打印内容；URL 行属于 shell。
监听失败（EADDRINUSE……）会从激活过程抛出，并以绑定诊断信息拒绝 Loader 组合；失败的候选 fiber 会被 dispose（资源释放）。处理 HTTP 请求时抛错（例如 fallback 持有者的 decodeURIComponent 收到格式错误的百分号转义，或客户端在请求体传输中途断开）时，服务器会响应 400；若响应头已经发出，则销毁 socket，并记录 warning，但绝不会退出进程。upgrade handler 抛错或升级 socket 出现传输错误时，会记录 warning 并销毁对应 socket。资源释放会启动 close() 与 closeAllConnections()，销毁所有受跟踪的升级 socket，并仅在 HTTP server 与这些 socket 均已关闭后返回。
模型体验
无。该包只是浏览器与其他插件所注册 HTTP／upgrade route 之间的 Web 载体，其中没有任何内容会进入模型请求。
KV Cache 影响
无；该包既不组装也不发送提供方请求。
已知限制与暂缓事项
- 不提供 TLS、认证或来源策略：绑定非回环地址会向对应网络公开服务器；面向部署的加固措施（或在前方放置真正的反向代理）有意不纳入这台开发服务器。
- Socket 选项固定不变：配置只选择绑定宿主与端口；在具体部署产生需求前，backlog 和其他 socket 设置仍保持内部实现。