~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
461 lines · 15.5 KB Raw History
//! 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<Read> {
        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<Line>),
}

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::<usize>(),
                );
                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::<Vec<_>>() })
            }
        }
    }
}

/// A kept line: as written, and as parsed.
pub(crate) struct Line {
    raw: String,
    obj: Map<String, Json>,
}

/// Answer a read: the call's `nsid` is its route.
pub(crate) async fn read(svc: &Shared, read: Read, call: &Call<'_>) -> Result<Answer, XrpcError> {
    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<Shared>,
    method: Method,
    uri: Uri,
    headers: HeaderMap,
    peer: Option<Extension<limits::Peer>>,
) -> Response<Body> {
    xrpc(st, Read::Logs, method, uri, headers, peer).await
}

/// `GET /xrpc/_stats`.
pub(crate) async fn stats(
    st: State<Shared>,
    method: Method,
    uri: Uri,
    headers: HeaderMap,
    peer: Option<Extension<limits::Peer>>,
) -> Response<Body> {
    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<Shared>,
    read_: Read,
    method: Method,
    uri: Uri,
    headers: HeaderMap,
    peer: Option<Extension<limits::Peer>>,
) -> Response<Body> {
    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: &params,
        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<String>,
    msg: Option<String>,
    method: Option<String>,
    level: Option<Level>,
    min_ms: Option<i64>,
    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<Query, XrpcError> {
        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::<i64>() {
            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<String, Json>) -> bool {
        let is = |field: &str, want: &Option<String>| {
            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<Vec<Line>> {
        // 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<Map<String, Json>> {
    let fields: Map<String, Json> = serde_json::from_str::<
        std::collections::BTreeMap<String, Box<serde_json::value::RawValue>>,
    >(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::<f64>().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<Query, &'static str> {
        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));
    }
}