//! The admin's reads, `GET /xrpc/_logs` and `GET /xrpc/_stats` //! (`spec/OPERATIONS.md`, "The admin's reads"): the lines kept in //! `PDS_LOG_DIR`, and what the metrics counted. Each is answered by `read`, //! over XRPC (`logs`, `stats`) and as the MCP tools `admin_logs` and //! `admin_stats` (`spec/COMMANDS.md`, "The admin's reads"): the admin's //! `Basic` auth first, then the method, then the parameters, then a point of //! `global`. use super::{Level, kept::Snapshot}; use crate::{Call, Shared, XrpcError, err, invalid, limits, sessions}; use axum::body::Body; use axum::extract::{Extension, State}; use axum::http::{HeaderMap, Method, Response, StatusCode, Uri, header}; use serde_json::{Map, Value as Json, json}; use std::sync::OnceLock; /// One of the admin's reads. #[derive(Clone, Copy, PartialEq, Eq, Debug)] pub(crate) enum Read { Logs, Stats, } /// `limit`'s bounds, and its value when not given. const MOST: i64 = 500; const LIMIT: i64 = 100; impl Read { /// Its route, as its request's line and metrics label it. pub fn route(self) -> &'static str { match self { Read::Logs => "_logs", Read::Stats => "_stats", } } /// The read whose MCP tool has this name. pub fn of_tool(name: &str) -> Option { match name { "admin_logs" => Some(Read::Logs), "admin_stats" => Some(Read::Stats), _ => None, } } /// Their MCP tools, as `spec/COMMANDS.md`, "The admin's reads", gives them. pub fn tools() -> [Json; 2] { let string = json!({ "type": "string" }); [ json!({ "name": "admin_logs", "title": pds_lexicon::title("admin", "logs"), "description": "As the admin, the lines the server logged and kept in PDS_LOG_DIR, oldest first: the last of those of a trace, a message, a route, a level and above, or a time. Needs the admin's Basic auth.", "inputSchema": { "type": "object", "properties": { "trace": string, "msg": string, "method": string, "level": { "type": "string", "enum": ["debug", "info", "warn", "error"] }, "minMs": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": MOST }, }, "required": [], }, "annotations": { "readOnlyHint": true }, }), json!({ "name": "admin_stats", "title": pds_lexicon::title("admin", "stats"), "description": "As the admin, what the server counted since it started: its requests by route and status with their mean times, the requests it made, its syncs, its accounts and its firehose. Needs the admin's Basic auth.", "inputSchema": { "type": "object", "properties": {}, "required": [] }, "annotations": { "readOnlyHint": true }, }), ] } } /// A read's answer: `_stats`' JSON, or `_logs`' lines. pub(crate) enum Answer { Json(Json), Lines(Vec), } impl Answer { /// Its JSON text, each line of `_logs` as it was written, its fields /// in their order. fn text(&self) -> String { match self { Answer::Json(j) => j.to_string(), Answer::Lines(lines) => { let mut s = String::with_capacity( 14 + lines.iter().map(|l| l.raw.len() + 1).sum::(), ); s.push_str("{\"lines\":["); for (i, l) in lines.iter().enumerate() { if i > 0 { s.push(','); } s.push_str(&l.raw); } s.push_str("]}"); s } } } /// As a JSON value, as an MCP tool answers it. pub fn json(self) -> Json { match self { Answer::Json(j) => j, Answer::Lines(lines) => { json!({ "lines": lines.into_iter().map(|l| Json::Object(l.obj)).collect::>() }) } } } } /// A kept line: as written, and as parsed. pub(crate) struct Line { raw: String, obj: Map, } /// Answer a read: the call's `nsid` is its route. pub(crate) async fn read(svc: &Shared, read: Read, call: &Call<'_>) -> Result { crate::invites::admin(svc, call.bearer)?; if *call.method != Method::GET { return invalid(format!( "Incorrect HTTP method ({}) expected GET", call.method )); } match read { Read::Logs => { let q = Query::parse(call.params)?; limits::charge(svc, call, None, None)?; let Some(kept) = super::kept_now() else { return err(404, "LogNotKept", "PDS_LOG_DIR is not set: no log is kept"); }; match tokio::task::spawn_blocking(move || q.lines(&kept)).await { Ok(Ok(lines)) => Ok(Answer::Lines(lines)), _ => crate::internal(), } } Read::Stats => { limits::charge(svc, call, None, None)?; let o = super::ops(); Ok(Answer::Json(o.metrics.stats(svc, &o.started))) } } } /// `GET /xrpc/_logs`. pub(crate) async fn logs( st: State, method: Method, uri: Uri, headers: HeaderMap, peer: Option>, ) -> Response { xrpc(st, Read::Logs, method, uri, headers, peer).await } /// `GET /xrpc/_stats`. pub(crate) async fn stats( st: State, method: Method, uri: Uri, headers: HeaderMap, peer: Option>, ) -> Response { xrpc(st, Read::Stats, method, uri, headers, peer).await } /// A read over XRPC: `200` with its JSON, or its error, with what it cost /// of the rate limits. async fn xrpc( State(svc): State, read_: Read, method: Method, uri: Uri, headers: HeaderMap, peer: Option>, ) -> Response { let params: Vec<(String, String)> = uri .query() .map(|q| { url::form_urlencoded::parse(q.as_bytes()) .into_owned() .collect() }) .unwrap_or_default(); let authorization = crate::authorization(&headers); let call = Call { nsid: read_.route(), method: &method, params: ¶ms, body: &[], bearer: sessions::Bearer::of(authorization.as_deref()), headers: &headers, client: limits::client( &svc.config.trusted_proxies, &headers, peer.map(|Extension(p)| p.0), ), charged: OnceLock::new(), http: None, }; match read(&svc, read_, &call).await { Ok(a) => { let mut res = Response::new(Body::from(a.text())); res.headers_mut().insert( header::CONTENT_TYPE, header::HeaderValue::from_static("application/json; charset=utf-8"), ); *res.status_mut() = StatusCode::OK; if let Some(c) = call.charged.get() { c.apply(res.headers_mut()); } res } Err(e) => crate::respond(Err(e), call.charged.get()), } } /// `_logs`'s parameters: what a line must be to match. #[derive(Debug, PartialEq)] struct Query { trace: Option, msg: Option, method: Option, level: Option, min_ms: Option, limit: usize, } impl Query { /// From the query's pairs: the first of a repeated one counts, and one /// `_logs` does not take is passed over. fn parse(params: &[(String, String)]) -> Result { let mut q = Query { trace: None, msg: None, method: None, level: None, min_ms: None, limit: LIMIT as usize, }; let mut seen: Vec<&str> = Vec::new(); let integer = |k: &str, v: &str, least: i64, most: i64| match v.parse::() { Ok(n) if (least..=most).contains(&n) => Ok(n), Ok(_) => invalid(format!("Params/{k} must be in the range {least}..={most}")), Err(_) => invalid(format!("Params/{k} must be an integer")), }; for (k, v) in params { let k = k.as_str(); if seen.contains(&k) { continue; } match k { "trace" => q.trace = Some(v.clone()), "msg" => q.msg = Some(v.clone()), "method" => q.method = Some(v.clone()), "level" => { q.level = Some(match v.as_str() { "debug" => Level::Debug, "info" => Level::Info, "warn" => Level::Warn, "error" => Level::Error, _ => { return invalid( "Params/level must be one of debug, info, warn or error", ); } }) } "minMs" => q.min_ms = Some(integer(k, v, 0, i64::MAX)?), "limit" => q.limit = integer(k, v, 1, MOST)? as usize, _ => continue, } seen.push(k); } Ok(q) } /// Whether a line, as it parsed, matches. fn matches(&self, line: &Map) -> bool { let is = |field: &str, want: &Option| { want.as_deref() .is_none_or(|w| line.get(field).and_then(Json::as_str) == Some(w)) }; is("trace_id", &self.trace) && is("msg", &self.msg) && is("method", &self.method) && self.level.is_none_or(|least| { let level = match line.get("level").and_then(Json::as_str) { Some("debug") => Level::Debug, Some("info") => Level::Info, Some("warn") => Level::Warn, Some("error") => Level::Error, _ => return false, }; level >= least }) && self.min_ms.is_none_or(|least| { line.get("ms") .and_then(Json::as_f64) .is_some_and(|ms| ms >= least as f64) }) } /// The last `limit` lines kept that match, oldest first. Lines that are /// no JSON object, as one cut short by a lost power, are passed over. fn lines(&self, kept: &Snapshot) -> std::io::Result> { // A value written as it is, with nothing JSON escapes, is in the // bytes of any line it matches: lines without it are not parsed. let needles: Vec<&[u8]> = [&self.trace, &self.msg, &self.method] .into_iter() .filter_map(|v| { v.as_deref() .filter(|v| !v.bytes().any(|b| b == b'"' || b == b'\\' || b < 0x20)) .map(str::as_bytes) }) .collect(); let mut out = Vec::new(); kept.lines_back(|line| { if needles.iter().all(|n| contains(line, n)) && let Ok(raw) = std::str::from_utf8(line) && let Some(obj) = parse_line(raw) && self.matches(&obj) { out.push(Line { raw: raw.to_string(), obj, }); } out.len() < self.limit })?; out.reverse(); Ok(out) } } /// A line as the JSON object it is, if it is one: each number with a /// fraction or an exponent read as the nearest `f64`, as it was written /// from (`serde_json` reads them to within a unit of the last place). fn parse_line(raw: &str) -> Option> { let fields: Map = serde_json::from_str::< std::collections::BTreeMap>, >(raw) .ok()? .into_iter() .map(|(k, v)| { let t = v.get(); let float = t.starts_with(|c: char| c == '-' || c.is_ascii_digit()) && t.contains(['.', 'e', 'E']); let value = float .then(|| t.parse::().ok().and_then(serde_json::Number::from_f64)) .flatten() .map(Json::Number) .or_else(|| serde_json::from_str(t).ok()) .unwrap_or(Json::Null); (k, value) }) .collect(); Some(fields) } fn contains(hay: &[u8], needle: &[u8]) -> bool { needle.is_empty() || hay.windows(needle.len()).any(|w| w == needle) } #[cfg(test)] mod tests { use super::*; fn q(pairs: &[(&str, &str)]) -> Result { let pairs: Vec<(String, String)> = pairs .iter() .map(|(k, v)| (k.to_string(), v.to_string())) .collect(); Query::parse(&pairs).map_err(|e| e.name) } #[test] fn parameters() { let all = q(&[ ("trace", "ab"), ("level", "warn"), ("minMs", "0"), ("limit", "500"), ("limit", "x"), ("other", "1"), ]) .unwrap(); assert_eq!( all, Query { trace: Some("ab".into()), msg: None, method: None, level: Some(Level::Warn), min_ms: Some(0), limit: 500, } ); assert_eq!(q(&[]).unwrap().limit, 100); for bad in [ ("level", "loud"), ("level", "off"), ("minMs", "-1"), ("minMs", "1.5"), ("limit", "0"), ("limit", "501"), ("limit", "x"), ] { assert_eq!(q(&[bad]).unwrap_err(), "InvalidRequest", "{bad:?}"); } } /// A line's numbers are read as the `f64`s they were written from, and /// what is no JSON object is no line. #[test] fn exact_lines() { for ms in [ 0.045791000000000005, 3.735292, 0.1 + 0.2, 1e-7, 12345.678901234567, ] { let raw = json!({ "msg": "request", "ms": ms, "status": 200 }).to_string(); let got = parse_line(&raw).unwrap(); assert_eq!(got["ms"].as_f64(), Some(ms), "{raw}"); assert_eq!(got["status"], json!(200)); } assert!(parse_line("{\"cut").is_none()); assert!(parse_line("[1]").is_none()); } #[test] fn matching() { let line = |v: Json| v.as_object().unwrap().clone(); let req = line( json!({ "level": "info", "msg": "request", "method": "/mcp", "ms": 3.5, "trace_id": "ab" }), ); let start = line(json!({ "level": "info", "msg": "start" })); let warn = line(json!({ "level": "warn", "msg": "plc failure" })); let query = |pairs: &[(&str, &str)]| q(pairs).unwrap(); assert!(query(&[]).matches(&req)); assert!(query(&[("minMs", "3")]).matches(&req)); assert!(!query(&[("minMs", "4")]).matches(&req)); assert!(!query(&[("minMs", "0")]).matches(&start)); assert!(query(&[("level", "info")]).matches(&warn)); assert!(!query(&[("level", "error")]).matches(&warn)); assert!(query(&[("trace", "ab"), ("method", "/mcp")]).matches(&req)); assert!(!query(&[("trace", "ab")]).matches(&start)); assert!(!query(&[("msg", "request")]).matches(&warn)); } }