From 4bfb097be68822513173e74d15f701025c19301c Mon Sep 17 00:00:00 2001 From: ari Date: Mon, 19 Oct 2026 17:50:24 -0400 Subject: [PATCH] A0: contract stubs types, transport, fake and registry seams Land the shared peer contracts: types, error mapping, transport trait, fake transport and fixtures, registry/proxy/health skeletons, the AppState.peers and Config.peers seams, the ping and peers route stubs, and unit plus integration tests. No loops, no network, feature off by default. --- Cargo.lock | 3 + Cargo.toml | 2 + plan/phase-5-consolidator/ws-a-config.md | 6 + plan/phase-5-consolidator/ws-c-rest.md | 1 + plan/phase-5-consolidator/ws-d-mcp.md | 1 + plan/phase-5-consolidator/ws-e-telemetry.md | 1 + src/api/mod.rs | 12 +- src/api/peers.rs | 12 + src/api/ping.rs | 41 ++ src/config.rs | 3 + src/lib.rs | 1 + src/peers/error.rs | 172 ++++++++ src/peers/health.rs | 164 ++++++++ src/peers/mod.rs | 17 + src/peers/proxy.rs | 114 ++++++ src/peers/registry.rs | 254 ++++++++++++ src/peers/testing.rs | 433 ++++++++++++++++++++ src/peers/transport.rs | 61 +++ src/peers/types.rs | 319 ++++++++++++++ src/sources/fake.rs | 1 + src/state.rs | 4 + tests/peers_config.rs | 160 ++++++++ 22 files changed, 1781 insertions(+), 1 deletion(-) create mode 100644 src/api/peers.rs create mode 100644 src/api/ping.rs create mode 100644 src/peers/error.rs create mode 100644 src/peers/health.rs create mode 100644 src/peers/mod.rs create mode 100644 src/peers/proxy.rs create mode 100644 src/peers/registry.rs create mode 100644 src/peers/testing.rs create mode 100644 src/peers/transport.rs create mode 100644 src/peers/types.rs create mode 100644 tests/peers_config.rs diff --git a/Cargo.lock b/Cargo.lock index 13e1c31..c5af64c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2815,6 +2815,7 @@ dependencies = [ "axum", "base64 0.23.1", "bollard", + "bytes", "clap", "figment", "futures", @@ -2845,6 +2846,7 @@ dependencies = [ "tracing", "tracing-opentelemetry", "tracing-subscriber", + "url", "zbus", "zbus_systemd", ] @@ -3675,6 +3677,7 @@ dependencies = [ "idna", "percent-encoding", "serde", + "serde_derive", ] [[package]] diff --git a/Cargo.toml b/Cargo.toml index d81ad04..053ff6f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -35,8 +35,10 @@ tokio-rustls = { version = "0.26.5", default-features = false, features = ["ring hyper-util = { version = "0.1.21", features = ["tokio", "server-auto", "service"] } # Data +bytes = "1.12.1" serde = { version = "1.0.229", features = ["derive"] } serde_json = "1.0.154" +url = { version = "2.5.8", features = ["serde"] } percent-encoding = "2.3.2" schemars = { version = "1.2.3", features = ["jiff02"] } jiff = { version = "0.2.38", features = ["serde"] } diff --git a/plan/phase-5-consolidator/ws-a-config.md b/plan/phase-5-consolidator/ws-a-config.md index 63403ea..293c085 100644 --- a/plan/phase-5-consolidator/ws-a-config.md +++ b/plan/phase-5-consolidator/ws-a-config.md @@ -44,6 +44,7 @@ Unit tests for validation and loader; a peer-less default config is byte-identic ## Handoff +- 2026-10-19 (A0): stubs are on branch `ws/A0`; C, D, E and B can compile against `src/peers/` now. Rebase rather than re-creating the files. `src/peers/{types,error,transport,testing}.rs` change only through contracts.md after this point; `registry.rs`, `proxy.rs` and `health.rs` are skeletons to be filled by WS-B (registry, health) and WS-C (proxy). - A0 merged: C, D, E, B compile against the stubs; post in all their Logs. - `PeersConfig`/`PeerConfig`, the secrets loader (`Secret`, `load_token(&PeerConfig) -> Result`) and `config.example.toml` `[peers]` block for B and F. - The `peer` subcommand for the docs (F4). @@ -51,3 +52,8 @@ Unit tests for validation and loader; a peer-less default config is byte-identic ## Log - 2026-10-19: Split from the single phase plan 2026-10-19. A0 added to cover the shared stubs so C/D/E/F can start against fakes; ownership of the stub files passes to B/C after A0 merges. +- 2026-10-19 A0 (done): contract stubs landed. `src/peers/{types,error,transport,testing,registry,proxy,health}.rs`, `src/api/{ping,peers}.rs` stubs, `AppState.peers`, `Config.peers`, `src/api/mod.rs` merge seam, `tests/peers_config.rs`. + - Decisions taken here (contract allows the implementer to choose): timestamps are `jiff::Timestamp` (the type the existing DTOs use); `testing.rs` is plain `pub` like `sources::fake`, because integration tests compile the library without `cfg(test)`; `health::check_once` is a minimal TCP + `GET /api/v1/ping` probe (401/403 -> `api.up = true, auth = rejected`, D4) and WS-B replaces its classification/version parsing; `ProxyOpts` lives in `registry.rs` as the contract says; `proxy::get` already adds `x-slinuxm-hop: 1` and any traceparent (never an Authorization header) but no allowlist (WS-C). + - Contract discrepancy: section 3 declares `reload(&self, new: PeersConfig) -> Result<(), PeerConfigError>` but no `PeerConfigError` type exists in the contract or the tree. Implemented as `Result<(), crate::config::ConfigError>` (the existing error for invalid configuration). Please fix the name in contracts.md if that is not the intent. + - `Cargo.toml`: added `url` (needed for the contract's `url::Url` field, already in `Cargo.lock` via reqwest) and `bytes` (contract's `Bytes` body type, already in the lock). `cargo tree -i openssl` still empty. + - Logged in WS-C, WS-D and WS-E: stubs are available, compile against them. diff --git a/plan/phase-5-consolidator/ws-c-rest.md b/plan/phase-5-consolidator/ws-c-rest.md index ee55e9f..babe1b4 100644 --- a/plan/phase-5-consolidator/ws-c-rest.md +++ b/plan/phase-5-consolidator/ws-c-rest.md @@ -43,3 +43,4 @@ Behaviour tests with the fake transport for every error mapping row in D9; 405 o ## Log - 2026-10-19: Split from the single phase plan 2026-10-19. The proxy logic is placed in `src/peers/proxy.rs` (not `api/peers.rs`) so REST and MCP share one implementation, as the original plan required. +- 2026-10-19 (A0): contract stubs landed (`src/peers/{types,error,transport,testing,registry,proxy,health}.rs`, `src/api/peers.rs` stub, `AppState.peers`, `Config.peers`, `tests/peers_config.rs`). `PeerRegistry::get` forwards through `PeerTransport` and `proxy.rs` already adds `x-slinuxm-hop` and traceparent; path/query allowlists, the hop-header rejection and the `x-slinuxm-peer` response header are still yours. `api::peers::routes()` is empty and merged only when `state.peers.is_some()`, so fill it without touching `api/mod.rs`. diff --git a/plan/phase-5-consolidator/ws-d-mcp.md b/plan/phase-5-consolidator/ws-d-mcp.md index f7b9e26..88d5745 100644 --- a/plan/phase-5-consolidator/ws-d-mcp.md +++ b/plan/phase-5-consolidator/ws-d-mcp.md @@ -82,3 +82,4 @@ Both snapshot variants pass; each tool with `peer` returns the peer's data via t 4. Not a risk for the rest of D3: `list_resources`, `list_prompts` and `get_info`/instructions are hand-written in this repo, so `peers://status`, the peer-aware prompt argument and the conditional instructions text are plain `state.peers.is_some()` branches, not router features. 5. Runtime toggling is not required (peers are declared at startup; SIGHUP rotates tokens, not `enabled`), but `disable_route`/`enable_route` can emit `notifications/tools/list_changed` via `bind_peer_notifier` if a later phase needs it. - 2026-10-19: **Handoff (D0 complete).** Deliverable: the spike answer and recommendation above. Verdict: `rmcp` 3.5.1 supports the 8/10 conditional tool list natively via `ToolRouter::disable_route`, so D2 can proceed without a contract change; the only follow-up is stripping the optional `peer` property from the eight schemas when peers are disabled (point 3 above). No `src/` production code was changed; the throwaway test was removed after running and the tree is clean apart from this Log. Verification: `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings` and `cargo test` all pass. Commits: findings `c168551`, this handoff. Next: D1/D2 once A0 (`AppState.peers`, `registry_with`, `static_registry`, `fake_state_with_peers`) is merged; rewrite the snapshot test to use `TrackerService::new` for both variants. +- 2026-10-19 (A0): contract stubs landed. `PeerRegistry` (`snapshot`, `status`, `contains`, `config`, `get`) and `ProxyOpts` are available, `AppState.peers: Option>` exists, and `testing::{fake_peers_config, registry_with, static_registry, fake_state_with_peers, FakeTransport}` let MCP tests run without sockets. `PeerRegistry::get` is the single proxy path to call. diff --git a/plan/phase-5-consolidator/ws-e-telemetry.md b/plan/phase-5-consolidator/ws-e-telemetry.md index 712eda9..3418007 100644 --- a/plan/phase-5-consolidator/ws-e-telemetry.md +++ b/plan/phase-5-consolidator/ws-e-telemetry.md @@ -40,3 +40,4 @@ Metrics test with the fake registry; with `otel.enabled` and no peers nothing ne ## Log - 2026-10-19: Split from the single phase plan 2026-10-19. Note added that "peer remove" in the collector check means removal from config plus SIGHUP (D1). +- 2026-10-19 (A0): contract stubs landed. `PeerRegistry::snapshot()` returns `PeerStatus` sorted by name (jiff timestamps, `since: None` until a check), `AppState.peers` is `None` when the feature is off, and `testing::static_registry` renders fixed snapshots for metric tests. diff --git a/src/api/mod.rs b/src/api/mod.rs index d2c87a1..280eaa8 100644 --- a/src/api/mod.rs +++ b/src/api/mod.rs @@ -9,6 +9,8 @@ mod behaviour_tests; pub mod docker; pub mod journal; +pub mod peers; +pub mod ping; pub mod systemd; use std::convert::Infallible; @@ -29,10 +31,18 @@ use crate::state::AppState; /// Routes under `/api/v1`, already bound to `state`. pub fn router(state: AppState) -> Router { - Router::new() + let router = Router::new() .merge(systemd::routes()) .merge(journal::routes()) .merge(docker::routes()) + .merge(ping::routes()); + // Peer routes are absent entirely when the feature is off. + let router = if state.peers.is_some() { + router.merge(peers::routes()) + } else { + router + }; + router .fallback(not_found) .method_not_allowed_fallback(method_not_allowed) .with_state(state) diff --git a/src/api/peers.rs b/src/api/peers.rs new file mode 100644 index 0000000..aefd191 --- /dev/null +++ b/src/api/peers.rs @@ -0,0 +1,12 @@ +//! Peer status and GET-only pass-through routes. +//! +//! Handlers are added here; the module is merged only when `state.peers` is +//! set, so a peer-less instance has no peers routes at all. + +use axum::Router; + +use crate::state::AppState; + +pub fn routes() -> Router { + Router::new() +} diff --git a/src/api/ping.rs b/src/api/ping.rs new file mode 100644 index 0000000..6bee47d --- /dev/null +++ b/src/api/ping.rs @@ -0,0 +1,41 @@ +//! GET /api/v1/ping: cheap authenticated liveness. +//! +//! `/healthz` does not validate a token, so a consolidator cannot use it to +//! prove "API running with our credentials". This route sits behind the same +//! auth layer as every other `/api/v1` route. + +use axum::routing::get; +use axum::{Json, Router}; + +use crate::state::AppState; + +pub fn routes() -> Router { + Router::new().route("/ping", get(ping)) +} + +async fn ping() -> Json { + Json(serde_json::json!({ + "status": "ok", + "version": env!("CARGO_PKG_VERSION"), + })) +} + +#[cfg(test)] +mod tests { + use axum::http::StatusCode; + + use crate::api::router; + use crate::api::testutil::{get, json}; + use crate::config::Config; + use crate::sources::fake::fake_state; + + #[tokio::test] + async fn ping_reports_version() { + let app = router(fake_state(Config::default())); + let (status, body) = get(&app, "/ping").await; + assert_eq!(status, StatusCode::OK); + let v = json(&body); + assert_eq!(v["status"], "ok"); + assert_eq!(v["version"], env!("CARGO_PKG_VERSION")); + } +} diff --git a/src/config.rs b/src/config.rs index 0f14aa3..edd118b 100644 --- a/src/config.rs +++ b/src/config.rs @@ -15,6 +15,8 @@ use figment::providers::{Env, Format, Serialized, Toml}; use figment::Figment; use serde::{Deserialize, Serialize}; +use crate::peers::PeersConfig; + /// Default config file location, used only when it exists and `--config` is absent. pub const DEFAULT_CONFIG_PATH: &str = "/etc/skyg-linux-tracker.toml"; /// Environment variable prefix. @@ -28,6 +30,7 @@ pub struct Config { pub otel: OtelConfig, pub sources: SourcesConfig, pub limits: LimitsConfig, + pub peers: PeersConfig, } #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] diff --git a/src/lib.rs b/src/lib.rs index 88168b4..775e770 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,6 +9,7 @@ pub mod config; pub mod db; pub mod error; pub mod mcp; +pub mod peers; pub mod server; pub mod sources; pub mod state; diff --git a/src/peers/error.rs b/src/peers/error.rs new file mode 100644 index 0000000..b022f20 --- /dev/null +++ b/src/peers/error.rs @@ -0,0 +1,172 @@ +//! Peer failures and their mapping onto [`AppError`]. +//! +//! This is the only place peer failures become `AppError`, so REST and MCP +//! report the same class and wording. + +use crate::error::AppError; +use crate::peers::types::{CheckClass, PeerName}; + +#[derive(Debug, Clone)] +pub enum PeerError { + /// Peer answered 401/403: our credential was refused. + Rejected, + NotFound, + BadRequest(String), + /// Any other unexpected status. + Http(u16), + Timeout, + Unreachable, + Dns, + Tls, + Oversize, + Malformed(String), + /// Missing, empty or oversized token file. + TokenFile(String), + /// Per-peer or global concurrency limit hit. + Saturated, +} + +impl PeerError { + /// Coarse classification for health state. The precise cause stays in the + /// error and in [`Self::class_str`]. + pub fn class(&self) -> CheckClass { + match self { + Self::Rejected => CheckClass::Unauthorized, + Self::Timeout => CheckClass::Timeout, + Self::Tls => CheckClass::TlsError, + Self::Unreachable | Self::Dns | Self::Saturated | Self::TokenFile(_) => { + CheckClass::Unreachable + } + Self::NotFound + | Self::BadRequest(_) + | Self::Http(_) + | Self::Oversize + | Self::Malformed(_) => CheckClass::HttpError, + } + } + + /// Short, secret-free class string used in status errors and messages. + pub fn class_str(&self) -> String { + match self { + Self::Rejected => "unauthorized".into(), + Self::NotFound => "not_found".into(), + Self::BadRequest(m) => m.clone(), + Self::Http(code) => format!("http_{code}"), + Self::Timeout => "timeout".into(), + Self::Unreachable => "unreachable".into(), + Self::Dns => "dns".into(), + Self::Tls => "tls_error".into(), + Self::Oversize => "oversize".into(), + Self::Malformed(_) => "malformed".into(), + Self::TokenFile(_) => "token_file".into(), + Self::Saturated => "saturated".into(), + } + } +} + +/// Map a peer failure for the caller of this consolidator. A peer rejecting +/// our credential is `Unavailable`, never `Unauthorized`: the caller's own +/// token is fine and re-authenticating with us would not help. +pub fn peer_error_to_app(peer: &PeerName, e: &PeerError) -> AppError { + match e { + PeerError::NotFound => AppError::NotFound(format!("peer {peer}: not found on peer")), + PeerError::BadRequest(m) => AppError::BadRequest(format!("peer {peer}: {m}")), + PeerError::Rejected => { + AppError::Unavailable(format!("peer {peer}: peer rejected credentials")) + } + PeerError::Malformed(_) => AppError::Internal(format!("peer {peer}: malformed response")), + other => AppError::Unavailable(format!("peer {peer}: {}", other.class_str())), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn name() -> PeerName { + PeerName::parse("beta").unwrap() + } + + /// Every peer failure reaches REST and MCP with the same class. + #[test] + fn mapping_table() { + let rows = [ + ( + PeerError::NotFound, + "not_found", + "peer beta: not found on peer", + ), + ( + PeerError::BadRequest("bad limit".into()), + "bad_request", + "peer beta: bad limit", + ), + ( + PeerError::Rejected, + "unavailable", + "peer beta: peer rejected credentials", + ), + (PeerError::Timeout, "unavailable", "peer beta: timeout"), + ( + PeerError::Unreachable, + "unavailable", + "peer beta: unreachable", + ), + (PeerError::Dns, "unavailable", "peer beta: dns"), + (PeerError::Tls, "unavailable", "peer beta: tls_error"), + (PeerError::Http(502), "unavailable", "peer beta: http_502"), + (PeerError::Oversize, "unavailable", "peer beta: oversize"), + (PeerError::Saturated, "unavailable", "peer beta: saturated"), + ( + PeerError::TokenFile("missing".into()), + "unavailable", + "peer beta: token_file", + ), + ( + PeerError::Malformed("not json".into()), + "internal", + "peer beta: malformed response", + ), + ]; + for (err, code, message) in rows { + let app = peer_error_to_app(&name(), &err); + assert_eq!(app.code(), code, "{err:?}"); + assert_eq!(app.message(), message, "{err:?}"); + assert_ne!( + app.status(), + axum::http::StatusCode::UNAUTHORIZED, + "{err:?}" + ); + } + } + + #[test] + fn rejected_is_never_unauthorized() { + let app = peer_error_to_app(&name(), &PeerError::Rejected); + assert_eq!(app.status(), axum::http::StatusCode::SERVICE_UNAVAILABLE); + } + + #[test] + fn token_file_detail_never_leaks() { + let app = peer_error_to_app( + &name(), + &PeerError::TokenFile("/run/credentials/secret".into()), + ); + assert!(!format!("{app:?}").contains("/run/credentials")); + assert!(!app.message().contains("/run/credentials")); + } + + #[test] + fn coarse_class() { + assert_eq!(PeerError::Rejected.class(), CheckClass::Unauthorized); + assert_eq!(PeerError::Timeout.class(), CheckClass::Timeout); + assert_eq!(PeerError::Dns.class(), CheckClass::Unreachable); + assert_eq!(PeerError::Saturated.class(), CheckClass::Unreachable); + assert_eq!(PeerError::Http(500).class(), CheckClass::HttpError); + assert_eq!( + PeerError::Malformed("x".into()).class(), + CheckClass::HttpError + ); + assert_eq!(PeerError::Tls.class(), CheckClass::TlsError); + } +} diff --git a/src/peers/health.rs b/src/peers/health.rs new file mode 100644 index 0000000..5aaea09 --- /dev/null +++ b/src/peers/health.rs @@ -0,0 +1,164 @@ +//! One-shot peer probes used by the diagnostic CLI. +//! +//! The registry's periodic loops reuse the transport; this module only +//! classifies a single round so `slinuxm peer check` can report it. + +use std::time::Duration; + +use jiff::Timestamp; + +use super::error::PeerError; +use super::transport::{PeerRequest, PeerTransport}; +use super::types::{ApiStatus, AuthState, PeerConfig, ServerStatus}; + +fn millis(d: Duration) -> u64 { + u64::try_from(d.as_millis()).unwrap_or(u64::MAX) +} + +fn failed_server(err: &PeerError, at: Timestamp) -> ServerStatus { + ServerStatus { + up: false, + since: None, + last_checked: Some(at), + last_error: Some(err.class_str()), + latency_ms: None, + } +} + +fn failed_api(err: &PeerError, at: Timestamp) -> ApiStatus { + ApiStatus { + up: false, + since: None, + last_checked: Some(at), + last_error: Some(err.class_str()), + latency_ms: None, + auth: AuthState::Unknown, + peer_version: None, + } +} + +/// One TCP connect and one authenticated `GET /api/v1/ping`. +/// +/// A peer that answers 401 is up with `auth = rejected`: the API is running +/// and our credential is the fault. Version and error classification beyond +/// that belong to the registry loops. +pub async fn check_once( + transport: &dyn PeerTransport, + peer: &PeerConfig, + tcp_timeout: Duration, + api_timeout: Duration, +) -> (ServerStatus, ApiStatus) { + let now = Timestamp::now(); + let server = match transport.tcp_check(peer, tcp_timeout).await { + Ok(latency) => ServerStatus { + up: true, + since: Some(now), + last_checked: Some(now), + last_error: None, + latency_ms: Some(millis(latency)), + }, + Err(err) => failed_server(&err, now), + }; + + let req = PeerRequest { + path: "/api/v1/ping".into(), + query: Vec::new(), + headers: Vec::new(), + accept: None, + }; + let api = match transport.get(peer, req, api_timeout).await { + Ok(resp) if (200..300).contains(&resp.status) => ApiStatus { + up: true, + since: Some(now), + last_checked: Some(now), + last_error: None, + latency_ms: None, + auth: AuthState::Ok, + peer_version: None, + }, + Ok(resp) if resp.status == 401 || resp.status == 403 => ApiStatus { + up: true, + since: Some(now), + last_checked: Some(now), + last_error: Some("unauthorized".into()), + latency_ms: None, + auth: AuthState::Rejected, + peer_version: None, + }, + Ok(resp) => failed_api(&PeerError::Http(resp.status), now), + Err(PeerError::Rejected) => ApiStatus { + up: true, + since: Some(now), + last_checked: Some(now), + last_error: Some("unauthorized".into()), + latency_ms: None, + auth: AuthState::Rejected, + peer_version: None, + }, + Err(err) => failed_api(&err, now), + }; + (server, api) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::peers::error::PeerError; + use crate::peers::testing::{fake_peers_config, FakeTransport}; + + #[tokio::test] + async fn healthy_peer() { + let fake = FakeTransport::new(); + let cfg = fake_peers_config(&["beta"]); + let (server, api) = check_once( + fake.as_ref(), + &cfg.peer[0], + Duration::from_secs(1), + Duration::from_secs(1), + ) + .await; + assert!(server.up); + assert_eq!(server.latency_ms, Some(1)); + assert!(api.up); + assert_eq!(api.auth, AuthState::Ok); + assert_eq!(fake.calls().len(), 1); + } + + #[tokio::test] + async fn rejected_credentials_still_mean_api_up() { + let fake = FakeTransport::new(); + fake.peer("beta") + .respond_err("/api/v1/ping", PeerError::Rejected); + let cfg = fake_peers_config(&["beta"]); + let (_, api) = check_once( + fake.as_ref(), + &cfg.peer[0], + Duration::from_secs(1), + Duration::from_secs(1), + ) + .await; + assert!(api.up); + assert_eq!(api.auth, AuthState::Rejected); + assert_eq!(api.last_error.as_deref(), Some("unauthorized")); + } + + #[tokio::test] + async fn down_peer_reports_class() { + let fake = FakeTransport::new(); + fake.peer("beta").tcp(Err(PeerError::Timeout)); + fake.peer("beta") + .respond_err("/api/v1/ping", PeerError::Timeout); + let cfg = fake_peers_config(&["beta"]); + let (server, api) = check_once( + fake.as_ref(), + &cfg.peer[0], + Duration::from_secs(1), + Duration::from_secs(1), + ) + .await; + assert!(!server.up); + assert_eq!(server.last_error.as_deref(), Some("timeout")); + assert!(!api.up); + assert_eq!(api.auth, AuthState::Unknown); + } +} diff --git a/src/peers/mod.rs b/src/peers/mod.rs new file mode 100644 index 0000000..4b49d11 --- /dev/null +++ b/src/peers/mod.rs @@ -0,0 +1,17 @@ +//! Peers: a consolidator's view of other `slinuxm` instances. +//! +//! Configuration is declarative; nothing in this module writes to a peer or +//! to the host. The registry read side is lock-light because REST, MCP and +//! metrics render status on every scrape. + +pub mod error; +pub mod health; +pub mod proxy; +pub mod registry; +pub mod testing; +pub mod transport; +pub mod types; + +pub use error::PeerError; +pub use registry::{PeerRegistry, ProxyOpts}; +pub use types::{PeerConfig, PeerName, PeerStatus, PeersConfig, Secret}; diff --git a/src/peers/proxy.rs b/src/peers/proxy.rs new file mode 100644 index 0000000..9da3171 --- /dev/null +++ b/src/peers/proxy.rs @@ -0,0 +1,114 @@ +//! Proxy one GET to a peer. +//! +//! Path and query allowlists and caller header checks happen in the REST +//! layer; this layer builds the outbound request and maps peer failures. It +//! never forwards caller credentials. + +use std::time::Duration; + +use axum::http::{HeaderName, HeaderValue}; + +use super::error::peer_error_to_app; +use super::registry::ProxyOpts; +use super::transport::{PeerRequest, PeerResponse, PeerTransport}; +use super::types::PeerConfig; +use crate::error::AppError; + +const HOP_HEADER: &str = "x-slinuxm-hop"; +const TRACEPARENT: &str = "traceparent"; + +fn header(name: &'static str, value: &str) -> (HeaderName, HeaderValue) { + let name = HeaderName::from_static(name); + let value = HeaderValue::from_str(value).expect("static header value"); + (name, value) +} + +pub(crate) async fn get( + transport: &dyn PeerTransport, + peer: &PeerConfig, + path: &str, + query: &[(String, String)], + opts: ProxyOpts, + timeout: Duration, +) -> Result { + // Marks the hop so a peer refuses chained consolidation. + let mut headers = vec![header(HOP_HEADER, "1")]; + if let Some(traceparent) = opts.traceparent.as_deref() { + if let Ok(value) = HeaderValue::from_str(traceparent) { + headers.push((HeaderName::from_static(TRACEPARENT), value)); + } + } + let req = PeerRequest { + path: path.to_owned(), + query: query.to_vec(), + headers, + accept: opts.accept_sse.then(|| "text/event-stream".to_owned()), + }; + transport + .get(peer, req, timeout) + .await + .map_err(|e| peer_error_to_app(&peer.name, &e)) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::peers::testing::{fake_peers_config, FakeTransport}; + + #[tokio::test] + async fn adds_hop_and_trace_context_but_no_credentials() { + let fake = FakeTransport::new(); + let cfg = fake_peers_config(&["beta"]); + let opts = ProxyOpts { + traceparent: Some("00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01".into()), + accept_sse: true, + }; + get( + fake.as_ref(), + &cfg.peer[0], + "/journal/follow", + &[("lines".into(), "10".into())], + opts, + Duration::from_secs(1), + ) + .await + .unwrap(); + + let calls = fake.calls(); + assert_eq!(calls.len(), 1); + let req = &calls[0].1; + assert_eq!(req.path, "/journal/follow"); + assert_eq!(req.query, vec![("lines".to_owned(), "10".to_owned())]); + assert_eq!(req.accept.as_deref(), Some("text/event-stream")); + let header = |name: &str| { + req.headers + .iter() + .find(|(k, _)| k.as_str() == name) + .map(|(_, v)| v.to_str().unwrap()) + }; + assert_eq!(header("x-slinuxm-hop"), Some("1")); + assert!(header("traceparent").unwrap().starts_with("00-")); + assert_eq!(header("authorization"), None); + } + + #[tokio::test] + async fn maps_rejected_with_peer_name() { + let fake = FakeTransport::new(); + fake.peer("beta") + .respond_err("/systemd/units", crate::peers::error::PeerError::Rejected); + let cfg = fake_peers_config(&["beta"]); + let err = get( + fake.as_ref(), + &cfg.peer[0], + "/systemd/units", + &[], + ProxyOpts::default(), + Duration::from_secs(1), + ) + .await + .unwrap_err(); + assert_eq!(err.code(), "unavailable"); + assert!(err.message().contains("beta")); + assert_eq!(err.message(), "peer beta: peer rejected credentials"); + } +} diff --git a/src/peers/registry.rs b/src/peers/registry.rs new file mode 100644 index 0000000..3b5d974 --- /dev/null +++ b/src/peers/registry.rs @@ -0,0 +1,254 @@ +//! In-memory peer views. Health loops refresh the status entries; the read +//! side never awaits on a peer and is cheap enough for a metrics scrape. + +use std::collections::BTreeMap; +use std::sync::{Arc, RwLock}; +use std::time::Duration; + +use crate::config::ConfigError; +use crate::error::AppError; +use crate::peers::transport::{PeerResponse, PeerTransport}; +use crate::peers::types::{ApiStatus, PeerConfig, PeerName, PeerStatus, PeersConfig, ServerStatus}; + +/// Options a surface passes down to the proxy layer. Trace context is a +/// pre-built `traceparent` header value; the peer hop is always marked. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct ProxyOpts { + pub traceparent: Option, + pub accept_sse: bool, +} + +struct RegistryState { + config: Arc, + statuses: BTreeMap, +} + +pub struct PeerRegistry { + transport: Arc, + state: RwLock, +} + +fn initial_status(peer: &PeerConfig) -> PeerStatus { + PeerStatus { + name: peer.name.clone(), + enabled: peer.enabled, + url: peer.display_url(), + server: ServerStatus::default(), + api: ApiStatus::default(), + } +} + +fn lock_read(lock: &RwLock) -> std::sync::RwLockReadGuard<'_, T> { + lock.read().unwrap_or_else(|e| e.into_inner()) +} + +fn lock_write(lock: &RwLock) -> std::sync::RwLockWriteGuard<'_, T> { + lock.write().unwrap_or_else(|e| e.into_inner()) +} + +impl PeerRegistry { + pub(crate) fn new(config: PeersConfig, transport: Arc) -> Self { + let statuses = config + .peer + .iter() + .map(|peer| (peer.name.clone(), initial_status(peer))) + .collect(); + Self { + transport, + state: RwLock::new(RegistryState { + config: Arc::new(config), + statuses, + }), + } + } + + pub(crate) fn from_statuses( + statuses: Vec, + config: PeersConfig, + transport: Arc, + ) -> Self { + Self { + transport, + state: RwLock::new(RegistryState { + config: Arc::new(config), + statuses: statuses.into_iter().map(|s| (s.name.clone(), s)).collect(), + }), + } + } + + /// Sorted by name; disabled peers included. + pub fn snapshot(&self) -> Vec { + lock_read(&self.state).statuses.values().cloned().collect() + } + + pub fn status(&self, name: &str) -> Result { + lock_read(&self.state) + .statuses + .values() + .find(|s| s.name.as_str() == name) + .cloned() + .ok_or_else(|| AppError::NotFound(format!("peer {name}: unknown peer"))) + } + + pub fn contains(&self, name: &str) -> bool { + lock_read(&self.state) + .statuses + .keys() + .any(|n| n.as_str() == name) + } + + pub fn config(&self) -> Arc { + lock_read(&self.state).config.clone() + } + + /// Single proxy entry point for REST and MCP. + pub async fn get( + &self, + name: &str, + path: &str, + query: &[(String, String)], + opts: ProxyOpts, + ) -> Result { + let (peer, timeout) = { + let st = lock_read(&self.state); + let peer = st + .config + .peer + .iter() + .find(|p| p.name.as_str() == name) + .cloned(); + (peer, Duration::from_secs(st.config.request_timeout_secs)) + }; + let peer = peer.ok_or_else(|| AppError::NotFound(format!("peer {name}: unknown peer")))?; + crate::peers::proxy::get(self.transport.as_ref(), &peer, path, query, opts, timeout).await + } + + /// Replace the peer set. Statuses of peers that survive a reload are kept + /// so `since` survives a config change. Validation arrives with the + /// config and secrets tasks; this body only swaps state. + pub async fn reload(&self, new: PeersConfig) -> Result<(), ConfigError> { + let mut st = lock_write(&self.state); + let old = std::mem::take(&mut st.statuses); + st.statuses = new + .peer + .iter() + .map(|peer| { + let mut status = old + .get(&peer.name) + .cloned() + .unwrap_or_else(|| initial_status(peer)); + status.enabled = peer.enabled; + status.url = peer.display_url(); + (peer.name.clone(), status) + }) + .collect(); + st.config = Arc::new(new); + Ok(()) + } + + /// Health loops stop on this; nothing is running yet. + pub async fn shutdown(&self) {} +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::peers::testing::{fake_peers_config, registry_with, static_registry, FakeTransport}; + use crate::peers::transport::PeerBody; + + fn status(name: &str, up: bool) -> PeerStatus { + PeerStatus { + name: PeerName::parse(name).unwrap(), + enabled: true, + url: format!("http://{name}:1984"), + server: ServerStatus { + up, + ..ServerStatus::default() + }, + api: ApiStatus::default(), + } + } + + #[test] + fn snapshot_is_sorted_and_includes_initial_state() { + let reg = static_registry(vec![status("gamma", false), status("beta", true)]); + let names: Vec<_> = reg + .snapshot() + .into_iter() + .map(|s| s.name.as_str().to_owned()) + .collect(); + assert_eq!(names, ["beta", "gamma"]); + let b = reg.status("beta").unwrap(); + assert!(b.server.up); + assert_eq!(b.api.auth, crate::peers::types::AuthState::Unknown); + } + + #[test] + fn unknown_peer_status_is_not_found() { + let reg = static_registry(vec![status("beta", true)]); + let err = reg.status("nope").unwrap_err(); + assert_eq!(err.code(), "not_found"); + assert_eq!(err.message(), "peer nope: unknown peer"); + assert!(reg.contains("beta")); + assert!(!reg.contains("nope")); + } + + #[test] + fn config_is_shared() { + let cfg = fake_peers_config(&["beta"]); + let reg = registry_with(FakeTransport::new(), cfg); + let got = reg.config(); + assert!(got.enabled); + assert_eq!(got.peer[0].name.as_str(), "beta"); + assert_eq!(got.request_timeout_secs, 2); + } + + #[tokio::test] + async fn get_forwards_and_maps_errors() { + let fake = FakeTransport::new(); + fake.peer("beta") + .respond("/systemd/units", 200, "application/json", "{\"ok\":true}"); + let reg = registry_with(fake, fake_peers_config(&["beta"])); + + let resp = reg + .get("beta", "/systemd/units", &[], ProxyOpts::default()) + .await + .unwrap(); + assert_eq!(resp.status, 200); + match resp.body { + PeerBody::Bytes(b) => assert_eq!(&b[..], b"{\"ok\":true}"), + PeerBody::Stream(_) => panic!("expected buffered body"), + } + + let err = reg + .get("nope", "/x", &[], ProxyOpts::default()) + .await + .unwrap_err(); + assert_eq!(err.code(), "not_found"); + assert_eq!(err.message(), "peer nope: unknown peer"); + } + + #[tokio::test] + async fn reload_keeps_surviving_status_and_prunes_removed() { + let reg = registry_with(FakeTransport::new(), fake_peers_config(&["beta", "gamma"])); + { + let mut st = lock_write(®.state); + let beta = st + .statuses + .get_mut(&PeerName::parse("beta").unwrap()) + .unwrap(); + beta.server.up = true; + } + let mut new = fake_peers_config(&["beta", "delta"]); + new.peer[0].enabled = false; + reg.reload(new).await.unwrap(); + + let snap = reg.snapshot(); + assert_eq!(snap.len(), 2); + assert_eq!(snap[0].name.as_str(), "beta"); + assert!(snap[0].server.up, "health survives a reload"); + assert!(!snap[0].enabled); + assert_eq!(snap[1].name.as_str(), "delta"); + assert!(!snap[1].server.up); + } +} diff --git a/src/peers/testing.rs b/src/peers/testing.rs new file mode 100644 index 0000000..6cfc7b9 --- /dev/null +++ b/src/peers/testing.rs @@ -0,0 +1,433 @@ +//! In-memory peer fixtures, mirroring `sources::fake` for the peer transport. +//! +//! Public (not `cfg(test)`) because integration tests compile the library +//! without the test cfg; the binary gets dead code only, no behaviour. + +use std::collections::BTreeMap; +use std::path::PathBuf; +use std::sync::{Arc, Mutex}; +use std::time::Duration; + +use async_trait::async_trait; +use bytes::Bytes; +use url::Url; + +use super::error::PeerError; +use super::registry::PeerRegistry; +use super::transport::{PeerBody, PeerRequest, PeerResponse, PeerTransport}; +use super::types::{PeerConfig, PeerName, PeerStatus, PeersConfig}; +use crate::config::Config; +use crate::state::AppState; + +const DEFAULT_PING_BODY: &str = r#"{"status":"ok","version":"0.0.0-fake"}"#; + +#[derive(Clone)] +enum Scripted { + Response { + status: u16, + content_type: Option, + body: Bytes, + }, + Stream { + content_type: String, + chunks: Vec, + }, + Err(PeerError), +} + +#[derive(Clone)] +struct PeerState { + tcp: Result, + scripts: Vec<(String, Scripted)>, + delay: Option, +} + +impl Default for PeerState { + fn default() -> Self { + Self { + tcp: Ok(Duration::from_millis(1)), + scripts: Vec::new(), + delay: None, + } + } +} + +/// Scriptable transport. Every GET is recorded for assertions; unscripted +/// peers behave like a healthy `slinuxm` instance. +#[derive(Default)] +pub struct FakeTransport { + peers: Mutex>, + calls: Mutex>, +} + +impl FakeTransport { + pub fn new() -> Arc { + Arc::new(Self::default()) + } + + pub fn peer(self: &Arc, name: &str) -> FakePeerBuilder { + FakePeerBuilder { + fake: self.clone(), + name: PeerName::parse(name).expect("valid peer name"), + } + } + + /// Every GET in call order. + pub fn calls(&self) -> Vec<(PeerName, PeerRequest)> { + self.calls.lock().expect("fake calls lock").clone() + } + + fn state_of(&self, name: &PeerName) -> PeerState { + self.peers + .lock() + .expect("fake peers lock") + .get(name) + .cloned() + .unwrap_or_default() + } + + fn update(&self, name: &PeerName, f: impl FnOnce(&mut PeerState)) { + let mut peers = self.peers.lock().expect("fake peers lock"); + f(peers.entry(name.clone()).or_default()); + } +} + +/// Builder returned by [`FakeTransport::peer`]. Mutates the shared fake, so +/// scripts can be added after the registry exists. +pub struct FakePeerBuilder { + fake: Arc, + name: PeerName, +} + +impl FakePeerBuilder { + pub fn tcp(self, result: Result) -> Self { + self.fake.update(&self.name, |p| p.tcp = result); + self + } + + /// Scripted GET for paths starting with `path_prefix`; the first match + /// wins over later ones and over the defaults. + pub fn respond( + self, + path_prefix: &str, + status: u16, + content_type: &str, + body: impl Into, + ) -> Self { + self.fake.update(&self.name, |p| { + p.scripts.push(( + path_prefix.to_owned(), + Scripted::Response { + status, + content_type: Some(content_type.to_owned()), + body: body.into(), + }, + )); + }); + self + } + + pub fn respond_err(self, path_prefix: &str, err: PeerError) -> Self { + self.fake.update(&self.name, |p| { + p.scripts.push((path_prefix.to_owned(), Scripted::Err(err))); + }); + self + } + + /// Scripted SSE body; the content type is always `text/event-stream`. + pub fn stream(self, path_prefix: &str, chunks: Vec) -> Self { + self.fake.update(&self.name, |p| { + p.scripts.push(( + path_prefix.to_owned(), + Scripted::Stream { + content_type: "text/event-stream".to_owned(), + chunks, + }, + )); + }); + self + } + + /// Simulate slowness on both checks (pauseable `tokio::time`). + pub fn delay(self, delay: Duration) -> Self { + self.fake.update(&self.name, |p| p.delay = Some(delay)); + self + } +} + +#[async_trait] +impl PeerTransport for FakeTransport { + async fn tcp_check( + &self, + peer: &PeerConfig, + _timeout: Duration, + ) -> Result { + let state = self.state_of(&peer.name); + if let Some(delay) = state.delay { + tokio::time::sleep(delay).await; + } + state.tcp + } + + async fn get( + &self, + peer: &PeerConfig, + req: PeerRequest, + _timeout: Duration, + ) -> Result { + let state = self.state_of(&peer.name); + self.calls + .lock() + .expect("fake calls lock") + .push((peer.name.clone(), req.clone())); + if let Some(delay) = state.delay { + tokio::time::sleep(delay).await; + } + for (prefix, script) in state.scripts { + if req.path.starts_with(&prefix) { + return Ok(match script { + Scripted::Response { + status, + content_type, + body, + } => PeerResponse { + status, + content_type, + body: PeerBody::Bytes(body), + }, + Scripted::Stream { + content_type, + chunks, + } => PeerResponse { + status: 200, + content_type: Some(content_type), + body: PeerBody::Stream(Box::pin(futures::stream::iter( + chunks.into_iter().map(Ok), + ))), + }, + Scripted::Err(err) => return Err(err), + }); + } + } + if req.path == "/api/v1/ping" { + return Ok(PeerResponse { + status: 200, + content_type: Some("application/json".into()), + body: PeerBody::Bytes(Bytes::from_static(DEFAULT_PING_BODY.as_bytes())), + }); + } + Ok(PeerResponse { + status: 404, + content_type: Some("application/json".into()), + body: PeerBody::Bytes(Bytes::from_static( + br#"{"error":{"code":"not_found","message":"no such route"}}"#, + )), + }) + } +} + +fn fake_peer(name: &str, url: &str) -> PeerConfig { + PeerConfig { + name: PeerName::parse(name).expect("valid peer name"), + url: Url::parse(url).expect("valid peer url"), + token_file: PathBuf::from(format!("/run/peers/{name}.token")), + ca_file: None, + allow_plain_http: true, + enabled: true, + } +} + +/// Enabled peers with short intervals and loopback-safe plain HTTP, matching +/// what the tests script. +pub fn fake_peers_config(names: &[&str]) -> PeersConfig { + PeersConfig { + enabled: true, + tcp_interval_secs: 1, + tcp_timeout_secs: 1, + api_interval_secs: 1, + api_timeout_secs: 1, + fail_threshold: 1, + request_timeout_secs: 2, + peer: names + .iter() + .map(|n| fake_peer(n, &format!("http://{n}:1984"))) + .collect(), + ..PeersConfig::default() + } +} + +/// Registry over the fake transport; no health loops are spawned. +pub fn registry_with(fake: Arc, cfg: PeersConfig) -> Arc { + Arc::new(PeerRegistry::new(cfg, fake)) +} + +/// Registry with a fixed snapshot, for tests that only render status. +pub fn static_registry(statuses: Vec) -> Arc { + let peer = statuses + .iter() + .map(|s| { + let mut cfg = fake_peer(s.name.as_str(), &s.url); + cfg.enabled = s.enabled; + cfg + }) + .collect(); + let cfg = PeersConfig { + enabled: true, + peer, + ..PeersConfig::default() + }; + Arc::new(PeerRegistry::from_statuses( + statuses, + cfg, + FakeTransport::new(), + )) +} + +/// Fake sources plus a peer registry. +pub fn fake_state_with_peers(config: Config, reg: Arc) -> AppState { + AppState { + peers: Some(reg), + ..crate::sources::fake::fake_state(config) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[tokio::test] + async fn defaults_are_healthy_for_ping_and_404_elsewhere() { + let fake = FakeTransport::new(); + let cfg = fake_peers_config(&["beta"]); + let peer = &cfg.peer[0]; + + let latency = fake.tcp_check(peer, Duration::from_secs(1)).await.unwrap(); + assert_eq!(latency, Duration::from_millis(1)); + + let req = PeerRequest { + path: "/api/v1/ping".into(), + query: vec![], + headers: vec![], + accept: None, + }; + let resp = fake.get(peer, req, Duration::from_secs(1)).await.unwrap(); + assert_eq!(resp.status, 200); + match resp.body { + PeerBody::Bytes(b) => { + assert!(b.windows(10).any(|w| w == b"0.0.0-fake")) + } + PeerBody::Stream(_) => panic!("expected buffered body"), + } + + let req = PeerRequest { + path: "/systemd/units".into(), + query: vec![], + headers: vec![], + accept: None, + }; + let resp = fake.get(peer, req, Duration::from_secs(1)).await.unwrap(); + assert_eq!(resp.status, 404); + assert_eq!(fake.calls().len(), 2); + } + + #[tokio::test] + async fn scripts_first_match_wins_and_record_calls() { + let fake = FakeTransport::new(); + fake.peer("beta") + .respond("/systemd/units", 200, "application/json", "{\"a\":1}") + .respond("/systemd", 500, "application/json", "{}") + .respond_err("/docker", PeerError::Timeout); + let cfg = fake_peers_config(&["beta"]); + let peer = &cfg.peer[0]; + let get = |path: &str| PeerRequest { + path: path.into(), + query: vec![], + headers: vec![], + accept: None, + }; + + let r = fake + .get( + peer, + get("/systemd/units?state=failed"), + Duration::from_secs(1), + ) + .await + .unwrap(); + assert_eq!(r.status, 200); + let r = fake + .get(peer, get("/systemd/timers"), Duration::from_secs(1)) + .await + .unwrap(); + assert_eq!(r.status, 500); + assert!(matches!( + fake.get(peer, get("/docker/containers"), Duration::from_secs(1)) + .await, + Err(PeerError::Timeout) + )); + let calls = fake.calls(); + assert_eq!(calls.len(), 3); + assert_eq!(calls[0].0.as_str(), "beta"); + assert_eq!(calls[0].1.path, "/systemd/units?state=failed"); + } + + #[tokio::test] + async fn streams_chunks() { + let fake = FakeTransport::new(); + fake.peer("beta").stream( + "/journal/follow", + vec![Bytes::from_static(b"a"), Bytes::from_static(b"b")], + ); + let cfg = fake_peers_config(&["beta"]); + let req = PeerRequest { + path: "/journal/follow".into(), + query: vec![], + headers: vec![], + accept: Some("text/event-stream".into()), + }; + let resp = fake + .get(&cfg.peer[0], req, Duration::from_secs(1)) + .await + .unwrap(); + assert_eq!(resp.content_type.as_deref(), Some("text/event-stream")); + match resp.body { + PeerBody::Stream(mut s) => { + use futures::StreamExt; + let first = s.next().await.unwrap().unwrap(); + assert_eq!(first, Bytes::from_static(b"a")); + } + PeerBody::Bytes(_) => panic!("expected stream"), + } + } + + #[tokio::test] + async fn per_peer_isolation_and_delay() { + let fake = FakeTransport::new(); + fake.peer("beta") + .respond_err("/systemd/units", PeerError::Rejected) + .delay(Duration::from_millis(5)); + let cfg = fake_peers_config(&["beta", "gamma"]); + let beta = cfg.peer.iter().find(|p| p.name.as_str() == "beta").unwrap(); + let gamma = cfg + .peer + .iter() + .find(|p| p.name.as_str() == "gamma") + .unwrap(); + let get = || PeerRequest { + path: "/systemd/units".into(), + query: vec![], + headers: vec![], + accept: None, + }; + assert!(matches!( + fake.get(beta, get(), Duration::from_secs(1)).await, + Err(PeerError::Rejected) + )); + // gamma keeps the default 404. + let r = fake + .get(gamma, get(), Duration::from_secs(1)) + .await + .unwrap(); + assert_eq!(r.status, 404); + } +} diff --git a/src/peers/transport.rs b/src/peers/transport.rs new file mode 100644 index 0000000..25a4a87 --- /dev/null +++ b/src/peers/transport.rs @@ -0,0 +1,61 @@ +//! Outbound transport abstraction so surfaces and tests never need sockets. + +use std::time::Duration; + +use async_trait::async_trait; +use axum::http::{HeaderName, HeaderValue}; +use bytes::Bytes; +use futures::stream::BoxStream; + +use crate::peers::error::PeerError; +use crate::peers::types::PeerConfig; + +/// One GET to a peer. `path` is validated by the proxy layer before it gets +/// here; headers carry trace context and the hop marker, never credentials. +#[derive(Debug, Clone)] +pub struct PeerRequest { + pub path: String, + pub query: Vec<(String, String)>, + pub headers: Vec<(HeaderName, HeaderValue)>, + /// `text/event-stream` for follow requests. + pub accept: Option, +} + +#[derive(Debug)] +pub struct PeerResponse { + pub status: u16, + pub content_type: Option, + pub body: PeerBody, +} + +/// Body of a peer response: buffered (capped by the transport) or streamed. +pub enum PeerBody { + Bytes(Bytes), + Stream(BoxStream<'static, Result>), +} + +impl std::fmt::Debug for PeerBody { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Self::Bytes(b) => write!(f, "Bytes({} bytes)", b.len()), + Self::Stream(_) => f.write_str("Stream(..)"), + } + } +} + +#[async_trait] +pub trait PeerTransport: Send + Sync { + /// TCP connect to the peer's host:port under `timeout`; returns connect + /// latency. The peer's URL is the only source of the target address. + async fn tcp_check(&self, peer: &PeerConfig, timeout: Duration) -> Result; + + /// Authenticated GET. Implementations read the token file on each call so + /// rotation needs no restart, and enforce redirect-off, the size cap and + /// concurrency limits. + async fn get( + &self, + peer: &PeerConfig, + req: PeerRequest, + timeout: Duration, + ) -> Result; +} diff --git a/src/peers/types.rs b/src/peers/types.rs new file mode 100644 index 0000000..1a5bee5 --- /dev/null +++ b/src/peers/types.rs @@ -0,0 +1,319 @@ +//! Types shared by peer configuration, the registry, proxying and fixtures. + +use std::fmt; +use std::path::PathBuf; + +use jiff::Timestamp; +use serde::{Deserialize, Deserializer, Serialize, Serializer}; +use url::Url; + +use crate::config::ConfigError; + +/// Upper bound on configured peers; keeps health loops and snapshots bounded. +pub const MAX_PEERS: usize = 64; + +/// Validated peer name, `^[a-z0-9][a-z0-9_-]{0,31}$`. +/// +/// Names end up in URLs, MCP arguments and metric attributes, so the +/// character set is deliberately narrow. +#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)] +pub struct PeerName(String); + +impl PeerName { + pub fn parse(s: &str) -> Result { + let valid = !s.is_empty() + && s.len() <= 32 + && s.bytes().enumerate().all(|(i, b)| match b { + b'a'..=b'z' | b'0'..=b'9' => true, + b'_' | b'-' => i > 0, + _ => false, + }); + if !valid { + return Err(ConfigError::Invalid(format!( + "peer name {s:?} must match ^[a-z0-9][a-z0-9_-]{{0,31}}$" + ))); + } + Ok(Self(s.to_owned())) + } + + pub fn as_str(&self) -> &str { + &self.0 + } +} + +impl fmt::Display for PeerName { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.0) + } +} + +impl Serialize for PeerName { + fn serialize(&self, s: S) -> Result { + s.serialize_str(&self.0) + } +} + +impl<'de> Deserialize<'de> for PeerName { + fn deserialize>(d: D) -> Result { + let s = String::deserialize(d)?; + Self::parse(&s).map_err(serde::de::Error::custom) + } +} + +/// A token value that must never reach logs, `Debug` output or serialized +/// config. Only the transport may read it. +#[derive(Clone, PartialEq, Eq)] +pub struct Secret(String); + +impl Secret { + pub fn new(value: impl Into) -> Self { + Self(value.into()) + } + + pub fn expose(&self) -> &str { + &self.0 + } +} + +impl fmt::Debug for Secret { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("Secret(***)") + } +} + +impl fmt::Display for Secret { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("***") + } +} + +/// One validated `[[peers.peer]]` entry. The token itself is not held here; +/// only the path of the externally managed file. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct PeerConfig { + pub name: PeerName, + pub url: Url, + pub token_file: PathBuf, + pub ca_file: Option, + pub allow_plain_http: bool, + pub enabled: bool, +} + +impl PeerConfig { + /// Display form for REST and MCP output. `Url` normalizes an empty path + /// to `/`; drop it so `http://beta:1984` does not render as `.../`. + pub fn display_url(&self) -> String { + let s = self.url.as_str(); + if self.url.path() == "/" { + s.strip_suffix('/').unwrap_or(s).to_owned() + } else { + s.to_owned() + } + } +} + +/// The `[peers]` config section. Defaults keep the feature off. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(default)] +pub struct PeersConfig { + pub enabled: bool, + pub tcp_interval_secs: u64, + pub tcp_timeout_secs: u64, + pub api_interval_secs: u64, + pub api_timeout_secs: u64, + pub fail_threshold: u32, + pub request_timeout_secs: u64, + pub max_response_bytes: u64, + pub max_concurrent_per_peer: usize, + pub max_concurrent_total: usize, + pub deny_cidrs: Vec, + pub peer: Vec, +} + +impl Default for PeersConfig { + fn default() -> Self { + Self { + enabled: false, + tcp_interval_secs: 10, + tcp_timeout_secs: 3, + api_interval_secs: 30, + api_timeout_secs: 5, + fail_threshold: 2, + request_timeout_secs: 10, + max_response_bytes: 8 * 1024 * 1024, + max_concurrent_per_peer: 4, + max_concurrent_total: 16, + deny_cidrs: vec!["169.254.0.0/16".into(), "0.0.0.0/8".into()], + peer: Vec::new(), + } + } +} + +/// Registry snapshot entry, serialized as-is by REST and MCP. +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct PeerStatus { + pub name: PeerName, + pub enabled: bool, + pub url: String, + pub server: ServerStatus, + pub api: ApiStatus, +} + +#[derive(Debug, Clone, PartialEq, Default, Serialize)] +pub struct ServerStatus { + pub up: bool, + /// Last change; `None` until the first check and reset on restart. + pub since: Option, + pub last_checked: Option, + pub last_error: Option, + pub latency_ms: Option, +} + +#[derive(Debug, Clone, PartialEq, Default, Serialize)] +pub struct ApiStatus { + pub up: bool, + pub since: Option, + pub last_checked: Option, + pub last_error: Option, + pub latency_ms: Option, + pub auth: AuthState, + pub peer_version: Option, +} + +/// `Ok` and `Rejected` refer to our credential; `Unknown` is used before the +/// first check and for peers without the authenticated ping endpoint. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum AuthState { + Ok, + Rejected, + #[default] + Unknown, +} + +/// Coarse outcome of a check; the precise cause is in [`crate::peers::error::PeerError`]. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum CheckClass { + Ok, + Unauthorized, + HttpError, + Timeout, + Unreachable, + TlsError, +} + +impl CheckClass { + pub fn as_str(&self) -> &'static str { + match self { + Self::Ok => "ok", + Self::Unauthorized => "unauthorized", + Self::HttpError => "http_error", + Self::Timeout => "timeout", + Self::Unreachable => "unreachable", + Self::TlsError => "tls_error", + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn peer(name: &str, url: &str) -> PeerConfig { + PeerConfig { + name: PeerName::parse(name).unwrap(), + url: Url::parse(url).unwrap(), + token_file: PathBuf::from(format!("/run/peers/{name}.token")), + ca_file: None, + allow_plain_http: false, + enabled: true, + } + } + + #[test] + fn peer_name_accepts_and_rejects() { + assert!(PeerName::parse("a").is_ok()); + assert!(PeerName::parse("minipc1").is_ok()); + assert!(PeerName::parse("a_b-c9").is_ok()); + assert!(PeerName::parse(&"a".repeat(32)).is_ok()); + for bad in ["", "-a", "_a", "Beta", "beta!", "a b", &"a".repeat(33)] { + assert!(PeerName::parse(bad).is_err(), "{bad:?} should be rejected"); + } + } + + #[test] + fn peer_name_serde_roundtrip_and_validation() { + let n = PeerName::parse("beta").unwrap(); + let json = serde_json::to_string(&n).unwrap(); + assert_eq!(json, "\"beta\""); + assert_eq!(serde_json::from_str::(&json).unwrap(), n); + assert!(serde_json::from_str::("\"Beta\"").is_err()); + assert_eq!(n.to_string(), "beta"); + } + + #[test] + fn secret_redacts_debug_and_display() { + let s = Secret::new("slinuxm_super_secret"); + assert_eq!(s.expose(), "slinuxm_super_secret"); + assert!(!format!("{s:?}").contains("super")); + assert!(!format!("{s}").contains("super")); + assert_eq!(format!("{s:?}"), "Secret(***)"); + } + + #[test] + fn peer_defaults_are_off() { + let c = PeersConfig::default(); + assert!(!c.enabled); + assert!(c.peer.is_empty()); + assert_eq!(c.tcp_interval_secs, 10); + assert_eq!(c.request_timeout_secs, 10); + assert_eq!(c.max_response_bytes, 8 * 1024 * 1024); + assert_eq!(c.deny_cidrs, vec!["169.254.0.0/16", "0.0.0.0/8"]); + } + + #[test] + fn partial_toml_keeps_defaults() { + let c: PeersConfig = toml::from_str("enabled = true\napi_interval_secs = 7\n").unwrap(); + assert!(c.enabled); + assert_eq!(c.api_interval_secs, 7); + assert_eq!(c.tcp_interval_secs, 10); + } + + #[test] + fn display_url_drops_normalized_root_path() { + assert_eq!( + peer("beta", "http://beta:1984").display_url(), + "http://beta:1984" + ); + assert_eq!( + peer("beta", "https://beta:1984/").display_url(), + "https://beta:1984" + ); + assert_eq!( + peer("beta", "https://beta:1984/base").display_url(), + "https://beta:1984/base" + ); + } + + #[test] + fn status_json_shape() { + let st = PeerStatus { + name: PeerName::parse("beta").unwrap(), + enabled: true, + url: "http://beta:1984".into(), + server: ServerStatus::default(), + api: ApiStatus::default(), + }; + let v = serde_json::to_value(&st).unwrap(); + assert_eq!(v["name"], "beta"); + assert_eq!(v["server"]["up"], serde_json::json!(false)); + assert_eq!(v["server"]["since"], serde_json::Value::Null); + assert_eq!(v["api"]["auth"], "unknown"); + assert_eq!( + serde_json::to_value(CheckClass::TlsError).unwrap(), + "tls_error" + ); + assert_eq!(serde_json::to_value(AuthState::Ok).unwrap(), "ok"); + } +} diff --git a/src/sources/fake.rs b/src/sources/fake.rs index 33fc53d..bf5184e 100644 --- a/src/sources/fake.rs +++ b/src/sources/fake.rs @@ -32,6 +32,7 @@ pub fn fake_state(config: Config) -> AppState { journal: Arc::new(FakeJournal::new(shutdown.clone())), docker: Arc::new(FakeDocker::new(shutdown.clone())), db: None, + peers: None, shutdown, } } diff --git a/src/state.rs b/src/state.rs index ed1ad2c..4a540b2 100644 --- a/src/state.rs +++ b/src/state.rs @@ -6,6 +6,7 @@ use sqlx::SqlitePool; use tokio_util::sync::CancellationToken; use crate::config::Config; +use crate::peers::PeerRegistry; use crate::sources::{DockerSource, JournalSource, SystemdSource}; /// Cheap to clone. Every stream and background task must select on @@ -18,6 +19,8 @@ pub struct AppState { pub docker: Arc, /// `None` when auth is disabled. pub db: Option, + /// `None` when the peers feature is off: no routes, tools, tasks or metrics. + pub peers: Option>, pub shutdown: CancellationToken, } @@ -32,6 +35,7 @@ impl AppState { docker: Arc::new(BollardDocker::new(&config, shutdown.clone())), config: Arc::new(config), db, + peers: None, shutdown, } } diff --git a/tests/peers_config.rs b/tests/peers_config.rs new file mode 100644 index 0000000..3bdf331 --- /dev/null +++ b/tests/peers_config.rs @@ -0,0 +1,160 @@ +//! Peer seams exercised end to end against the fake transport and fake +//! sources: the peer-less default, the ping route, and registry reads. + +use std::time::Duration; + +use axum::body::{to_bytes, Body}; +use axum::http::{Request, StatusCode}; +use skyg_linux_tracker::api; +use skyg_linux_tracker::config::Config; +use skyg_linux_tracker::peers::testing::{ + fake_peers_config, fake_state_with_peers, registry_with, static_registry, FakeTransport, +}; +use skyg_linux_tracker::peers::types::{ApiStatus, AuthState, PeerName, PeerStatus, ServerStatus}; +use skyg_linux_tracker::peers::{PeerError, ProxyOpts}; +use tower::ServiceExt; + +async fn get(app: &axum::Router, uri: &str) -> (StatusCode, String) { + let resp = app + .clone() + .oneshot(Request::get(uri).body(Body::empty()).unwrap()) + .await + .unwrap(); + let status = resp.status(); + let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap(); + (status, String::from_utf8(body.to_vec()).unwrap()) +} + +fn status(name: &str, up: bool) -> PeerStatus { + PeerStatus { + name: PeerName::parse(name).unwrap(), + enabled: true, + url: format!("http://{name}:1984"), + server: ServerStatus { + up, + ..ServerStatus::default() + }, + api: ApiStatus::default(), + } +} + +#[tokio::test] +async fn peerless_default_is_off_and_unchanged() { + let config = Config::default(); + assert!(!config.peers.enabled); + assert!(config.peers.peer.is_empty()); + + let state = skyg_linux_tracker::sources::fake::fake_state(config); + assert!(state.peers.is_none()); + let (s, b) = get(&api::router(state), "/systemd/units").await; + assert_eq!(s, StatusCode::OK); + assert!(!b.is_empty()); +} + +#[tokio::test] +async fn ping_route_is_present_without_peers() { + let app = api::router(skyg_linux_tracker::sources::fake::fake_state( + Config::default(), + )); + let (s, b) = get(&app, "/ping").await; + assert_eq!(s, StatusCode::OK); + let v: serde_json::Value = serde_json::from_str(&b).unwrap(); + assert_eq!(v["status"], "ok"); + assert!(v["version"].is_string()); +} + +#[tokio::test] +async fn fake_state_carries_the_registry() { + let fake = FakeTransport::new(); + let reg = registry_with(fake, fake_peers_config(&["beta", "gamma"])); + let state = fake_state_with_peers(Config::default(), reg); + let peers = state.peers.as_ref().expect("registry present"); + let names: Vec<_> = peers + .snapshot() + .into_iter() + .map(|p| p.name.as_str().to_owned()) + .collect(); + assert_eq!(names, ["beta", "gamma"]); + assert_eq!(peers.status("beta").unwrap().api.auth, AuthState::Unknown); +} + +#[tokio::test] +async fn registry_proxies_through_the_fake_and_records_the_request() { + let fake = FakeTransport::new(); + fake.peer("beta") + .respond("/systemd/units", 200, "application/json", r#"{"units":[]}"#); + let reg = registry_with(fake.clone(), fake_peers_config(&["beta"])); + + let resp = reg + .get( + "beta", + "/systemd/units", + &[("state".into(), "failed".into())], + ProxyOpts::default(), + ) + .await + .unwrap(); + assert_eq!(resp.status, 200); + + let calls = fake.calls(); + assert_eq!(calls.len(), 1); + assert_eq!( + calls[0].1.query, + vec![("state".to_owned(), "failed".to_owned())] + ); + assert!(calls[0] + .1 + .headers + .iter() + .any(|(k, v)| k.as_str() == "x-slinuxm-hop" && v == "1")); + assert!(!calls[0] + .1 + .headers + .iter() + .any(|(k, _)| k.as_str() == "authorization")); +} + +#[tokio::test] +async fn unknown_peer_and_peer_failures_use_the_shared_mapping() { + let fake = FakeTransport::new(); + fake.peer("beta") + .respond_err("/systemd/units", PeerError::Rejected); + let reg = registry_with(fake, fake_peers_config(&["beta"])); + + let err = reg + .get("nope", "/systemd/units", &[], ProxyOpts::default()) + .await + .unwrap_err(); + assert_eq!(err.code(), "not_found"); + assert_eq!(err.message(), "peer nope: unknown peer"); + + let err = reg + .get("beta", "/systemd/units", &[], ProxyOpts::default()) + .await + .unwrap_err(); + assert_eq!(err.code(), "unavailable"); + assert_eq!(err.status(), StatusCode::SERVICE_UNAVAILABLE); + assert!(err.message().contains("beta")); + assert_eq!(err.message(), "peer beta: peer rejected credentials"); +} + +#[tokio::test] +async fn static_registry_is_sorted_and_serves_rendering() { + let reg = static_registry(vec![status("gamma", false), status("beta", true)]); + let snap = reg.snapshot(); + assert_eq!(snap[0].name.as_str(), "beta"); + assert_eq!(snap[1].name.as_str(), "gamma"); + assert!(reg.status("beta").unwrap().server.up); + assert_eq!(reg.status("nope").unwrap_err().code(), "not_found"); + + // Static snapshots do not script the transport; unscripted GETs still use + // the fake defaults, so a proxy call is bounded and never touches a socket. + let resp = tokio::time::timeout( + Duration::from_secs(1), + reg.get("beta", "/systemd/units", &[], ProxyOpts::default()), + ) + .await + .expect("fake transport must not block") + .unwrap(); + assert_eq!(resp.status, 404); +}