Files
skyg-linux-tracker/plan/workstreams/WS-E-rest.md
T
2026-10-15 17:07:03 -04:00

51 lines
2.1 KiB
Markdown

# WS-E — REST API
| Field | Value |
|---|---|
| Status | Backlog |
| Owner | — |
| Phase | 2 (parallel) |
| Depends on | P0 to start (fakes). A, B, C, D to finish. |
| Blocks | P3 |
| Owned files | `src/api/mod.rs`, `src/api/systemd.rs`, `src/api/journal.rs`, `src/api/docker.rs` |
## Goal
Build thin, read-only GET handlers over `AppState` sources, with SSE for follow endpoints. `api::router(state)` returns a router that P3 nests under `/api/v1`.
## Tasks
Tick these in [`TODO.md`](../../TODO.md).
- **E1** `api::router(AppState) -> Router`. Use axum 0.8 path syntax `/{name}`, because `:name` panics (review R4). GET only.
- **E2** Systemd routes:
- `/systemd/units?state=failed|active|…`
- `/systemd/units/{name}`
- `/systemd/timers`
- **E3** `/journal?unit=&priority=err|3&lines=`. Parse priority by name or number. Clamp `lines` and return 400 on bad input.
- **E4** `/journal/follow?unit=&priority=` returns `Sse` built from the source receiver:
- `KeepAlive::default()`.
- The stream ends on client disconnect, which drops the receiver and stops the blocking thread, or on `state.shutdown` (review G3).
- **E5** Docker routes:
- `/docker/ps`
- `/docker/containers/{name}`
- `/docker/containers/{name}/logs?tail=&since=&follow=`: JSON array when `follow=0`, SSE when `follow=1`. Each SSE event's `event:` is `stdout` or `stderr`.
- **E6** Provide a public `healthz` handler for P3 to mount outside auth. It returns `{"status":"ok","version":…}`.
- **E7** All errors go through `AppError`, giving one JSON shape everywhere.
- **E8** Tests with `fake.rs` sources via `tower::ServiceExt::oneshot`. Cover each route's happy path, 400, 404, and one SSE stream that yields events and then ends.
- **E9** When the fake docker returns `Unavailable`, docker routes return 503 and systemd and journal routes still return 200.
## Done when
- E8 and E9 pass.
- With real sources wired by P3, Verification #3 curl checks pass, including `curl -N` on both SSE endpoints.
## Notes
- Handlers stay thin: parse, call the source, serialize. No business logic.
- `tower-http` `TraceLayer` is applied in P3, not here.
## Log
- 2026-10-15: Card created.