18 KiB
WS-G: Generated OpenAPI documentation
Stand-alone workstream, not part of Phase 5. Request: an autogenerated OpenAPI doc for the REST API and the MCP server.
| Field | Value |
|---|---|
| Status | Merged |
| Owner | goose |
| Depends on | Phase 5 routes and tools on main (peer routes are part of the spec) |
| Owned files | src/openapi.rs, src/api/**, src/mcp/**, src/main.rs, src/lib.rs, src/cli.rs, Cargo.toml, tests/openapi.rs, docs/openapi.json, docs/api.md, README.md, config.example.toml, TODO.md is NOT owned (merger ticks) |
Tasks
- G1 REST spec. Add
utoipa(check thatcargo tree -i opensslstays empty). DeriveToSchemaon the response DTOs and annotate every REST handler with#[utoipa::path](systemd, journal, docker, tokens-free endpoints,/healthz,/api/v1/ping, peers status and the peer proxy as one documented wildcardGET /api/v1/peers/{peer}/{path}listing the allowlist). Declare the bearer security scheme. SingleApiDocinsrc/openapi.rs. The peer paths appear only when peers are enabled, matching the real router. - G2 MCP description. MCP is JSON-RPC, so it cannot be modelled as paths. Document
POST /mcp(Streamable HTTP) in the same spec and add a vendor extensionx-mcp-toolslisting every tool with its description and input JSON Schema, generated from the rmcp tool router (the schemars schemas it already holds), not hand-written. Tool count is 8, or 10 with peers; the existing snapshot test must still pass. - G3 Serving and CLI.
GET /api/v1/openapi.jsonbehind the normal auth (no new public route), andslinuxm openapi [--peers]printing the spec offline without starting the server or reading any token. Keep the spec generation in one function shared by both. - G4 Drift guard and docs. Commit the generated
docs/openapi.json(peers on).tests/openapi.rsregenerates it and fails with the regeneration command if it differs; also validates structure (every route in the real router is documented, every tool in the tool router appears inx-mcp-tools, so an undocumented new route or tool fails a test). Updatedocs/api.mdandREADME.mdbriefly.
Rules
Reuse existing DTOs, do not duplicate types for the doc. Read-only, no secrets in the spec or examples. Surfaces call sources/, do not touch D-Bus or Docker from the doc code. Tests in the same commit as the code. No workstream tags in comments.
Log
-
2026-10-20: G1 REST spec.
utoipa6.0.0 (default features, macros included) added toCargo.toml;cargo tree -i opensslis still empty. Every REST handler carries#[utoipa::path]with an explicitoperationId, tag, params and the real response set (200 body plus 400/401/404/405/503ErrorBodywhere they exist); handlers becamepub(crate)so theApiDocderive insrc/openapi.rscan name them. OneApiDocplus onedocument(peers: bool)function; the bearer scheme is declared once (bearer_auth) and applied globally, with/healthzopting out viasecurity(()). Peer paths are dropped whenpeersis false, matching the router (paths.retain). The peer pass-through is documented as one wildcard operationGET /api/v1/peers/{peer}/{path}whose description lists the allowlist.Owned-files conflict with G1 as written. G1 says "derive
ToSchemaon the response DTOs", but those DTOs live insrc/sources/mod.rsandsrc/peers/types.rs, which are not in this workstream's owned files, so no derive could be added there. Resolution, insidesrc/openapi.rsonly: the DTOs already deriveschemars::JsonSchemafor MCP, so a small bridge (reflected<T>()+ aPartialSchema/ToSchemaimpl macro) reflects each component from the schemars schema of the same type. There is exactly one definition per DTO and a field added to a DTO shows up in the spec with no edit here.peer_status_components...-style payloads that exist only as JSON (error body,/healthzand/api/v1/pingbody) or have no schemars derive (PeerStatus,ServerStatus,ApiStatus,AuthStatefromsrc/peers/types.rs) are described by hand with utoipa builders and checked against the JSON the server really emits (error_body_and_health_match_the_real_payloads,peer_status_components_cover_the_serialized_fields), so an added field fails a test instead of vanishing from the document.reflected_schemas_match_schemarsasserts the reflected component equals the schemars output exactly, which pins the converter (object/array/oneOf/anyOf/allOf/format/enum/default/minimum/maximum/required/properties).Translation note for a future merger: if WS-G is ever allowed to touch the DTO files, the derive can replace the bridge for
src/sources/mod.rs; the peer types would still needJsonSchemaadded.Tests: 10 unit tests in
src/openapi.rs(reflection parity, payload parity, peer gating, operation ids and 2xx, bearer scheme, determinism) andtests/openapi.rswith the router drift guard started here (source scan of every.route(...)literal insrc/api/**plussrc/server.rs,/api/v1prefix applied asserver.rsnests it, axum{*path}normalised to OpenAPI{path}, and one request per documented path that must not hit the fallback'sno such route).cargo fmt --check,cargo clippy --all-targets -- -D warningsandcargo testgreen. -
2026-10-20: G2 MCP description. MCP is JSON-RPC, so it is documented as one operation
POST /mcp(declared on a doc-onlymcp_endpoint()insrc/openapi.rs; the real handler is rmcp'sStreamableHttpService, which has no axum handler fn to annotate) with the request body, theapplication/json+text/event-streamresponse, and the 400/401/403/404/406/415 codes rmcp and the auth layer really return.x-mcp-toolsis generated from the tool router itself:TrackerService::advertised_tools(peers)builds the sameToolRouterthatTrackerService::newstores (extracted intorouter_for, so there is one place that applies the peer gating) and returnsname,descriptionandinput_schemafor every tool, sorted, so the extension cannot drift fromtools/list. Tool count stays 8 without peers and 10 with them; the existing peers-off snapshot test is untouched and still passes.Tests:
mcp_endpoint_is_documented_in_both_modesandmcp_extension_lists_tools_sorted_with_schemasinsrc/openapi.rs;mcp_tools_match_the_tool_router(every entry equal to the router's name/description/input schema, both modes),mcp_tool_count_follows_the_peers_flagand the/mcpmount added to the route scan intests/openapi.rs.cargo fmt --check,cargo clippy --all-targets -- -D warningsandcargo testgreen. -
2026-10-20: G3 Serving and CLI.
document(peers)now returns a cachedArc<OpenApi>(oneOnceLockper mode; generation walks every DTO and the whole tool router, and the result cannot change while the process runs), withbuild/to_pretty_jsonbehind it so one function is shared by every consumer.GET /api/v1/openapi.jsonis mounted inapi::router, i.e. under/api/v1and therefore behind the existing auth layer; no new public route, no change toserver::build_routeror/healthz. It serves the mode of the running instance (state.peers.is_some()), so a peer-less instance advertises no peer paths. Newslinuxm openapi [--peers](src/cli.rs,Command::Openapi) prints the pretty document;mainreturns beforeConfig::load, so it needs no config file, no token file and no socket and cannot start a server or bind a port.--print-configstill wins if combined. Thepeers::cliimport inmain.rsis now aliased topeer_clibecausecliis the new module.Tests:
render_is_valid_json_for_both_modes,generation_is_deterministic(bytes, not just values, because the committed file is compared) in the unit tests;openapi_route_is_authenticated_and_serves_the_document(401 without a token, 200 with one, body equals the generated peers-on document,application/json) andcli_prints_the_same_document_offline(real binary,--config /nonexistent/..., both modes, output equals the generated document) intests/openapi.rs. -
2026-10-20: G4 Drift guard and docs.
docs/openapi.jsonis committed (peers on, pretty-printed byslinuxm openapi --peers, 15 paths and 10 tools).tests/openapi.rsnow holds the guards:committed_spec_matches_the_codecompares the file byte for byte withcli::render(true)and prints the regeneration command (cargo run -- openapi --peers > docs/openapi.json) on failure;every_router_route_is_documentedscans every.route(...)literal insrc/api/**andsrc/server.rsplus the/mcpmount and requires each path in the document (verified by adding a throwaway route: the test failed with/api/v1/ping/extra is routed but missing from the OpenAPI document);every_documented_path_is_routedsends one request per documented path through the assembled router and fails if it hits the fallback'sno such route;mcp_tools_match_the_tool_routerrequires every tool of the router inx-mcp-toolswith the same description and input schema (a new or gated-off tool changes the spec and then fails the staleness check);every_operation_is_read_onlykeeps every operation a GET exceptPOST /mcp;operation_ids_and_tags_are_declaredcatches duplicate ids and undeclared tags. A crate version bump changesinfo.version, so it also needs the regeneration in the same commit; that is deliberate (the file is the artifact that is published).Docs:
docs/api.mdgains a "Generated reference (OpenAPI)" section (what the file contains,GET /api/v1/openapi.json,slinuxm openapi [--peers], regeneration, what the tests guard) and a route-table row;README.mdgets a short paragraph in the REST section.config.example.tomlneeds nothing (no new key).docs/README.mddoes not listdocs/openapi.jsonyet; it is outside this workstream's owned files, so the merger should add the row.Verification:
cargo fmt --check,cargo clippy --all-targets -- -D warnings,cargo testgreen (10 tests intests/openapi.rs, 12 unit tests insrc/openapi.rs/src/cli.rs);cargo tree -i opensslempty; the committed spec contains no token, token-file path or URL other than the documented default server. No nix build was run; no VM test is involved in this workstream. -
2026-10-20: G4 self-review fixes. Three accuracy gaps found on a second read: the
ErrorBody.codeenum listed only theAppErrorcodes, but two status-only bodies reuseerror_response(method_not_allowedfrom the 405 fallback,forbidden_hostfrom the auth-off Host guard), so both are now documented andevery_error_code_is_documentedties the enum toAppError::code()plus those two; the dockerlogsand the peer pass-through 200s now declare bothapplication/jsonandtext/event-streaminstead of JSON only;schema_typeno longer maps an unknown JSON Schema type name toobject(it leaves the type out), so the converter cannot invent a type the DTO does not have. Spec regenerated. -
2026-10-20: Handoff (G1 to G4 complete). The REST API and the MCP server are described by one generated OpenAPI 3.1 document.
- G1
utoipa6.0.0;#[utoipa::path]on every handler (explicitoperationIds, tags, parameters and the real status set), bearer scheme declared and applied globally with/healthzopting out, singleApiDoc+document(peers)insrc/openapi.rs. Commitsd21e5e7, plus the ownership-conflict resolution described above: DTO components are reflected from the existingschemarsderives instead of a newToSchemaderive in files WS-G does not own; the peer status types and the JSON-only bodies are handwritten and parity-tested. - G2
POST /mcpdocumented (request body, JSON/SSE 200, the real 400/401/403/404/406/415),x-mcp-toolsgenerated fromTrackerService::advertised_tools(the same router that servestools/list), 8 or 10 tools. Commitf7a18dc. - G3
GET /api/v1/openapi.jsonbehind the existing auth, cached per mode, andslinuxm openapi [--peers], which returns beforeConfig::loadso it needs no config, token or socket. Commitf1cb210. - G4
docs/openapi.jsoncommitted (peers on), staleness test printing the regeneration command, route-scan and path-probe guards, tool-table guard, read-only and operationId/tag checks;docs/api.mdandREADME.mdupdated. Commits539651c,646e5d4.
Verification.
cargo fmt --check,cargo clippy --all-targets -- -D warningsandcargo testare green on the final tree (273 unit tests, of which 12 insrc/openapi.rsand 1 insrc/cli.rs; 10 integration tests intests/openapi.rs; the existing peers/MCP/TLS/plain suites unchanged).cargo tree -i opensslis empty;utoipabrings onlyutoipaandutoipa-gen, no crypto. The route scan was proved live by adding a throwaway route (test failed naming it) and the staleness guard by appending a byte to the committed file (test failed with the regeneration command). No write path, no secrets, no nix build, no VM test in this workstream.Note on running the checks here.
devenv shell -- dev-test …does not start in this worktree:devenvaborts with "Failed assertions: - To use 'git-hooks', run the following command: $ devenv inputs add git-hooks github:cachix/git-hooks.nix --follows nixpkgs" (devenv.yamlin this worktree lists only the nixpkgs input). The equivalent commands were run directly (cargo fmt --check,cargo clippy --all-targets -- -D warnings,cargo test).dev/hooks/select.shalready mapssrc/openapi.rstotest-unit:openapi+test-it:openapi, so the hooks pick the new tests up without a change.For the merger. (1) Tick the G1 to G4 boxes in
TODO.md(not owned here). (2)docs/README.mdhas no row fordocs/openapi.jsonyet; add one under "Reference" (not owned here). (3)AGENTS.md"The MCP tool count is 8" can now point atx-mcp-toolsandtests/openapi.rs, which pin both counts (8 peer-less, 10 with peers); not owned here. (4)config.example.tomlneeds nothing: the workstream adds no config key. (5) A crate version bump changesinfo.version, sodocs/openapi.jsonmust be regenerated in the same commit; the test message says how. If that turns out to be noisy, the alternative is to leaveinfo.versionout of the committed file, which weakens it. (6) If WS-G is ever allowed to touchsrc/sources/mod.rsandsrc/peers/types.rs, theToSchemaderives from the G1 task can replace the schemars bridge and the handwritten peer schemas; until then the bridge is the cheaper way to keep one definition per DTO. - G1
-
2026-10-20: Review-1 fixes. Each finding from
loop/G/review-1.md(verdict line ignored) was addressed and committed on its own:- F1
every_documented_path_is_routedprobed with auth on, sorequire_tokenanswered 401 before routing and the test could never fail. It now builds the router withauth.enabled = false, sends the method each operation actually declares (not GET for everything), asserts the body is not the fallback'sno such route, and a newdocumented_peer_paths_are_absent_without_peerschecks everydocument(false)path through a peer-less router plus three peer paths that must answer the fallback. Commitf8595b6. - F2 The peer status types now derive
schemars::JsonSchema(PeerNameis#[schemars(transparent)]), soPeerStatus,ServerStatus,ApiStatusandAuthStatejoin the reflected components; the ~150-line handwritten block,check_properties,nullable,date_timeandSINCE_DOCare gone.assert_coversnow checks both directions (serialized keys equal documented properties), and the exact schemars parity test covers the peer types too. Commit9449499. - F3
JournalParams,PsParams,LogParamsandUnitsQueryderiveIntoParams(parameter_in = Query) and the path macros name the structs, so a new query key cannot drift. This also correctedsincetoformat: date-timeand setminimum: 1onlinesandtail. Commitb1b39e8. - F4 The route scan now parses
.routecalls independently of formatting (the newlines in.route(\n "/path"no longer hide a route), reads the method builders and compares them with the document both ways, requires exactly 15 routes, requires every file that builds aRouterto contribute a route, walkssrc/apirecursively and rejects an unscanned.nest/.nest_serviceinsrc/api. A unit test pins a multilineget(...).post(...)call. Commit0f07ee4. - F5
/mcpnow documents all three operations the defaultLocalSessionManagermode serves:POST(JSON-RPC),GET(standalone SSE, 400/404/406) andDELETE(session end, 202).every_operation_is_read_onlyallows the sessionDELETEbecause it changes no host state, anddocs/api.mdsays the same. Commit8f6c94a. - F6 The
healthtag no longer calls/api/v1/pingunauthenticated; the auth layer's 503 is documented onping, both peer reads,openapi.jsonand/mcp; theinfo.descriptionexplains that[auth] enabled = falsedisables the bearer requirement while the host guard can still answer 403forbidden_host. Thesinceformat andlines/tailbounds landed with F3. Commit83b4546. - F7
docs/README.mdgains thedocs/openapi.jsonrow under Reference. Commite17d537.
Deviation from the owned files. F2 required
src/peers/types.rs, which the header does not own; the reviewer and the task explicitly allowed this, and it is a strictly smaller deviation than the schemars bridge's handwritten copy. F7 requireddocs/README.md, also outside the owned list; the previous handoff had left that row to the merger. Nosrc/sourcesfile was touched.TODO.mdneeds no change: the G1 to G4 tasks were never migrated into it, so there are no boxes to tick, and the merger still owns that move.Handoff (2026-10-20). All seven findings are fixed and committed separately.
docs/openapi.jsonwas regenerated with the documented command (cargo run -- openapi --peers > docs/openapi.json) after the last spec change.cargo fmt --check,cargo clippy --all-targets -- -D warningsandcargo testare green on the final tree (273 unit tests, 12 insrc/openapi.rs; 12 integration tests intests/openapi.rs; the peers, MCP, TLS, plain and binary suites unchanged).cargo tree -i opensslis still empty. The remaining merger items from the previous handoff are unchanged; thedocs/README.mdrow is now done. - F1