Files
skyg-linux-tracker/src/peers/proxy.rs
T

426 lines
14 KiB
Rust

//! Proxy one GET to a peer.
//!
//! REST and MCP both call [`get`]. The allowlist is the peer's documented
//! read routes; `ping` and `peers` are excluded so this cannot chain or
//! become an open proxy. Caller credentials are never copied: the transport
//! attaches the peer token itself.
//!
//! Callers may name a route with or without the `/api/v1` prefix; validation
//! works on the route alone (`/systemd/units`) and forwards the canonical peer
//! path (`/api/v1/systemd/units`), which is what a peer serves.
use std::time::Duration;
use tokio::time::Instant;
use axum::http::{HeaderMap, HeaderName, HeaderValue, StatusCode};
use bytes::Bytes;
use futures::stream::{BoxStream, Stream, StreamExt};
use tokio_util::sync::CancellationToken;
use super::error::{peer_error_to_app, PeerError};
use super::registry::ProxyOpts;
use super::transport::{PeerBody, PeerRequest, PeerResponse, PeerTransport};
use super::types::{PeerConfig, PeerName};
use crate::error::AppError;
use crate::sources::systemd::validate_unit_name;
const HOP_HEADER: &str = "x-slinuxm-hop";
const TRACEPARENT: &str = "traceparent";
/// Response header naming the peer a proxied response came from.
pub(crate) const PEER_HEADER: &str = "x-slinuxm-peer";
/// Reject an inbound hop marker. Any value counts: a consolidator must not
/// forward a request that has already been proxied.
pub(crate) fn reject_inbound_hop(peer: &str, headers: &HeaderMap) -> Result<(), AppError> {
if headers.contains_key(HOP_HEADER) {
return Err(chained(peer));
}
Ok(())
}
fn chained(peer: &str) -> AppError {
AppError::BadRequest(format!("peer {peer}: chained requests are not allowed"))
}
fn path_rejected(peer: &PeerName) -> AppError {
AppError::BadRequest(format!("peer {peer}: path not allowed"))
}
fn query_rejected(peer: &str) -> AppError {
AppError::BadRequest(format!("peer {peer}: unsupported query parameter"))
}
/// Parse a raw query string. Bad encodings are rejected before the pairs are
/// handed to [`get`], which checks the allowlist again.
pub(crate) fn query_from_raw(
peer: &str,
raw: Option<&str>,
) -> Result<Vec<(String, String)>, AppError> {
let Some(raw) = raw.filter(|s| !s.is_empty()) else {
return Ok(Vec::new());
};
if raw.len() > 4096 || encoding_forbidden(raw) || raw.chars().any(|c| c.is_control()) {
return Err(query_rejected(peer));
}
Ok(url::form_urlencoded::parse(raw.as_bytes())
.map(|(k, v)| (k.into_owned(), v.into_owned()))
.collect())
}
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> {
let Validated { path, query, sse } = validate(&peer.name, path, query, opts.accept_sse)?;
// 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) {
if !value.as_bytes().contains(&b' ') {
headers.push((HeaderName::from_static(TRACEPARENT), value));
}
}
}
let req = PeerRequest {
path,
query,
headers,
accept: sse.then(|| "text/event-stream".to_owned()),
};
let result = tokio::time::timeout(timeout, transport.get(peer, req, timeout)).await;
match result {
Ok(Ok(resp)) => Ok(resp),
Ok(Err(e)) => Err(peer_error_to_app(&peer.name, &e)),
Err(_elapsed) => Err(peer_error_to_app(&peer.name, &PeerError::Timeout)),
}
}
/// A peer response shaped for a surface: status already classified, the
/// peer's content type checked, body bounded. REST and MCP both build their
/// response from this so neither owns a second copy of the limits.
pub(crate) struct PreparedResponse {
pub status: StatusCode,
pub content_type: Option<HeaderValue>,
pub body: PreparedBody,
}
/// One table for peer statuses: the transport classifies a live response with
/// it and [`prepare_response`] checks again, so neither side can drift.
pub(crate) fn classify_status(status: u16) -> PeerError {
match status {
404 => PeerError::NotFound,
401 | 403 => PeerError::Rejected,
code => PeerError::Http(code),
}
}
/// The contract promises pass-through only for 2xx, so anything else is
/// classified here rather than relayed: a transport that forgot to map a
/// redirect or the peer's own error body must not reach the caller.
pub(crate) fn prepare_response(
peer: &PeerName,
resp: PeerResponse,
max_bytes: u64,
deadline: Instant,
shutdown: CancellationToken,
) -> Result<PreparedResponse, AppError> {
let status = match StatusCode::from_u16(resp.status) {
Ok(status) if status.is_success() => status,
_ => return Err(peer_error_to_app(peer, &classify_status(resp.status))),
};
let content_type = content_type(peer, resp.content_type.as_deref())?;
let body = prepare_body(peer, resp.body, max_bytes, deadline, shutdown)?;
Ok(PreparedResponse {
status,
content_type,
body,
})
}
fn content_type(peer: &PeerName, value: Option<&str>) -> Result<Option<HeaderValue>, AppError> {
match value {
None => Ok(None),
Some(value) => HeaderValue::from_str(value)
.map(Some)
.map_err(|_| peer_error_to_app(peer, &PeerError::Malformed(String::new()))),
}
}
/// Buffered bodies over the cap become `Oversize`. Streams are cut off at the
/// cap, at `deadline`, or when `shutdown` fires, because a follow holds a
/// connection until the peer closes it.
pub(crate) fn prepare_body(
peer: &PeerName,
body: PeerBody,
max_bytes: u64,
deadline: Instant,
shutdown: CancellationToken,
) -> Result<PreparedBody, AppError> {
match body {
PeerBody::Bytes(bytes) if bytes.len() as u64 > max_bytes => {
Err(peer_error_to_app(peer, &PeerError::Oversize))
}
PeerBody::Bytes(bytes) => Ok(PreparedBody::Bytes(bytes)),
PeerBody::Stream(stream) => Ok(PreparedBody::Stream(Box::pin(bound_stream(
stream, max_bytes, deadline, shutdown,
)))),
}
}
pub(crate) enum PreparedBody {
Bytes(Bytes),
Stream(BoxStream<'static, Result<Bytes, std::io::Error>>),
}
fn bound_stream(
stream: BoxStream<'static, Result<Bytes, PeerError>>,
max_bytes: u64,
deadline: Instant,
shutdown: CancellationToken,
) -> impl Stream<Item = Result<Bytes, std::io::Error>> + Send {
futures::stream::unfold((stream, 0u64), move |(mut stream, sent)| {
let shutdown = shutdown.clone();
async move {
let next = tokio::select! {
biased;
() = shutdown.cancelled() => return None,
() = tokio::time::sleep_until(deadline) => return None,
item = stream.next() => item,
};
let bytes = match next? {
Ok(bytes) => bytes,
// Headers are already sent. Dropping the chunk keeps a
// token-file path or peer URL out of the body.
Err(_) => return None,
};
if sent.saturating_add(bytes.len() as u64) > max_bytes {
return None;
}
let sent = sent + bytes.len() as u64;
Some((Ok(bytes), (stream, sent)))
}
})
}
struct Validated {
path: String,
query: Vec<(String, String)>,
sse: bool,
}
fn validate(
peer: &PeerName,
path: &str,
query: &[(String, String)],
accept_sse: bool,
) -> Result<Validated, AppError> {
let route = canonical_route(path).ok_or_else(|| path_rejected(peer))?;
let query = allow_query(peer, &route, query)?;
let sse = accept_sse || route_is_follow(&route, &query);
Ok(Validated {
// The allowlist and the query rules work on the route; the peer only
// serves it below its own API prefix.
path: format!("/api/v1/{route}"),
query,
sse,
})
}
fn canonical_route(path: &str) -> Option<String> {
if path.len() > 512 || encoding_forbidden(path) {
return None;
}
let mut rel = path.trim_start_matches('/');
if let Some(rest) = rel.strip_prefix("api/v1/") {
rel = rest;
}
if rel.is_empty() {
return None;
}
let mut decoded = Vec::new();
let mut forward = Vec::new();
for raw in rel.split('/') {
let segment = percent_encoding::percent_decode_str(raw)
.decode_utf8()
.ok()?;
if !segment_ok(&segment) {
return None;
}
forward.push(percent_encoding::utf8_percent_encode(&segment, SEGMENT_SET).to_string());
decoded.push(segment.into_owned());
}
if !route_allowed(&decoded.join("/")) {
return None;
}
// The forward path is re-encoded rather than the caller's text reused so
// a backslash from an escaped unit name cannot be read as a separator by
// the HTTP client.
Some(forward.join("/"))
}
/// Characters that must stay percent-encoded in a forwarded segment.
const SEGMENT_SET: &percent_encoding::AsciiSet = &percent_encoding::CONTROLS
.add(b' ')
.add(b'"')
.add(b'#')
.add(b'%')
.add(b'/')
.add(b'<')
.add(b'>')
.add(b'?')
.add(b'[')
.add(b'\\')
.add(b']')
.add(b'^')
.add(b'`')
.add(b'{')
.add(b'|')
.add(b'}');
/// Segment-level rules only; the allowlist below decides which characters a
/// segment may carry for its route.
fn segment_ok(segment: &str) -> bool {
!segment.is_empty()
&& segment != "."
&& segment != ".."
&& !segment
.chars()
.any(|c| c.is_control() || matches!(c, '%' | '?' | '#' | '/'))
}
/// Encoded slash, dot-dot, NUL and CRLF, including a second layer of encoding
/// (`%252f`, `%255c`). A single `%5c` is not listed: systemd escapes names
/// such as `dev-disk-by\x2did.device`, and the local route accepts them, so
/// the allowlist decides where a backslash is legal.
fn encoding_forbidden(raw: &str) -> bool {
let lower = raw.to_ascii_lowercase();
["%2f", "%00", "%0a", "%0d", "%2e%2e", "%252f", "%255c"]
.iter()
.any(|needle| lower.contains(needle))
}
fn route_allowed(route: &str) -> bool {
matches!(
route,
"systemd/units" | "systemd/timers" | "journal" | "journal/follow" | "docker/ps"
) || unit_path(route)
|| container_path(route)
}
/// Unit names go through the same validation as the local route.
fn unit_path(route: &str) -> bool {
route
.strip_prefix("systemd/units/")
.is_some_and(|name| validate_unit_name(name).is_ok())
}
fn container_path(route: &str) -> bool {
let Some(rest) = route.strip_prefix("docker/containers/") else {
return false;
};
match rest.strip_suffix("/logs") {
Some(name) => resource_segment(name),
None => resource_segment(rest),
}
}
fn resource_segment(name: &str) -> bool {
let mut chars = name.chars();
let Some(first) = chars.next() else {
return false;
};
first.is_ascii_alphanumeric()
&& name
.chars()
.all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-' | '@' | ':'))
}
fn allowed_keys(route: &str) -> &'static [&'static str] {
match route {
"systemd/units" => &["state"],
"journal" | "journal/follow" => &["unit", "priority", "lines", "since"],
"docker/ps" => &["all"],
logs if logs.starts_with("docker/containers/") && logs.ends_with("/logs") => {
&["tail", "since", "follow"]
}
_ => &[],
}
}
fn allow_query(
peer: &PeerName,
route: &str,
query: &[(String, String)],
) -> Result<Vec<(String, String)>, AppError> {
if query.len() > 8 {
return Err(query_rejected(peer.as_str()));
}
let allowed = allowed_keys(route);
let mut seen = Vec::new();
let mut out = Vec::with_capacity(query.len());
for (key, value) in query {
let known = allowed.iter().any(|name| *name == key);
if !known
|| !query_key_ok(key)
|| !query_value_ok(key, value)
|| seen.contains(&key.as_str())
{
return Err(query_rejected(peer.as_str()));
}
seen.push(key.as_str());
out.push((key.clone(), value.clone()));
}
Ok(out)
}
fn query_key_ok(key: &str) -> bool {
!key.is_empty()
&& key.len() <= 32
&& key
.chars()
.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_')
}
/// Values arrive decoded and leave as encoded query pairs, so only control
/// characters and a second encoding layer are unsafe here. The journal `unit`
/// filter is a unit name, so it gets the local route's unit check verbatim:
/// that is where a backslash (systemd's escape) is legal.
fn query_value_ok(key: &str, value: &str) -> bool {
if value.len() > 1024 || encoding_forbidden(value) {
return false;
}
if key == "unit" {
return validate_unit_name(value).is_ok();
}
!value
.chars()
.any(|c| c.is_control() || c == '\\' || c == '/')
&& !value.contains("..")
}
fn route_is_follow(route: &str, query: &[(String, String)]) -> bool {
if route == "journal/follow" {
return true;
}
route.ends_with("/logs")
&& query
.iter()
.any(|(key, value)| key == "follow" && matches!(value.as_str(), "1" | "true"))
}
#[cfg(test)]
#[path = "proxy_tests.rs"]
mod tests;