//! Peer status and GET-only pass-through routes. //! //! Merged only when `state.peers` is set, so a peer-less instance has no //! peers routes at all. Pass-through lives in `crate::peers::proxy` so MCP //! calls the same code. use std::time::Duration; use axum::body::Body; use axum::extract::{Path, Request, State}; use axum::http::{header, HeaderName, HeaderValue}; use axum::response::{IntoResponse, Response}; use axum::routing::get; use axum::{Json, Router}; use serde::Serialize; use crate::error::AppError; use crate::openapi::ErrorBody; use crate::peers::proxy::{self, PreparedBody, PreparedResponse}; use crate::peers::types::{PeerName, PeerStatus}; use crate::peers::{PeerRegistry, ProxyOpts}; use crate::state::AppState; pub fn routes() -> Router { Router::new() .route("/peers", get(list)) .route("/peers/{peer}", get(one)) .route("/peers/{peer}/{*path}", get(pass)) } #[derive(Serialize, utoipa::ToSchema)] pub(crate) struct PeerList { peers: Vec, } /// Only reachable with a registry: `api::router` merges these routes on /// `state.peers.is_some()` and the field is fixed for the process lifetime. fn registry(st: &AppState) -> &PeerRegistry { st.peers .as_deref() .expect("peer routes are mounted only with a peer registry") } #[utoipa::path( get, path = "/api/v1/peers", operation_id = "list_peers", tag = "peers", summary = "Peer status list", description = "Every configured peer, sorted by name, including disabled ones. Present only \ when `[peers] enabled = true`.", responses( (status = 200, body = PeerList, description = "Peer status, sorted by name"), (status = 401, body = ErrorBody, description = "Missing or unknown bearer token"), (status = 503, body = ErrorBody, description = "The token database is unavailable"), ) )] pub(crate) async fn list(State(st): State) -> Json { Json(PeerList { peers: registry(&st).snapshot(), }) } #[utoipa::path( get, path = "/api/v1/peers/{peer}", operation_id = "get_peer", tag = "peers", summary = "Status of one peer", params(( "peer" = String, Path, description = "Configured peer name" )), responses( (status = 200, body = PeerStatus, description = "The peer, not wrapped in an object"), (status = 401, body = ErrorBody, description = "Missing or unknown bearer token"), (status = 404, body = ErrorBody, description = "Unknown peer"), (status = 503, body = ErrorBody, description = "The token database is unavailable"), ) )] pub(crate) async fn one( State(st): State, Path(peer): Path, ) -> Result, AppError> { Ok(Json(registry(&st).status(&peer)?)) } /// Pass-through of one peer's read routes. The wildcard is documented as one /// operation because the peer's own routes are the peer's business; the /// allowlist below is what this instance forwards. #[utoipa::path( get, path = "/api/v1/peers/{peer}/{path}", operation_id = "proxy_peer_get", tag = "peers", summary = "GET-only pass-through to a peer", description = "Forwards a GET to the same path on the peer and returns the peer's status and \ body unchanged for 2xx. Allowed paths: `systemd/units`, \ `systemd/units/{name}`, `systemd/timers`, `journal`, `journal/follow`, \ `docker/ps`, `docker/containers/{name}`, `docker/containers/{name}/logs`. \ `ping` and `peers/...` are not forwarded, nor is any other path. Query keys \ are those the local route accepts (`state`, `unit`, `priority`, `lines`, \ `since`, `all`, `tail`, `follow`). Only GET is accepted. A peer failure is a \ 503 naming the peer, never a 401: a peer rejecting the consolidator's token \ does not mean the caller must re-authenticate here. Peer data is untrusted.", params(( "peer" = String, Path, description = "Configured peer name" ), ( "path" = String, Path, description = "Peer route below `/api/v1`, e.g. `systemd/units`" )), responses( (status = 200, description = "The peer's body with the peer's status and `x-slinuxm-peer`; JSON, or `text/event-stream` for a follow", content((String = "application/json"), (String = "text/event-stream"))), (status = 400, body = ErrorBody, description = "Path or query not allowed, or a chained request (`x-slinuxm-hop`)"), (status = 401, body = ErrorBody, description = "Missing or unknown bearer token"), (status = 404, body = ErrorBody, description = "Unknown peer, or the peer answered 404"), (status = 405, body = ErrorBody, description = "Not a GET"), (status = 503, body = ErrorBody, description = "Peer unreachable, timed out, rejected the consolidator's token, exceeded the size cap, or answered another error status"), ) )] pub(crate) async fn pass( State(st): State, Path((peer, _path)): Path<(String, String)>, request: Request, ) -> Response { let reg = registry(&st); // The registry parses and looks the name up in one call, so an unknown or // malformed name gets the contract's 404 and no peer header: the response // does not come from a peer. let name = match reg.status(&peer) { Ok(status) => status.name, Err(err) => return err.into_response(), }; with_peer_header(&name, pass_through(reg, &name, &st, request).await) } /// Every outcome for a proxy call names the peer, including consolidator-side /// errors (bad path, dead peer), so a client can tell which peer failed. fn with_peer_header(name: &PeerName, mut response: Response) -> Response { let value = HeaderValue::from_str(name.as_str()).expect("validated peer name"); response .headers_mut() .insert(HeaderName::from_static(proxy::PEER_HEADER), value); response } async fn pass_through( reg: &PeerRegistry, name: &PeerName, st: &AppState, request: Request, ) -> Response { if let Err(err) = proxy::reject_inbound_hop(name.as_str(), request.headers()) { return err.into_response(); } let Some(raw_path) = raw_peer_path(request.uri().path()) else { return AppError::BadRequest(format!("peer {name}: path not allowed")).into_response(); }; let query = match proxy::query_from_raw(name.as_str(), request.uri().query()) { Ok(query) => query, Err(err) => return err.into_response(), }; let opts = ProxyOpts { traceparent: inbound_traceparent(request.headers()), accept_sse: accepts_event_stream(request.headers()), }; let resp = match reg.get(name.as_str(), raw_path, &query, opts).await { Ok(resp) => resp, Err(err) => return err.into_response(), }; let deadline = tokio::time::Instant::now() + Duration::from_secs(st.config.limits.max_follow_secs); match proxy::prepare_response( name, resp, reg.config().max_response_bytes, deadline, st.shutdown.clone(), ) { Ok(prepared) => prepared_response(prepared), Err(err) => err.into_response(), } } fn prepared_response(prepared: PreparedResponse) -> Response { let sse = prepared .content_type .as_ref() .is_some_and(|value| value.as_bytes() == b"text/event-stream"); let body = match prepared.body { PreparedBody::Bytes(bytes) => Body::from(bytes), PreparedBody::Stream(stream) => Body::from_stream(stream), }; let mut response = Response::new(body); *response.status_mut() = prepared.status; if let Some(content_type) = prepared.content_type { response .headers_mut() .insert(header::CONTENT_TYPE, content_type); } // A follow must not be buffered or cached by an intermediary; the local // routes get this from axum's `Sse`. if sse { response .headers_mut() .insert(header::CACHE_CONTROL, HeaderValue::from_static("no-cache")); } response } /// Path after `/peers/{name}/`, still percent-encoded. Nesting strips /// `/api/v1` before this runs, so both the mounted server and the bare API /// router yield `/peers/...`. fn raw_peer_path(uri_path: &str) -> Option<&str> { let mut rest = uri_path; while let Some(stripped) = rest.strip_prefix('/') { if let Some(after) = stripped.strip_prefix("peers/") { let (_name, path) = after.split_once('/')?; return Some(path); } rest = &stripped[stripped.find('/')?..]; } None } fn inbound_traceparent(headers: &axum::http::HeaderMap) -> Option { let value = headers.get("traceparent")?.to_str().ok()?; if (1..=128).contains(&value.len()) && value.bytes().all(|b| b.is_ascii_graphic()) { Some(value.to_owned()) } else { None } } fn accepts_event_stream(headers: &axum::http::HeaderMap) -> bool { headers .get(header::ACCEPT) .and_then(|value| value.to_str().ok()) .is_some_and(|value| { value .split(',') .any(|part| part.trim().starts_with("text/event-stream")) }) } #[cfg(test)] mod tests { use axum::http::StatusCode; use super::super::router; use super::super::testutil::{get, json}; use crate::config::Config; use crate::peers::testing::{fake_state_with_peers, static_registry}; use crate::peers::types::{ApiStatus, AuthState, PeerName, PeerStatus, ServerStatus}; use crate::sources::fake::fake_state; fn status(name: &str, enabled: bool, up: bool, auth: AuthState) -> PeerStatus { PeerStatus { name: PeerName::parse(name).unwrap(), enabled, url: format!("http://{name}:1984"), server: ServerStatus { up, since: Some("2026-10-19T10:00:00Z".parse().unwrap()), last_checked: Some("2026-10-19T10:00:09Z".parse().unwrap()), last_error: None, latency_ms: Some(1), }, api: ApiStatus { up, since: Some("2026-10-19T10:00:00Z".parse().unwrap()), last_checked: Some("2026-10-19T10:00:05Z".parse().unwrap()), last_error: None, latency_ms: Some(7), auth, peer_version: Some("0.1.0".into()), }, } } fn app(statuses: Vec) -> axum::Router { router(fake_state_with_peers( Config::default(), static_registry(statuses), )) } #[tokio::test] async fn list_is_sorted_and_shaped() { let app = app(vec![ status("gamma", false, false, AuthState::Unknown), status("beta", true, true, AuthState::Ok), ]); let (s, b) = get(&app, "/peers").await; assert_eq!(s, StatusCode::OK); let v = json(&b); let peers = v["peers"].as_array().unwrap(); assert_eq!(peers.len(), 2); assert_eq!(peers[0]["name"], "beta"); assert_eq!(peers[1]["name"], "gamma"); assert_eq!(peers[0]["enabled"], true); assert_eq!(peers[1]["enabled"], false); assert_eq!(peers[0]["url"], "http://beta:1984"); assert_eq!(peers[0]["server"]["up"], true); assert_eq!(peers[0]["server"]["since"], "2026-10-19T10:00:00Z"); assert_eq!(peers[0]["server"]["last_checked"], "2026-10-19T10:00:09Z"); assert_eq!(peers[0]["server"]["last_error"], serde_json::Value::Null); assert_eq!(peers[0]["server"]["latency_ms"], 1); assert_eq!(peers[0]["api"]["up"], true); assert_eq!(peers[0]["api"]["auth"], "ok"); assert_eq!(peers[0]["api"]["peer_version"], "0.1.0"); assert_eq!(peers[1]["api"]["auth"], "unknown"); assert_eq!(peers[1]["server"]["up"], false); } #[tokio::test] async fn one_peer_is_the_object_not_a_list() { let app = app(vec![status("beta", true, true, AuthState::Rejected)]); let (s, b) = get(&app, "/peers/beta").await; assert_eq!(s, StatusCode::OK); let v = json(&b); assert!(v.get("peers").is_none()); assert_eq!(v["name"], "beta"); assert_eq!(v["server"]["up"], true); assert_eq!(v["api"]["up"], true); assert_eq!(v["api"]["auth"], "rejected"); } #[tokio::test] async fn unknown_peer_is_not_found() { let app = app(vec![status("beta", true, true, AuthState::Ok)]); for name in ["nope", "Beta", "-beta"] { let (s, b) = get(&app, &format!("/peers/{name}")).await; assert_eq!(s, StatusCode::NOT_FOUND, "{name}"); assert_eq!(json(&b)["error"]["code"], "not_found"); assert_eq!( json(&b)["error"]["message"], format!("peer {name}: unknown peer") ); } } #[tokio::test] async fn empty_registry_lists_nothing() { let (s, b) = get(&app(vec![]), "/peers").await; assert_eq!(s, StatusCode::OK); assert_eq!(json(&b)["peers"].as_array().unwrap().len(), 0); } #[tokio::test] async fn routes_are_absent_when_peers_are_disabled() { let app = router(fake_state(Config::default())); for path in ["/peers", "/peers/beta"] { let (s, b) = get(&app, path).await; assert_eq!(s, StatusCode::NOT_FOUND, "{path}"); assert_eq!(json(&b)["error"]["code"], "not_found"); } let (s, _) = get(&app, "/systemd/units").await; assert_eq!(s, StatusCode::OK); } #[tokio::test] async fn local_routes_stay_available() { let app = app(vec![status("beta", true, true, AuthState::Ok)]); let (s, _) = get(&app, "/systemd/units").await; assert_eq!(s, StatusCode::OK); let (s, _) = get(&app, "/journal").await; assert_eq!(s, StatusCode::OK); } }