koala73 / koala73/worldmonitor

feat(sites): sebuf SitesService — protos, handlers, gateway, rate policy, OpenAPI

Open
#6,632 0 comments 0 reactions 0 assignees View on GitHub
crisis feature P2
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.