G: G1 REST spec derive the OpenAPI document from the handlers
This commit is contained in:
1 parent
5f4a0583f3
commit
3d8e840427
13 files changed
+1347
-20
No files matched your search
+72
-5
@@ -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,
|
||||
|
||||
Reference in new issue
Block a user