chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.4.0 Latest 5 packages
0
0
//! 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 })
);
}
}