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