Files
2026-10-19 14:14:29 -04:00

2.7 KiB

WS-E — REST API

Field Value
Status Done
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.

  • 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.
  • 2026-10-15: Implemented on branch ws-e/rest-api. E1-E9 done. Query errors, missing routes and source errors all use the AppError JSON shape. lines/tail are rejected at 0 and clamped to limits.max_*; priority parsed via Priority::from_str; state validated by the source (400). SSE ends on disconnect, state.shutdown, or limits.max_follow_secs. Journal SSE event name is journal; docker is stdout/stderr; data is the JSON DTO. api::healthz is public for P3 to mount at /healthz. follow and all accept 0/1/true/false.