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

+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");
}
}