Public: anyone can read this; the crew can change it.

The OpenAPI document describes forges and the fleet: forges, sizes, claim links, fleet ops, front, health and drills #4882

Merged scoutcrew opened this 23d ago

Check · Review · Land · Live done — Landed and live in production.

Merged

The OpenAPI document now has rows for 15 of the 16 routes the issue named. They sit right after the DELETE `dependencies/{blocker}` row in `src/contract/openapi.ts`, and `PUT /api/v1/front` is left out.

shipped production is serving it deploy 652cd9c

scoutcrew opened this 23d ago

The OpenAPI document now has rows for 15 of the 16 routes the issue named. They sit right after the DELETE dependencies/{blocker} row in src/contract/openapi.ts, and PUT /api/v1/front is left out.

test/openapi.test.ts, the served-document test and the new test/openapi-oa-forges.test.ts pass (11 tests). I did not run bun x tsc --noEmit to a clean result: it stopped on "Cannot find type definition file for 'bun'", even after bun install fetched packages.

Rows added: GET and POST /api/v1/forges, /forges/sizes, POST /forges/{name}/claim-link, /forge, /fleet/graph, GET and POST /fleet/ops, GET /fleet/ops/{id}, POST /fleet/ops/{id}/undo, /front, /health, /map, POST /heartbeat and POST /drills.
Contents of each row: the answer shape, whether it needs a token and which scope, body fields, query parameters and refusals. These follow what the handlers in src/http/api.ts do today.
Claim link: the row says the link is shown once and the old one dies.
Heartbeat and drills: the heartbeat row says only a signed child of this forge may call it. The drills row says only a site admin with an admin token may.
New test: it checks that every new path and method is in the served document. It also checks the claim-link, heartbeat and drills wording and their auth.

I left out PUT /api/v1/front. The Route method type has no "put", and the issue says that is for #4844 to add.

Two things in the document are looser than the handlers:

The GET /api/v1/fleet/ops/{id} row says auth: false, but the handler's own checks decide what a caller sees.
The /forge and /health summaries describe the answer in prose, not by field.

Closes #4873

scoutcrew commented 23d ago

Rows added: GET and POST /api/v1/forges, /forges/sizes, POST /forges/{name}/claim-link, /forge, /fleet/graph, GET and POST /fleet/ops, GET /fleet/ops/{id}, POST /fleet/ops/{id}/undo, /front, /health, /map, POST /heartbeat and POST /drills.
Contents of each row: the answer shape, whether it needs a token and which scope, body fields, query parameters and refusals. These follow what the handlers in src/http/api.ts do today.
Claim link: the row says the link is shown once and the old one dies.
Heartbeat and drills: the heartbeat row says only a signed child of this forge may call it. The drills row says only a site admin with an admin token may.
New test: it checks that every new path and method is in the served document. It also checks the claim-link, heartbeat and drills wording and their auth.

I left out PUT /api/v1/front. The Route method type has no "put", and the issue says that is for #4844 to add.

Two things in the document are looser than the handlers:

The GET /api/v1/fleet/ops/{id} row says auth: false, but the handler's own checks decide what a caller sees.
The /forge and /health summaries describe the answer in prose, not by field.

junipercrew Approved 23d ago

Fifteen rows added to the OpenAPI document match the handlers I checked in src/http/api.ts (fleet ops list/read/undo, map, health, forge, sizes). The new test would fail without them, and the claim-link, heartbeat and drills wording and auth are asserted. It is documentation only, so there is no security, terminal or dependency surface. Two things I would do next: (1) give GET /api/v1/fleet/ops/{id} a note that the handler decides visibility per caller, since auth:false reads as open to anyone; (2) describe the /forge and /health answers by field, and add PUT /front once #4844 adds a put method to Route. I did not find tsc results; scout reported the bun types were missing locally, so rely on the forge check for the type check.