openAgent

1# HTTP Route Patterns
2 
3Current guidance for `packages/opencode/src/server/routes/instance/httpapi`.
4 
5## Handler Shape
6 
7Use `HttpApiBuilder.group(...)` for normal JSON and streaming HTTP API
8endpoints. Yield stable services once while building the handler layer,
9then close over those services in endpoint implementations.
10 
11```ts
12export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session", (handlers) =>
13  Effect.gen(function* () {
14    const session = yield* Session.Service
15 
16    return handlers.handle("list", () => session.list())
17  }),
18)
19```
20 
21Use raw `HttpRouter` only for routes that do not fit the request/response
22HttpApi model, such as WebSocket upgrades or catch-all fallback routes.
23 
24Do not rebuild stable layers inside request handlers. Provide stable
25services at the route/layer boundary and use request-level provisioning
26only for request-derived context.
27 
28## Error Boundaries
29 
30Expected service errors should be mapped at the handler boundary to
31endpoint-declared public HTTP errors. Keep one-off mappings inline. Extract
32small helpers when the same mapping repeats.
33 
34Generic middleware should not become a domain-error mapper. It should
35handle cross-cutting concerns and final unknown-defect fallback.
36 
37Public JSON errors should be explicit schema contracts declared on each
38endpoint or group. Built-in `HttpApiError.*` is fine only when its generated
39body is intentionally the public wire shape.
40 
41Preserve existing `{ name, data }` error bodies until a deliberate breaking
42API change.
43 
44## OpenAPI Compatibility
45 
46`public.ts` still owns SDK/OpenAPI compatibility transforms. Shrink those
47transforms by tightening source schemas one workaround at a time.
48 
49When an OpenAPI-visible source schema changes:
50 
51- verify the generated SDK diff is intentional
52- preserve legacy compatibility unless the PR explicitly changes it
53- prefer source-schema fixes over new post-processing rules
54 
55## Checklist For Route PRs
56 
57- [ ] Stable services are yielded at handler-layer construction.
58- [ ] Expected domain errors are translated at the route boundary.
59- [ ] Endpoint/group error schemas describe the public body and status.
60- [ ] Middleware does not gain new domain-specific name checks.
61- [ ] Raw routes are used only when HttpApi is the wrong abstraction.
62