From 6130e01b925ff3559c79aed961ef67c316930700 Mon Sep 17 00:00:00 2001 From: Ari Sosnovsky Date: Thu, 15 Oct 2026 18:32:52 -0400 Subject: [PATCH] WS-E: REST API handlers, SSE follow, healthz, tests Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01YShymaPrXmc3KYRUg2HMSs --- TODO.md | 18 +-- plan/workstreams/WS-E-rest.md | 3 +- src/api/docker.rs | 216 +++++++++++++++++++++++++++++++++- src/api/journal.rs | 133 ++++++++++++++++++++- src/api/mod.rs | 95 ++++++++++++++- src/api/systemd.rs | 94 ++++++++++++++- 6 files changed, 537 insertions(+), 22 deletions(-) diff --git a/TODO.md b/TODO.md index 3edda80..6c1fcf5 100644 --- a/TODO.md +++ b/TODO.md @@ -64,15 +64,15 @@ Design: [`plan.md`](plan.md) · Review fixes: [`plan/review.md`](plan/review.md) ## Phase 2 — Surfaces (parallel) ### WS-E REST API · [card](plan/workstreams/WS-E-rest.md) -- [ ] **E1** `api::router(state)` using axum 0.8 `{name}` path syntax -- [ ] **E2** `GET /systemd/units?state=`, `/systemd/units/{name}`, `/systemd/timers` -- [ ] **E3** `GET /journal?unit=&priority=&lines=` with validation -- [ ] **E4** `GET /journal/follow` SSE with keep-alive. Ends on disconnect or shutdown. -- [ ] **E5** `GET /docker/ps`, `/docker/containers/{name}`, `/docker/containers/{name}/logs` (JSON, or SSE with `follow=1`) -- [ ] **E6** `GET /healthz` on the public router -- [ ] **E7** Consistent JSON error body from `AppError` -- [ ] **E8** Handler tests against fake sources (`tower::ServiceExt::oneshot`) -- [ ] **E9** Docker unavailable returns 503 on docker routes only +- [x] **E1** `api::router(state)` using axum 0.8 `{name}` path syntax +- [x] **E2** `GET /systemd/units?state=`, `/systemd/units/{name}`, `/systemd/timers` +- [x] **E3** `GET /journal?unit=&priority=&lines=` with validation +- [x] **E4** `GET /journal/follow` SSE with keep-alive. Ends on disconnect or shutdown. +- [x] **E5** `GET /docker/ps`, `/docker/containers/{name}`, `/docker/containers/{name}/logs` (JSON, or SSE with `follow=1`) +- [x] **E6** `GET /healthz` on the public router +- [x] **E7** Consistent JSON error body from `AppError` +- [x] **E8** Handler tests against fake sources (`tower::ServiceExt::oneshot`) +- [x] **E9** Docker unavailable returns 503 on docker routes only ### WS-F MCP · [card](plan/workstreams/WS-F-mcp.md) - [ ] **F1** `TrackerService` with `#[tool_router]` and 8 tools diff --git a/plan/workstreams/WS-E-rest.md b/plan/workstreams/WS-E-rest.md index e6e7328..eda9a81 100644 --- a/plan/workstreams/WS-E-rest.md +++ b/plan/workstreams/WS-E-rest.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Backlog | +| Status | Done (pending merge) | | Owner | — | | Phase | 2 (parallel) | | Depends on | P0 to start (fakes). A, B, C, D to finish. | @@ -48,3 +48,4 @@ Tick these in [`TODO.md`](../../TODO.md). ## 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. diff --git a/src/api/docker.rs b/src/api/docker.rs index 9e6cd3f..d655d58 100644 --- a/src/api/docker.rs +++ b/src/api/docker.rs @@ -1,3 +1,215 @@ //! GET /api/v1/docker/* handlers (WS-E) -//! -//! Placeholder created in P0 so the owning workstream only edits its own files. + +use axum::extract::rejection::QueryRejection; +use axum::extract::{Path, Query, State}; +use axum::response::sse::Event; +use axum::response::{IntoResponse, Response}; +use axum::routing::get; +use axum::{Json, Router}; +use jiff::Timestamp; +use serde::Deserialize; + +use super::{query, sse_from}; +use crate::error::AppError; +use crate::sources::{ContainerStatus, ContainerSummary, LogLine, LogOptions, LogStream}; +use crate::state::AppState; + +pub fn routes() -> Router { + Router::new() + .route("/docker/ps", get(ps)) + .route("/docker/containers/{name}", get(container)) + .route("/docker/containers/{name}/logs", get(logs)) +} + +#[derive(Deserialize)] +struct PsParams { + all: Option, +} + +/// Accepts `1|0|true|false`. +fn parse_bool(name: &str, v: Option<&str>) -> Result { + match v { + None => Ok(false), + Some("1" | "true") => Ok(true), + Some("0" | "false") => Ok(false), + Some(o) => Err(AppError::BadRequest(format!( + "{name} must be 0, 1, true or false, got '{o}'" + ))), + } +} + +async fn ps( + State(st): State, + q: Result, QueryRejection>, +) -> Result>, AppError> { + let all = parse_bool("all", query(q)?.all.as_deref())?; + Ok(Json(st.docker.ps(all).await?)) +} + +async fn container( + State(st): State, + Path(name): Path, +) -> Result, AppError> { + Ok(Json(st.docker.container_status(&name).await?)) +} + +#[derive(Deserialize)] +struct LogParams { + tail: Option, + since: Option, + follow: Option, +} + +async fn logs( + State(st): State, + Path(name): Path, + q: Result, QueryRejection>, +) -> Result { + let p = query(q)?; + let follow = parse_bool("follow", p.follow.as_deref())?; + if p.tail == Some(0) { + return Err(AppError::BadRequest("tail must be at least 1".into())); + } + let opts = LogOptions { + tail: p.tail.map(|n| n.min(st.config.limits.max_tail)), + since: p.since, + }; + if !follow { + return Ok(Json(st.docker.logs(&name, &opts).await?).into_response()); + } + let rx = st.docker.follow_logs(&name, &opts).await?; + Ok(sse_from( + rx, + st.shutdown.clone(), + st.config.limits.max_follow_secs, + |l: &LogLine| { + let ev = match l.stream { + LogStream::Stdout => "stdout", + LogStream::Stderr => "stderr", + }; + Event::default() + .event(ev) + .json_data(l) + .unwrap_or_else(|_| Event::default().comment("serialize error")) + }, + ) + .into_response()) +} + +#[cfg(test)] +mod tests { + use std::sync::Arc; + + use async_trait::async_trait; + use axum::http::StatusCode; + use tokio::sync::mpsc; + + use crate::api::router; + use crate::api::testutil::{get, json}; + use crate::config::Config; + use crate::error::AppError; + use crate::sources::fake::fake_state; + use crate::sources::{ContainerStatus, ContainerSummary, DockerSource, LogLine, LogOptions}; + + fn app() -> axum::Router { + router(fake_state(Config::default())) + } + + #[tokio::test] + async fn ps_and_detail() { + let (s, b) = get(&app(), "/docker/ps").await; + assert_eq!(s, StatusCode::OK); + assert_eq!(json(&b).as_array().unwrap().len(), 2); + let (_, b) = get(&app(), "/docker/ps?all=1").await; + assert_eq!(json(&b).as_array().unwrap().len(), 3); + let (s, b) = get(&app(), "/docker/containers/web").await; + assert_eq!(s, StatusCode::OK); + assert_eq!(json(&b)["health"], "healthy"); + } + + #[tokio::test] + async fn errors_400_404() { + let (s, _) = get(&app(), "/docker/containers/nope").await; + assert_eq!(s, StatusCode::NOT_FOUND); + let (s, _) = get(&app(), "/docker/containers/nope/logs").await; + assert_eq!(s, StatusCode::NOT_FOUND); + for u in [ + "/docker/ps?all=maybe", + "/docker/containers/web/logs?tail=abc", + "/docker/containers/web/logs?tail=0", + "/docker/containers/web/logs?follow=2", + "/docker/containers/web/logs?since=nonsense", + ] { + let (s, b) = get(&app(), u).await; + assert_eq!(s, StatusCode::BAD_REQUEST, "{u}"); + assert_eq!(json(&b)["error"]["code"], "bad_request"); + } + } + + #[tokio::test] + async fn logs_json() { + let (s, b) = get(&app(), "/docker/containers/web/logs?follow=0").await; + assert_eq!(s, StatusCode::OK); + assert_eq!(json(&b).as_array().unwrap().len(), 2); + let (_, b) = get(&app(), "/docker/containers/web/logs?tail=1").await; + assert_eq!(json(&b)[0]["stream"], "stderr"); + } + + #[tokio::test] + async fn logs_sse_ends_on_shutdown() { + let st = fake_state(Config::default()); + let token = st.shutdown.clone(); + let app = router(st); + tokio::spawn(async move { + tokio::time::sleep(std::time::Duration::from_millis(200)).await; + token.cancel(); + }); + let (s, b) = get(&app, "/docker/containers/web/logs?follow=1").await; + assert_eq!(s, StatusCode::OK); + assert!(b.contains("event: stdout"), "{b}"); + assert!(b.contains("event: stderr"), "{b}"); + } + + struct Down; + + #[async_trait] + impl DockerSource for Down { + async fn ps(&self, _: bool) -> Result, AppError> { + Err(AppError::Unavailable("docker socket".into())) + } + async fn container_status(&self, _: &str) -> Result { + Err(AppError::Unavailable("docker socket".into())) + } + async fn logs(&self, _: &str, _: &LogOptions) -> Result, AppError> { + Err(AppError::Unavailable("docker socket".into())) + } + async fn follow_logs( + &self, + _: &str, + _: &LogOptions, + ) -> Result, AppError> { + Err(AppError::Unavailable("docker socket".into())) + } + } + + #[tokio::test] + async fn docker_unavailable_isolated() { + let mut st = fake_state(Config::default()); + st.docker = Arc::new(Down); + let app = router(st); + for u in [ + "/docker/ps", + "/docker/containers/web", + "/docker/containers/web/logs", + "/docker/containers/web/logs?follow=1", + ] { + let (s, b) = get(&app, u).await; + assert_eq!(s, StatusCode::SERVICE_UNAVAILABLE, "{u}"); + assert_eq!(json(&b)["error"]["code"], "unavailable"); + } + for u in ["/systemd/units", "/systemd/timers", "/journal"] { + let (s, _) = get(&app, u).await; + assert_eq!(s, StatusCode::OK, "{u}"); + } + } +} diff --git a/src/api/journal.rs b/src/api/journal.rs index 02faf40..142f9b5 100644 --- a/src/api/journal.rs +++ b/src/api/journal.rs @@ -1,3 +1,132 @@ //! GET /api/v1/journal and /journal/follow handlers (WS-E) -//! -//! Placeholder created in P0 so the owning workstream only edits its own files. + +use std::convert::Infallible; + +use axum::extract::rejection::QueryRejection; +use axum::extract::{Query, State}; +use axum::response::sse::{Event, Sse}; +use axum::routing::get; +use axum::{Json, Router}; +use futures::Stream; +use jiff::Timestamp; +use serde::Deserialize; + +use super::{query, sse_from}; +use crate::error::AppError; +use crate::sources::{JournalEntry, JournalQuery}; +use crate::state::AppState; + +pub fn routes() -> Router { + Router::new() + .route("/journal", get(snapshot)) + .route("/journal/follow", get(follow)) +} + +#[derive(Deserialize)] +struct JournalParams { + unit: Option, + priority: Option, + lines: Option, + since: Option, +} + +impl JournalParams { + /// Parse priority and clamp `lines` to the configured cap. `lines=0` is + /// rejected. + fn into_query(self, st: &AppState) -> Result { + if self.lines == Some(0) { + return Err(AppError::BadRequest("lines must be at least 1".into())); + } + let priority = self.priority.as_deref().map(str::parse).transpose()?; + Ok(JournalQuery { + unit: self.unit, + priority, + lines: self.lines.map(|n| n.min(st.config.limits.max_lines)), + since: self.since, + }) + } +} + +async fn snapshot( + State(st): State, + q: Result, QueryRejection>, +) -> Result>, AppError> { + let q = query(q)?.into_query(&st)?; + Ok(Json(st.journal.query(&q).await?)) +} + +async fn follow( + State(st): State, + q: Result, QueryRejection>, +) -> Result>>, AppError> { + let q = query(q)?.into_query(&st)?; + let rx = st.journal.follow(&q).await?; + Ok(sse_from( + rx, + st.shutdown.clone(), + st.config.limits.max_follow_secs, + |e: &JournalEntry| { + Event::default() + .event("journal") + .json_data(e) + .unwrap_or_else(|_| Event::default().comment("serialize error")) + }, + )) +} + +#[cfg(test)] +mod tests { + use axum::http::StatusCode; + + use crate::api::router; + use crate::api::testutil::{get, json}; + use crate::config::Config; + use crate::sources::fake::fake_state; + + #[tokio::test] + async fn snapshot_filters() { + let app = router(fake_state(Config::default())); + let (s, b) = get(&app, "/journal").await; + assert_eq!(s, StatusCode::OK); + assert_eq!(json(&b).as_array().unwrap().len(), 3); + for p in ["err", "3"] { + let (s, b) = get(&app, &format!("/journal?priority={p}&unit=nginx.service")).await; + assert_eq!(s, StatusCode::OK); + assert_eq!(json(&b).as_array().unwrap().len(), 2); + } + let (_, b) = get(&app, "/journal?lines=1&priority=err").await; + assert_eq!(json(&b).as_array().unwrap().len(), 1); + } + + #[tokio::test] + async fn bad_input_is_400() { + let app = router(fake_state(Config::default())); + for u in [ + "/journal?priority=loud", + "/journal?priority=9", + "/journal?lines=abc", + "/journal?lines=0", + "/journal?since=yesterday", + "/journal/follow?priority=loud", + ] { + let (s, b) = get(&app, u).await; + assert_eq!(s, StatusCode::BAD_REQUEST, "{u}"); + assert_eq!(json(&b)["error"]["code"], "bad_request"); + } + } + + #[tokio::test] + async fn follow_streams_then_ends_on_shutdown() { + let st = fake_state(Config::default()); + let token = st.shutdown.clone(); + let app = router(st); + tokio::spawn(async move { + tokio::time::sleep(std::time::Duration::from_millis(200)).await; + token.cancel(); + }); + let (s, b) = get(&app, "/journal/follow?priority=err").await; + assert_eq!(s, StatusCode::OK); + assert_eq!(b.matches("event: journal").count(), 2, "{b}"); + assert!(b.contains("bind() to 0.0.0.0:80 failed")); + } +} diff --git a/src/api/mod.rs b/src/api/mod.rs index a246258..8bac050 100644 --- a/src/api/mod.rs +++ b/src/api/mod.rs @@ -1,18 +1,101 @@ //! REST layer (WS-E owns `src/api/`). //! -//! STUB: signature is final. Uses axum 0.8 `{name}` path syntax. The router -//! contains `/api/v1/*` only; `/healthz`, auth and `/mcp` are merged by -//! `main.rs` (P3 I1) so `/healthz` stays public. +//! The router contains `/api/v1/*` handlers only (paths are relative; P3 +//! nests it). `healthz` is public and mounted outside auth by `main.rs`. +//! Handlers are thin: parse, call the source, serialize. All errors render +//! through `AppError` as `{"error":{"code","message"}}`. pub mod docker; pub mod journal; pub mod systemd; -use axum::Router; +use std::convert::Infallible; +use std::time::Duration; +use axum::extract::rejection::QueryRejection; +use axum::extract::Query; +use axum::response::sse::{Event, KeepAlive, Sse}; +use axum::{Json, Router}; +use futures::Stream; +use serde::de::DeserializeOwned; +use tokio::sync::mpsc; +use tokio_util::sync::CancellationToken; + +use crate::error::AppError; use crate::state::AppState; /// Routes under `/api/v1`, already bound to `state`. -pub fn router(_state: AppState) -> Router { - todo!("WS-E E1") +pub fn router(state: AppState) -> Router { + Router::new() + .merge(systemd::routes()) + .merge(journal::routes()) + .merge(docker::routes()) + .fallback(not_found) + .with_state(state) +} + +/// Public liveness handler: `{"status":"ok","version":"…"}`. +pub async fn healthz() -> Json { + Json(serde_json::json!({ + "status": "ok", + "version": env!("CARGO_PKG_VERSION"), + })) +} + +/// Route-level 404 in the common error shape. +pub async fn not_found() -> AppError { + AppError::NotFound("no such route".into()) +} + +/// Query extraction that reports failures as `AppError::BadRequest`. +pub(crate) fn query( + q: Result, QueryRejection>, +) -> Result { + q.map(|Query(v)| v) + .map_err(|e| AppError::BadRequest(e.body_text())) +} + +/// Build an SSE response from a source receiver. `to_event` maps an item to +/// an event. The stream ends when the producer closes the channel, the +/// shutdown token fires, or `max_secs` elapses. Dropping the response (client +/// disconnect) drops the receiver, which stops the producer. +pub(crate) fn sse_from( + rx: mpsc::Receiver, + shutdown: CancellationToken, + max_secs: u64, + to_event: fn(&T) -> Event, +) -> Sse>> { + let deadline = tokio::time::Instant::now() + Duration::from_secs(max_secs); + let stream = futures::stream::unfold((rx, shutdown), move |(mut rx, shutdown)| async move { + let item = tokio::select! { + () = shutdown.cancelled() => None, + () = tokio::time::sleep_until(deadline) => None, + item = rx.recv() => item, + }?; + Some((Ok(to_event(&item)), (rx, shutdown))) + }); + Sse::new(stream).keep_alive(KeepAlive::default()) +} + +#[cfg(test)] +pub(crate) mod testutil { + use axum::body::{to_bytes, Body}; + use axum::http::{Request, StatusCode}; + use axum::Router; + use tower::ServiceExt; + + pub async fn get(app: &Router, uri: &str) -> (StatusCode, String) { + let resp = app + .clone() + .oneshot(Request::get(uri).body(Body::empty()).unwrap()) + .await + .unwrap(); + let status = resp.status(); + let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap(); + (status, String::from_utf8(body.to_vec()).unwrap()) + } + + pub fn json(s: &str) -> serde_json::Value { + serde_json::from_str(s).unwrap() + } } diff --git a/src/api/systemd.rs b/src/api/systemd.rs index 5cd6eed..bff23fb 100644 --- a/src/api/systemd.rs +++ b/src/api/systemd.rs @@ -1,3 +1,93 @@ //! GET /api/v1/systemd/* handlers (WS-E) -//! -//! Placeholder created in P0 so the owning workstream only edits its own files. + +use axum::extract::rejection::QueryRejection; +use axum::extract::{Path, Query, State}; +use axum::routing::get; +use axum::{Json, Router}; +use serde::Deserialize; + +use super::query; +use crate::error::AppError; +use crate::sources::{TimerInfo, UnitStatus, UnitSummary}; +use crate::state::AppState; + +pub fn routes() -> Router { + Router::new() + .route("/systemd/units", get(units)) + .route("/systemd/units/{name}", get(unit)) + .route("/systemd/timers", get(timers)) +} + +#[derive(Deserialize)] +struct UnitsQuery { + state: Option, +} + +async fn units( + State(st): State, + q: Result, QueryRejection>, +) -> Result>, AppError> { + let q = query(q)?; + Ok(Json(st.systemd.list_units(q.state.as_deref()).await?)) +} + +async fn unit( + State(st): State, + Path(name): Path, +) -> Result, AppError> { + Ok(Json(st.systemd.unit_status(&name).await?)) +} + +async fn timers(State(st): State) -> Result>, AppError> { + Ok(Json(st.systemd.list_timers().await?)) +} + +#[cfg(test)] +mod tests { + use axum::http::StatusCode; + + use crate::api::testutil::{get, json}; + use crate::api::{healthz, router}; + use crate::config::Config; + use crate::sources::fake::fake_state; + + fn app() -> axum::Router { + router(fake_state(Config::default())) + } + + #[tokio::test] + async fn list_and_filter() { + let (s, b) = get(&app(), "/systemd/units").await; + assert_eq!(s, StatusCode::OK); + assert!(json(&b).as_array().unwrap().len() >= 2); + let (s, b) = get(&app(), "/systemd/units?state=failed").await; + assert_eq!(s, StatusCode::OK); + assert_eq!(json(&b)[0]["name"], "nginx.service"); + } + + #[tokio::test] + async fn unit_detail_and_404() { + let (s, b) = get(&app(), "/systemd/units/sshd.service").await; + assert_eq!(s, StatusCode::OK); + assert_eq!(json(&b)["main_pid"], 1234); + let (s, b) = get(&app(), "/systemd/units/nope.service").await; + assert_eq!(s, StatusCode::NOT_FOUND); + assert_eq!(json(&b)["error"]["code"], "not_found"); + } + + #[tokio::test] + async fn timers_ok_and_unknown_route() { + let (s, _) = get(&app(), "/systemd/timers").await; + assert_eq!(s, StatusCode::OK); + let (s, b) = get(&app(), "/nope").await; + assert_eq!(s, StatusCode::NOT_FOUND); + assert_eq!(json(&b)["error"]["code"], "not_found"); + } + + #[tokio::test] + async fn healthz_shape() { + let v = healthz().await.0; + assert_eq!(v["status"], "ok"); + assert!(v["version"].is_string()); + } +}