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.
This commit is contained in:
ari committed 2026-10-19 20:02:17 -04:00
1 parent 746b389a2b
commit 4bfb097be6
22 files changed
+1781 -1

No files matched your search

Generated
+3
View File
@@ -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]]
+2
View File
@@ -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"] }
+6
View File
@@ -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<Secret, PeerError>`) 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.
+1
View File
@@ -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`.
+1
View File
@@ -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<Arc<PeerRegistry>>` 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.
@@ -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.
+11 -1
View File
@@ -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)
+12
View File
@@ -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<AppState> {
Router::new()
}
+41
View File
@@ -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<AppState> {
Router::new().route("/ping", get(ping))
}
async fn ping() -> Json<serde_json::Value> {
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"));
}
}
+3
View File
@@ -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)]
+1
View File
@@ -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;
+172
View File
@@ -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);
}
}
+164
View File
@@ -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);
}
}
+17
View File
@@ -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};
+114
View File
@@ -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<PeerResponse, AppError> {
// 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");
}
}
+254
View File
@@ -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<String>,
pub accept_sse: bool,
}
struct RegistryState {
config: Arc<PeersConfig>,
statuses: BTreeMap<PeerName, PeerStatus>,
}
pub struct PeerRegistry {
transport: Arc<dyn PeerTransport>,
state: RwLock<RegistryState>,
}
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<T>(lock: &RwLock<T>) -> std::sync::RwLockReadGuard<'_, T> {
lock.read().unwrap_or_else(|e| e.into_inner())
}
fn lock_write<T>(lock: &RwLock<T>) -> std::sync::RwLockWriteGuard<'_, T> {
lock.write().unwrap_or_else(|e| e.into_inner())
}
impl PeerRegistry {
pub(crate) fn new(config: PeersConfig, transport: Arc<dyn PeerTransport>) -> 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<PeerStatus>,
config: PeersConfig,
transport: Arc<dyn PeerTransport>,
) -> 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<PeerStatus> {
lock_read(&self.state).statuses.values().cloned().collect()
}
pub fn status(&self, name: &str) -> Result<PeerStatus, AppError> {
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<PeersConfig> {
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<PeerResponse, AppError> {
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(&reg.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);
}
}
+433
View File
@@ -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<String>,
body: Bytes,
},
Stream {
content_type: String,
chunks: Vec<Bytes>,
},
Err(PeerError),
}
#[derive(Clone)]
struct PeerState {
tcp: Result<Duration, PeerError>,
scripts: Vec<(String, Scripted)>,
delay: Option<Duration>,
}
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<BTreeMap<PeerName, PeerState>>,
calls: Mutex<Vec<(PeerName, PeerRequest)>>,
}
impl FakeTransport {
pub fn new() -> Arc<Self> {
Arc::new(Self::default())
}
pub fn peer(self: &Arc<Self>, 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<FakeTransport>,
name: PeerName,
}
impl FakePeerBuilder {
pub fn tcp(self, result: Result<Duration, PeerError>) -> 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<Bytes>,
) -> 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<Bytes>) -> 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<Duration, PeerError> {
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<PeerResponse, PeerError> {
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<FakeTransport>, cfg: PeersConfig) -> Arc<PeerRegistry> {
Arc::new(PeerRegistry::new(cfg, fake))
}
/// Registry with a fixed snapshot, for tests that only render status.
pub fn static_registry(statuses: Vec<PeerStatus>) -> Arc<PeerRegistry> {
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<PeerRegistry>) -> 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);
}
}
+61
View File
@@ -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<String>,
}
#[derive(Debug)]
pub struct PeerResponse {
pub status: u16,
pub content_type: Option<String>,
pub body: PeerBody,
}
/// Body of a peer response: buffered (capped by the transport) or streamed.
pub enum PeerBody {
Bytes(Bytes),
Stream(BoxStream<'static, Result<Bytes, PeerError>>),
}
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<Duration, PeerError>;
/// 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<PeerResponse, PeerError>;
}
+319
View File
@@ -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<Self, ConfigError> {
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<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
s.serialize_str(&self.0)
}
}
impl<'de> Deserialize<'de> for PeerName {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
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<String>) -> 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<PathBuf>,
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<String>,
pub peer: Vec<PeerConfig>,
}
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<Timestamp>,
pub last_checked: Option<Timestamp>,
pub last_error: Option<String>,
pub latency_ms: Option<u64>,
}
#[derive(Debug, Clone, PartialEq, Default, Serialize)]
pub struct ApiStatus {
pub up: bool,
pub since: Option<Timestamp>,
pub last_checked: Option<Timestamp>,
pub last_error: Option<String>,
pub latency_ms: Option<u64>,
pub auth: AuthState,
pub peer_version: Option<String>,
}
/// `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::<PeerName>(&json).unwrap(), n);
assert!(serde_json::from_str::<PeerName>("\"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");
}
}
+1
View File
@@ -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,
}
}
+4
View File
@@ -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<dyn DockerSource>,
/// `None` when auth is disabled.
pub db: Option<SqlitePool>,
/// `None` when the peers feature is off: no routes, tools, tasks or metrics.
pub peers: Option<Arc<PeerRegistry>>,
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,
}
}
+160
View File
@@ -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);
}