koala73 / koala73/worldmonitor
feat(sites): sebuf SitesService — protos, handlers, gateway, rate policy, OpenAPI
- Dominant language
- TypeScript
- Stars
- 87k
- Forks
- 13.2k
- Avg merge
- 8h 4m
- Merged PRs (30d)
- 825
Description
## Context
`api/api-route-exceptions.json`'s `$comment` is unambiguous: "All new JSON data
APIs MUST use sebuf (proto → buf generate → handler)", enforced by
`scripts/enforce-sebuf-api-contract.mjs` — which also checks the reverse, so a
generated service without a gateway entry fails CI.
## Files
- `proto/worldmonitor/sites/v1/monitored_site.proto`
- `proto/worldmonitor/sites/v1/{list,create,update,delete}_monitored_site.proto`
- `proto/worldmonitor/sites/v1/service.proto`
- `buf generate` → `src/generated/server/worldmonitor/sites/v1/service_server.ts` + client
- `server/worldmonitor/sites/v1/{handler,list-monitored-sites,...}.ts`
- `api/sites/v1/[rpc].ts` gateway
- Route registration + tier in `server/gateway.ts` (pattern at `:218`, `:331`) —
authenticated writes, so **not** `'fast'`
- `ENDPOINT_RATE_POLICIES` entry, or `npm run lint:rate-limit-policies` fails
- `docs/api/SitesService.openapi.{yaml,json}` + the consolidated bundle
## Note
The biome CI job runs the sebuf contract gate — a new `api/` file without a
manifest entry or matching generated service reds the build.
## Sequencing
**Ship the Convex-direct demo slice first** (schema + CRUD + relay join on
weather and aviation only, ~5 days). Let a real partner integration inform the
API shape before committing it to proto. Reversing a published proto contract is
far more expensive than delaying it.
## Acceptance
- [ ] Full CRUD over sebuf with generated client
- [ ] Gateway routes registered with correct tier and rate policy
- [ ] OpenAPI regenerated incl. consolidated bundle
- [ ] Contract gate green
Effort: L (~7d). Mechanical but broad.
Contributor guide
Research direction
Start with the Convex-direct demo slice described in the issue, then inspect the listed proto files, the existing gateway patterns at server/gateway.ts lines 218 and 331, and scripts/enforce-sebuf-api-contract.mjs. Trace the buf generate outputs and the api/sites/v1/[rpc].ts gateway before changing the service shape. Done means CRUD, gateway registration and rate policy, regenerated OpenAPI files and bundle, and a green contract gate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, typescript
- Domain
- api, backend, ci-cd, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100