[api] implement endpoints per openapi.yaml #8
Loading…
Reference in a new issue
No description provided.
Delete branch "agent/api"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Closes #1 — fulfills the
[agent] apibrief indocs/TASKS.md.What changed
Scope:
crates/rgxr-api/+ new top-levelmigrations/(nothing else;Cargo.lockupdated only from the new deps declared insidecrates/rgxr-api/Cargo.toml).DATABASE_URLneeded at build), tokio, tracing, uuid v7. New deps (sqlx,tower-http,chrono; dev:tower,http-body-util) are declared in my crate's[dependencies]with explicit versions, rootCargo.tomluntouched.migrations/0001_automata.sql(repo root, as briefed):automatatable +automata_owner_updated_at_idxindex. Embedded withsqlx::migrate!("../../migrations"), applied on startup; if the DB isn't reachable yet (compose/k8s cold start) a background task retries with backoff so a pod that boots before postgres self-heals.src/identity.rs): readsRemote-User/Remote-Name/Remote-Email/Remote-Groups(comma-separated), implementsFromRequestParts<AppState>so handlers stay clean. Missing header → 401 envelope in prod,anonymousfallback whenRGXR_DEV_MODE=true. Empty/whitespace header values are treated as missing.src/automata.rs):GET/POST /api/v1/automata,GET/PUT/DELETE /api/v1/automata/{id}, fully real against Postgres. Every query is scoped toRemote-User; a foreign row is indistinguishable from a missing one (404). Ids are app-side uuid v7 (time-ordered, index-friendly); the DDL defaultgen_random_uuid()remains as fallback.layoutis opaque JSONB passthrough, never parsed (contract)./run,/render,/ops/*,/regex/*): deserialize strictly, validate FAs withrgxr_core::Fa::validate(FaError→ 400invalid_fa, regex variant →invalid_regex), then return 501internal/"engine pending — see core PR"(see decisions). Each handler is a thin call-site with the exactrgxr_core/rgxr_renderone-liner commented in place./readyz: realSELECT 1against the pool with a 2 s timeout →200 {status: ok, db: ok}/503 {status: unavailable, db: down};200 {status: ok, db: unconfigured}whenDATABASE_URLis unset./healthzunchanged (ok).openapi.yamlbyte-for-byte at/api-docs/openapi.json(include_str!from repo root viaCARGO_MANIFEST_DIR) plus a minimal Scalar UI page at/api-docs(CDN script, spec loaded from the endpoint above). No utoipa — the file is the only source of truth.RGXR_DEV_MODE=true, anAllowOrigin::listallowlist forhttp://localhost:5173(+ methods/headers incl. theRemote-*set for direct dev calls). Prod = same-origin behind the proxy, no CORS layer at all. Verified: matching origin gets ACAO, foreign origin gets none.ApiJson<T>extractor maps serde rejections (malformed body, unknown fields, bad types) to400 invalid_request; unknown routes fall through to the envelope-shaped 404. Panic-free: workspace lints inherited, nounwrap/expectoutside#[cfg(test)](crate-root exemption atsrc/main.rs).Gate results
47 tests total, 40 in
rgxr-api: identity extractor (dev/prod/empty-header/groups parsing),FaError→envelope mapping (invalid_favsinvalid_regex, 501 shape), name validation (unicode-aware 1..=200), engine cardinality + latex-gate rules, SavedData strictness, camelCase wire shapes, plus router-level probe tests (401, dev fallback, 501, 400s, 500-without-db, openapi serving).Beyond unit tests, smoke-tested the built binary against a throwaway
postgres:17-alpinecontainer: migrations apply, create/list/get/put/delete round-trip,bobgets 404 onalice's row, readyz flips ok→unconfigured→(down) with the DB's lifecycle, prod mode returns the 401 envelope, CORS verified as above.Semantic decisions
internal(interim, as briefed): the frozenErrorCodeenum has nonot_implementedvariant, so the envelope usesinternalwhile the status is 501. Swapping in the real engine later is a one-line change per handler (call-site left as a comment); the 501s disappear then.POST /renderwithengine=latexreturns503 render_unavailablewhenRGXR_LATEX_ENABLEDis unset/false — that behavior is fully specified in openapi.yaml and deployable without the engine, so I implemented it instead of returning 501 for a request the deployment has already ruled out.engine=fast(and the default) → 501 like the rest.{id}path segments → 404, not 400: the documented response set forGET/DELETE /automata/{id}has no 400, and an id that isn't a uuid cannot exist for any user. (PUT documents 400, but only for body problems — a malformed id still yields 404.)/readyzwith unsetDATABASE_URL→ 200{ok, unconfigured}(matching the pre-existing bootstrap behavior):unconfigured≠down; the k8s probe only fails when a configured DB is unreachable.internalwith a clear message ("database not configured (DATABASE_URL is unset)"): the service still boots so probes/engine routes//api-docswork in local no-DB dev; there is no documented 503 for these endpoints.400 invalid_request;Fa::validatefailures are400 invalid_fa(regex parse →invalid_regex). The strict-schema rule (unknown fields rejected) applies to my input types (SavedData,AutomatonInput, all engine request bodies) in addition to the already-frozenFa.Fa::validateon POST/PUT: an editor mid-edit must be able to save a transiently invalid automaton (the brief mandates engine-side validation only). The storedfais deserialized strictly (shape/type/unknown-field errors are 400), but structural validation is deliberately left to the engine endpoints./api-docs/openapi.jsonserves the YAML bytes as-is withContent-Type: application/yaml— the file's own header comment specifies "serves it as-is"; Scalar and Swagger UI both parse YAML specs regardless of the.jsonextension.Remote-*header trust: exactly per contract — no extra hardening (e.g. stripping inbound headers) since the proxy is the only path to the pod; noted here so infra can double-check Traefik doesn't forward client-suppliedRemote-*headers.No blockers. The only cross-agent follow-up: once the core PR lands, the commented call-sites in
src/engine.rsget swapped in and the 501s go away (separate small PR).