T3 Code HTTP边界实现详解http、ws、CORS与响应错误防护如何配合的完整指南【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3codeT3 Code 是一款面向开发者的 AI 编程协作工具它的本地服务端构建在HTTP 边界之上http.ts 负责路由与静态资源安全、ws.ts 承载 WebSocket RPC 实时通道、httpCors.ts 统一管理 CORS 跨域配置、httpResponseErrorGuard.ts 则守护响应写错误防止单个断连客户端拖垮整个服务进程。本文带你快速看懂这四者如何协同工作。一、HTTP 边界全景四个模块各管一摊 T3 Code 的服务端apps/server/把对外通信拆成了清晰的四层职责模块文件职责HTTP 路由与安全头http.ts路由装配、静态资源防穿越、下载安全头、CORS 层WebSocket RPCws.ts/ws升级鉴权、实时事件流、命令分发CORS 配置httpCors.ts允许的方法、请求头白名单响应错误防护httpResponseErrorGuard.ts兜底 socket 写错误避免进程崩溃二、http.ts路由中枢与安全响应头这是 HTTP 边界的核心文件几个值得新手重点关注的实现1. 静态资源路径防穿越staticAndDevRouteLayerhttp.ts在服务端托管 Web 界面时做了多重防线规范化相对路径、拒绝..前缀、拒绝空字节、并要求最终路径必须落在静态根目录内isWithinStaticRoot检查非法请求统一返回 400。无扩展名的路径还会自动回退到index.html支持前端路由。2. 下载与 SVG 的 CSP 防护assetResponseHeadershttp.ts为附件下载附加X-Content-Type-Options: nosniff和沙箱化 CSP对可能被代理剥离 disposition 头的危险类型如text/html、XML 系强制降级为application/octet-stream防止内容被当作文档渲染。3. 压缩与 CORS 两个全局中间件httpCompressionLayer → HttpMiddleware.compression()全局生效 browserApiCorsLayer → HttpRouter.cors(...)按环境动态配置见 http.ts开发模式下允许 Vite 开发源与 Electron 自定义源t3code://app、t3code-dev://app并携带凭证打包后的桌面端则回退到 Effect 的默认通配源。预检结果缓存 600 秒减少重复 preflight 开销。4. 开发模式回环重定向isLoopbackHostname与resolveDevRedirectUrlhttp.ts让本地访问自动 302 重定向到 Vite 开发服务器同时保留原始路径、查询与 hash。三、ws.tsWebSocket RPC 实时通道websocketRpcRouteLayerws.ts把GET /ws注册为路由流程是升级鉴权authenticateWebSocketUpgrade校验凭证失败时直接返回EnvironmentAuthInvalidError对应的 HTTP 响应而不是留下一个半开连接客户端归因从升级 URL 读取clientSurface、clientAppVersion等参数readClientConnectionOrigin宽松解析——归因元数据异常不会让连接失败RPC 会话RpcServer.toHttpEffectWebsocket建立 JSON 序列化的 RPC 分组每个方法都经过requiredScopeForRpcMethod做作用域鉴权再叠加可观测性埋点连接生命周期acquireUseRelease确保连接建立与断开时正确markConnected/markDisconnected供后台策略等模块感知在线客户端。事件侧还有精细的工程考量SHELL_RESUME_MAX_GAP/THREAD_RESUME_MAX_GAPws.ts限制断线重放的游标差距超过阈值直接下发全新快照避免旧游标回放数十万条事件导致内存溢出。四、httpCors.ts最小化的跨域白名单CORS 配置被刻意收窄只有三个方法、五个请求头httpCors.ts允许方法GET、POST、OPTIONS允许头authorization、b3、traceparent、content-type、dpop其中traceparent/b3用于分布式追踪透传dpop是客户端凭证DPoP的令牌绑定头。这种白名单式配置比通配*头安全得多也方便审计哪些跨域请求能真正到达服务。五、httpResponseErrorGuard.ts一个客户端断开不该杀死整个服务这是最容易被忽略、却最关键的一块。文件头部的注释httpResponseErrorGuard.ts解释了问题本质Node 会把 socket 的后期写失败EPIPE、ECONNRESET、ERR_STREAM_DESTROYED以error事件抛出。没有监听器的error事件会升级为未捕获异常直接终止整个服务进程——所有其他客户端和进行中的 AI 会话工作都会陪葬。需要兜底的是两个裸露的发射源Upgrade socket连接升级后WebSocket RPC 路径Node http server 会剥离自己的 socket 错误处理直到 WebSocket 层接管前处于无监听状态Server response响应流同样没有默认的错误监听器。guardHttpResponseWriteErrorshttpResponseErrorGuard.ts只需两行核心逻辑就同时覆盖了request的 response 与upgrade的 socketserver.on(request, (_request, response) { response.on(error, (error) { onError?.(error); }); }); server.on(upgrade, (_request, socket) { socket.on(error, (error) { onError?.(error); }); });断连客户端只会影响自己的请求——请求 fiber 早已随 response 的close事件被中断写入失败只需要被观察到即可。对应的回归测试在 httpResponseErrorGuard.test.ts。六、装配现场server.ts 中的分层组合各模块在 server.ts 中通过 Effect 的 Layer 体系拼合路由层server.tsmakeRoutesLayer合并 HTTP API 路由、OTLP 追踪代理、资源路由、附件上传、静态路由与websocketRpcRouteLayer再依次提供commandReadinessLayer命令就绪前排队、browserApiCorsLayer与httpCompressionLayer服务器层server.ts运行时自动选择 Bun 或 Node 平台Node 路径下正是guardHttpResponseWriteErrors(NodeHttp.createServer())包裹原生 serverWebSocket 启用perMessageDeflate帧压缩Bun 下采用 dedicated 压缩器 shared 解压器规避上游解压器对合法 DEFLATE 输入中断连接的问题。两条传输共用同一套服务实例因此 WebSocket 上的变更能即时让 HTTP 侧读到的缓存失效多客户端看到一致状态。七、总结一条请求的完整旅程 请求进入 →错误防护层已预先为 response/upgrade socket 挂好监听CORS 中间件判定来源必要时放行并附预检头压缩中间件统一处理编码路由分发静态资源走防穿越检查/ws走升级鉴权进入 RPC 会话API 走 HttpApi 分组鉴权响应写出即使用户此时断网error事件也有监听器兜底——进程安然无恙其他会话不受影响。核心文件速查HTTP 路由与安全头apps/server/src/http.tsWebSocket RPCapps/server/src/ws.tsCORS 白名单apps/server/src/httpCors.ts响应错误防护apps/server/src/httpResponseErrorGuard.ts装配与启动apps/server/src/server.ts运行架构总览docs/internals/overview.md【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 T3 Code HTTP边界实现详解：http、ws、CORS与响应错误防护如何配合的完整指南
T3 Code HTTP边界实现详解http、ws、CORS与响应错误防护如何配合的完整指南【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3codeT3 Code 是一款面向开发者的 AI 编程协作工具它的本地服务端构建在HTTP 边界之上http.ts 负责路由与静态资源安全、ws.ts 承载 WebSocket RPC 实时通道、httpCors.ts 统一管理 CORS 跨域配置、httpResponseErrorGuard.ts 则守护响应写错误防止单个断连客户端拖垮整个服务进程。本文带你快速看懂这四者如何协同工作。一、HTTP 边界全景四个模块各管一摊 T3 Code 的服务端apps/server/把对外通信拆成了清晰的四层职责模块文件职责HTTP 路由与安全头http.ts路由装配、静态资源防穿越、下载安全头、CORS 层WebSocket RPCws.ts/ws升级鉴权、实时事件流、命令分发CORS 配置httpCors.ts允许的方法、请求头白名单响应错误防护httpResponseErrorGuard.ts兜底 socket 写错误避免进程崩溃二、http.ts路由中枢与安全响应头这是 HTTP 边界的核心文件几个值得新手重点关注的实现1. 静态资源路径防穿越staticAndDevRouteLayerhttp.ts在服务端托管 Web 界面时做了多重防线规范化相对路径、拒绝..前缀、拒绝空字节、并要求最终路径必须落在静态根目录内isWithinStaticRoot检查非法请求统一返回 400。无扩展名的路径还会自动回退到index.html支持前端路由。2. 下载与 SVG 的 CSP 防护assetResponseHeadershttp.ts为附件下载附加X-Content-Type-Options: nosniff和沙箱化 CSP对可能被代理剥离 disposition 头的危险类型如text/html、XML 系强制降级为application/octet-stream防止内容被当作文档渲染。3. 压缩与 CORS 两个全局中间件httpCompressionLayer → HttpMiddleware.compression()全局生效 browserApiCorsLayer → HttpRouter.cors(...)按环境动态配置见 http.ts开发模式下允许 Vite 开发源与 Electron 自定义源t3code://app、t3code-dev://app并携带凭证打包后的桌面端则回退到 Effect 的默认通配源。预检结果缓存 600 秒减少重复 preflight 开销。4. 开发模式回环重定向isLoopbackHostname与resolveDevRedirectUrlhttp.ts让本地访问自动 302 重定向到 Vite 开发服务器同时保留原始路径、查询与 hash。三、ws.tsWebSocket RPC 实时通道websocketRpcRouteLayerws.ts把GET /ws注册为路由流程是升级鉴权authenticateWebSocketUpgrade校验凭证失败时直接返回EnvironmentAuthInvalidError对应的 HTTP 响应而不是留下一个半开连接客户端归因从升级 URL 读取clientSurface、clientAppVersion等参数readClientConnectionOrigin宽松解析——归因元数据异常不会让连接失败RPC 会话RpcServer.toHttpEffectWebsocket建立 JSON 序列化的 RPC 分组每个方法都经过requiredScopeForRpcMethod做作用域鉴权再叠加可观测性埋点连接生命周期acquireUseRelease确保连接建立与断开时正确markConnected/markDisconnected供后台策略等模块感知在线客户端。事件侧还有精细的工程考量SHELL_RESUME_MAX_GAP/THREAD_RESUME_MAX_GAPws.ts限制断线重放的游标差距超过阈值直接下发全新快照避免旧游标回放数十万条事件导致内存溢出。四、httpCors.ts最小化的跨域白名单CORS 配置被刻意收窄只有三个方法、五个请求头httpCors.ts允许方法GET、POST、OPTIONS允许头authorization、b3、traceparent、content-type、dpop其中traceparent/b3用于分布式追踪透传dpop是客户端凭证DPoP的令牌绑定头。这种白名单式配置比通配*头安全得多也方便审计哪些跨域请求能真正到达服务。五、httpResponseErrorGuard.ts一个客户端断开不该杀死整个服务这是最容易被忽略、却最关键的一块。文件头部的注释httpResponseErrorGuard.ts解释了问题本质Node 会把 socket 的后期写失败EPIPE、ECONNRESET、ERR_STREAM_DESTROYED以error事件抛出。没有监听器的error事件会升级为未捕获异常直接终止整个服务进程——所有其他客户端和进行中的 AI 会话工作都会陪葬。需要兜底的是两个裸露的发射源Upgrade socket连接升级后WebSocket RPC 路径Node http server 会剥离自己的 socket 错误处理直到 WebSocket 层接管前处于无监听状态Server response响应流同样没有默认的错误监听器。guardHttpResponseWriteErrorshttpResponseErrorGuard.ts只需两行核心逻辑就同时覆盖了request的 response 与upgrade的 socketserver.on(request, (_request, response) { response.on(error, (error) { onError?.(error); }); }); server.on(upgrade, (_request, socket) { socket.on(error, (error) { onError?.(error); }); });断连客户端只会影响自己的请求——请求 fiber 早已随 response 的close事件被中断写入失败只需要被观察到即可。对应的回归测试在 httpResponseErrorGuard.test.ts。六、装配现场server.ts 中的分层组合各模块在 server.ts 中通过 Effect 的 Layer 体系拼合路由层server.tsmakeRoutesLayer合并 HTTP API 路由、OTLP 追踪代理、资源路由、附件上传、静态路由与websocketRpcRouteLayer再依次提供commandReadinessLayer命令就绪前排队、browserApiCorsLayer与httpCompressionLayer服务器层server.ts运行时自动选择 Bun 或 Node 平台Node 路径下正是guardHttpResponseWriteErrors(NodeHttp.createServer())包裹原生 serverWebSocket 启用perMessageDeflate帧压缩Bun 下采用 dedicated 压缩器 shared 解压器规避上游解压器对合法 DEFLATE 输入中断连接的问题。两条传输共用同一套服务实例因此 WebSocket 上的变更能即时让 HTTP 侧读到的缓存失效多客户端看到一致状态。七、总结一条请求的完整旅程 请求进入 →错误防护层已预先为 response/upgrade socket 挂好监听CORS 中间件判定来源必要时放行并附预检头压缩中间件统一处理编码路由分发静态资源走防穿越检查/ws走升级鉴权进入 RPC 会话API 走 HttpApi 分组鉴权响应写出即使用户此时断网error事件也有监听器兜底——进程安然无恙其他会话不受影响。核心文件速查HTTP 路由与安全头apps/server/src/http.tsWebSocket RPCapps/server/src/ws.tsCORS 白名单apps/server/src/httpCors.ts响应错误防护apps/server/src/httpResponseErrorGuard.ts装配与启动apps/server/src/server.ts运行架构总览docs/internals/overview.md【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考