chadtmiller.com/monolith
An atproto PDS
0
0
//! `pds xrpc <kind> <name> [args]`: one XRPC call of the server at
//! `PDS_URL` by its name, with `goat xrpc`'s arguments (`spec/COMMANDS.md`,
//! "Any call"). It knows no lexicon: it fills in nothing and checks no
//! argument against one, so the server answers what is wrong with a call.
use super::{Server, Stop, is_help, print_error, usage};
use pds_lexicon::JSON;
use reqwest::header::{AUTHORIZATION, CONTENT_TYPE, HeaderName, HeaderValue};
use serde_json::value::RawValue;
use serde_json::{Map, Value as Json};
use std::io::{Read, Write};
/// The command's name, after `pds`; no group of methods is named so.
pub const COMMAND: &str = "xrpc";
const HELP: &str = "Usage: pds xrpc <kind> <name> [args]
Make one XRPC call of the server at PDS_URL by its name, with the auth the
other commands send (PDS_TOKEN, else PDS_ADMIN_PASSWORD): a method it serves,
one it forwards, or one of its own routes, as _logs. Nothing is checked
against a lexicon: the server answers what is wrong with a call.
<kind> query (or get), a GET; procedure (or post), a POST; in any case
<name> an NSID, or a route of the server's own, _ then letters
key==value a query parameter; given again, one more value of it
key=value a string property of the JSON body
key:=json a property of the JSON body, any JSON
Name:value a request header; Authorization given so replaces the CLI's
- the body, standard input as it comes
@path a JSON object read from the file, its properties the body's
before any given after it
An argument is read at its first : or =: == makes a parameter, := a JSON
property, a lone = a string property and a lone : a header. A procedure's body
is -'s, or else the JSON object of its properties, {} with none, as
application/json unless a header names another Content-Type; a query has none.
A JSON answer is printed on one line, exit 0; an answer of another
Content-Type is written as its bytes; an error is printed as
{status, error, message}, exit 1; a server that cannot be reached is exit 3;
a usage error is exit 2, with no call made.
Examples:
pds xrpc query com.atproto.repo.listRecords repo==alice.test collection==app.bsky.feed.post limit==5
pds xrpc procedure com.atproto.repo.createRecord repo=alice.test collection=com.example.note 'record:={\"text\":\"hi\"}'
pds xrpc query _oauthSessions
pds xrpc procedure com.atproto.repo.uploadBlob Content-Type:image/png - < cat.png
";
/// A call, as its arguments give it.
#[derive(Debug, PartialEq)]
struct Call {
/// A procedure's `POST`, rather than a query's `GET`.
post: bool,
name: String,
params: Vec<(String, String)>,
headers: Vec<(HeaderName, HeaderValue)>,
/// The JSON body's properties.
props: Map<String, Json>,
/// Whether a body property, or an `@path`, was given.
props_given: bool,
/// Whether the body is standard input (`-`).
stdin: bool,
}
/// Run `pds xrpc` with its arguments, after `xrpc`.
pub fn run(args: &[String]) -> Result<u8, Stop> {
if args.iter().any(|a| is_help(a)) {
print!("{HELP}");
return Ok(0);
}
send(parse(args)?)
}
/// The call the arguments make, or the usage error they are.
fn parse(args: &[String]) -> Result<Call, Stop> {
let [kind, name, rest @ ..] = args else {
return usage(format!("pds xrpc needs a kind and a name\n\n{HELP}"));
};
let post = match kind.to_ascii_lowercase().as_str() {
"query" | "get" => false,
"procedure" | "post" => true,
_ => {
return usage(format!(
"pds xrpc: no kind {kind:?}: it is query (or get) or procedure (or post)"
));
}
};
if !is_nsid(name) && !is_route(name) {
return usage(format!(
"pds xrpc: {name:?} is neither an NSID nor a route of the server's own, _ then letters"
));
}
let mut call = Call {
post,
name: name.clone(),
params: Vec::new(),
headers: Vec::new(),
props: Map::new(),
props_given: false,
stdin: false,
};
for a in rest {
if a == "-" {
if call.stdin {
return usage("pds xrpc: - is given twice");
}
call.stdin = true;
continue;
}
if let Some(path) = a.strip_prefix('@') {
let text = std::fs::read_to_string(path)
.or_else(|e| usage(format!("pds xrpc: cannot read {path:?}: {e}")))?;
let Ok(Json::Object(props)) = serde_json::from_str(&text) else {
return usage(format!("pds xrpc: {path:?} is not a JSON object"));
};
call.props.extend(props);
call.props_given = true;
continue;
}
let Some(at) = a.find([':', '=']) else {
return usage(format!(
"pds xrpc: {a:?} is none of key==value, key=value, key:=json, Name:value, - or @path"
));
};
let (key, sep) = a.split_at(at);
if key.is_empty() {
return usage(format!(
"pds xrpc: {a:?} has nothing before its {}",
&sep[..1]
));
}
if let Some(value) = sep.strip_prefix("==") {
call.params.push((key.to_string(), value.to_string()));
} else if let Some(text) = sep.strip_prefix(":=") {
let value = serde_json::from_str(text)
.or_else(|e| usage(format!("pds xrpc: {key}:= takes JSON: {e}")))?;
call.props.insert(key.to_string(), value);
call.props_given = true;
} else if let Some(value) = sep.strip_prefix('=') {
call.props
.insert(key.to_string(), Json::String(value.to_string()));
call.props_given = true;
} else {
let value = &sep[1..];
let (Ok(n), Ok(v)) = (
HeaderName::from_bytes(key.as_bytes()),
HeaderValue::from_str(value),
) else {
return usage(format!("pds xrpc: {a:?} is no header"));
};
call.headers.push((n, v));
}
}
if !call.post && call.stdin {
return usage("pds xrpc: a query has no body, so takes no -");
}
if !call.post && call.props_given {
return usage("pds xrpc: a query has no body, so takes no key=value, key:=json or @path");
}
if call.stdin && call.props_given {
return usage("pds xrpc: the body is - or its properties, not both");
}
Ok(call)
}
/// Whether `s` is an NSID: two or more domain segments, then a name.
fn is_nsid(s: &str) -> bool {
let segments: Vec<&str> = s.split('.').collect();
let Some((name, authority)) = segments.split_last() else {
return false;
};
let fits = |seg: &str| (1..=63).contains(&seg.len());
s.len() <= 317
&& authority.len() >= 2
&& authority.iter().all(|seg| {
fits(seg)
&& seg.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-')
&& !seg.starts_with('-')
&& !seg.ends_with('-')
})
&& !authority[0].starts_with(|c: char| c.is_ascii_digit())
&& fits(name)
&& name.starts_with(|c: char| c.is_ascii_alphabetic())
&& name.bytes().all(|b| b.is_ascii_alphanumeric())
}
/// Whether `s` is a route of the server's own: `_` then letters.
fn is_route(s: &str) -> bool {
s.strip_prefix('_')
.is_some_and(|r| !r.is_empty() && r.bytes().all(|b| b.is_ascii_alphabetic()))
}
/// Make the call, and print its answer as a command does.
fn send(call: Call) -> Result<u8, Stop> {
let body = if call.stdin {
let mut body = Vec::new();
if let Err(e) = std::io::stdin().read_to_end(&mut body) {
return usage(format!("pds xrpc: cannot read standard input: {e}"));
}
body
} else {
Json::Object(call.props).to_string().into_bytes()
};
let server = Server::from_env()?;
let url = format!("{}/xrpc/{}", server.url, call.name);
let mut req = if call.post {
server.http.post(&url)
} else {
server.http.get(&url)
};
if !call.params.is_empty() {
req = req.query(&call.params);
}
let given = |name: &HeaderName| call.headers.iter().any(|(n, _)| n == name);
if !given(&AUTHORIZATION) {
req = server.authorized(req);
}
if call.post {
if !given(&CONTENT_TYPE) {
req = req.header(CONTENT_TYPE, JSON);
}
req = req.body(body);
}
for (n, v) in call.headers {
req = req.header(n, v);
}
let res = server.sent(req)?;
let status = res.status().as_u16();
let json = res
.headers()
.get(CONTENT_TYPE)
.map(|v| is_json(v.as_bytes()));
let bytes = res
.bytes()
.map_err(|e| Stop::Unreachable(format!("cannot read the answer of {}: {e}", server.url)))?;
if !(200..300).contains(&status) {
let body = serde_json::from_slice(&bytes)
.unwrap_or_else(|_| Json::String(String::from_utf8_lossy(&bytes).into_owned()));
return Ok(print_error(status, &body));
}
let mut out = std::io::stdout().lock();
let text = std::str::from_utf8(&bytes)
.ok()
.filter(|t| serde_json::from_str::<&RawValue>(t).is_ok());
match (json, text) {
// Nothing, as a method that answers nothing: `{}`.
(None | Some(true), _) if bytes.is_empty() => {
let _ = writeln!(out, "{{}}");
}
(Some(true), Some(text)) => {
let _ = writeln!(out, "{}", one_line(text));
}
_ => {
let _ = out.write_all(&bytes);
}
}
let _ = out.flush();
Ok(0)
}
/// Whether a `Content-Type` is JSON's, whatever its parameters.
fn is_json(content_type: &[u8]) -> bool {
let media = content_type.split(|&b| b == b';').next().unwrap_or(b"");
media.trim_ascii().eq_ignore_ascii_case(JSON.as_bytes())
}
/// JSON text on one line: as it was written, its properties in their
/// order, but for the whitespace between its tokens.
fn one_line(text: &str) -> String {
let mut out = String::with_capacity(text.len());
let (mut in_string, mut escaped) = (false, false);
for c in text.chars() {
if in_string {
out.push(c);
if escaped {
escaped = false;
} else if c == '\\' {
escaped = true;
} else if c == '"' {
in_string = false;
}
} else if c == '"' {
in_string = true;
out.push(c);
} else if !c.is_ascii_whitespace() {
out.push(c);
}
}
out
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn parsed(argv: &[&str]) -> Result<Call, String> {
let argv: Vec<String> = argv.iter().map(|a| a.to_string()).collect();
parse(&argv).map_err(|e| match e {
Stop::Usage(why) | Stop::Unreachable(why) => why,
})
}
/// A file of `text` for an `@path`, under a name of this test's own.
fn file(name: &str, text: &str) -> String {
let path = std::env::temp_dir().join(format!("pds-xrpc-{}-{name}", std::process::id()));
std::fs::write(&path, text).unwrap();
path.to_string_lossy().into_owned()
}
#[test]
fn kinds_and_names() {
for (kind, post) in [
("query", false),
("GET", false),
("Query", false),
("procedure", true),
("post", true),
("PROCEDURE", true),
] {
assert_eq!(
parsed(&[kind, "com.atproto.server.describeServer"]).map(|c| c.post),
Ok(post),
"{kind}"
);
}
for name in [
"com.atproto.repo.createRecord",
"app.bsky.actor.getProfile",
"a.b.c",
"_logs",
"_oauthSessions",
] {
assert_eq!(parsed(&["query", name]).map(|c| c.name), Ok(name.into()));
}
}
/// Each form of argument, split at its first `:` or `=`.
#[test]
fn argument_forms() {
let at = file(
"forms",
r#"{"collection":"a.b.c","record":{"n":1},"rkey":"x"}"#,
);
let call = parsed(&[
"procedure",
"com.atproto.repo.putRecord",
"repo=alice.test",
&format!("@{at}"),
"rkey:=\"y\"",
"validate:=false",
"text=a:b=c",
"x-thing==1",
"Atproto-Proxy:did:web:api.bsky.app#bsky_appview",
])
.unwrap();
assert_eq!(
Json::Object(call.props),
json!({ "repo": "alice.test", "collection": "a.b.c", "record": { "n": 1 },
"rkey": "y", "validate": false, "text": "a:b=c" })
);
assert_eq!(call.params, [("x-thing".to_string(), "1".to_string())]);
assert_eq!(
call.headers,
[(
HeaderName::from_static("atproto-proxy"),
HeaderValue::from_static("did:web:api.bsky.app#bsky_appview")
)]
);
assert!(!call.stdin);
// A parameter given again is one more value of it; `==` with nothing after is empty.
let call = parsed(&["get", "a.b.c", "uris==x", "uris==y", "cursor=="]).unwrap();
assert_eq!(
call.params,
[("uris", "x"), ("uris", "y"), ("cursor", "")]
.map(|(k, v)| (k.to_string(), v.to_string()))
);
// A later property replaces an `@path`'s.
let call = parsed(&["post", "a.b.c", &format!("@{at}"), "collection=d.e.f"]).unwrap();
assert_eq!(call.props["collection"], "d.e.f");
let call = parsed(&["post", "a.b.c", "Content-Type:image/png", "-"]).unwrap();
assert!(call.stdin && call.props.is_empty());
assert_eq!(call.headers[0].0, CONTENT_TYPE);
let _ = std::fs::remove_file(at);
}
/// Each usage error of "Any call".
#[test]
fn usage_errors() {
let not_object = file("array", "[1]");
let not_json = file("bad", "{");
let missing = std::env::temp_dir()
.join(format!("pds-xrpc-{}-missing", std::process::id()))
.to_string_lossy()
.into_owned();
for argv in [
&[][..],
&["query"],
&["put", "a.b.c"],
&["query", "createRecord"],
&["query", "a.b"],
&["query", "a.b.1c"],
&["query", "a.-b.c"],
&["query", "_"],
&["query", "_o1"],
&["query", "logs"],
&["post", "a.b.c", "plain"],
&["post", "a.b.c", "=v"],
&["post", "a.b.c", "==v"],
&["post", "a.b.c", ":=1"],
&["post", "a.b.c", ":v"],
&["post", "a.b.c", "k:={"],
&["post", "a.b.c", "k:="],
&["post", "a.b.c", "Bad Name:v"],
&["query", "a.b.c", "k=v"],
&["query", "a.b.c", "k:=1"],
&["query", "a.b.c", "-"],
&["post", "a.b.c", "-", "k=v"],
&["post", "a.b.c", "k:=1", "-"],
&["post", "a.b.c", "-", "-"],
&["post", "a.b.c", "@"],
] {
assert!(parsed(argv).is_err(), "{argv:?}");
}
for path in [¬_object, ¬_json, &missing] {
let at = format!("@{path}");
assert!(parsed(&["post", "a.b.c", &at]).is_err(), "{path}");
assert!(parsed(&["query", "a.b.c", &at]).is_err(), "{path}");
}
let empty = file("empty", "{}");
assert!(parsed(&["query", "a.b.c", &format!("@{empty}")]).is_err());
assert!(parsed(&["post", "a.b.c", &format!("@{empty}"), "-"]).is_err());
for path in [not_object, not_json, empty] {
let _ = std::fs::remove_file(path);
}
}
/// `pds xrpc --help` says how; `pds --help` lists it.
#[test]
fn help() {
assert_eq!(run(&["--help".into()]).ok(), Some(0));
assert!(HELP.contains("key:=json"));
assert!(super::super::top_help().contains("pds xrpc <kind> <name> [args]"));
}
#[test]
fn answers() {
assert!(is_json(b"application/json"));
assert!(is_json(b"Application/JSON; charset=utf-8"));
assert!(!is_json(b"application/vnd.ipld.car"));
assert_eq!(
one_line("{\n \"a\" : [1, 2],\n \"b\": \"x y\\\" \\n z\"\n}"),
r#"{"a":[1,2],"b":"x y\" \n z"}"#
);
}
}