G: F2 reflect peer status schemas from JsonSchema derives
This commit is contained in:
1 parent
1506af11fc
commit
d2917b2483
3 files changed
+155
-184
No files matched your search
+26
-158
@@ -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)
|
||||
|
||||
Reference in new issue
Block a user