//! 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) } /// Route literals under `src/api`, which `server.rs` nests at `/api/v1`. fn api_route_literals() -> Vec { let dir = Path::new(MANIFEST).join("src/api"); let mut out = Vec::new(); let mut files: Vec<_> = fs::read_dir(&dir) .unwrap() .map(|entry| entry.unwrap().path()) .filter(|path| path.extension().is_some_and(|e| e == "rs")) .collect(); files.sort(); for file in files { let source = fs::read_to_string(&file).unwrap(); out.extend(route_literals(&source).into_iter().map(|route| { assert!(route.starts_with('/'), "{}: {route}", file.display()); format!("/api/v1{route}") })); } out } /// Route literals declared outside the API router: `/healthz` and the `/mcp` /// mount in `server.rs`. fn server_route_literals() -> Vec { let source = fs::read_to_string(Path::new(MANIFEST).join("src/server.rs")).unwrap(); let mut out = route_literals(&source); let mount = ".nest_service(\"/mcp\""; assert!(source.contains(mount), "server.rs no longer mounts /mcp"); out.push("/mcp".to_owned()); out.sort(); out } /// The path argument of every `.route("...")` call. Splitting on the marker /// keeps this independent of how the call is formatted. Mount points /// (`.nest`, `.nest_service`) are added by the caller. fn route_literals(source: &str) -> Vec { let marker = ".route(\""; source .match_indices(marker) .map(|(index, _)| { let rest = &source[index + marker.len()..]; let end = rest.find('"').expect("a route literal ends"); rest[..end].to_owned() }) .collect() } #[tokio::test] async fn every_router_route_is_documented() { let doc = document(true); let mut routes = api_route_literals(); routes.extend(server_route_literals()); // A scan that stops matching would make the check below vacuous. assert!( routes.len() >= 13, "route scan found too little: {routes:?}" ); for route in routes { let route = openapi_path(&route); assert!( doc.paths.paths.contains_key(&route), "{route} is routed but missing from the OpenAPI document" ); } } #[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" ); } }