chadtmiller.com/monolith
An atproto PDS
0
0
//! 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: ¶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<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));
}
}