621 lines
21 KiB
Rust
621 lines
21 KiB
Rust
//! 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> {
|
|
[
|
|
(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<Vec<Method>>,
|
|
}
|
|
|
|
/// Every `.rs` file below `src/api`, recursively, in stable order.
|
|
fn api_files() -> Vec<std::path::PathBuf> {
|
|
fn walk(dir: &Path, out: &mut Vec<std::path::PathBuf>) {
|
|
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<Route> {
|
|
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<Route> {
|
|
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<Route> {
|
|
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<Method> {
|
|
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<Method> {
|
|
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<String> {
|
|
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 {
|
|
// `DELETE /mcp` ends an MCP session, a server-local session
|
|
// only; it is not a write path to the host.
|
|
let session = matches!((method, path.as_str()), ("post" | "delete", "/mcp"));
|
|
assert!(session, "{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<String> = 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"
|
|
);
|
|
}
|
|
}
|