From 214e074cca77dd13a1b6a23826587f6f09e8a6fe Mon Sep 17 00:00:00 2001 From: ari Date: Tue, 20 Oct 2026 11:02:35 -0400 Subject: [PATCH] G: G4 document every error code and both content types per response --- docs/openapi.json | 20 +++++++++--- plan/ws-g-openapi.md | 2 ++ src/api/docker.rs | 4 ++- src/api/peers.rs | 4 ++- src/openapi.rs | 74 ++++++++++++++++++++++++++++++++++---------- 5 files changed, 82 insertions(+), 22 deletions(-) diff --git a/docs/openapi.json b/docs/openapi.json index 387f24c..339a6dd 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -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": { diff --git a/plan/ws-g-openapi.md b/plan/ws-g-openapi.md index b95f58d..87e86ba 100644 --- a/plan/ws-g-openapi.md +++ b/plan/ws-g-openapi.md @@ -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. diff --git a/src/api/docker.rs b/src/api/docker.rs index ff50e53..4cd38a7 100644 --- a/src/api/docker.rs +++ b/src/api/docker.rs @@ -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, 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 = "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"), diff --git a/src/api/peers.rs b/src/api/peers.rs index 8197587..26c56f5 100644 --- a/src/api/peers.rs +++ b/src/api/peers.rs @@ -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"), diff --git a/src/openapi.rs b/src/openapi.rs index c42ae93..97b63b1 100644 --- a/src/openapi.rs +++ b/src/openapi.rs @@ -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 { + // `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, key: &str) -> Option<&'a Vec> } 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::>() - .into_iter() - .collect::(), - 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::>() + .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 { + 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 { @@ -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::(&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);