G: G4 document every error code and both content types per response

This commit is contained in:
ari committed 2026-10-20 15:54:13 -04:00
1 parent 34a1e1644c
commit 214e074cca
5 files changed
+82 -22

No files matched your search

+16 -4
View File
@@ -136,7 +136,7 @@
],
"responses": {
"200": {
"description": "Log lines; `text/event-stream` when following",
"description": "Log lines, or `text/event-stream` with `stdout`/`stderr` events when following",
"content": {
"application/json": {
"schema": {
@@ -145,6 +145,11 @@
"$ref": "#/components/schemas/LogLine"
}
}
},
"text/event-stream": {
"schema": {
"type": "string"
}
}
}
},
@@ -585,9 +590,14 @@
],
"responses": {
"200": {
"description": "The peer's body, with `x-slinuxm-peer`, `Content-Type` (`application/json` or `text/event-stream`) and the peer's status",
"description": "The peer's body with the peer's status and `x-slinuxm-peer`; JSON, or `text/event-stream` for a follow",
"content": {
"text/plain": {
"application/json": {
"schema": {
"type": "string"
}
},
"text/event-stream": {
"schema": {
"type": "string"
}
@@ -1194,7 +1204,9 @@
"bad_request",
"unauthorized",
"unavailable",
"internal"
"internal",
"method_not_allowed",
"forbidden_host"
]
},
"message": {
+2
View File
@@ -43,3 +43,5 @@ Reuse existing DTOs, do not duplicate types for the doc. Read-only, no secrets i
Docs: `docs/api.md` gains a "Generated reference (OpenAPI)" section (what the file contains, `GET /api/v1/openapi.json`, `slinuxm openapi [--peers]`, regeneration, what the tests guard) and a route-table row; `README.md` gets a short paragraph in the REST section. `config.example.toml` needs nothing (no new key). `docs/README.md` does not list `docs/openapi.json` yet; it is outside this workstream's owned files, so the merger should add the row.
Verification: `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, `cargo test` green (10 tests in `tests/openapi.rs`, 12 unit tests in `src/openapi.rs`/`src/cli.rs`); `cargo tree -i openssl` empty; the committed spec contains no token, token-file path or URL other than the documented default server. No nix build was run; no VM test is involved in this workstream.
- 2026-10-20: **G4 self-review fixes.** Three accuracy gaps found on a second read: the `ErrorBody.code` enum listed only the `AppError` codes, but two status-only bodies reuse `error_response` (`method_not_allowed` from the 405 fallback, `forbidden_host` from the auth-off Host guard), so both are now documented and `every_error_code_is_documented` ties the enum to `AppError::code()` plus those two; the docker `logs` and the peer pass-through 200s now declare both `application/json` and `text/event-stream` instead of JSON only; `schema_type` no longer maps an unknown JSON Schema type name to `object` (it leaves the type out), so the converter cannot invent a type the DTO does not have. Spec regenerated.
+3 -1
View File
@@ -125,7 +125,9 @@ pub(crate) struct LogParams {
description = "`1`/`true` streams new lines as SSE, `0`/`false` (default) returns a snapshot"
)),
responses(
(status = 200, body = Vec<LogLine>, description = "Log lines; `text/event-stream` when following"),
(status = 200,
description = "Log lines, or `text/event-stream` with `stdout`/`stderr` events when following",
content((Vec<LogLine> = "application/json"), (String = "text/event-stream"))),
(status = 400, body = ErrorBody, description = "Invalid query parameter"),
(status = 401, body = ErrorBody, description = "Missing or unknown bearer token"),
(status = 404, body = ErrorBody, description = "Unknown container"),
+3 -1
View File
@@ -112,7 +112,9 @@ pub(crate) async fn one(
description = "Peer route below `/api/v1`, e.g. `systemd/units`"
)),
responses(
(status = 200, body = String, description = "The peer's body, with `x-slinuxm-peer`, `Content-Type` (`application/json` or `text/event-stream`) and the peer's status"),
(status = 200,
description = "The peer's body with the peer's status and `x-slinuxm-peer`; JSON, or `text/event-stream` for a follow",
content((String = "application/json"), (String = "text/event-stream"))),
(status = 400, body = ErrorBody, description = "Path or query not allowed, or a chained request (`x-slinuxm-hop`)"),
(status = 401, body = ErrorBody, description = "Missing or unknown bearer token"),
(status = 404, body = ErrorBody, description = "Unknown peer, or the peer answered 404"),
+58 -16
View File
@@ -294,6 +294,9 @@ reflected_schema!(ContainerSummary, ContainerStatus, LogLine);
/// schemars output, so a keyword this function does not know fails a test
/// instead of vanishing from the document.
fn convert(value: &Value) -> RefOr<Schema> {
// `reflected` inlines every nested schema, so a `$ref` cannot occur; a
// keyword this function does not know is dropped, which the parity test
// turns into a failure as soon as a DTO starts emitting one.
let object = value.as_object().cloned().unwrap_or_default();
let description = object.get("description").and_then(Value::as_str);
if let Some(items) = list(&object, "oneOf") {
@@ -368,22 +371,27 @@ fn list<'a>(object: &'a Map<String, Value>, key: &str) -> Option<&'a Vec<Value>>
}
fn schema_type(value: Option<&Value>) -> SchemaType {
match value {
None => SchemaType::AnyValue,
Some(Value::String(name)) => SchemaType::Type(scalar_type(name)),
Some(Value::Array(names)) => names
.iter()
.filter_map(Value::as_str)
.map(scalar_type)
.collect::<Vec<_>>()
.into_iter()
.collect::<SchemaType>(),
Some(_) => SchemaType::AnyValue,
let names: Vec<&str> = match value {
Some(Value::String(name)) => vec![name.as_str()],
Some(Value::Array(names)) => names.iter().filter_map(Value::as_str).collect(),
_ => return SchemaType::AnyValue,
};
match names
.iter()
.filter_map(|name| scalar_type(name))
.collect::<Vec<Type>>()
.as_slice()
{
[] => SchemaType::AnyValue,
[single] => SchemaType::Type(single.clone()),
many => SchemaType::Array(many.to_vec()),
}
}
fn scalar_type(name: &str) -> Type {
match name {
/// `None` for a name utoipa cannot express, which leaves the type out rather
/// than inventing one.
fn scalar_type(name: &str) -> Option<Type> {
Some(match name {
"string" => Type::String,
"integer" => Type::Integer,
"number" => Type::Number,
@@ -391,8 +399,8 @@ fn scalar_type(name: &str) -> Type {
"object" => Type::Object,
"array" => Type::Array,
"null" => Type::Null,
_ => Type::Object,
}
_ => return None,
})
}
fn number_value(value: &Value) -> Option<utoipa::Number> {
@@ -461,7 +469,9 @@ handwritten_schema!(
"bad_request",
"unauthorized",
"unavailable",
"internal"
"internal",
"method_not_allowed",
"forbidden_host",
]
.into_iter()
.map(Value::from),
@@ -799,6 +809,38 @@ mod tests {
);
}
/// The `code` enum is handwritten, so it is tied to the codes the server
/// can emit: one per `AppError` variant plus the two status-only bodies.
#[test]
fn every_error_code_is_documented() {
let doc = document(false);
let schema = component::<ErrorBody>(&doc, "ErrorBody");
let documented: Vec<&str> = schema["properties"]["error"]["properties"]["code"]["enum"]
.as_array()
.unwrap()
.iter()
.map(|v| v.as_str().unwrap())
.collect();
let errors = [
crate::error::AppError::NotFound(String::new()),
crate::error::AppError::BadRequest(String::new()),
crate::error::AppError::Unauthorized(String::new()),
crate::error::AppError::Unavailable(String::new()),
crate::error::AppError::Internal(String::new()),
];
for error in &errors {
assert!(
documented.contains(&error.code()),
"{} is not documented",
error.code()
);
}
for code in ["method_not_allowed", "forbidden_host"] {
assert!(documented.contains(&code), "{code} is not documented");
}
assert_eq!(documented.len(), errors.len() + 2);
}
#[test]
fn auth_state_enum_matches_serialization() {
let doc = document(true);