G: G1 REST spec derive the OpenAPI document from the handlers

This commit is contained in:
ari committed 2026-10-20 15:54:13 -04:00
1 parent 5f4a0583f3
commit 3d8e840427
13 files changed
+1347 -20

No files matched your search

+72 -5
View File
@@ -15,6 +15,7 @@ use axum::{Json, Router};
use serde::Serialize;
use crate::error::AppError;
use crate::openapi::ErrorBody;
use crate::peers::proxy::{self, PreparedBody, PreparedResponse};
use crate::peers::types::{PeerName, PeerStatus};
use crate::peers::{PeerRegistry, ProxyOpts};
@@ -27,8 +28,8 @@ pub fn routes() -> Router<AppState> {
.route("/peers/{peer}/{*path}", get(pass))
}
#[derive(Serialize)]
struct PeerList {
#[derive(Serialize, utoipa::ToSchema)]
pub(crate) struct PeerList {
peers: Vec<PeerStatus>,
}
@@ -40,20 +41,86 @@ fn registry(st: &AppState) -> &PeerRegistry {
.expect("peer routes are mounted only with a peer registry")
}
async fn list(State(st): State<AppState>) -> Json<PeerList> {
#[utoipa::path(
get,
path = "/api/v1/peers",
operation_id = "list_peers",
tag = "peers",
summary = "Peer status list",
description = "Every configured peer, sorted by name, including disabled ones. Present only \
when `[peers] enabled = true`.",
responses(
(status = 200, body = PeerList, description = "Peer status, sorted by name"),
(status = 401, body = ErrorBody, description = "Missing or unknown bearer token"),
)
)]
pub(crate) async fn list(State(st): State<AppState>) -> Json<PeerList> {
Json(PeerList {
peers: registry(&st).snapshot(),
})
}
async fn one(
#[utoipa::path(
get,
path = "/api/v1/peers/{peer}",
operation_id = "get_peer",
tag = "peers",
summary = "Status of one peer",
params((
"peer" = String,
Path,
description = "Configured peer name"
)),
responses(
(status = 200, body = PeerStatus, description = "The peer, not wrapped in an object"),
(status = 401, body = ErrorBody, description = "Missing or unknown bearer token"),
(status = 404, body = ErrorBody, description = "Unknown peer"),
)
)]
pub(crate) async fn one(
State(st): State<AppState>,
Path(peer): Path<String>,
) -> Result<Json<PeerStatus>, AppError> {
Ok(Json(registry(&st).status(&peer)?))
}
async fn pass(
/// Pass-through of one peer's read routes. The wildcard is documented as one
/// operation because the peer's own routes are the peer's business; the
/// allowlist below is what this instance forwards.
#[utoipa::path(
get,
path = "/api/v1/peers/{peer}/{path}",
operation_id = "proxy_peer_get",
tag = "peers",
summary = "GET-only pass-through to a peer",
description = "Forwards a GET to the same path on the peer and returns the peer's status and \
body unchanged for 2xx. Allowed paths: `systemd/units`, \
`systemd/units/{name}`, `systemd/timers`, `journal`, `journal/follow`, \
`docker/ps`, `docker/containers/{name}`, `docker/containers/{name}/logs`. \
`ping` and `peers/...` are not forwarded, nor is any other path. Query keys \
are those the local route accepts (`state`, `unit`, `priority`, `lines`, \
`since`, `all`, `tail`, `follow`). Only GET is accepted. A peer failure is a \
503 naming the peer, never a 401: a peer rejecting the consolidator's token \
does not mean the caller must re-authenticate here. Peer data is untrusted.",
params((
"peer" = String,
Path,
description = "Configured peer name"
), (
"path" = String,
Path,
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 = 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"),
(status = 405, body = ErrorBody, description = "Not a GET"),
(status = 503, body = ErrorBody, description = "Peer unreachable, timed out, rejected the consolidator's token, exceeded the size cap, or answered another error status"),
)
)]
pub(crate) async fn pass(
State(st): State<AppState>,
Path((peer, _path)): Path<(String, String)>,
request: Request,