feat(api): scaffold @gbfm/api with Effect HttpApi health contract#136
Closed
guidefari wants to merge 10 commits into
Closed
feat(api): scaffold @gbfm/api with Effect HttpApi health contract#136guidefari wants to merge 10 commits into
guidefari wants to merge 10 commits into
Conversation
Step 1 of the Hono -> Effect HttpApi migration (docs/migration-effect-http-api.md).
- New leaf workspace package packages/api so server-only code cannot leak
into the www client bundle. Depends only on effect (4.0.0-beta.93).
- Health group contract: live (/health/live), ready (/health/ready), and
check (/health) endpoints with response schemas preserving the current
Hono behavior (live -> { ok: true }, ready/check -> { dbConnected: true }).
- Shared ReadinessCheckFailedError (Schema.TaggedErrorClass, httpApiStatus
500) for the readiness 500 path; first of the Phase 2 error ports.
- Contract unit tests (packages/api) verify endpoint shape, schema decode
rejects, error tagging/encoding, and the typed HttpApiClient interface.
- Behavior-preserving integration test (apps/vps) characterizes the current
Hono health endpoints as a migration safety net (status, body, 5s cache,
rate-limit exclusion) before the serving topology changes in Step 2.
The packages/api contract test duplicated the vps health integration test
at the boundary (e.g. { ok: true } decodes) and the rest was internal-shape
noise (endpoint names, schema internals, error encoding). User-facing
behavior parity belongs at the HTTP boundary, which the vps curl-style
integration test already captures as the migration baseline.
Step 2 will run the same request->response spec against the Effect
HttpApiBuilder server to prove parity without duplicating assertions.
Owner
Author
|
Closing to restart clean. Scope crept past Step 1 (contract-only) into Step 2 territory (serving topology: app.ts, routes.ts, index.ts, runtime/services.ts, sentry, OTel) in the same PR, and the test approach went sideways -- a hand-rolled curl/assertion script (scripts/api-test/health.ts) duplicating what the vitest integration test already covers, instead of just extending that test. Redoing this in smaller, single-purpose check-ins per the revised step breakdown in docs/migration-effect-http-api.md (steps 1a/1b, 2a/2b/2c, 3a/3b, ...). Branch/commits stay around for reference, not deleting anything. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Step 1 of the Hono -> Effect HttpApi migration tracked in `docs/migration-effect-http-api.md` (Migration Order step 1: "Create packages/api with contract for health group — proves the pattern").
What
Why this is safe
No runtime server behavior changes. `apps/vps` does not yet import `@gbfm/api`; nothing serves the new contract. This only establishes the shared contract and a baseline test so the subsequent serving-topology change (Step 2) can be validated against captured behavior.
Verification
Note
`bun precommit` currently fails on a pre-existing `@gbfm/www` typecheck error in `src/lib/spotify-pkce.ts` (9 errors on a clean `prod` checkout, unrelated to this PR). Root-level `bun run typecheck` will surface that independently; it is not introduced here.
Next (out of scope for this PR)
Step 2: wire `HttpRouter.toWebHandler` + Hono wildcard fallback + better-auth route + background forks + shutdown, porting the health handlers to `HttpApiBuilder.group` and validating the serving topology in prod.