：Effect 類型化路由樹、SSE 流與 WebSocket 升級的正確寫法)
opencode HttpApi 路由模式實戰(zhàn)Effect 類型化路由樹、SSE 流與 WebSocket 升級的正確寫法【免費下載鏈接】opencodeThe open source coding agent.項目地址: https://gitcode.com/GitHub_Trending/openc/opencode本文基于 opencode 倉庫中packages/opencode實例 HTTP 服務的內部路由規(guī)范AGENTS.md展開講清楚該項目如何基于 Effect 的HttpApiBuilder組織類型化路由樹普通 JSON 端點、SSE 流式端點、WebSocket 升級路由分別應該用哪套 API 寫法中間件、錯誤契約與依賴注入應該放在哪一層。讀完本篇你可以直接按照倉庫既有風格為 opencode 新增一個 HttpApi 端點并理解 server.ts 中整棵路由樹是如何組裝、鑒權并對外提供 OpenAPI 文檔的。一、總覽三層路由寫法及其適用邊界規(guī)范文件 AGENTS.md 給出的核心規(guī)則可以概括為一張“寫法選擇表”路由類型推薦寫法倉庫實例普通 HTTP 端點含 SSE 流式響應HttpApiBuilder.group(...)handlers/session.ts、handlers/event.ts需要原始請求/響應體的聲明式端點如 WebSocket 升級HttpApiBuilder.group(...)內使用handleRaw(...)handlers/pty.ts聲明式 API 面之外的路由如 UI 兜底路由原生HttpRouter.use(...)server.ts 中的uiRoute這套分層的意義在于只要端點在“聲明式 API 面”內它的中間件、路由上下文與 OpenAPI 元數(shù)據(jù)就能掛在同一棵類型化路由樹上只有真正脫離 API 面的路由才允許退化為原始HttpRouter。目錄結構上規(guī)范所指的代碼位于 packages/opencode/src/server/routes/instance/httpapi 下分為groups/端點契約聲明、handlers/端點實現(xiàn)、middleware/中間件契約與實現(xiàn)以及api.ts/server.ts組裝邊界四個部分正好對應規(guī)范中“聲明、實現(xiàn)、中間件、組裝”四個位置。二、普通端點HttpApiBuilder.group中一次性取出穩(wěn)定服務規(guī)范的第一條要求構建 handler 層時把穩(wěn)定服務一次性yield*出來然后在各端點實現(xiàn)中閉包引用它們而不是在每個請求回調里反復構造依賴。規(guī)范給出的最小范例export const sessionHandlers HttpApiBuilder.group(InstanceHttpApi, session, (handlers) Effect.gen(function* () { const session yield* Session.Service return handlers.handle(list, () session.list()) }), )倉庫中真實的 sessionHandlers 是這一模式的完整體現(xiàn)export const sessionHandlers HttpApiBuilder.group(InstanceHttpApi, session, (handlers) Effect.gen(function* () { const session yield* Session.Service const shareSvc yield* SessionShare.Service const promptSvc yield* SessionPrompt.Service const revertSvc yield* SessionRevert.Service // ...共 12 個穩(wěn)定服務一次取出 const scope yield* Scope.Scope const list Effect.fn(SessionHttpApi.list)(function* (ctx: { query: typeof ListQuery.Type }) { const directory ctx.query.directory ? yield* InstanceState.directory : undefined return yield* session.list({ directory: ctx.query.scope project ? undefined : directory, scope: ctx.query.scope, // ... }) }) // ... }), )幾個值得注意的實現(xiàn)細節(jié)每個端點實現(xiàn)都用Effect.fn(SessionHttpApi.xxx)包一層帶上了帶作用域的函數(shù)名。從源碼結構看這是為了在 Effect 追蹤/日志中區(qū)分各端點的執(zhí)行軌跡端點入?yún)tx的字段params/query/payload由組聲明端的 Schema 決定實現(xiàn)處直接得到解碼后的類型例如typeof ListQuery.Type錯誤轉換發(fā)生在 handler 邊界如 session-errors.ts 中把存儲層的 NotFound 領域錯誤映射為ApiError聲明的錯誤類型而不是讓領域服務感知 HTTP。三、SSE 流式端點留在group內用HttpServerResponse.stream返回規(guī)范明確要求SSE 端點不要改走原始路由仍然留在HttpApiBuilder.group(...)內由 handler 返回HttpServerResponse.stream(...)同時在端點契約上用HttpApiSchema.asText({ contentType: text/event-stream })標注成功 Schema讓 OpenAPI 正確記錄流的 Content-Type。opencode 的事件訂閱端點/event是標準實現(xiàn)。契約聲明見 groups/event.tsHttpApiEndpoint.get(subscribe, /event, { query: WorkspaceRoutingQuery, success: Schema.String.pipe(HttpApiSchema.asText({ contentType: text/event-stream })), }) .annotateMerge(OpenApi.annotations({ identifier: event.subscribe, summary: Subscribe to events, description: Get events, }))對應 handler 在 handlers/event.ts 中通過handleRaw(subscribe, ...)實現(xiàn)核心響應構造過程是先注冊監(jiān)聽再開始發(fā)射Queue.unbounded接收EventV2Bridge的事件events.listen(...)是急切注冊保證監(jiān)聽注冊到 HTTP 響應體 fiber 啟動之間不會丟事件按實例過濾流按event.location.directory instance.directory且 workspace 匹配過濾再合并一條server.instance.disposed的終止流Stream.takeUntil到 disposed 事件為止心跳?；蠲?10 秒發(fā)一個server.heartbeat事件首幀為server.connected編碼為 SSE 并掛響應頭Stream.pipeThroughChannel(Sse.encode())之后以contentType: text/event-stream返回并附加Cache-Control: no-cache, no-transform、X-Accel-Buffering: no關閉 nginx 類代理的緩沖、X-Content-Type-Options: nosniff。這正是規(guī)范中“SSE 留在聲明式路由樹內、用asText標注流內容類型”兩條規(guī)則的完整落地。四、WebSocket 升級handleRaw保留類型化路由樹規(guī)范指出聲明式端點如果需要原始請求或響應典型即 WebSocket 升級用HttpApiBuilder.group(...)配handleRaw(...)。這樣端點的中間件、路由上下文和 OpenAPI 元數(shù)據(jù)仍然掛在同一棵類型化路由樹上。規(guī)范給的范例與倉庫實現(xiàn)高度一致。groups/pty.ts 中聲明了一個獨立的PtyConnectApiconnect端點掛在/pty/:ptyID/connect上并掛了三組中間件InstanceContextMiddleware、WorkspaceRoutingMiddleware和專門的PtyConnectAuthorizationexport const PtyConnectApi HttpApi.make(pty-connect).add( HttpApiGroup.make(pty-connect) .add( HttpApiEndpoint.get(connect, PtyPaths.connect, { params: Params, success: described(Schema.Boolean, Connected session), error: [HttpApiError.Forbidden, HttpApiError.NotFound], }).annotateMerge(OpenApi.annotations({ identifier: pty.connect, summary: Connect to PTY session, description: Establish a WebSocket connection to interact with a pseudo-terminal (PTY) session in real-time., // transform: 手工補齊 directory/workspace/cursor/ticket 查詢參數(shù) // 因為這些參數(shù)是在 raw handler 里解碼的 transform: (operation) ({ ... }), })), ) .middleware(InstanceContextMiddleware) .middleware(WorkspaceRoutingMiddleware) .middleware(PtyConnectAuthorization), )注意一個工程細節(jié)因為 raw handler 里先檢查 PTY 是否存在再解碼查詢參數(shù)為了保持“不存在先返回空 404”的既有響應順序這些查詢字段沒有聲明進端點 Schema而是通過 OpenAPI 注解的transform回調手工補進文檔。注釋里明確寫了這一取舍是閱讀 raw 端點契約時的關鍵線索。實現(xiàn)側 ptyConnectHandlers 展示了 raw handler 的完整能力面從ctx.request取查詢參數(shù)中的 PTY 連接 ticket經tickets.consume(...)校驗一次性票據(jù)非法時返回空 403 響應yield* Effect.orDie(ctx.request.upgrade)拿到 WebSocket 句柄進入真正的 socket 讀寫出站幀回放幀、實時數(shù)據(jù)、關閉幀統(tǒng)一進一個Queue.unbounded由單個 drain writer 順序寫出保證重放與實時輸出的順序一致用Effect.race并行跑讀attachment.write與寫drain任一側結束即整體結束并ensuring(attachment.detach())確保 PTY 附著一定釋放。五、原始HttpRouter.use只用于 API 面之外的路由規(guī)范的第四條原始HttpRouter.use(...)只允許用于聲明式 API 面之外的路由例如兜底 UI 路由。server.ts 用一段注釋把整棵路由樹說得很清楚// Route tree: // - rootApiRoutes: typed /global/* and control routes; auth is declared by RootHttpApi. // - eventApiRoutes: typed SSE route with instance routing context and its existing API contract. // - ptyConnectApiRoutes: typed WebSocket upgrade route with ticket-aware auth. // - instanceApiRoutes: remaining typed instance routes. // - uiRoute: raw catch-all fallback; auth is router middleware so public static assets can bypass it.其中真正用到原始HttpRouter.use的只有兩個/doc延遲構造 OpenAPI JSON 響應見下文與uiRoute*, /*兜底服務內嵌 Web UI。uiRoute特意用 router 級中間件做鑒權正是為了讓公開靜態(tài)資源可以繞過認證——這是規(guī)范中“raw 路由配 router 中間件”說法的直接對應。/doc路由還體現(xiàn)了“穩(wěn)定層一次性提供”的性能意識源碼注釋原文// OpenApi.fromApi is non-trivial; defer until /doc is actually hit so // processes that never serve it (CLI, scripts) dont pay at module load. const docResponse lazy(() HttpServerResponse.jsonUnsafe(OpenApi.fromApi(PublicApi)))OpenAPI 文檔只在首次命中/doc時惰性生成且序列化后的響應被緩存復用避免每個請求重新JSON.stringify。六、依賴注入紀律層提供一次而不是每請求重建規(guī)范對 Layer 使用有兩條明確的“避免”規(guī)則倉庫代碼是它們的注腳規(guī)則 1避免在請求 handler 或 raw 路由回調內部執(zhí)行Effect.provide(SomeLayer)。穩(wěn)定層應在應用/層邊界提供一次而不是每請求重建或按請求做作用域化。反面教材式的反例在規(guī)范里被直接點名正面做法可見server.ts的組裝段所有穩(wěn)定服務Session、Pty、Provider等約 50 個LayerNode先在app組中聲明再由createRoutes在Layer.provide(...)鏈上一次性提供handler 內部只yield*服務、不提供層。規(guī)則 2避免HttpRouter.provideRequest(...)除非依賴天然是請求級的。穩(wěn)定的應用服務應走HttpRouter.use(...)。規(guī)則 3Effect.provideService(...)在中間件里只用于“由請求推導出的上下文”例如WorkspaceRouteContext派生出的InstanceRef、WorkspaceRef不要拿它把穩(wěn)定服務偷偷塞進請求 effect。倉庫中 middleware/instance-context.ts 就是規(guī)范中“請求派生上下文”的標準寫法function provideInstanceContextE( effect: Effect.EffectHttpServerResponse.HttpServerResponse, E, store: InstanceStore.Interface, ): Effect.EffectHttpServerResponse.HttpServerResponse, E, WorkspaceRouteContext { return Effect.gen(function* () { const route yield* WorkspaceRouteContext const ctx yield* store.load({ directory: decode(route.directory) }) return yield* effect.pipe( Effect.provideService(InstanceRef, ctx), Effect.provideService(WorkspaceRef, route.workspaceID), ) }) }這里provideService提供的是InstanceRef/WorkspaceRef兩個從路由目錄/workspace 參數(shù)推導出來的上下文完全符合規(guī)范第 35 行的限定而InstanceStore.Service本身是穩(wěn)定服務是在instanceContextLayer構建時yield*出來的沒有混進請求 effect。七、公開 JSON 錯誤顯式的Schema.ErrorClass契約規(guī)范最后一段對錯誤契約的表述是全套規(guī)范中最容易被忽視、也最影響 SDK 兼容性的部分每個端點的公開 JSON 錯誤都應該是顯式聲明在端點上的Schema.ErrorClass契約僅當“空/tagged body 就是期望的線上形態(tài)”時才使用內置HttpApiError.*如HttpApiError.BadRequest這類無字段體對 SDK 可見、需要攜帶message的錯誤要定義專用 API 錯誤 Schema規(guī)范點名了ApiNotFoundError這類命名并以聲明的那個精確錯誤失敗領域服務與存儲服務必須保持不含 HttpApi 類型預期領域錯誤在handler 邊界翻譯為 API 錯誤。倉庫的 errors.ts 就是這套契約的集中定義全部用Schema.TaggedErrorClass生成、并綁定httpApiStatusexport class SessionNotFoundError extends Schema.TaggedErrorClassSessionNotFoundError()( SessionNotFoundError, { sessionID: Schema.String, message: Schema.String, }, { httpApiStatus: 404 }, ) {} export class PtyNotFoundError extends Schema.TaggedErrorClassPtyNotFoundError()( PtyNotFoundError, { ptyID: Schema.String, message: Schema.String }, { httpApiStatus: 404 }, ) {} // 另有 InvalidRequestError(400)、UnauthorizedError(401)、ForbiddenError(403)、 // ConflictError(409)、UpstreamError(502)、ServiceUnavailableError(503)、 // TimeoutError(504)、UnknownError(500) 等端點側的用法可在 groups/pty.ts 看到get端點聲明error: PtyNotFoundErrorupdate端點聲明error: [PtyNotFoundError, HttpApiError.BadRequest]connectToken聲明error: [PtyForbiddenError, PtyNotFoundError]。handler 側則在 catch 領域錯誤時翻譯成這些聲明類例如 handlers/pty.tsEffect.catchTag( Pty.NotFoundError, (error) new ApiError.PtyNotFoundError({ ptyID: error.ptyID, message: PTY session not found: ${error.ptyID}, }), )Pty.NotFoundError是領域錯誤PtyNotFoundError是 API 契約錯誤翻譯發(fā)生在 handler 邊界——這正是規(guī)范要求的分層opencode-ai/core下的 Pty 服務不知道任何 HttpApi 類型的存在。八、中間件聲明與提供的正確位置規(guī)范最后一條新增中間件時把“端點契約中間件”聲明在歸屬它的HttpApiGroup上實現(xiàn)層則在server.ts的組裝邊界提供router 級中間件只留給真正 raw 的兜底路由或全局傳輸策略。倉庫的對應關系非常清晰聲明端各 group 在自己身上掛中間件。如 groups/event.ts 的HttpApiGroup.make(event).middleware(InstanceContextMiddleware).middleware(WorkspaceRoutingMiddleware).middleware(Authorization)PtyApi/PtyConnectApi同樣在組上聲明見 groups/pty.ts提供端server.ts 按“路由子樹”分塊提供。instanceRoutes統(tǒng)一在實例級路由子樹掛httpApiAuthLayer workspaceRoutingLive instanceContextLayer schemaErrorLayereventApiRoutes與ptyConnectApiRoutes各自在子樹級提供對應層。中間件契約在組上聲明一次實現(xiàn)層在組裝邊界注入一次兩端解耦API 聚合api.ts 展示了契約中間件的另一種聲明位置——根 API 直接在HttpApi.make鏈上掛.middleware(SchemaErrorMiddleware).middleware(Authorization)得到RootHttpApi/global 與控制面路由與InstanceHttpApiconfig、file、instance、mcp、project、pty、question、permission、provider、session、sync、tui、workspace 共 14 個 group最終聚合為OpenCodeHttpApi并追加EventSchema等附加 Schema 供 OpenAPI 引用全局傳輸策略createRoutes返回的層在Layer.mergeAll(六條路由子樹)之上統(tǒng)一Layer.provide了errorLayer、compressionLayer、corsVaryFix、fenceLayer與 CORS 中間件server.tsCORS 甚至以{ global: true }的 router 中間件形式提供maxAge: 86_400——這正對應規(guī)范“router 中間件留給全局傳輸策略”的定位。server.ts末尾還有一處值得注意的組裝順序注釋Observability.layer必須放在 provide 鏈的最后“Must stay last”因為 Effect 中后 provide 的層構建在更底層過早提供會讓急切 fork 的 fiber 捕獲默認 stdout logger 從而污染 TUI引用了 issue #34730。這說明規(guī)范中“穩(wěn)定層在應用邊界提供”不只是風格要求也直接影響可觀測性正確性。九、小結新增一個 HttpApi 端點的標準流程綜合規(guī)范與源碼在 opencode 中新增端點可以按以下清單執(zhí)行定契約在groups/對應文件中用HttpApiGroup.make(...).add(HttpApiEndpoint.method(...))聲明端點配OpenApi.annotationsidentifier/summary/descriptionSSE 端點的 success Schema 用HttpApiSchema.asText({ contentType: text/event-stream })標注錯誤字段填 errors.ts 中已聲明的TaggedErrorClass缺失則新增并綁定httpApiStatus定中間件把端點契約中間件聲明在歸屬 group 上參照InstanceContextMiddleware/WorkspaceRoutingMiddleware/Authorization的三層組合實現(xiàn)層留到server.ts組裝寫 handler在handlers/對應文件中用HttpApiBuilder.group(InstanceHttpApi, name, ...)包裹開頭yield*全部穩(wěn)定服務端點實現(xiàn)里只做參數(shù)解碼后的業(yè)務編排與領域錯誤翻譯需要原始請求/響應socket 升級等才用handleRaw掛路由樹在api.ts把 group 并入InstanceHttpApi或獨立HttpApi.make參照PtyConnectApi的做法并在server.ts的對應子樹instanceApiRoutes/ 新子樹中Layer.providehandler 層與中間件實現(xiàn)層自檢紀律handler 內不Effect.provide(SomeLayer)中間件內provideService只注入請求派生上下文領域服務保持零 HttpApi 依賴/doc的 OpenAPI 文檔會自動反映新端點。遵循這套模式新端點天然獲得類型化的參數(shù)/響應校驗、統(tǒng)一的鑒權與實例上下文注入、顯式的錯誤契約以及無需額外維護的 OpenAPI 文檔——這也是該目錄路由代碼在規(guī)模上14 個實例級 group 事件流 PTY WebSocket仍能保持可組裝、可測試的根本原因?！久赓M下載鏈接】opencodeThe open source coding agent.項目地址: https://gitcode.com/GitHub_Trending/openc/opencode創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 opencode HttpApi 路由模式實戰(zhàn)：Effect 類型化路由樹、SSE 流與 WebSocket 升級的正確寫法
opencode HttpApi 路由模式實戰(zhàn)Effect 類型化路由樹、SSE 流與 WebSocket 升級的正確寫法【免費下載鏈接】opencodeThe open source coding agent.項目地址: https://gitcode.com/GitHub_Trending/openc/opencode本文基于 opencode 倉庫中packages/opencode實例 HTTP 服務的內部路由規(guī)范AGENTS.md展開講清楚該項目如何基于 Effect 的HttpApiBuilder組織類型化路由樹普通 JSON 端點、SSE 流式端點、WebSocket 升級路由分別應該用哪套 API 寫法中間件、錯誤契約與依賴注入應該放在哪一層。讀完本篇你可以直接按照倉庫既有風格為 opencode 新增一個 HttpApi 端點并理解 server.ts 中整棵路由樹是如何組裝、鑒權并對外提供 OpenAPI 文檔的。一、總覽三層路由寫法及其適用邊界規(guī)范文件 AGENTS.md 給出的核心規(guī)則可以概括為一張“寫法選擇表”路由類型推薦寫法倉庫實例普通 HTTP 端點含 SSE 流式響應HttpApiBuilder.group(...)handlers/session.ts、handlers/event.ts需要原始請求/響應體的聲明式端點如 WebSocket 升級HttpApiBuilder.group(...)內使用handleRaw(...)handlers/pty.ts聲明式 API 面之外的路由如 UI 兜底路由原生HttpRouter.use(...)server.ts 中的uiRoute這套分層的意義在于只要端點在“聲明式 API 面”內它的中間件、路由上下文與 OpenAPI 元數(shù)據(jù)就能掛在同一棵類型化路由樹上只有真正脫離 API 面的路由才允許退化為原始HttpRouter。目錄結構上規(guī)范所指的代碼位于 packages/opencode/src/server/routes/instance/httpapi 下分為groups/端點契約聲明、handlers/端點實現(xiàn)、middleware/中間件契約與實現(xiàn)以及api.ts/server.ts組裝邊界四個部分正好對應規(guī)范中“聲明、實現(xiàn)、中間件、組裝”四個位置。二、普通端點HttpApiBuilder.group中一次性取出穩(wěn)定服務規(guī)范的第一條要求構建 handler 層時把穩(wěn)定服務一次性yield*出來然后在各端點實現(xiàn)中閉包引用它們而不是在每個請求回調里反復構造依賴。規(guī)范給出的最小范例export const sessionHandlers HttpApiBuilder.group(InstanceHttpApi, session, (handlers) Effect.gen(function* () { const session yield* Session.Service return handlers.handle(list, () session.list()) }), )倉庫中真實的 sessionHandlers 是這一模式的完整體現(xiàn)export const sessionHandlers HttpApiBuilder.group(InstanceHttpApi, session, (handlers) Effect.gen(function* () { const session yield* Session.Service const shareSvc yield* SessionShare.Service const promptSvc yield* SessionPrompt.Service const revertSvc yield* SessionRevert.Service // ...共 12 個穩(wěn)定服務一次取出 const scope yield* Scope.Scope const list Effect.fn(SessionHttpApi.list)(function* (ctx: { query: typeof ListQuery.Type }) { const directory ctx.query.directory ? yield* InstanceState.directory : undefined return yield* session.list({ directory: ctx.query.scope project ? undefined : directory, scope: ctx.query.scope, // ... }) }) // ... }), )幾個值得注意的實現(xiàn)細節(jié)每個端點實現(xiàn)都用Effect.fn(SessionHttpApi.xxx)包一層帶上了帶作用域的函數(shù)名。從源碼結構看這是為了在 Effect 追蹤/日志中區(qū)分各端點的執(zhí)行軌跡端點入?yún)tx的字段params/query/payload由組聲明端的 Schema 決定實現(xiàn)處直接得到解碼后的類型例如typeof ListQuery.Type錯誤轉換發(fā)生在 handler 邊界如 session-errors.ts 中把存儲層的 NotFound 領域錯誤映射為ApiError聲明的錯誤類型而不是讓領域服務感知 HTTP。三、SSE 流式端點留在group內用HttpServerResponse.stream返回規(guī)范明確要求SSE 端點不要改走原始路由仍然留在HttpApiBuilder.group(...)內由 handler 返回HttpServerResponse.stream(...)同時在端點契約上用HttpApiSchema.asText({ contentType: text/event-stream })標注成功 Schema讓 OpenAPI 正確記錄流的 Content-Type。opencode 的事件訂閱端點/event是標準實現(xiàn)。契約聲明見 groups/event.tsHttpApiEndpoint.get(subscribe, /event, { query: WorkspaceRoutingQuery, success: Schema.String.pipe(HttpApiSchema.asText({ contentType: text/event-stream })), }) .annotateMerge(OpenApi.annotations({ identifier: event.subscribe, summary: Subscribe to events, description: Get events, }))對應 handler 在 handlers/event.ts 中通過handleRaw(subscribe, ...)實現(xiàn)核心響應構造過程是先注冊監(jiān)聽再開始發(fā)射Queue.unbounded接收EventV2Bridge的事件events.listen(...)是急切注冊保證監(jiān)聽注冊到 HTTP 響應體 fiber 啟動之間不會丟事件按實例過濾流按event.location.directory instance.directory且 workspace 匹配過濾再合并一條server.instance.disposed的終止流Stream.takeUntil到 disposed 事件為止心跳?；蠲?10 秒發(fā)一個server.heartbeat事件首幀為server.connected編碼為 SSE 并掛響應頭Stream.pipeThroughChannel(Sse.encode())之后以contentType: text/event-stream返回并附加Cache-Control: no-cache, no-transform、X-Accel-Buffering: no關閉 nginx 類代理的緩沖、X-Content-Type-Options: nosniff。這正是規(guī)范中“SSE 留在聲明式路由樹內、用asText標注流內容類型”兩條規(guī)則的完整落地。四、WebSocket 升級handleRaw保留類型化路由樹規(guī)范指出聲明式端點如果需要原始請求或響應典型即 WebSocket 升級用HttpApiBuilder.group(...)配handleRaw(...)。這樣端點的中間件、路由上下文和 OpenAPI 元數(shù)據(jù)仍然掛在同一棵類型化路由樹上。規(guī)范給的范例與倉庫實現(xiàn)高度一致。groups/pty.ts 中聲明了一個獨立的PtyConnectApiconnect端點掛在/pty/:ptyID/connect上并掛了三組中間件InstanceContextMiddleware、WorkspaceRoutingMiddleware和專門的PtyConnectAuthorizationexport const PtyConnectApi HttpApi.make(pty-connect).add( HttpApiGroup.make(pty-connect) .add( HttpApiEndpoint.get(connect, PtyPaths.connect, { params: Params, success: described(Schema.Boolean, Connected session), error: [HttpApiError.Forbidden, HttpApiError.NotFound], }).annotateMerge(OpenApi.annotations({ identifier: pty.connect, summary: Connect to PTY session, description: Establish a WebSocket connection to interact with a pseudo-terminal (PTY) session in real-time., // transform: 手工補齊 directory/workspace/cursor/ticket 查詢參數(shù) // 因為這些參數(shù)是在 raw handler 里解碼的 transform: (operation) ({ ... }), })), ) .middleware(InstanceContextMiddleware) .middleware(WorkspaceRoutingMiddleware) .middleware(PtyConnectAuthorization), )注意一個工程細節(jié)因為 raw handler 里先檢查 PTY 是否存在再解碼查詢參數(shù)為了保持“不存在先返回空 404”的既有響應順序這些查詢字段沒有聲明進端點 Schema而是通過 OpenAPI 注解的transform回調手工補進文檔。注釋里明確寫了這一取舍是閱讀 raw 端點契約時的關鍵線索。實現(xiàn)側 ptyConnectHandlers 展示了 raw handler 的完整能力面從ctx.request取查詢參數(shù)中的 PTY 連接 ticket經tickets.consume(...)校驗一次性票據(jù)非法時返回空 403 響應yield* Effect.orDie(ctx.request.upgrade)拿到 WebSocket 句柄進入真正的 socket 讀寫出站幀回放幀、實時數(shù)據(jù)、關閉幀統(tǒng)一進一個Queue.unbounded由單個 drain writer 順序寫出保證重放與實時輸出的順序一致用Effect.race并行跑讀attachment.write與寫drain任一側結束即整體結束并ensuring(attachment.detach())確保 PTY 附著一定釋放。五、原始HttpRouter.use只用于 API 面之外的路由規(guī)范的第四條原始HttpRouter.use(...)只允許用于聲明式 API 面之外的路由例如兜底 UI 路由。server.ts 用一段注釋把整棵路由樹說得很清楚// Route tree: // - rootApiRoutes: typed /global/* and control routes; auth is declared by RootHttpApi. // - eventApiRoutes: typed SSE route with instance routing context and its existing API contract. // - ptyConnectApiRoutes: typed WebSocket upgrade route with ticket-aware auth. // - instanceApiRoutes: remaining typed instance routes. // - uiRoute: raw catch-all fallback; auth is router middleware so public static assets can bypass it.其中真正用到原始HttpRouter.use的只有兩個/doc延遲構造 OpenAPI JSON 響應見下文與uiRoute*, /*兜底服務內嵌 Web UI。uiRoute特意用 router 級中間件做鑒權正是為了讓公開靜態(tài)資源可以繞過認證——這是規(guī)范中“raw 路由配 router 中間件”說法的直接對應。/doc路由還體現(xiàn)了“穩(wěn)定層一次性提供”的性能意識源碼注釋原文// OpenApi.fromApi is non-trivial; defer until /doc is actually hit so // processes that never serve it (CLI, scripts) dont pay at module load. const docResponse lazy(() HttpServerResponse.jsonUnsafe(OpenApi.fromApi(PublicApi)))OpenAPI 文檔只在首次命中/doc時惰性生成且序列化后的響應被緩存復用避免每個請求重新JSON.stringify。六、依賴注入紀律層提供一次而不是每請求重建規(guī)范對 Layer 使用有兩條明確的“避免”規(guī)則倉庫代碼是它們的注腳規(guī)則 1避免在請求 handler 或 raw 路由回調內部執(zhí)行Effect.provide(SomeLayer)。穩(wěn)定層應在應用/層邊界提供一次而不是每請求重建或按請求做作用域化。反面教材式的反例在規(guī)范里被直接點名正面做法可見server.ts的組裝段所有穩(wěn)定服務Session、Pty、Provider等約 50 個LayerNode先在app組中聲明再由createRoutes在Layer.provide(...)鏈上一次性提供handler 內部只yield*服務、不提供層。規(guī)則 2避免HttpRouter.provideRequest(...)除非依賴天然是請求級的。穩(wěn)定的應用服務應走HttpRouter.use(...)。規(guī)則 3Effect.provideService(...)在中間件里只用于“由請求推導出的上下文”例如WorkspaceRouteContext派生出的InstanceRef、WorkspaceRef不要拿它把穩(wěn)定服務偷偷塞進請求 effect。倉庫中 middleware/instance-context.ts 就是規(guī)范中“請求派生上下文”的標準寫法function provideInstanceContextE( effect: Effect.EffectHttpServerResponse.HttpServerResponse, E, store: InstanceStore.Interface, ): Effect.EffectHttpServerResponse.HttpServerResponse, E, WorkspaceRouteContext { return Effect.gen(function* () { const route yield* WorkspaceRouteContext const ctx yield* store.load({ directory: decode(route.directory) }) return yield* effect.pipe( Effect.provideService(InstanceRef, ctx), Effect.provideService(WorkspaceRef, route.workspaceID), ) }) }這里provideService提供的是InstanceRef/WorkspaceRef兩個從路由目錄/workspace 參數(shù)推導出來的上下文完全符合規(guī)范第 35 行的限定而InstanceStore.Service本身是穩(wěn)定服務是在instanceContextLayer構建時yield*出來的沒有混進請求 effect。七、公開 JSON 錯誤顯式的Schema.ErrorClass契約規(guī)范最后一段對錯誤契約的表述是全套規(guī)范中最容易被忽視、也最影響 SDK 兼容性的部分每個端點的公開 JSON 錯誤都應該是顯式聲明在端點上的Schema.ErrorClass契約僅當“空/tagged body 就是期望的線上形態(tài)”時才使用內置HttpApiError.*如HttpApiError.BadRequest這類無字段體對 SDK 可見、需要攜帶message的錯誤要定義專用 API 錯誤 Schema規(guī)范點名了ApiNotFoundError這類命名并以聲明的那個精確錯誤失敗領域服務與存儲服務必須保持不含 HttpApi 類型預期領域錯誤在handler 邊界翻譯為 API 錯誤。倉庫的 errors.ts 就是這套契約的集中定義全部用Schema.TaggedErrorClass生成、并綁定httpApiStatusexport class SessionNotFoundError extends Schema.TaggedErrorClassSessionNotFoundError()( SessionNotFoundError, { sessionID: Schema.String, message: Schema.String, }, { httpApiStatus: 404 }, ) {} export class PtyNotFoundError extends Schema.TaggedErrorClassPtyNotFoundError()( PtyNotFoundError, { ptyID: Schema.String, message: Schema.String }, { httpApiStatus: 404 }, ) {} // 另有 InvalidRequestError(400)、UnauthorizedError(401)、ForbiddenError(403)、 // ConflictError(409)、UpstreamError(502)、ServiceUnavailableError(503)、 // TimeoutError(504)、UnknownError(500) 等端點側的用法可在 groups/pty.ts 看到get端點聲明error: PtyNotFoundErrorupdate端點聲明error: [PtyNotFoundError, HttpApiError.BadRequest]connectToken聲明error: [PtyForbiddenError, PtyNotFoundError]。handler 側則在 catch 領域錯誤時翻譯成這些聲明類例如 handlers/pty.tsEffect.catchTag( Pty.NotFoundError, (error) new ApiError.PtyNotFoundError({ ptyID: error.ptyID, message: PTY session not found: ${error.ptyID}, }), )Pty.NotFoundError是領域錯誤PtyNotFoundError是 API 契約錯誤翻譯發(fā)生在 handler 邊界——這正是規(guī)范要求的分層opencode-ai/core下的 Pty 服務不知道任何 HttpApi 類型的存在。八、中間件聲明與提供的正確位置規(guī)范最后一條新增中間件時把“端點契約中間件”聲明在歸屬它的HttpApiGroup上實現(xiàn)層則在server.ts的組裝邊界提供router 級中間件只留給真正 raw 的兜底路由或全局傳輸策略。倉庫的對應關系非常清晰聲明端各 group 在自己身上掛中間件。如 groups/event.ts 的HttpApiGroup.make(event).middleware(InstanceContextMiddleware).middleware(WorkspaceRoutingMiddleware).middleware(Authorization)PtyApi/PtyConnectApi同樣在組上聲明見 groups/pty.ts提供端server.ts 按“路由子樹”分塊提供。instanceRoutes統(tǒng)一在實例級路由子樹掛httpApiAuthLayer workspaceRoutingLive instanceContextLayer schemaErrorLayereventApiRoutes與ptyConnectApiRoutes各自在子樹級提供對應層。中間件契約在組上聲明一次實現(xiàn)層在組裝邊界注入一次兩端解耦API 聚合api.ts 展示了契約中間件的另一種聲明位置——根 API 直接在HttpApi.make鏈上掛.middleware(SchemaErrorMiddleware).middleware(Authorization)得到RootHttpApi/global 與控制面路由與InstanceHttpApiconfig、file、instance、mcp、project、pty、question、permission、provider、session、sync、tui、workspace 共 14 個 group最終聚合為OpenCodeHttpApi并追加EventSchema等附加 Schema 供 OpenAPI 引用全局傳輸策略createRoutes返回的層在Layer.mergeAll(六條路由子樹)之上統(tǒng)一Layer.provide了errorLayer、compressionLayer、corsVaryFix、fenceLayer與 CORS 中間件server.tsCORS 甚至以{ global: true }的 router 中間件形式提供maxAge: 86_400——這正對應規(guī)范“router 中間件留給全局傳輸策略”的定位。server.ts末尾還有一處值得注意的組裝順序注釋Observability.layer必須放在 provide 鏈的最后“Must stay last”因為 Effect 中后 provide 的層構建在更底層過早提供會讓急切 fork 的 fiber 捕獲默認 stdout logger 從而污染 TUI引用了 issue #34730。這說明規(guī)范中“穩(wěn)定層在應用邊界提供”不只是風格要求也直接影響可觀測性正確性。九、小結新增一個 HttpApi 端點的標準流程綜合規(guī)范與源碼在 opencode 中新增端點可以按以下清單執(zhí)行定契約在groups/對應文件中用HttpApiGroup.make(...).add(HttpApiEndpoint.method(...))聲明端點配OpenApi.annotationsidentifier/summary/descriptionSSE 端點的 success Schema 用HttpApiSchema.asText({ contentType: text/event-stream })標注錯誤字段填 errors.ts 中已聲明的TaggedErrorClass缺失則新增并綁定httpApiStatus定中間件把端點契約中間件聲明在歸屬 group 上參照InstanceContextMiddleware/WorkspaceRoutingMiddleware/Authorization的三層組合實現(xiàn)層留到server.ts組裝寫 handler在handlers/對應文件中用HttpApiBuilder.group(InstanceHttpApi, name, ...)包裹開頭yield*全部穩(wěn)定服務端點實現(xiàn)里只做參數(shù)解碼后的業(yè)務編排與領域錯誤翻譯需要原始請求/響應socket 升級等才用handleRaw掛路由樹在api.ts把 group 并入InstanceHttpApi或獨立HttpApi.make參照PtyConnectApi的做法并在server.ts的對應子樹instanceApiRoutes/ 新子樹中Layer.providehandler 層與中間件實現(xiàn)層自檢紀律handler 內不Effect.provide(SomeLayer)中間件內provideService只注入請求派生上下文領域服務保持零 HttpApi 依賴/doc的 OpenAPI 文檔會自動反映新端點。遵循這套模式新端點天然獲得類型化的參數(shù)/響應校驗、統(tǒng)一的鑒權與實例上下文注入、顯式的錯誤契約以及無需額外維護的 OpenAPI 文檔——這也是該目錄路由代碼在規(guī)模上14 個實例級 group 事件流 PTY WebSocket仍能保持可組裝、可測試的根本原因?！久赓M下載鏈接】opencodeThe open source coding agent.項目地址: https://gitcode.com/GitHub_Trending/openc/opencode創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考