G: F2 reflect peer status schemas from JsonSchema derives

This commit is contained in:
ari committed 2026-10-20 15:54:13 -04:00
1 parent 1506af11fc
commit d2917b2483
3 files changed
+155 -184

No files matched your search

+113 -21
View File
@@ -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"
+26 -158
View File
@@ -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": ["<scalar>", "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::<Vec<Type>>()
.into_iter()
.collect::<SchemaType>(),
)
}
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)
+16 -5
View File
@@ -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<Timestamp>,
pub last_checked: Option<Timestamp>,
/// Failure class such as `timeout` or `unreachable`; never a URL or a secret.
pub last_error: Option<String>,
pub latency_ms: Option<u64>,
}
#[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<Timestamp>,
pub last_checked: Option<Timestamp>,
/// Failure class such as `http_500` or `token_file`; never a URL or a secret.
pub last_error: Option<String>,
pub latency_ms: Option<u64>,
/// 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<String>,
}
/// `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,