G: handoff for G1-G4
This commit is contained in:
1 parent
214e074cca
commit
e7f1d1a488
1 file changed
+13
@@ -45,3 +45,16 @@ Reuse existing DTOs, do not duplicate types for the doc. Read-only, no secrets i
|
||||
Verification: `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, `cargo test` green (10 tests in `tests/openapi.rs`, 12 unit tests in `src/openapi.rs`/`src/cli.rs`); `cargo tree -i openssl` empty; 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.code` enum listed only the `AppError` codes, but two status-only bodies reuse `error_response` (`method_not_allowed` from the 405 fallback, `forbidden_host` from the auth-off Host guard), so both are now documented and `every_error_code_is_documented` ties the enum to `AppError::code()` plus those two; the docker `logs` and the peer pass-through 200s now declare both `application/json` and `text/event-stream` instead of JSON only; `schema_type` no longer maps an unknown JSON Schema type name to `object` (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** `utoipa` 6.0.0; `#[utoipa::path]` on every handler (explicit `operationId`s, tags, parameters and the real status set), bearer scheme declared and applied globally with `/healthz` opting out, single `ApiDoc` + `document(peers)` in `src/openapi.rs`. Commits `d21e5e7`, plus the ownership-conflict resolution described above: DTO components are reflected from the existing `schemars` derives instead of a new `ToSchema` derive in files WS-G does not own; the peer status types and the JSON-only bodies are handwritten and parity-tested.
|
||||
- **G2** `POST /mcp` documented (request body, JSON/SSE 200, the real 400/401/403/404/406/415), `x-mcp-tools` generated from `TrackerService::advertised_tools` (the same router that serves `tools/list`), 8 or 10 tools. Commit `f7a18dc`.
|
||||
- **G3** `GET /api/v1/openapi.json` behind the existing auth, cached per mode, and `slinuxm openapi [--peers]`, which returns before `Config::load` so it needs no config, token or socket. Commit `f1cb210`.
|
||||
- **G4** `docs/openapi.json` committed (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.md` and `README.md` updated. Commits `539651c`, `646e5d4`.
|
||||
|
||||
**Verification.** `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings` and `cargo test` are green on the final tree (273 unit tests, of which 12 in `src/openapi.rs` and 1 in `src/cli.rs`; 10 integration tests in `tests/openapi.rs`; the existing peers/MCP/TLS/plain suites unchanged). `cargo tree -i openssl` is empty; `utoipa` brings only `utoipa` and `utoipa-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: `devenv` aborts with "Failed assertions: - To use 'git-hooks', run the following command: $ devenv inputs add git-hooks github:cachix/git-hooks.nix --follows nixpkgs" (`devenv.yaml` in 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.sh` already maps `src/openapi.rs` to `test-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.md` has no row for `docs/openapi.json` yet; add one under "Reference" (not owned here). (3) `AGENTS.md` "The MCP tool count is 8" can now point at `x-mcp-tools` and `tests/openapi.rs`, which pin both counts (8 peer-less, 10 with peers); not owned here. (4) `config.example.toml` needs nothing: the workstream adds no config key. (5) A crate version bump changes `info.version`, so `docs/openapi.json` must be regenerated in the same commit; the test message says how. If that turns out to be noisy, the alternative is to leave `info.version` out of the committed file, which weakens it. (6) If WS-G is ever allowed to touch `src/sources/mod.rs` and `src/peers/types.rs`, the `ToSchema` derives 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.
|
||||
Reference in new issue
Block a user