//! The generated OpenAPI description against the real router. //! //! axum does not expose its route table, so the router side of the drift //! guard is a scan of the route literals in the source plus one request per //! documented path: a route that exists but is not documented fails the scan, //! and a documented path the router does not know fails the request (it gets //! the fallback's `no such route`). use std::fs; use std::path::Path; use std::time::Duration; use axum::body::{to_bytes, Body}; use axum::http::{Method, Request, StatusCode}; use axum::Router; use serde_json::Value; use skyg_linux_tracker::auth::tokens; use skyg_linux_tracker::config::Config; use skyg_linux_tracker::mcp::TrackerService; use skyg_linux_tracker::openapi::{self, document}; use skyg_linux_tracker::peers::testing::{fake_state_with_peers, static_registry}; use skyg_linux_tracker::peers::types::{ApiStatus, AuthState, PeerName, PeerStatus, ServerStatus}; use skyg_linux_tracker::server; use skyg_linux_tracker::sources::fake::fake_state; use skyg_linux_tracker::state::AppState; use sqlx::sqlite::SqlitePoolOptions; use tokio_util::sync::CancellationToken; use tower::ServiceExt; const MANIFEST: &str = env!("CARGO_MANIFEST_DIR"); /// Auth off: these probes are about routing, not about the token layer, and /// the fallback's `no such route` never reached the router while auth answered /// every request with 401 first. fn open_config() -> Config { let mut config = Config::default(); config.auth.enabled = false; config } /// The process shutdown token, so a probe of the two follow routes ends. fn probe(state: AppState) -> (Router, CancellationToken) { let shutdown = state.shutdown.clone(); (server::build_router(state), shutdown) } fn cancel_soon(shutdown: CancellationToken) { tokio::spawn(async move { tokio::time::sleep(Duration::from_millis(50)).await; shutdown.cancel(); }); } /// The router with peer routes mounted, so every documented path is present. fn app() -> (Router, CancellationToken) { let status = PeerStatus { name: PeerName::parse("beta").unwrap(), enabled: true, url: "http://beta:1984".into(), server: ServerStatus::default(), api: ApiStatus { auth: AuthState::Unknown, ..Default::default() }, }; probe(fake_state_with_peers( open_config(), static_registry(vec![status]), )) } /// axum spells a wildcard `{*path}`, OpenAPI `{path}`. fn openapi_path(route: &str) -> String { route.replace("{*", "{") } /// A request that reaches a route, with concrete values for its parameters. fn sample(path: &str) -> String { path.replace("{name}", "sshd.service") .replace("{peer}", "beta") .replace("{path}", "systemd/units") } /// Operations of one documented path, by the method the document declares. fn documented_methods(item: &utoipa::openapi::path::PathItem) -> Vec { [ (Method::GET, item.get.is_some()), (Method::POST, item.post.is_some()), (Method::PUT, item.put.is_some()), (Method::DELETE, item.delete.is_some()), (Method::PATCH, item.patch.is_some()), (Method::HEAD, item.head.is_some()), (Method::OPTIONS, item.options.is_some()), ] .into_iter() .filter(|(_, present)| *present) .map(|(method, _)| method) .collect() } /// Status and body of one request through the assembled router. async fn call(app: &Router, method: Method, uri: &str) -> (StatusCode, Value) { let request = Request::builder() .method(method) .uri(uri) .header("host", "127.0.0.1") .body(Body::empty()) .unwrap(); let response = app.clone().oneshot(request).await.unwrap(); let status = response.status(); let body = to_bytes(response.into_body(), usize::MAX).await.unwrap(); let json = serde_json::from_slice(&body).unwrap_or(Value::Null); (status, json) } /// One `.route(...)` call: path plus the methods its builder names, or /// `None` for a mount where the mounted service decides. #[derive(Debug)] struct Route { path: String, methods: Option>, } /// Every `.rs` file below `src/api`, recursively, in stable order. fn api_files() -> Vec { fn walk(dir: &Path, out: &mut Vec) { let mut entries: Vec<_> = fs::read_dir(dir) .unwrap() .map(|entry| entry.unwrap().path()) .collect(); entries.sort(); for path in entries { if path.is_dir() { walk(&path, out); } else if path.extension().is_some_and(|e| e == "rs") { out.push(path); } } } let mut files = Vec::new(); walk(&Path::new(MANIFEST).join("src/api"), &mut files); files } /// Route literals under `src/api`, which `server.rs` nests at `/api/v1`. fn api_routes() -> Vec { let mut out = Vec::new(); for file in api_files() { let source = fs::read_to_string(&file).unwrap(); let routes = route_calls(&source); // A new file that builds a router but contributes no route would be // invisible to the scan. if source.contains("Router::new") { assert!( !routes.is_empty(), "{}: builds a router but contributes no route", file.display() ); } assert!( !source.contains(".nest(\"") && !source.contains(".nest_service(\""), "{}: nested routers need to be added to the scan", file.display() ); out.extend(routes.into_iter().map(|mut route| { assert!(route.path.starts_with('/'), "{}: {route:?}", file.display()); route.path = format!("/api/v1{}", route.path); route })); } out } /// Routes declared outside the API router: `/healthz` and the `/mcp` mount in /// `server.rs`. `nest_service` accepts every method, so `/mcp` has none here. fn server_routes() -> Vec { let source = fs::read_to_string(Path::new(MANIFEST).join("src/server.rs")).unwrap(); let mut out = route_calls(&source); let mount = ".nest_service(\"/mcp\""; assert!(source.contains(mount), "server.rs no longer mounts /mcp"); out.push(Route { path: "/mcp".to_owned(), methods: None, }); out.sort_by(|a, b| a.path.cmp(&b.path)); out } /// Every `.route(...)` call, independent of how rustfmt breaks the line. fn route_calls(source: &str) -> Vec { let mut out = Vec::new(); let mut from = 0; while let Some(index) = source[from..].find(".route") { let marker = from + index; let mut cursor = marker + ".route".len(); cursor = skip_space(source, cursor); if !source[cursor..].starts_with('(') { from = cursor; continue; } let end = matching_paren(source, cursor); let call = &source[cursor + 1..end]; let (path, rest) = string_literal(call); out.push(Route { path, methods: Some(method_calls(rest)), }); from = end + 1; } out } fn skip_space(source: &str, mut cursor: usize) -> usize { while source[cursor..] .chars() .next() .is_some_and(char::is_whitespace) { cursor += source[cursor..].chars().next().unwrap().len_utf8(); } cursor } /// Index of the `)` matching the `(` at `open`, ignoring string contents. fn matching_paren(source: &str, open: usize) -> usize { let bytes = source.as_bytes(); let mut depth = 0; let mut in_string = false; let mut escaped = false; let mut index = open; while index < bytes.len() { let byte = bytes[index]; if in_string { if escaped { escaped = false; } else if byte == b'\\' { escaped = true; } else if byte == b'"' { in_string = false; } } else { match byte { b'"' => in_string = true, b'(' => depth += 1, b')' => { depth -= 1; if depth == 0 { return index; } } _ => {} } } index += 1; } panic!("unclosed .route( call at byte {open}"); } /// The leading string literal of a route call and the rest of the call. fn string_literal(call: &str) -> (String, &str) { let start = skip_space(call, 0); let rest = &call[start..]; let rest = rest .strip_prefix('"') .unwrap_or_else(|| panic!("route call does not start with a path: {call}")); let end = rest.find('"').expect("a route literal ends"); (rest[..end].to_owned(), &rest[end + 1..]) } /// Method builders named in the handler argument (`get`, `post`, ...). fn method_calls(rest: &str) -> Vec { let mut methods = Vec::new(); let mut remaining = rest; while let Some(index) = remaining.find(|c: char| c.is_ascii_alphabetic()) { remaining = &remaining[index..]; let end = remaining .find(|c: char| !c.is_ascii_alphanumeric() && c != '_') .unwrap_or(remaining.len()); let word = &remaining[..end]; if let Some(method) = method(word) { if remaining[end..].trim_start().starts_with('(') { methods.push(method); } } remaining = &remaining[end..]; } methods.sort_by(|a, b| a.as_str().cmp(b.as_str())); methods.dedup(); methods } fn method(name: &str) -> Option { Some(match name { "get" => Method::GET, "post" => Method::POST, "put" => Method::PUT, "delete" => Method::DELETE, "patch" => Method::PATCH, "head" => Method::HEAD, "options" => Method::OPTIONS, _ => return None, }) } /// The scan must survive rustfmt breaking a long route and must read the /// method builders, not just the path. #[test] fn route_scan_handles_multiline_calls_and_methods() { let source = r#" Router::new() .route( "/long/path", get(one).post(two), ) .route("/short", delete(three)) "#; let routes = route_calls(source); assert_eq!(routes.len(), 2); assert_eq!(routes[0].path, "/long/path"); assert_eq!( routes[0].methods.as_ref().unwrap(), &[Method::GET, Method::POST] ); assert_eq!(routes[1].path, "/short"); assert_eq!(routes[1].methods.as_ref().unwrap(), &[Method::DELETE]); } #[tokio::test] async fn every_router_route_is_documented() { let doc = document(true); let mut routes = api_routes(); routes.extend(server_routes()); // A scan that stops matching would make the checks below vacuous. assert_eq!(routes.len(), 15, "route scan found: {routes:?}"); for route in routes { let path = openapi_path(&route.path); let item = doc.paths.paths.get(&path).unwrap_or_else(|| { panic!("{path} is routed but missing from the OpenAPI document") }); let Some(methods) = route.methods else { continue; }; let documented = documented_methods(item); for method in &methods { assert!( documented.contains(method), "{method} {path} is routed but missing from the OpenAPI document" ); } for method in documented { assert!( methods.contains(&method), "{method} {path} is documented but not routed" ); } } } #[tokio::test] async fn every_documented_path_is_routed() { let doc = document(true); let (app, shutdown) = app(); cancel_soon(shutdown); for (path, item) in &doc.paths.paths { for method in documented_methods(item) { let (status, body) = call(&app, method.clone(), &sample(path)).await; let fallback = body["error"]["message"] == "no such route"; assert!( !fallback, "{method} {path} is documented but not routed ({status})" ); } } } /// The other half of the probe: a peer-less instance mounts no peer paths, so /// those documented paths must answer with the fallback. #[tokio::test] async fn documented_peer_paths_are_absent_without_peers() { let doc = document(false); assert!( !doc.paths .paths .keys() .any(|path| path.starts_with("/api/v1/peers")), "document(false) still has peer paths" ); let (app, shutdown) = probe(fake_state(open_config())); cancel_soon(shutdown); for (path, item) in &doc.paths.paths { for method in documented_methods(item) { let (status, body) = call(&app, method.clone(), &sample(path)).await; assert_ne!( body["error"]["message"], "no such route", "{method} {path} is documented but not routed ({status})" ); } } for path in [ "/api/v1/peers", "/api/v1/peers/beta", "/api/v1/peers/beta/systemd/units", ] { let (status, body) = call(&app, Method::GET, path).await; assert_eq!(status, StatusCode::NOT_FOUND, "{path}"); assert_eq!(body["error"]["message"], "no such route", "{path}"); } } /// The tools in `x-mcp-tools` are the ones `tools/list` serves in that mode. #[test] fn mcp_tools_match_the_tool_router() { for peers in [false, true] { let spec = serde_json::to_value(document(peers)).unwrap(); let documented = spec["x-mcp-tools"]["tools"].as_array().unwrap(); let advertised = TrackerService::advertised_tools(peers); assert_eq!( documented.len(), advertised.len(), "x-mcp-tools has a different number of tools (peers = {peers})" ); for (entry, tool) in documented.iter().zip(&advertised) { assert_eq!( entry["name"], tool.name.as_ref(), "tool order or names differ" ); assert_eq!( entry["description"], tool.description.as_deref().unwrap_or_default(), "{} has a different description", tool.name ); assert_eq!( entry["inputSchema"], Value::Object((*tool.input_schema).clone()), "{} has a different input schema", tool.name ); } } } /// The tool count is part of the contract: 8 without peers, 10 with them. #[test] fn mcp_tool_count_follows_the_peers_flag() { let names = |peers: bool| -> Vec { let spec = serde_json::to_value(document(peers)).unwrap(); spec["x-mcp-tools"]["tools"] .as_array() .unwrap() .iter() .map(|tool| tool["name"].as_str().unwrap().to_owned()) .collect() }; let off = names(false); assert_eq!(off.len(), 8); assert!(!off .iter() .any(|name| name == "list_peers" || name == "get_peer")); let on = names(true); assert_eq!(on.len(), 10); assert!(on.iter().any(|name| name == "list_peers")); assert!(on.iter().any(|name| name == "get_peer")); } /// The committed document is the one the code generates. Regenerate it (and /// commit the result) whenever a route, a tool, a DTO or the crate version /// changes. #[test] fn committed_spec_matches_the_code() { let path = Path::new(MANIFEST).join("docs/openapi.json"); let committed = fs::read_to_string(&path).unwrap_or_default(); let generated = skyg_linux_tracker::cli::render(true).unwrap(); assert_eq!( committed, generated, "docs/openapi.json is stale; regenerate it with\n \ cargo run -- openapi --peers > docs/openapi.json" ); } /// Read-only by construction: every operation is a GET, except the MCP /// endpoint, which is POST by protocol. #[test] fn every_operation_is_read_only() { let doc = document(true); for (path, item) in &doc.paths.paths { for (method, present) in [ ("post", item.post.is_some()), ("put", item.put.is_some()), ("delete", item.delete.is_some()), ("patch", item.patch.is_some()), ] { if present { assert_eq!( (method, path.as_str()), ("post", "/mcp"), "{method} {path} is a write path" ); } } } } /// Operation ids are unique and every tag is declared, so client generators /// and UI tools do not have to guess. #[test] fn operation_ids_and_tags_are_declared() { let doc = document(true); let declared: Vec = doc .tags .clone() .unwrap_or_default() .into_iter() .map(|tag| tag.name) .collect(); let mut ids = Vec::new(); for (path, item) in &doc.paths.paths { for operation in [&item.get, &item.post].into_iter().flatten() { let id = operation.operation_id.clone().expect("operationId"); assert!(!ids.contains(&id), "duplicate operationId {id} ({path})"); ids.push(id); for tag in operation.tags.iter().flatten() { assert!( declared.iter().any(|declared| declared == tag), "tag {tag} of {path} is not declared" ); } } } } #[test] fn the_spec_is_valid_json_with_the_expected_shape() { let doc = document(true); let spec = serde_json::to_value(&doc).unwrap(); assert_eq!(spec["openapi"], "3.1.0"); assert!(spec["info"]["title"].is_string()); assert!(spec["components"]["securitySchemes"][openapi::BEARER_SCHEME].is_object()); assert!(spec["paths"].is_object()); // Peer routes are present in this mode and absent in the other. assert!(spec["paths"].get("/api/v1/peers").is_some()); let off = serde_json::to_value(document(false)).unwrap(); assert!(off["paths"].get("/api/v1/peers").is_none()); assert!(off["paths"].get("/api/v1/systemd/units").is_some()); } /// The served document is the generated one, and only a token opens it. #[tokio::test] async fn openapi_route_is_authenticated_and_serves_the_document() { let mut config = Config::default(); config.auth.enabled = true; let mut state = fake_state_with_peers(config, static_registry(Vec::new())); let pool = SqlitePoolOptions::new() .max_connections(1) .connect("sqlite::memory:") .await .unwrap(); skyg_linux_tracker::db::migrate(&pool).await.unwrap(); let token = tokens::create(&pool, "openapi-test").await.unwrap(); state.db = Some(pool); let app = server::build_router(state); let anonymous = Request::get("/api/v1/openapi.json") .header("host", "127.0.0.1") .body(Body::empty()) .unwrap(); let anonymous = app.clone().oneshot(anonymous).await.unwrap(); assert_eq!(anonymous.status(), StatusCode::UNAUTHORIZED); let authorized = Request::get("/api/v1/openapi.json") .header("host", "127.0.0.1") .header("authorization", format!("Bearer {token}")) .body(Body::empty()) .unwrap(); let response = app.clone().oneshot(authorized).await.unwrap(); assert_eq!(response.status(), StatusCode::OK); assert_eq!( response .headers() .get("content-type") .and_then(|v| v.to_str().ok()), Some("application/json") ); let body = to_bytes(response.into_body(), usize::MAX).await.unwrap(); let served: Value = serde_json::from_slice(&body).unwrap(); // This router has a registry, so the served document is the peer one. assert_eq!(served, serde_json::to_value(&*document(true)).unwrap()); assert!(served["paths"].get("/api/v1/peers").is_some()); } /// `slinuxm openapi` prints the same document the route serves, without a /// config file: the server is never started and no token is read. #[test] fn cli_prints_the_same_document_offline() { let run = |args: &[&str]| -> Value { let output = std::process::Command::new(env!("CARGO_BIN_EXE_slinuxm")) .args(args) .arg("--config") .arg("/nonexistent/slinuxm-openapi.toml") .output() .expect("the slinuxm binary runs"); assert!( output.status.success(), "slinuxm {args:?} failed: {}", String::from_utf8_lossy(&output.stderr) ); serde_json::from_slice(&output.stdout).expect("the output is JSON") }; for (peers, extra) in [(false, None), (true, Some("--peers"))] { let args: Vec<&str> = ["openapi"].into_iter().chain(extra).collect(); let printed = run(&args); assert_eq!( printed, serde_json::to_value(&*document(peers)).unwrap(), "the CLI and the served route must share one generation" ); } }