62 lines
2.2 KiB
Markdown
62 lines
2.2 KiB
Markdown
# HTTP Route Patterns
|
|
|
|
Current guidance for `packages/opencode/src/server/routes/instance/httpapi`.
|
|
|
|
## Handler Shape
|
|
|
|
Use `HttpApiBuilder.group(...)` for normal JSON and streaming HTTP API
|
|
endpoints. Yield stable services once while building the handler layer,
|
|
then close over those services in endpoint implementations.
|
|
|
|
```ts
|
|
export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session", (handlers) =>
|
|
Effect.gen(function* () {
|
|
const session = yield* Session.Service
|
|
|
|
return handlers.handle("list", () => session.list())
|
|
}),
|
|
)
|
|
```
|
|
|
|
Use raw `HttpRouter` only for routes that do not fit the request/response
|
|
HttpApi model, such as WebSocket upgrades or catch-all fallback routes.
|
|
|
|
Do not rebuild stable layers inside request handlers. Provide stable
|
|
services at the route/layer boundary and use request-level provisioning
|
|
only for request-derived context.
|
|
|
|
## Error Boundaries
|
|
|
|
Expected service errors should be mapped at the handler boundary to
|
|
endpoint-declared public HTTP errors. Keep one-off mappings inline. Extract
|
|
small helpers when the same mapping repeats.
|
|
|
|
Generic middleware should not become a domain-error mapper. It should
|
|
handle cross-cutting concerns and final unknown-defect fallback.
|
|
|
|
Public JSON errors should be explicit schema contracts declared on each
|
|
endpoint or group. Built-in `HttpApiError.*` is fine only when its generated
|
|
body is intentionally the public wire shape.
|
|
|
|
Preserve existing `{ name, data }` error bodies until a deliberate breaking
|
|
API change.
|
|
|
|
## OpenAPI Compatibility
|
|
|
|
`public.ts` still owns SDK/OpenAPI compatibility transforms. Shrink those
|
|
transforms by tightening source schemas one workaround at a time.
|
|
|
|
When an OpenAPI-visible source schema changes:
|
|
|
|
- verify the generated SDK diff is intentional
|
|
- preserve legacy compatibility unless the PR explicitly changes it
|
|
- prefer source-schema fixes over new post-processing rules
|
|
|
|
## Checklist For Route PRs
|
|
|
|
- [ ] Stable services are yielded at handler-layer construction.
|
|
- [ ] Expected domain errors are translated at the route boundary.
|
|
- [ ] Endpoint/group error schemas describe the public body and status.
|
|
- [ ] Middleware does not gain new domain-specific name checks.
|
|
- [ ] Raw routes are used only when HttpApi is the wrong abstraction.
|