diff --git a/docs/openapi.json b/docs/openapi.json index 339a6dd..19738b1 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -964,19 +964,19 @@ "schemas": { "ApiStatus": { "type": "object", - "description": "\"API running\": an authenticated `GET /api/v1/ping`. `up` is true also when the peer answered 401, so a revoked token reads as `auth = rejected` rather than as an outage.", "required": [ "up", - "since", - "last_checked", - "last_error", - "latency_ms", - "auth", - "peer_version" + "auth" ], "properties": { "auth": { - "$ref": "#/components/schemas/AuthState" + "type": "string", + "description": "State of the consolidator's credential on the peer.", + "enum": [ + "ok", + "rejected", + "unknown" + ] }, "last_checked": { "type": [ @@ -997,6 +997,7 @@ "integer", "null" ], + "format": "uint64", "minimum": 0 }, "peer_version": { @@ -1012,7 +1013,7 @@ "null" ], "format": "date-time", - "description": "Time of the last state change; null until the first check and reset on restart." + "description": "Last change; `None` until the first check and reset on restart." }, "up": { "type": "boolean" @@ -1021,7 +1022,7 @@ }, "AuthState": { "type": "string", - "description": "State of the consolidator's credential on the peer: `ok`, `rejected` or `unknown`.", + "description": "`Ok` and `Rejected` refer to our credential; `Unknown` is used before the\nfirst check and for peers without the authenticated ping endpoint.", "enum": [ "ok", "rejected", @@ -1360,7 +1361,7 @@ }, "PeerStatus": { "type": "object", - "description": "One configured peer and the last result of both health checks.", + "description": "Registry snapshot entry, serialized as-is by REST and MCP.", "required": [ "name", "enabled", @@ -1370,7 +1371,63 @@ ], "properties": { "api": { - "$ref": "#/components/schemas/ApiStatus" + "type": "object", + "description": "\"API running\": an authenticated `GET /api/v1/ping`.", + "required": [ + "up", + "auth" + ], + "properties": { + "auth": { + "type": "string", + "description": "State of the consolidator's credential on the peer.", + "enum": [ + "ok", + "rejected", + "unknown" + ] + }, + "last_checked": { + "type": [ + "string", + "null" + ], + "format": "date-time" + }, + "last_error": { + "type": [ + "string", + "null" + ], + "description": "Failure class such as `http_500` or `token_file`; never a URL or a secret." + }, + "latency_ms": { + "type": [ + "integer", + "null" + ], + "format": "uint64", + "minimum": 0 + }, + "peer_version": { + "type": [ + "string", + "null" + ], + "description": "Version the peer reported, when it has the ping route." + }, + "since": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Last change; `None` until the first check and reset on restart." + }, + "up": { + "type": "boolean" + } + } }, "enabled": { "type": "boolean", @@ -1378,10 +1435,49 @@ }, "name": { "type": "string", - "description": "Configured peer name, `^[a-z0-9][a-z0-9_-]{0,31}$`." + "description": "Configured peer name." }, "server": { - "$ref": "#/components/schemas/ServerStatus" + "type": "object", + "description": "\"Server up\": a TCP connect to the peer's host and port.", + "required": [ + "up" + ], + "properties": { + "last_checked": { + "type": [ + "string", + "null" + ], + "format": "date-time" + }, + "last_error": { + "type": [ + "string", + "null" + ], + "description": "Failure class such as `timeout` or `unreachable`; never a URL or a secret." + }, + "latency_ms": { + "type": [ + "integer", + "null" + ], + "format": "uint64", + "minimum": 0 + }, + "since": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Last change; `None` until the first check and reset on restart." + }, + "up": { + "type": "boolean" + } + } }, "url": { "type": "string", @@ -1391,13 +1487,8 @@ }, "ServerStatus": { "type": "object", - "description": "\"Server up\": a TCP connect to the peer's host and port.", "required": [ - "up", - "since", - "last_checked", - "last_error", - "latency_ms" + "up" ], "properties": { "last_checked": { @@ -1419,6 +1510,7 @@ "integer", "null" ], + "format": "uint64", "minimum": 0 }, "since": { @@ -1427,7 +1519,7 @@ "null" ], "format": "date-time", - "description": "Time of the last state change; null until the first check and reset on restart." + "description": "Last change; `None` until the first check and reset on restart." }, "up": { "type": "boolean" diff --git a/src/openapi.rs b/src/openapi.rs index ef6d02a..87724d5 100644 --- a/src/openapi.rs +++ b/src/openapi.rs @@ -6,13 +6,12 @@ //! collected by `ApiDoc`; the MCP tools come from the tool router's own //! schemars schemas. Nothing here talks to D-Bus, journald or Docker. //! -//! Response DTOs already derive `schemars::JsonSchema` for the MCP surface, so -//! their spec schemas are reflected from that derive rather than declared a -//! second time: a field added to a DTO appears in the document without an -//! edit here. The exceptions are payloads that exist only as `serde_json` -//! literals (the error body, health) and the peer status types, which are -//! described by hand; the tests compare both with the JSON the server really -//! produces, so a field cannot go missing quietly. +//! Response DTOs derive `schemars::JsonSchema` for the MCP surface, so their +//! spec schemas are reflected from that derive rather than declared a second +//! time: a field added to a DTO appears in the document without an edit here. +//! The only hand-written schemas are payloads that exist as `serde_json` +//! literals (the error body and health); the tests compare them with the JSON +//! the server really produces, so a field cannot go missing quietly. use std::borrow::Cow; use std::sync::{Arc, OnceLock}; @@ -28,7 +27,7 @@ use utoipa::openapi::schema::{ use utoipa::openapi::security::{HttpAuthScheme, HttpBuilder, SecurityScheme}; use utoipa::openapi::tag::TagBuilder; use utoipa::openapi::{ - Info, InfoBuilder, License, OpenApi, Ref, RefOr, SecurityRequirement, ServerBuilder, + Info, InfoBuilder, License, OpenApi, RefOr, SecurityRequirement, ServerBuilder, }; use utoipa::{OpenApi as OpenApiDoc, PartialSchema, ToSchema}; @@ -286,6 +285,7 @@ macro_rules! reflected_schema { reflected_schema!(UnitSummary, UnitStatus, TimerInfo, JournalEntry); reflected_schema!(ContainerSummary, ContainerStatus, LogLine); +reflected_schema!(PeerStatus, ServerStatus, ApiStatus, AuthState); /// Translate one JSON Schema 2020-12 object into utoipa's model. /// @@ -500,152 +500,6 @@ handwritten_schema!( .into() ); -handwritten_schema!( - AuthState, - "AuthState", - ObjectBuilder::new() - .description(Some( - "State of the consolidator's credential on the peer: `ok`, `rejected` or `unknown`.", - )) - .schema_type(Type::String) - .enum_values(Some( - ["ok", "rejected", "unknown"].into_iter().map(Value::from) - )) - .into() -); - -handwritten_schema!( - ServerStatus, - "ServerStatus", - check_properties( - ObjectBuilder::new() - .description(Some( - "\"Server up\": a TCP connect to the peer's host and port." - )) - .required("up") - .required("since") - .required("last_checked") - .required("last_error") - .required("latency_ms"), - "Failure class such as `timeout` or `unreachable`; never a URL or a secret.", - ) - .into() -); - -handwritten_schema!( - ApiStatus, - "ApiStatus", - check_properties( - ObjectBuilder::new() - .description(Some( - "\"API running\": an authenticated `GET /api/v1/ping`. `up` is true also when the \ - peer answered 401, so a revoked token reads as `auth = rejected` rather than as an \ - outage.", - )) - .required("up") - .required("since") - .required("last_checked") - .required("last_error") - .required("latency_ms") - .required("auth") - .required("peer_version"), - "Failure class such as `http_500` or `token_file`; never a URL or a secret.", - ) - .property("auth", Ref::from_schema_name("AuthState")) - .property( - "peer_version", - nullable(Type::String).description(Some( - "Version the peer reported, when it has the ping route." - )), - ) - .into() -); - -handwritten_schema!( - PeerStatus, - "PeerStatus", - ObjectBuilder::new() - .description(Some( - "One configured peer and the last result of both health checks." - )) - .required("name") - .required("enabled") - .required("url") - .required("server") - .required("api") - .property( - "name", - ObjectBuilder::new() - .schema_type(Type::String) - .description(Some("Configured peer name, `^[a-z0-9][a-z0-9_-]{0,31}$`.")), - ) - .property( - "enabled", - ObjectBuilder::new() - .schema_type(Type::Boolean) - .description(Some( - "`false` for a peer kept in configuration but not checked." - )), - ) - .property( - "url", - ObjectBuilder::new() - .schema_type(Type::String) - .description(Some( - "Display form of the configured URL; never carries credentials.", - )), - ) - .property("server", Ref::from_schema_name("ServerStatus")) - .property("api", Ref::from_schema_name("ApiStatus")) - .into() -); - -/// Shared by both checks; the registry resets it on restart. -const SINCE_DOC: &str = - "Time of the last state change; null until the first check and reset on restart."; - -/// `{"type": ["", "null"]}`, how JSON Schema 2020-12 marks an -/// optional value. utoipa renders a two-type `SchemaType` the same way. -fn nullable(ty: Type) -> ObjectBuilder { - ObjectBuilder::new().schema_type( - [ty, Type::Null] - .into_iter() - .collect::>() - .into_iter() - .collect::(), - ) -} - -fn date_time() -> SchemaFormat { - SchemaFormat::Custom("date-time".into()) -} - -/// The properties both peer checks share: `up`, `since` and `last_checked` -/// (described by [`SINCE_DOC`]), `last_error` with its check-specific wording -/// and `latency_ms`. Added in document order so the keys stay where they were. -fn check_properties(builder: ObjectBuilder, last_error: &str) -> ObjectBuilder { - builder - .property("up", ObjectBuilder::new().schema_type(Type::Boolean)) - .property( - "since", - nullable(Type::String) - .format(Some(date_time())) - .description(Some(SINCE_DOC)), - ) - .property( - "last_checked", - nullable(Type::String).format(Some(date_time())), - ) - .property( - "last_error", - nullable(Type::String).description(Some(last_error)), - ) - .property( - "latency_ms", - nullable(Type::Integer).minimum(Some(utoipa::Number::UInt(0))), - ) -} - #[cfg(test)] mod tests { use super::*; @@ -682,17 +536,25 @@ mod tests { JournalEntry, ContainerSummary, ContainerStatus, - LogLine + LogLine, + PeerStatus, + ServerStatus, + ApiStatus, + AuthState ); } - /// Compare the properties of a schema object with the keys of a JSON - /// instance; a field added to the type fails the test. + /// Compare a schema object with a JSON instance in both directions: every + /// serialized key must be documented, and every documented property must + /// be serialized. A renamed field fails both ways and no stale property + /// survives. fn assert_covers(schema: &Value, instance: &Value, what: &str) { + if instance.is_null() { + return; + } let (schema, instance) = match (schema, instance) { (Value::Object(schema), Value::Object(instance)) => (schema, instance), // A `$ref` points at a component covered by another assertion. - (_, Value::Null) => return, _ => panic!("{what}: expected object schemas and instances"), }; if let Some(reference) = schema.get("$ref").and_then(Value::as_str) { @@ -703,6 +565,12 @@ mod tests { .get("properties") .and_then(Value::as_object) .unwrap_or_else(|| panic!("{what}: no properties")); + for key in properties.keys() { + assert!( + instance.contains_key(key), + "{what}: documented property {key} is not serialized" + ); + } for (key, value) in instance { let property = properties .get(key) diff --git a/src/peers/types.rs b/src/peers/types.rs index a142412..0005c5a 100644 --- a/src/peers/types.rs +++ b/src/peers/types.rs @@ -16,7 +16,8 @@ pub const MAX_PEERS: usize = 64; /// /// Names end up in URLs, MCP arguments and metric attributes, so the /// character set is deliberately narrow. -#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)] +#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, schemars::JsonSchema)] +#[schemars(transparent)] pub struct PeerName(String); impl PeerName { @@ -160,39 +161,49 @@ impl Default for PeersConfig { } /// Registry snapshot entry, serialized as-is by REST and MCP. -#[derive(Debug, Clone, PartialEq, Serialize)] +#[derive(Debug, Clone, PartialEq, Serialize, schemars::JsonSchema)] pub struct PeerStatus { + /// Configured peer name. pub name: PeerName, + /// `false` for a peer kept in configuration but not checked. pub enabled: bool, + /// Display form of the configured URL; never carries credentials. pub url: String, + /// "Server up": a TCP connect to the peer's host and port. pub server: ServerStatus, + /// "API running": an authenticated `GET /api/v1/ping`. pub api: ApiStatus, } -#[derive(Debug, Clone, PartialEq, Default, Serialize)] +#[derive(Debug, Clone, PartialEq, Default, Serialize, schemars::JsonSchema)] pub struct ServerStatus { pub up: bool, /// Last change; `None` until the first check and reset on restart. pub since: Option, pub last_checked: Option, + /// Failure class such as `timeout` or `unreachable`; never a URL or a secret. pub last_error: Option, pub latency_ms: Option, } -#[derive(Debug, Clone, PartialEq, Default, Serialize)] +#[derive(Debug, Clone, PartialEq, Default, Serialize, schemars::JsonSchema)] pub struct ApiStatus { pub up: bool, + /// Last change; `None` until the first check and reset on restart. pub since: Option, pub last_checked: Option, + /// Failure class such as `http_500` or `token_file`; never a URL or a secret. pub last_error: Option, pub latency_ms: Option, + /// State of the consolidator's credential on the peer. pub auth: AuthState, + /// Version the peer reported, when it has the ping route. pub peer_version: Option, } /// `Ok` and `Rejected` refer to our credential; `Unknown` is used before the /// first check and for peers without the authenticated ping endpoint. -#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize)] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, schemars::JsonSchema)] #[serde(rename_all = "snake_case")] pub enum AuthState { Ok,