//! `pds xrpc [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 [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. query (or get), a GET; procedure (or post), a POST; in any case 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, /// 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 { 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 { 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 { 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 { let argv: Vec = 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 [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"}"# ); } }