WS-E: REST API handlers, SSE follow, healthz, tests

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YShymaPrXmc3KYRUg2HMSs
This commit is contained in:
ariandClaude Sonnet 5.5 committed 2026-10-15 18:32:52 -04:00
1 parent 2d57fb1a78
commit 6130e01b92
6 files changed
+537 -22

No files matched your search

+214 -2
View File
@@ -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<AppState> {
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<String>,
}
/// Accepts `1|0|true|false`.
fn parse_bool(name: &str, v: Option<&str>) -> Result<bool, AppError> {
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<AppState>,
q: Result<Query<PsParams>, QueryRejection>,
) -> Result<Json<Vec<ContainerSummary>>, AppError> {
let all = parse_bool("all", query(q)?.all.as_deref())?;
Ok(Json(st.docker.ps(all).await?))
}
async fn container(
State(st): State<AppState>,
Path(name): Path<String>,
) -> Result<Json<ContainerStatus>, AppError> {
Ok(Json(st.docker.container_status(&name).await?))
}
#[derive(Deserialize)]
struct LogParams {
tail: Option<usize>,
since: Option<Timestamp>,
follow: Option<String>,
}
async fn logs(
State(st): State<AppState>,
Path(name): Path<String>,
q: Result<Query<LogParams>, QueryRejection>,
) -> Result<Response, AppError> {
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<Vec<ContainerSummary>, AppError> {
Err(AppError::Unavailable("docker socket".into()))
}
async fn container_status(&self, _: &str) -> Result<ContainerStatus, AppError> {
Err(AppError::Unavailable("docker socket".into()))
}
async fn logs(&self, _: &str, _: &LogOptions) -> Result<Vec<LogLine>, AppError> {
Err(AppError::Unavailable("docker socket".into()))
}
async fn follow_logs(
&self,
_: &str,
_: &LogOptions,
) -> Result<mpsc::Receiver<LogLine>, 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}");
}
}
}
+131 -2
View File
@@ -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<AppState> {
Router::new()
.route("/journal", get(snapshot))
.route("/journal/follow", get(follow))
}
#[derive(Deserialize)]
struct JournalParams {
unit: Option<String>,
priority: Option<String>,
lines: Option<usize>,
since: Option<Timestamp>,
}
impl JournalParams {
/// Parse priority and clamp `lines` to the configured cap. `lines=0` is
/// rejected.
fn into_query(self, st: &AppState) -> Result<JournalQuery, AppError> {
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<AppState>,
q: Result<Query<JournalParams>, QueryRejection>,
) -> Result<Json<Vec<JournalEntry>>, AppError> {
let q = query(q)?.into_query(&st)?;
Ok(Json(st.journal.query(&q).await?))
}
async fn follow(
State(st): State<AppState>,
q: Result<Query<JournalParams>, QueryRejection>,
) -> Result<Sse<impl Stream<Item = Result<Event, Infallible>>>, 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"));
}
}
+89 -6
View File
@@ -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<serde_json::Value> {
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<T: DeserializeOwned>(
q: Result<Query<T>, QueryRejection>,
) -> Result<T, AppError> {
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<T: Send + 'static>(
rx: mpsc::Receiver<T>,
shutdown: CancellationToken,
max_secs: u64,
to_event: fn(&T) -> Event,
) -> Sse<impl Stream<Item = Result<Event, Infallible>>> {
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()
}
}
+92 -2
View File
@@ -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<AppState> {
Router::new()
.route("/systemd/units", get(units))
.route("/systemd/units/{name}", get(unit))
.route("/systemd/timers", get(timers))
}
#[derive(Deserialize)]
struct UnitsQuery {
state: Option<String>,
}
async fn units(
State(st): State<AppState>,
q: Result<Query<UnitsQuery>, QueryRejection>,
) -> Result<Json<Vec<UnitSummary>>, AppError> {
let q = query(q)?;
Ok(Json(st.systemd.list_units(q.state.as_deref()).await?))
}
async fn unit(
State(st): State<AppState>,
Path(name): Path<String>,
) -> Result<Json<UnitStatus>, AppError> {
Ok(Json(st.systemd.unit_status(&name).await?))
}
async fn timers(State(st): State<AppState>) -> Result<Json<Vec<TimerInfo>>, 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());
}
}