zmo-cli/packages/opencode/specs/effect/http-api.md

HttpApi migration

Practical notes for an eventual migration of packages/opencode server routes from the current Hono handlers to Effect HttpApi, either as a full replacement or as a parallel surface.

Goal

Use Effect HttpApi where it gives us a better typed contract for:

• route definition
• request decoding and validation
• typed success and error responses
• OpenAPI generation
• handler composition inside Effect

This should be treated as a later-stage HTTP boundary migration, not a prerequisite for ongoing service, route-handler, or schema work.

Core model

HttpApi is definition-first.

• HttpApi is the root API
• HttpApiGroup groups related endpoints
• HttpApiEndpoint defines a single route and its request / response schemas
• handlers are implemented separately from the contract

This is a better fit once route inputs and outputs are already moving toward Effect Schema-first models.

Why it is relevant here

The current route-effectification work is already pushing handlers toward:

• one AppRuntime.runPromise(Effect.gen(...)) body
• yielding services from context
• using typed Effect errors instead of Promise wrappers

That work is a good prerequisite for HttpApi. Once the handler body is already a composed Effect, the remaining migration is mostly about replacing the Hono route declaration and validator layer.

What HttpApi gives us

Contracts

Request params, query, payload, success payloads, and typed error payloads are declared in one place using Effect Schema.

Validation and decoding

Incoming data is decoded through Effect Schema instead of hand-maintained Zod validators per route.

OpenAPI

HttpApi can derive OpenAPI from the API definition, which overlaps with the current describeRoute(...) and resolver(...) pattern.

Typed errors

Schema.TaggedErrorClass maps naturally to endpoint error contracts.

Likely fit for opencode

Best fit first:

• JSON request / response endpoints
• route groups that already mostly delegate into services
• endpoints whose request and response models can be defined with Effect Schema

Harder / later fit:

• SSE endpoints
• websocket endpoints
• streaming handlers
• routes with heavy Hono-specific middleware assumptions

Current blockers and gaps

Schema split

Many route boundaries still use Zod-first validators. That does not block all experimentation, but full HttpApi adoption is easier after the domain and boundary types are more consistently Schema-first with .zod compatibility only where needed.

Mixed handler styles

Many current server/instance/*.ts handlers still call async facades directly. Migrating those to composed Effect.gen(...) handlers is the low-risk step to do first.

Non-JSON routes

The server currently includes SSE, websocket, and streaming-style endpoints. Those should not be the first HttpApi targets.

Existing Hono integration

The current server composition, middleware, and docs flow are Hono-centered today. That suggests a parallel or incremental adoption plan is safer than a flag day rewrite.

Recommended strategy

1. Finish the prerequisites first

• continue route-handler effectification in server/instance/*.ts
• continue schema migration toward Effect Schema-first DTOs and errors
• keep removing service facades

2. Start with one parallel group

Introduce one small HttpApi group for plain JSON endpoints only. Good initial candidates are the least stateful endpoints in:

• server/instance/question.ts
• server/instance/provider.ts
• server/instance/permission.ts

Avoid session.ts, SSE, websocket, and TUI-facing routes first.

3. Reuse existing services

Do not re-architect business logic during the HTTP migration. HttpApi handlers should call the same Effect services already used by the Hono handlers.

4. Run in parallel before replacing

Prefer mounting an experimental HttpApi surface alongside the existing Hono routes first. That lowers migration risk and lets us compare:

• handler ergonomics
• OpenAPI output
• auth and middleware integration
• test ergonomics

5. Migrate JSON route groups gradually

If the parallel slice works well, migrate additional JSON route groups one at a time. Leave streaming-style endpoints on Hono until there is a clear reason to move them.

Proposed first steps

• add one small spike that defines an HttpApi group for a simple JSON route set
• use Effect Schema request / response types for that slice
• keep the underlying service calls identical to the current handlers
• compare generated OpenAPI against the current Hono/OpenAPI setup
• document how auth, instance lookup, and error mapping would compose in the new stack
• decide after the spike whether HttpApi should stay parallel, replace only some groups, or become the long-term default

Rule of thumb

Do not start with the hardest route file.

If HttpApi is adopted here, it should arrive after the handler body is already Effect-native and after the relevant request / response models have moved to Effect Schema.