~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
656 lines · 24.3 KB Raw History
//! A record's fields, read through its collection's lexicon: the required
//! fields, then the rest, in lexicon order, then those the lexicon does not
//! name; each with its name, a small tag of its type, and its value as what
//! it is drawn as. And `Json`, a value as it is, for the clients' JSON tree.
//!
//! A `Fields` node is `p: { uri?, fields: [field], extra: [field] }`, or
//! `{ uri?, json }` with no lexicon (the record's value, drawn open two
//! levels); `uri` draws it as a card under its uri, as a layout's Fields
//! does, and is left out where a list's card is its frame. A field is
//! `{ name, tag, value }`, a value `{ kind, … }`:
//!
//! - `text` `{ text, mono }`, `datetime` `{ iso }`, `scalar` `{ text }`;
//! - `record` `{ uri, open }`, `link` `{ url }`, `actor` `{ actor, label,
//!   open }`, `label` its verified handle (`@handle`) or its DID;
//! - `image` `{ src, mimeType, size }`, `audio` `{ url, mimeType, size }`,
//!   `file` `{ mimeType, size }`, `size` null where unknown;
//! - `array` `{ items: [value], inline }`, `inline` when every item is a
//!   short word or number (drawn as chips);
//! - `group` `{ type, fields: [field] }`, an object one level deep;
//! - `json` `{ value }`: anything the lexicon leaves open, does not match,
//!   or nested deeper.

use super::*;

const STRONG_REF: &str = "com.atproto.repo.strongRef#main";

/// String formats that are identifiers, drawn in the monospace face.
const IDENTIFIERS: &[&str] = &["cid", "nsid", "tid", "record-key", "language"];

/// A definition with the NSID of the document it was read from, which the
/// local refs (`#name`) inside it are relative to.
#[derive(Clone, Copy)]
struct Scoped<'a> {
    def: &'a Value,
    nsid: &'a str,
}

pub(super) fn fields_node(p: &Value, scope: &Value, ctx: &Ctx) -> R<Option<Value>> {
    let record = required("record", &p["record"], scope, |v| {
        v["uri"].is_string() && v["value"].is_object()
    })?;
    let mut o = card(&record["value"], ctx);
    o.insert("uri".into(), record["uri"].clone());
    Ok(Some(make("Fields", o, vec![])))
}

pub(super) fn json_node(p: &Value, scope: &Value) -> R<Option<Value>> {
    let value = required("value", &p["value"], scope, |_| true)?;
    Ok(Some(
        json!({ "c": "Json", "p": { "value": value, "open": 1 } }),
    ))
}

/// A record's value as a `Fields` node with no uri of its own: its card is
/// the frame around it.
pub fn record_fields(value: &Value, ctx: &Ctx) -> Value {
    make("Fields", card(value, ctx), vec![])
}

fn card(value: &Value, ctx: &Ctx) -> Map<String, Value> {
    let mut o = Map::new();
    match ctx.lexicon.and_then(|lex| Some((lex, record_def(lex)?))) {
        Some((lex, root)) => {
            let (known, extra) = fields(lex, root, value, 0, ctx);
            o.insert("fields".into(), Value::Array(known));
            o.insert("extra".into(), Value::Array(extra));
        }
        None => {
            o.insert("json".into(), value.clone());
        }
    }
    o
}

/// The object definition of the collection's records: `defs.main.record`.
fn record_def(lex: &Value) -> Option<Scoped<'_>> {
    let main = &lex["doc"]["defs"]["main"];
    (main["type"] == "record" && main["record"]["type"] == "object").then_some(Scoped {
        def: &main["record"],
        nsid: lex["nsid"].as_str()?,
    })
}

/// An object's fields: those the lexicon names that the value holds,
/// required first, each in lexicon order; then the keys it does not name,
/// `$type` left out.
fn fields(
    lex: &Value,
    scoped: Scoped,
    value: &Value,
    depth: u8,
    ctx: &Ctx,
) -> (Vec<Value>, Vec<Value>) {
    let empty = Map::new();
    let properties = scoped.def["properties"].as_object().unwrap_or(&empty);
    let needed: Vec<&str> = scoped.def["required"]
        .as_array()
        .into_iter()
        .flatten()
        .filter_map(Value::as_str)
        .collect();
    let held: Vec<(&String, &Value)> = properties
        .iter()
        .filter(|(name, _)| value.get(name.as_str()).is_some())
        .collect();
    let (first, rest): (Vec<_>, Vec<_>) = held
        .into_iter()
        .partition(|(n, _)| needed.contains(&n.as_str()));
    let known = first
        .into_iter()
        .chain(rest)
        .map(|(name, def)| {
            let field = Scoped {
                def,
                nsid: scoped.nsid,
            };
            row(
                name,
                type_tag(Some(def)),
                show(lex, Some(field), &value[name.as_str()], depth, ctx),
            )
        })
        .collect();
    let extra = value
        .as_object()
        .into_iter()
        .flatten()
        .filter(|(name, _)| *name != "$type" && !properties.contains_key(*name))
        .map(|(name, v)| row(name, "unknown".into(), show(lex, None, v, depth, ctx)))
        .collect();
    (known, extra)
}

fn row(name: &str, tag: String, value: Value) -> Value {
    json!({ "name": name, "tag": tag, "value": value })
}

/// A ref as the key of the lexicon's `refs`: `nsid#def`, a bare NSID its
/// main definition, `#def` one in the document at `nsid`.
fn ref_key(r: &str, nsid: &str) -> String {
    if r.starts_with('#') {
        format!("{nsid}{r}")
    } else if r.contains('#') {
        r.to_string()
    } else {
        format!("{r}#main")
    }
}

/// The definition a ref key names, from the collection's own document or
/// from the refs the server resolved.
fn resolve_ref<'a>(lex: &'a Value, key: &str) -> Option<Scoped<'a>> {
    let (id, name) = key.split_once('#')?;
    let own = lex["nsid"].as_str()?;
    if id == own {
        let def = &lex["doc"]["defs"][name];
        return (!def.is_null()).then_some(Scoped { def, nsid: own });
    }
    let (k, def) = lex["refs"].as_object()?.get_key_value(key)?;
    Some(Scoped {
        def,
        nsid: &k[..k.find('#')?],
    })
}

/// The small tag beside a field's name: its format, or its type.
fn type_tag(def: Option<&Value>) -> String {
    let Some(def) = def else {
        return "unknown".into();
    };
    let kind = def["type"].as_str().unwrap_or("");
    match (kind, def["format"].as_str()) {
        ("string", Some(f)) => f.into(),
        ("array", _) => format!("{}[]", type_tag(def.get("items"))),
        ("ref", _)
            if def["ref"]
                .as_str()
                .is_some_and(|r| ref_key(r, "") == STRONG_REF) =>
        {
            "strongRef".into()
        }
        _ => kind.into(),
    }
}

/// What a value is drawn as, by its definition; JSON where it does not
/// match, the lexicon leaves it open, or it is an object deeper than one
/// level (`depth` the groups around it).
fn show(lex: &Value, scoped: Option<Scoped>, v: &Value, depth: u8, ctx: &Ctx) -> Value {
    let shown = scoped.and_then(|Scoped { def, nsid }| match def["type"].as_str()? {
        "string" => v.as_str().map(|s| string(def["format"].as_str(), s, ctx)),
        "integer" => v
            .is_number()
            .then(|| json!({ "kind": "scalar", "text": write(v) })),
        "boolean" => v
            .is_boolean()
            .then(|| json!({ "kind": "scalar", "text": write(v) })),
        "blob" => blob(v, ctx),
        "cid-link" => v["$link"].as_str().map(|l| text(l, true)),
        "ref" => target(lex, &ref_key(def["ref"].as_str()?, nsid), v, depth, ctx),
        "union" => {
            let key = ref_key(v.as_object()?.get("$type")?.as_str()?, nsid);
            let allowed = def["refs"]
                .as_array()?
                .iter()
                .filter_map(Value::as_str)
                .any(|r| ref_key(r, nsid) == key);
            if allowed {
                target(lex, &key, v, depth, ctx)
            } else {
                None
            }
        }
        "object" => (v.is_object() && depth < 1).then(|| {
            let (known, extra) = fields(lex, Scoped { def, nsid }, v, depth + 1, ctx);
            let fields: Vec<Value> = known.into_iter().chain(extra).collect();
            json!({ "kind": "group", "type": v["$type"].as_str(), "fields": fields })
        }),
        "array" => v.as_array().map(|values| {
            let item = def.get("items").map(|d| Scoped { def: d, nsid });
            let inline = values.iter().all(|x| match x {
                Value::Number(_) | Value::Bool(_) => true,
                Value::String(s) => s.encode_utf16().count() <= 40 && !s.contains('\n'),
                _ => false,
            });
            let items: Vec<Value> = values
                .iter()
                .map(|x| show(lex, item, x, depth, ctx))
                .collect();
            json!({ "kind": "array", "items": items, "inline": inline })
        }),
        _ => None,
    });
    shown.unwrap_or_else(|| json!({ "kind": "json", "value": v }))
}

/// A ref's value: a strong ref as the record it names, anything else by
/// the definition the ref leads to.
fn target(lex: &Value, key: &str, v: &Value, depth: u8, ctx: &Ctx) -> Option<Value> {
    if key == STRONG_REF {
        let uri = v.as_object()?.get("uri")?.as_str()?;
        return Some(record(uri, ctx));
    }
    let scoped = resolve_ref(lex, key)?;
    Some(show(lex, Some(scoped), v, depth, ctx))
}

fn text(s: &str, mono: bool) -> Value {
    json!({ "kind": "text", "text": s, "mono": mono })
}

fn record(uri: &str, ctx: &Ctx) -> Value {
    json!({ "kind": "record", "uri": uri, "open": ctx.record_call(uri) })
}

fn string(format: Option<&str>, s: &str, ctx: &Ctx) -> Value {
    match format {
        Some("datetime") if datetime(s) => json!({ "kind": "datetime", "iso": s }),
        Some("datetime") => text(s, false),
        Some("at-uri") if s.starts_with("at://") => record(s, ctx),
        Some("at-uri") => text(s, true),
        Some("uri") if http_url(s) => json!({ "kind": "link", "url": s }),
        Some("uri") => text(s, false),
        Some("did" | "handle" | "at-identifier") => {
            let label = match ctx.handles.and_then(|h| h[s].as_str()) {
                Some(handle) => format!("@{handle}"),
                None if s.starts_with("did:") => s.to_string(),
                None => format!("@{s}"),
            };
            json!({ "kind": "actor", "actor": s, "label": label,
                    "open": call("describe_repo", json!({ "actor": s })) })
        }
        f => text(s, f.is_some_and(|f| IDENTIFIERS.contains(&f))),
    }
}

/// Whether a datetime string is one a client reads as a date: an ISO date,
/// optionally with its time.
fn datetime(s: &str) -> bool {
    let b = s.as_bytes();
    let digits =
        |r: std::ops::Range<usize>| b.get(r).is_some_and(|d| d.iter().all(u8::is_ascii_digit));
    let number = |r: std::ops::Range<usize>| s.get(r).and_then(|n| n.parse::<u32>().ok());
    let date = digits(0..4)
        && b.get(4) == Some(&b'-')
        && digits(5..7)
        && b.get(7) == Some(&b'-')
        && digits(8..10)
        && number(5..7).is_some_and(|m| (1..=12).contains(&m))
        && number(8..10).is_some_and(|d| (1..=31).contains(&d));
    let time = b.len() == 10
        || (b.get(10) == Some(&b'T')
            && digits(11..13)
            && b.get(13) == Some(&b':')
            && digits(14..16)
            && number(11..13).is_some_and(|h| h < 24)
            && number(14..16).is_some_and(|m| m < 60));
    date && time
}

/// A blob, new form or legacy: an image (its picture drawn small) or audio
/// when it has an http(s) URL, else its MIME type and size.
fn blob(v: &Value, ctx: &Ctx) -> Option<Value> {
    let mime = v.as_object()?.get("mimeType")?.as_str()?;
    if v["$type"] != "blob" && !v["cid"].is_string() {
        return None;
    }
    let size = if v["size"].is_number() {
        v["size"].clone()
    } else {
        Value::Null
    };
    if let Some(url) = v["url"].as_str().filter(|u| http_url(u)) {
        if mime.starts_with("image/") {
            let src = source_of(Some(v), ctx, true);
            return Some(json!({ "kind": "image", "src": src, "mimeType": mime, "size": size }));
        }
        if mime.starts_with("audio/") {
            return Some(json!({ "kind": "audio", "url": url, "mimeType": mime, "size": size }));
        }
    }
    Some(json!({ "kind": "file", "mimeType": mime, "size": size }))
}

#[cfg(test)]
mod tests {
    use super::*;

    fn lexicon() -> Value {
        json!({
            "nsid": "app.test.thing",
            "doc": { "lexicon": 1, "id": "app.test.thing", "defs": {
                "main": { "type": "record", "record": { "type": "object", "required": ["b"], "properties": {
                    "a": { "type": "string", "format": "datetime" },
                    "b": { "type": "string", "format": "at-uri" },
                    "subject": { "type": "ref", "ref": "com.atproto.repo.strongRef" },
                    "who": { "type": "string", "format": "did" },
                    "embed": { "type": "union", "refs": ["#inner"] },
                    "tags": { "type": "array", "items": { "type": "string" } },
                    "outer": { "type": "ref", "ref": "app.test.other#box" }
                } } },
                "inner": { "type": "object", "properties": { "deep": { "type": "object" } } }
            } },
            "refs": { "app.test.other#box": { "type": "object", "properties": { "n": { "type": "integer" } } } }
        })
    }

    fn drawn(value: Value, handles: Value) -> Value {
        let lex = lexicon();
        let root = Value::Null;
        let ctx = Ctx {
            origins: &[],
            thumbnails: vec![],
            trusted: false,
            root: &root,
            report: None,
            inline: None,
            lexicon: Some(&lex),
            handles: Some(&handles),
            paged: Vec::new(),
            more: More::default(),
            me: None,
            people: None,
        };
        let node = record_fields(&value, &ctx);
        check::checked(&node);
        node["p"].clone()
    }

    #[test]
    fn required_first_then_lexicon_order_then_extra() {
        let p = drawn(
            json!({ "$type": "app.test.thing", "z": 1, "a": "2024-01-02T03:04:05Z", "b": "at://did:plc:x/app.test.thing/1" }),
            json!({}),
        );
        let names: Vec<&str> = p["fields"]
            .as_array()
            .unwrap()
            .iter()
            .map(|f| f["name"].as_str().unwrap())
            .collect();
        assert_eq!(names, ["b", "a"]);
        assert_eq!(
            p["extra"],
            json!([{ "name": "z", "tag": "unknown", "value": { "kind": "json", "value": 1 } }])
        );
        assert_eq!(
            p["fields"][0]["value"]["open"]["call"]["name"],
            "get_record"
        );
        assert_eq!(p["fields"][1]["value"]["kind"], "datetime");
    }

    #[test]
    fn refs_unions_and_depth() {
        let p = drawn(
            json!({
                "b": "x", "a": "yesterday",
                "subject": { "uri": "at://did:plc:x/app.test.thing/2", "cid": "c" },
                "embed": { "$type": "app.test.thing#inner", "deep": { "k": 1 } },
                "outer": { "n": 3 },
                "who": "did:plc:alice",
                "tags": ["a", "b"]
            }),
            json!({ "did:plc:alice": "alice.test" }),
        );
        let by = |n: &str| {
            p["fields"]
                .as_array()
                .unwrap()
                .iter()
                .find(|f| f["name"] == n)
                .unwrap()
                .clone()
        };
        assert_eq!(
            by("b")["value"],
            json!({ "kind": "text", "text": "x", "mono": true })
        );
        assert_eq!(by("a")["value"]["kind"], "text");
        assert_eq!(by("subject")["tag"], "strongRef");
        assert_eq!(by("subject")["value"]["kind"], "record");
        let embed = &by("embed")["value"];
        assert_eq!(embed["kind"], "group");
        assert_eq!(embed["type"], "app.test.thing#inner");
        assert_eq!(embed["fields"][0]["value"]["kind"], "json");
        assert_eq!(
            by("outer")["value"]["fields"][0]["value"],
            json!({ "kind": "scalar", "text": "3" })
        );
        assert_eq!(by("who")["value"]["label"], "@alice.test");
        assert_eq!(by("tags")["tag"], "string[]");
        assert_eq!(by("tags")["value"]["inline"], true);
    }

    #[test]
    fn a_union_variant_not_listed_is_json() {
        let p = drawn(
            json!({ "b": "x", "embed": { "$type": "app.test.other#box", "n": 1 } }),
            json!({}),
        );
        assert_eq!(p["fields"][1]["value"]["kind"], "json");
    }

    #[test]
    fn blobs_and_dates() {
        let root = Value::Null;
        let ctx = Ctx {
            origins: &[],
            thumbnails: vec![],
            trusted: false,
            root: &root,
            report: None,
            inline: None,
            lexicon: None,
            handles: None,
            paged: Vec::new(),
            more: More::default(),
            me: None,
            people: None,
        };
        let image = json!({ "$type": "blob", "mimeType": "image/png", "size": 9, "url": "https://h.example/b", "thumb": "https://h.example/t" });
        assert_eq!(
            blob(&image, &ctx).unwrap()["src"]["src"],
            "https://h.example/t"
        );
        let page = json!({ "$type": "blob", "mimeType": "image/png", "url": "javascript:x" });
        assert_eq!(
            blob(&page, &ctx).unwrap(),
            json!({ "kind": "file", "mimeType": "image/png", "size": null })
        );
        assert!(blob(&json!({ "mimeType": "image/png" }), &ctx).is_none());
        assert!(datetime("2024-12-31") && datetime("2024-01-02T03:04:05.000Z"));
        assert!(!datetime("2024-13-01") && !datetime("soon") && !datetime("2024-01-02 03:04"));
        let bare = record_fields(&json!({ "a": 1 }), &ctx);
        check::checked(&bare);
        assert_eq!(bare["p"], json!({ "json": { "a": 1 } }));
    }

    /// A layout's `Fields` draws a record under its uri, through the
    /// lexicon; one that is no record is an error, none nothing. `Json`
    /// draws any value, open a level.
    #[test]
    fn a_layouts_fields_draw_a_record_and_json_any_value() {
        let lex = lexicon();
        let root = Value::Null;
        let ctx = Ctx {
            origins: &[],
            thumbnails: vec![],
            trusted: true,
            root: &root,
            report: None,
            inline: None,
            lexicon: Some(&lex),
            handles: None,
            paged: Vec::new(),
            more: More::default(),
            me: None,
            people: None,
        };
        let layout = json!({ "component": "Stack", "children": [
            { "component": "Fields", "props": { "record": { "$": "record" } } },
            { "component": "Json", "props": { "value": { "$": "record.value" } } },
        ] });
        let uri = "at://did:plc:x/app.test.thing/1";
        let scope = json!({ "record": { "uri": uri, "value": { "b": uri } } });
        let tree = resolve(&layout, &scope, &ctx).unwrap();
        check::checked(&tree);
        let fields = &tree["k"][0];
        assert_eq!(fields["c"], "Fields");
        assert_eq!(fields["p"]["uri"], uri);
        assert_eq!(fields["p"]["fields"][0]["name"], "b");
        assert_eq!(fields["p"]["extra"], json!([]));
        assert_eq!(
            tree["k"][1],
            json!({ "c": "Json", "p": { "value": { "b": uri }, "open": 1 } })
        );
        let unusable = json!({ "record": { "uri": uri } });
        let tree = resolve(&layout, &unusable, &ctx).unwrap();
        check::checked(&tree);
        assert_eq!(
            tree["k"],
            json!([{ "c": "Error", "p": { "component": "Fields", "message": "record: not usable" } }])
        );
        assert!(resolve(&layout, &json!({}), &ctx).is_none());
    }

    /// Booleans and numbers are scalars, an array of them chips, an array
    /// the lexicon gives no items of unknown; a type the reader has no
    /// drawing for is JSON; a uri a link only when it is http(s); an
    /// account its handle where one is known, else as written.
    #[test]
    fn scalars_links_and_accounts() {
        let lex = json!({
            "nsid": "app.test.flags",
            "doc": { "lexicon": 1, "id": "app.test.flags", "defs": {
                "main": { "type": "record", "record": { "type": "object", "properties": {
                    "on": { "type": "boolean" },
                    "mix": { "type": "array", "items": { "type": "unknown" } },
                    "loose": { "type": "array" },
                    "raw": { "type": "bytes" },
                    "site": { "type": "string", "format": "uri" },
                    "page": { "type": "string", "format": "uri" },
                    "bare": { "type": "string", "format": "did" },
                    "named": { "type": "string", "format": "handle" },
                    "pic": { "type": "blob" },
                    "link": { "type": "cid-link" },
                    "any": { "type": "union" },
                    "cid": { "type": "string", "format": "cid" }
                } } }
            } }
        });
        let root = Value::Null;
        let handles = json!({});
        let ctx = Ctx {
            origins: &[],
            thumbnails: vec![],
            trusted: false,
            root: &root,
            report: None,
            inline: None,
            lexicon: Some(&lex),
            handles: Some(&handles),
            paged: Vec::new(),
            more: More::default(),
            me: None,
            people: None,
        };
        let node = record_fields(
            &json!({ "on": true, "mix": [1, false, "x"], "loose": [{ "a": 1 }], "raw": { "$bytes": "AA" },
                "site": "https://a.example/", "page": "ftp://a.example/", "bare": "did:plc:a", "named": "bob.test",
                "pic": { "$type": "blob", "mimeType": "image/png", "size": 1 }, "link": { "$link": "bafyl" },
                "any": { "$type": "app.test.flags#other" }, "cid": "bafyc" }),
            &ctx,
        );
        check::checked(&node);
        let by = |n: &str| {
            node["p"]["fields"]
                .as_array()
                .unwrap()
                .iter()
                .find(|f| f["name"] == n)
                .unwrap()
                .clone()
        };
        assert_eq!(
            by("on")["value"],
            json!({ "kind": "scalar", "text": "true" })
        );
        assert_eq!(by("mix")["value"]["inline"], true);
        assert_eq!(by("mix")["value"]["items"][0]["kind"], "json");
        assert_eq!(by("loose")["tag"], "unknown[]");
        assert_eq!(by("loose")["value"]["inline"], false);
        assert_eq!(
            by("raw")["value"],
            json!({ "kind": "json", "value": { "$bytes": "AA" } })
        );
        assert_eq!(
            by("site")["value"],
            json!({ "kind": "link", "url": "https://a.example/" })
        );
        assert_eq!(
            by("page")["value"],
            json!({ "kind": "text", "text": "ftp://a.example/", "mono": false })
        );
        assert_eq!(by("bare")["value"]["label"], "did:plc:a");
        assert_eq!(by("named")["value"]["label"], "@bob.test");
        assert_eq!(
            by("pic")["value"],
            json!({ "kind": "file", "mimeType": "image/png", "size": 1 })
        );
        assert_eq!(
            by("link")["value"],
            json!({ "kind": "text", "text": "bafyl", "mono": true })
        );
        assert_eq!(
            by("any")["value"],
            json!({ "kind": "json", "value": { "$type": "app.test.flags#other" } }),
            "a union naming no refs takes none"
        );
        assert_eq!(
            by("cid")["value"],
            json!({ "kind": "text", "text": "bafyc", "mono": true })
        );
    }

    #[test]
    fn audio_with_a_url_plays_and_other_blobs_are_files() {
        let root = Value::Null;
        let ctx = Ctx {
            origins: &[],
            thumbnails: vec![],
            trusted: false,
            root: &root,
            report: None,
            inline: None,
            lexicon: None,
            handles: None,
            paged: Vec::new(),
            more: More::default(),
            me: None,
            people: None,
        };
        let audio = json!({ "cid": "bafy", "mimeType": "audio/mpeg", "size": 3, "url": "https://h.example/a" });
        assert_eq!(
            blob(&audio, &ctx).unwrap(),
            json!({ "kind": "audio", "url": "https://h.example/a", "mimeType": "audio/mpeg", "size": 3 })
        );
        let pdf =
            json!({ "$type": "blob", "mimeType": "application/pdf", "url": "https://h.example/p" });
        assert_eq!(
            blob(&pdf, &ctx).unwrap(),
            json!({ "kind": "file", "mimeType": "application/pdf", "size": null })
        );
    }
}