//! 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> { 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> { 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 { 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> { 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, Vec) { 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> { 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, 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 = 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 = 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 { 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| b.get(r).is_some_and(|d| d.iter().all(u8::is_ascii_digit)); let number = |r: std::ops::Range| s.get(r).and_then(|n| n.parse::().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 { 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 }) ); } }