51 lines
2.1 KiB
Markdown
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.
|