~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
457 lines · 16.3 KB Raw History
//! `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 [&not_object, &not_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"}"#
        );
    }
}