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 composer's writes: the template a view's `Compose` gives (`writes`),
//! filled with what the person wrote (`values`: its fields' and its given
//! values) into the records `apply_writes` writes at once, as Bluesky's and
//! Grain's apps do with `applyWrites`.
//!
//! A template is an array of writes, each `{ collection, record, as?,
//! each?, when?, whenItem?, rkey?, update? }`: `each` names a value that is
//! an array (photos), one record made per element; `when` names values that
//! must be there for it to be made; `whenItem` a path within the element
//! that must be; `as` names it, for others to read its at-uri or record
//! key; `rkey`, `{"$rkey": as}`, takes another write's key (a threadgate
//! keeps its post's). `update`, a record key (`self`) or `{"$value": name}`
//! holding one (a gallery's, given), replaces the one record there (a
//! profile, a gallery): `apply_writes` reads it first,
//! `{"$stored": path}` reads that, and what is written is the record as it
//! was stored with the fields the template names set to what they make
//! (taken out where they make nothing), the rest kept as they are; where
//! there is none yet, it is created. A record's values are literals or:
//!
//! - `{"$value": "name.path"}`: a value, or a path within it (an array's
//! element by its index, `photos.0.blob`);
//! - `{"$item": "path"}` (`"."` the element itself), `{"$index": true}`:
//! within an `each` write, or a `$each`;
//! - `{"$each": name, "value": template}`: an array, one per element;
//! - `{"$when": [names], "value": template}`: the template, where every
//! value named is there;
//! - `{"$first": [templates]}`: the first of 2 to 4 that is there;
//! - `{"$merge": [templates]}`: objects merged, the later winning;
//! - `{"$uri": as}`, `{"$rkey": as}`: another write's at-uri or record key
//! (the same element's, where both are made per element);
//! - `{"$stored": "path"}` (`"."` the record itself): within an update, the
//! record it replaces, as stored (a profile's avatar, its blob ref);
//! - `{"$now": true}`: the time it is sent;
//! - `{"$facets": key}`: left as it is, for `create`'s facets
//! (`writes::facets_made`), the text in the record's field `key`.
//!
//! What is not there (a value not given, null) is left out: an object's
//! field, an array's element; a record made of nothing is refused.
use serde_json::{Map, Value, json};
/// The most writes a template names.
pub const MAX_TEMPLATE: usize = 8;
/// The most records one send creates (Grain's 10 photos, each its item and
/// its camera's details, and the gallery).
pub const MAX_WRITES: usize = 32;
/// How deep a template nests.
const MAX_DEPTH: usize = 12;
/// A record to write: its collection, its record key and the record, and
/// for an update, what it replaces.
#[derive(Debug, PartialEq)]
pub struct Made {
pub collection: String,
pub rkey: String,
pub record: Value,
pub update: Option<Update>,
}
/// An update's: the record it replaces as stored (none where there is none
/// yet, and it is created) and the fields its template names.
#[derive(Clone, Debug, PartialEq)]
pub struct Update {
pub stored: Option<Value>,
pub names: Vec<String>,
}
impl Update {
/// The record written: the stored one, each field the template names
/// set to what it `made` (taken out where it made nothing), the rest
/// kept as they are; with none stored, what it made.
pub fn over(self, made: Value) -> Value {
match (self.stored, made) {
(Some(Value::Object(mut out)), Value::Object(made)) => {
out.retain(|k, _| !self.names.contains(k));
out.extend(made);
Value::Object(out)
}
(_, made) => made,
}
}
}
const KEYS: &[&str] = &[
"collection",
"record",
"as",
"each",
"when",
"whenItem",
"rkey",
"update",
];
fn is_name(s: &str) -> bool {
!s.is_empty()
&& s.len() <= 32
&& s.chars().next().is_some_and(|c| c.is_ascii_lowercase())
&& s.chars().all(|c| c.is_ascii_alphanumeric())
}
fn is_path(s: &str) -> bool {
s == "."
|| (!s.is_empty()
&& s.len() <= 128
&& s.split('.')
.all(|k| !k.is_empty() && k.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')))
}
/// What a writes template's problems are, each where it is: `names` the
/// values it may read (its fields' and given values' names), or any.
pub fn problems(writes: &Value, names: Option<&[String]>) -> Vec<String> {
let mut out = Vec::new();
let Some(list) = writes
.as_array()
.filter(|a| (1..=MAX_TEMPLATE).contains(&a.len()))
else {
out.push(format!(
"writes: must be an array of 1 to {MAX_TEMPLATE} writes"
));
return out;
};
let known = |n: &str| names.is_none_or(|ns| ns.iter().any(|k| k == n));
let named: Vec<&str> = list.iter().filter_map(|w| w["as"].as_str()).collect();
for (i, w) in list.iter().enumerate() {
let at = format!("writes[{i}]");
let Some(o) = w.as_object() else {
out.push(format!("{at}: must be an object"));
continue;
};
for k in o.keys().filter(|k| !KEYS.contains(&k.as_str())) {
out.push(format!("{at}.{k}: a write has no {k}"));
}
if !o
.get("collection")
.and_then(Value::as_str)
.is_some_and(atproto::syntax::is_nsid)
{
out.push(format!("{at}.collection: required: an NSID"));
}
if let Some(a) = o.get("as") {
match a.as_str() {
Some(a) if is_name(a) && named.iter().filter(|n| **n == a).count() == 1 => {}
_ => out.push(format!("{at}.as: a name, once among the writes")),
}
}
let each = o.get("each");
if let Some(e) = each
&& !e.as_str().is_some_and(|e| is_name(e) && known(e))
{
out.push(format!("{at}.each: names a value given or written"));
}
if let Some(w) = o.get("when") {
let ok = w.as_array().is_some_and(|a| {
(1..=4).contains(&a.len())
&& a.iter()
.all(|n| n.as_str().is_some_and(|n| is_name(n) && known(n)))
});
if !ok {
out.push(format!("{at}.when: 1 to 4 names of values"));
}
}
if let Some(p) = o.get("whenItem")
&& (each.is_none() || !p.as_str().is_some_and(is_path))
{
out.push(format!(
"{at}.whenItem: a path within each element, with each"
));
}
if let Some(r) = o.get("rkey")
&& !r
.as_object()
.filter(|r| r.len() == 1)
.and_then(|r| r.get("$rkey"))
.and_then(Value::as_str)
.is_some_and(|a| named.contains(&a))
{
out.push(format!("{at}.rkey: {{\"$rkey\": as}}, another write's"));
}
let update = o.contains_key("update");
let key_of_its_own = o
.get("update")
.and_then(Value::as_str)
.is_some_and(atproto::syntax::is_record_key);
let key_given = o.get("update").and_then(Value::as_object).is_some_and(|u| {
u.len() == 1
&& u.get("$value").and_then(Value::as_str).is_some_and(|p| {
is_path(p) && p != "." && known(p.split('.').next().unwrap_or(""))
})
});
if update && (!(key_of_its_own || key_given) || each.is_some() || o.contains_key("rkey")) {
out.push(format!(
"{at}.update: the record key of the one record it replaces, or {{\"$value\": name}} holding it, with no each or rkey"
));
}
match o.get("record") {
Some(Value::Object(r))
if update && r.keys().any(|k| k.starts_with('$') && k != "$type") =>
{
out.push(format!(
"{at}.record: an update's record names its fields, with no operator at its top"
));
}
Some(r @ Value::Object(_)) => {
let within = Within {
item: each.is_some(),
stored: update,
named: &named,
known: &known,
};
template(&mut out, r, &format!("{at}.record"), 1, within);
}
_ => out.push(format!("{at}.record: required: an object")),
}
}
out
}
/// What a template's operators may read where it is: an element (within
/// `each` or `$each`), the record an update replaces, the writes' names
/// (`as`), and whether a value's name is known.
#[derive(Clone, Copy)]
struct Within<'a> {
item: bool,
stored: bool,
named: &'a [&'a str],
known: &'a dyn Fn(&str) -> bool,
}
fn template(out: &mut Vec<String>, v: &Value, at: &str, depth: usize, w: Within) {
if depth > MAX_DEPTH {
out.push(format!("{at}: a template nests at most {MAX_DEPTH} deep"));
return;
}
let op = v
.as_object()
.and_then(|o| o.keys().find(|k| k.starts_with('$') && *k != "$type"))
.cloned();
let o = v.as_object();
let alone = |k: &str| o.is_some_and(|o| o.len() == 1 && o.contains_key(k));
let mut bad = |what: &str| out.push(format!("{at}: {what}"));
match op.as_deref() {
None => match v {
Value::Object(o) => {
for (k, x) in o {
if k == "$type" && !x.is_string() {
out.push(format!("{at}.$type: must be a string"));
} else if k != "$type" {
template(out, x, &format!("{at}.{k}"), depth + 1, w);
}
}
}
Value::Array(a) => {
for (i, x) in a.iter().enumerate() {
template(out, x, &format!("{at}[{i}]"), depth + 1, w);
}
}
_ => {}
},
Some("$value") => {
let ok = alone("$value")
&& v["$value"].as_str().is_some_and(|p| {
is_path(p) && p != "." && (w.known)(p.split('.').next().unwrap_or(""))
});
if !ok {
bad("{\"$value\": path} has the key alone, a path whose first key names a value");
}
}
Some("$item") => {
if !w.item {
bad("$item reads an element, within each or $each alone");
} else if !(alone("$item") && v["$item"].as_str().is_some_and(is_path)) {
bad("{\"$item\": path} has the key alone, a path or \".\"");
}
}
Some("$stored") => {
if !w.stored {
bad("$stored reads the record an update replaces, within an update alone");
} else if !(alone("$stored") && v["$stored"].as_str().is_some_and(is_path)) {
bad("{\"$stored\": path} has the key alone, a path or \".\"");
}
}
Some("$index") => {
if !w.item || !alone("$index") || v["$index"] != Value::Bool(true) {
bad("{\"$index\": true} alone, within each or $each");
}
}
Some("$now") => {
if !alone("$now") || v["$now"] != Value::Bool(true) {
bad("{\"$now\": true} has the key $now alone, true");
}
}
Some("$uri" | "$rkey") => {
let k = op.as_deref().unwrap_or_default();
if !(alone(k) && v[k].as_str().is_some_and(|a| w.named.contains(&a))) {
bad(&format!("{{\"{k}\": as}} has the key alone, a write's as"));
}
}
Some("$facets") => {
if !alone("$facets") || !v["$facets"].is_string() {
bad("{\"$facets\": key} has the key alone, the field holding the text");
}
}
Some("$each") => {
let ok = o.is_some_and(|o| o.len() == 2 && o.contains_key("value"))
&& v["$each"]
.as_str()
.is_some_and(|e| is_name(e) && (w.known)(e));
if ok {
let inner = Within { item: true, ..w };
template(out, &v["value"], &format!("{at}.value"), depth + 1, inner);
} else {
bad("{\"$each\": name, \"value\": template}, a value's name");
}
}
Some("$when") => {
let ok = o.is_some_and(|o| o.len() == 2 && o.contains_key("value"))
&& v["$when"].as_array().is_some_and(|a| {
(1..=4).contains(&a.len())
&& a.iter()
.all(|n| n.as_str().is_some_and(|n| is_name(n) && (w.known)(n)))
});
if ok {
template(out, &v["value"], &format!("{at}.value"), depth + 1, w);
} else {
bad("{\"$when\": [names], \"value\": template}, 1 to 4 values' names");
}
}
Some(k @ ("$first" | "$merge")) => match v[k].as_array() {
Some(a) if alone(k) && (2..=4).contains(&a.len()) => {
for (i, x) in a.iter().enumerate() {
template(out, x, &format!("{at}.{k}[{i}]"), depth + 1, w);
}
}
_ => bad(&format!(
"{{\"{k}\": [templates]}} has the key alone, 2 to 4 templates"
)),
},
Some(k) => bad(&format!(
"{k}: a key starting with $ is $type, or $value's, $item's, $index's, $each's, $when's, $first's, $merge's, $uri's, $rkey's, $stored's, $now's or $facets' alone"
)),
}
}
/// The kinds of field a composer asks, and the keys each takes beside
/// `name`, `kind`, `label` and `required`. `value`, a binding the view
/// reads, is what it opens holding: a text's words, a photo's picture
/// (shown, kept unless another is picked). A photos field's `exif` and a
/// place's `locate` may be bindings too, an account's preference, on
/// unless it holds false.
const KINDS: &[(&str, &[&str])] = &[
(
"text",
&["placeholder", "max", "facets", "suggest", "value"],
),
("line", &["placeholder", "max", "value"]),
(
"photos",
&[
"min", "max", "alt", "exif", "maxBytes", "maxSide", "value", "round", "camera",
],
),
("langs", &["max"]),
("labels", &["options"]),
("choice", &["options", "multiple"]),
("place", &["from", "locate"]),
("card", &["from"]),
];
/// A binding `{"$": path}` (or paths) the view reads.
fn is_bound(v: &Value) -> bool {
v.as_object()
.is_some_and(|o| o.len() == 1 && o.get("$").is_some_and(|p| p.is_string() || p.is_array()))
}
/// Words joined `{"$join": [parts]}`, each a string or a binding: what a
/// text or line opens holding, as a reply's `@handle ` of whom it answers.
fn is_joined(v: &Value) -> bool {
v.as_object()
.filter(|o| o.len() == 1)
.and_then(|o| o.get("$join"))
.and_then(Value::as_array)
.is_some_and(|parts| {
!parts.is_empty() && parts.iter().all(|p| p.is_string() || is_bound(p))
})
}
/// What a composer's fields' problems are, each where it is, and their
/// names (what its writes may read, with its given values').
pub fn fields_problems(fields: &Value, at: &str) -> (Vec<String>, Vec<String>) {
let mut out = Vec::new();
let mut names = Vec::new();
let Some(list) = fields.as_array().filter(|a| (1..=10).contains(&a.len())) else {
out.push(format!("{at}: must be an array of 1 to 10 fields"));
return (out, names);
};
let short = |v: &Value, max: usize| {
v.as_str().is_some_and(|s| {
(1..=max).contains(&s.chars().count()) && !s.contains(char::is_control)
})
};
let int = |v: &Value, lo: u64, hi: u64| v.as_u64().is_some_and(|n| (lo..=hi).contains(&n));
let of_kind = |kind: &str| -> Vec<&str> {
list.iter()
.filter(|f| f["kind"] == kind)
.filter_map(|f| f["name"].as_str())
.collect()
};
let (texts, photos) = (of_kind("text"), of_kind("photos"));
for (i, f) in list.iter().enumerate() {
let fat = format!("{at}[{i}]");
let mut bad = |k: &str, what: &str| out.push(format!("{fat}.{k}: {what}"));
let Some(o) = f.as_object() else {
out.push(format!("{fat}: must be an object"));
continue;
};
let name = o.get("name").and_then(Value::as_str).filter(|n| is_name(n));
match name {
Some(n) if !names.iter().any(|k| k == n) => names.push(n.to_string()),
_ => bad(
"name",
"a name (lowercase letters and digits), once among the fields",
),
}
let Some((kind, takes)) = o
.get("kind")
.and_then(Value::as_str)
.and_then(|k| KINDS.iter().find(|(n, _)| *n == k))
else {
bad(
"kind",
&format!(
"one of {}",
KINDS.iter().map(|(k, _)| *k).collect::<Vec<_>>().join(", ")
),
);
continue;
};
for (k, v) in o {
match k.as_str() {
"name" | "kind" => {}
"label" if !short(v, 40) => bad(k, "text of at most 40 characters"),
"required" if !v.is_boolean() => bad(k, "true or false"),
"label" | "required" => {}
k if !takes.contains(&k) => bad(k, &format!("a {kind} field takes no {k}")),
"placeholder" if !short(v, 80) => bad(k, "text of at most 80 characters"),
"max" if *kind == "text" && !int(v, 1, 10000) => bad(k, "graphemes, 1 to 10000"),
"max" if *kind == "line" && !int(v, 1, 1000) => bad(k, "graphemes, 1 to 1000"),
"max" if *kind == "photos" && !int(v, 1, 10) => bad(k, "1 to 10 photos"),
"max" if *kind == "langs" && !int(v, 1, 3) => bad(k, "1 to 3 languages"),
"min" if !int(v, 0, 10) => bad(k, "0 to 10 photos"),
"maxBytes" if !int(v, 10_000, 2_000_000) => bad(k, "bytes, 10000 to 2000000"),
"maxSide" if !int(v, 256, 4096) => bad(k, "pixels, 256 to 4096"),
"facets" | "alt" | "multiple" | "round" | "camera" if !v.is_boolean() => {
bad(k, "true or false")
}
"exif" | "locate" if !v.is_boolean() && !is_bound(v) => bad(
k,
"true or false, or a binding {\"$\": path}, on unless false",
),
"from" if *kind == "card" && !v.as_str().is_some_and(|t| texts.contains(&t)) => {
bad(k, "names a text field")
}
"from" if *kind == "place" && !v.as_str().is_some_and(|t| photos.contains(&t)) => {
bad(k, "names a photos field")
}
"suggest" => suggest_problems(v, &mut bad),
"value" if !is_bound(v) && !(*kind != "photos" && is_joined(v)) => bad(
k,
"a binding {\"$\": path} (a text or line's also {\"$join\": [parts]}), what it opens holding",
),
"options" => {
let opts = v.as_array().filter(|a| (1..=8).contains(&a.len()));
let ok = opts.is_some_and(|a| {
a.iter().all(|o| {
o.as_object().is_some_and(|o| {
o.keys()
.all(|k| matches!(k.as_str(), "label" | "value" | "only"))
&& short(&o["label"], 40)
&& o.contains_key("value")
&& (*kind != "labels" || short(&o["value"], 64))
&& o.get("only").is_none_or(Value::is_boolean)
})
})
});
if !ok {
bad(k, "1 to 8 options, each { label, value, only? }");
}
}
_ => {}
}
}
if *kind == "photos" {
let (min, max) = (
o.get("min").and_then(Value::as_u64),
o.get("max").and_then(Value::as_u64),
);
if min.zip(max).is_some_and(|(a, b)| a > b) {
bad("min", "at most max");
}
for k in ["max", "maxBytes", "maxSide"] {
if !o.contains_key(k) {
bad(k, "required");
}
}
}
if matches!(*kind, "labels" | "choice") && !o.contains_key("options") {
bad("options", "required");
}
if *kind == "card" && !o.contains_key("from") {
bad("from", "required: the text field whose link it shows");
}
}
(out, names)
}
/// The most a composer's field may hold, as the lexicons of the records its
/// value is written into say: grapheme clusters (`maxGraphemes`) and UTF-8
/// bytes (`maxLength`), the narrowest of each where several write it.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct Limit {
pub graphemes: Option<u64>,
pub bytes: Option<u64>,
}
/// `at` narrowed to `by`, whichever of them is a limit.
fn narrow(at: Option<u64>, by: Option<u64>) -> Option<u64> {
at.into_iter().chain(by).min()
}
/// The limit of the field `name` by the writes template `writes`: each
/// record property its value is, whole (`{"$value": name}`), read in the
/// record's bundled lexicon. A collection with none limits nothing.
pub fn limit(name: &str, writes: &Value) -> Limit {
let whole = json!({ "$value": name });
let mut out = Limit::default();
for w in writes.as_array().into_iter().flatten() {
let doc = w["collection"].as_str().and_then(crate::lexicon::bundled);
let main = doc.as_ref().map(|d| &d["defs"]["main"]);
let props = main.map(|m| &m["record"]["properties"]);
for (k, v) in w["record"].as_object().into_iter().flatten() {
if let Some(p) = props.map(|p| &p[k]).filter(|_| *v == whole) {
out.graphemes = narrow(out.graphemes, p["maxGraphemes"].as_u64());
out.bytes = narrow(out.bytes, p["maxLength"].as_u64());
}
}
}
out
}
/// What is wrong with a composer's text and line fields' `max` against
/// what its `writes` limit them to (`limit`): one wider than a lexicon's
/// graphemes or bytes (a grapheme is a byte at least), or none where no
/// lexicon limits it. A view's `max` only narrows a lexicon's.
pub fn limit_problems(fields: &Value, writes: &Value) -> Vec<String> {
let mut out = Vec::new();
for (i, f) in fields.as_array().into_iter().flatten().enumerate() {
let lex = limit(f["name"].as_str().unwrap_or_default(), writes);
let max = f.get("max");
let wider = |n: u64| max.and_then(Value::as_u64).is_some_and(|m| m > n);
let problem = match (f["kind"].as_str(), lex.graphemes, lex.bytes) {
(Some("text" | "line"), None, None) if max.is_none() => {
"required: no lexicon of a record it is written into limits it".to_string()
}
(Some("text" | "line"), Some(g), _) if wider(g) => {
format!("at most its record's lexicon's {g} graphemes")
}
(Some("text" | "line"), _, Some(b)) if wider(b) => {
format!("at most its record's lexicon's {b} bytes")
}
_ => continue,
};
out.push(format!("fields[{i}].max: {problem}"));
}
out
}
/// A composer's field as the form asks it, a text's or line's limits read
/// from its `writes` (`limit`): `max`, its graphemes, the view's narrowed
/// by the lexicon's, and `maxBytes`, its UTF-8 bytes, the lexicon's.
pub fn limited(mut field: Value, writes: &Value) -> Value {
if let (Some("text" | "line"), Some(name)) = (field["kind"].as_str(), field["name"].as_str()) {
let lex = limit(name, writes);
if let Some(g) = narrow(field["max"].as_u64(), lex.graphemes) {
field["max"] = g.into();
}
if let Some(b) = lex.bytes {
field["maxBytes"] = b.into();
}
}
field
}
/// A text field's suggestions: `{ method, service?, param, params?, items,
/// did, handle, name?, avatar? }`, a query and where in its answer the
/// accounts are.
fn suggest_problems(v: &Value, bad: &mut dyn FnMut(&str, &str)) {
const KEYS: &[&str] = &[
"method", "service", "param", "params", "items", "did", "handle", "name", "avatar",
];
let ok = v.as_object().is_some_and(|o| {
o.keys().all(|k| KEYS.contains(&k.as_str()))
&& o.get("method")
.and_then(Value::as_str)
.is_some_and(atproto::syntax::is_nsid)
&& o.get("service").is_none_or(|s| {
s.as_str()
.is_some_and(|s| crate::xrpc::Service::parse(s).is_ok())
})
&& o.get("param").and_then(Value::as_str).is_some_and(is_name)
&& o.get("params").is_none_or(|p| {
p.as_object().is_some_and(|p| {
p.len() <= 8 && p.values().all(|v| !v.is_object() && !v.is_array())
})
})
&& ["items", "did", "handle"]
.iter()
.all(|k| o.get(*k).and_then(Value::as_str).is_some_and(is_path))
&& ["name", "avatar"]
.iter()
.all(|k| o.get(*k).is_none_or(|p| p.as_str().is_some_and(is_path)))
});
if !ok {
bad(
"suggest",
"{ method, service?, param, params? (literals), items, did, handle, name?, avatar? }, paths into its answer",
);
}
}
/// What a value or element holds at `path` ("." itself; an array's
/// element by its index), if anything.
fn at<'a>(v: &'a Value, path: &str) -> Option<&'a Value> {
if path == "." {
return Some(v).filter(|v| !v.is_null());
}
path.split('.')
.try_fold(v, |v, k| match v {
Value::Array(a) => k.parse::<usize>().ok().and_then(|i| a.get(i)),
_ => v.get(k),
})
.filter(|v| !v.is_null())
}
/// What `values` holds at `path`, its first key a value's name.
fn value_at<'a>(values: &'a Map<String, Value>, path: &str) -> Option<&'a Value> {
let (name, rest) = path.split_once('.').unwrap_or((path, "."));
values.get(name).and_then(|v| at(v, rest))
}
/// The record key the `i`th write updates, if it is an update: its own,
/// or what the value it names holds (a gallery's, given), which must be
/// a record key.
fn update_key(w: &Value, values: &Map<String, Value>, i: usize) -> Result<Option<String>, String> {
let key = match &w["update"] {
Value::Null => return Ok(None),
Value::String(k) => Some(k.as_str()),
named => {
value_at(values, named["$value"].as_str().unwrap_or_default()).and_then(Value::as_str)
}
};
match key.filter(|k| atproto::syntax::is_record_key(k)) {
Some(k) => Ok(Some(k.to_string())),
None => Err(format!(
"writes[{i}].update: the value it names holds no record key"
)),
}
}
/// The record each write updates, where it is an update: its collection
/// and record key (its own, or read from `values`), for `apply_writes` to
/// read as it is stored before `expand`; a template with a problem, or an
/// update whose value holds no record key, refused, by the first.
pub fn updated(
writes: &Value,
values: &Map<String, Value>,
) -> Result<Vec<Option<(String, String)>>, String> {
if let Some(p) = problems(writes, None).into_iter().next() {
return Err(p);
}
let mut out = Vec::new();
for (i, w) in writes.as_array().into_iter().flatten().enumerate() {
let collection = w["collection"].as_str().unwrap_or_default();
out.push(update_key(w, values, i)?.map(|k| (collection.to_string(), k)));
}
Ok(out)
}
/// The writes a template makes with `values`, their record keys from `tid`
/// (or their own), their at-uris in `did`'s repository, `now` the time,
/// `stored` the record each update replaces as `updated` found it (by its
/// write's index; none where there is none yet): every record made.
pub fn expand(
writes: &Value,
values: &Map<String, Value>,
stored: &[Option<Value>],
did: &str,
now: &str,
mut tid: impl FnMut() -> String,
) -> Result<Vec<Made>, String> {
let problems = problems(writes, None);
if let Some(p) = problems.first() {
return Err(p.clone());
}
let list = writes.as_array().expect("checked");
let mut updates = Vec::new();
for (i, w) in list.iter().enumerate() {
updates.push(update_key(w, values, i)?);
}
let values = Value::Object(values.clone());
let stored_at = |i: usize| stored.get(i).and_then(Option::as_ref);
// Each write's instances: the element of its `each` each stands for
// (None for one made once), those `when` and `whenItem` leave.
let mut instances: Vec<Vec<Option<usize>>> = Vec::new();
for w in list {
let made = w["when"].as_array().is_none_or(|ns| {
ns.iter()
.all(|n| at(&values, n.as_str().unwrap_or("")).is_some())
});
let these = match (made, w["each"].as_str()) {
(false, _) => vec![],
(true, None) => vec![None],
(true, Some(e)) => {
let elements = at(&values, e)
.and_then(Value::as_array)
.cloned()
.unwrap_or_default();
(0..elements.len())
.filter(|&i| {
w["whenItem"]
.as_str()
.is_none_or(|p| at(&elements[i], p).is_some())
})
.map(Some)
.collect()
}
};
instances.push(these);
}
let total: usize = instances.iter().map(Vec::len).sum();
if total > MAX_WRITES {
return Err(format!(
"{total} records, more than the {MAX_WRITES} one send makes"
));
}
let index_of = |a: &str| list.iter().position(|w| w["as"] == a);
// Record keys first, so any write may name another's.
let mut rkeys: Vec<Vec<String>> = updates
.iter()
.zip(&instances)
.map(|(key, is)| {
is.iter()
.map(|_| key.clone().unwrap_or_else(&mut tid))
.collect()
})
.collect();
for (i, w) in list.iter().enumerate() {
if let Some(other) = w["rkey"]["$rkey"].as_str().and_then(index_of) {
for (n, element) in instances[i].clone().iter().enumerate() {
let found = pick(&instances[other], *element).map(|k| rkeys[other][k].clone());
let Some(found) = found else {
return Err(format!(
"writes[{i}].rkey: no record of writes[{other}] to share a key with"
));
};
rkeys[i][n] = found;
}
}
}
let refs = Refs {
list,
instances: &instances,
rkeys: &rkeys,
did,
};
let mut made = Vec::new();
for (i, w) in list.iter().enumerate() {
let collection = w["collection"].as_str().unwrap_or_default();
let elements = w["each"]
.as_str()
.and_then(|e| at(&values, e))
.and_then(Value::as_array);
let update = updates[i].is_some().then(|| Update {
stored: stored_at(i).cloned(),
names: w["record"]
.as_object()
.into_iter()
.flatten()
.map(|(k, _)| k.clone())
.collect(),
});
for (n, element) in instances[i].iter().enumerate() {
let scope = Scope {
values: &values,
item: element.and_then(|e| elements.map(|a| (&a[e], e))),
stored: stored_at(i),
now,
refs: &refs,
};
let record = fill(&w["record"], &scope)?
.filter(|r| r.as_object().is_some_and(|o| !o.is_empty()));
let Some(record) = record else {
return Err(format!("writes[{i}]: its record holds nothing"));
};
made.push(Made {
collection: collection.to_string(),
rkey: rkeys[i][n].clone(),
record,
update: update.clone(),
});
}
}
Ok(made)
}
/// Which of a write's instances goes with `element`: the same element's
/// where it is made per element, else its one.
fn pick(instances: &[Option<usize>], element: Option<usize>) -> Option<usize> {
match instances {
[None] => Some(0),
_ => instances.iter().position(|i| i.is_some() && *i == element),
}
}
struct Refs<'a> {
list: &'a [Value],
instances: &'a [Vec<Option<usize>>],
rkeys: &'a [Vec<String>],
did: &'a str,
}
struct Scope<'a> {
values: &'a Value,
/// The element read, and its index.
item: Option<(&'a Value, usize)>,
/// The record an update replaces, as stored.
stored: Option<&'a Value>,
now: &'a str,
refs: &'a Refs<'a>,
}
/// A template filled: `None` where what it reads is not there.
fn fill(v: &Value, s: &Scope) -> Result<Option<Value>, String> {
let Some(o) = v.as_object() else {
return match v {
Value::Array(a) => {
let mut out = Vec::new();
for x in a {
out.extend(fill(x, s)?);
}
Ok(Some(Value::Array(out)))
}
_ => Ok(Some(v.clone())),
};
};
if let Some(p) = o.get("$value").and_then(Value::as_str) {
return Ok(at(s.values, p).cloned());
}
if let Some(p) = o.get("$item").and_then(Value::as_str) {
return Ok(s.item.and_then(|(e, _)| at(e, p)).cloned());
}
if let Some(p) = o.get("$stored").and_then(Value::as_str) {
return Ok(s.stored.and_then(|r| at(r, p)).cloned());
}
if o.contains_key("$index") {
return Ok(s.item.map(|(_, i)| json!(i)));
}
if o.contains_key("$now") {
return Ok(Some(s.now.into()));
}
if o.contains_key("$facets") {
return Ok(Some(v.clone()));
}
for k in ["$uri", "$rkey"] {
if let Some(a) = o.get(k).and_then(Value::as_str) {
let r = s.refs;
// `problems` holds `a` to a write's `as`: what may be missing is
// its instance for this element.
let found = r.list.iter().position(|w| w["as"] == a).and_then(|w| {
let n = pick(&r.instances[w], s.item.map(|(_, i)| i))?;
Some((w, n))
});
let Some((w, n)) = found else {
return Ok(None);
};
let rkey = &r.rkeys[w][n];
return Ok(Some(if k == "$rkey" {
rkey.as_str().into()
} else {
format!(
"at://{}/{}/{rkey}",
r.did,
r.list[w]["collection"].as_str().unwrap_or_default()
)
.into()
}));
}
}
if let Some(e) = o.get("$each").and_then(Value::as_str) {
let Some(elements) = at(s.values, e).and_then(Value::as_array) else {
return Ok(None);
};
let mut out = Vec::new();
for (i, element) in elements.iter().enumerate() {
let inner = Scope {
values: s.values,
item: Some((element, i)),
stored: s.stored,
now: s.now,
refs: s.refs,
};
out.extend(fill(&o["value"], &inner)?);
}
return Ok(Some(Value::Array(out)));
}
if let Some(names) = o.get("$when").and_then(Value::as_array) {
let there = names
.iter()
.all(|n| at(s.values, n.as_str().unwrap_or("")).is_some());
return if there {
fill(&o["value"], s)
} else {
Ok(None)
};
}
if let Some(firsts) = o.get("$first").and_then(Value::as_array) {
for x in firsts {
if let Some(found) = fill(x, s)? {
return Ok(Some(found));
}
}
return Ok(None);
}
if let Some(parts) = o.get("$merge").and_then(Value::as_array) {
let mut out = Map::new();
for x in parts {
if let Some(Value::Object(part)) = fill(x, s)? {
out.extend(part);
}
}
return Ok(Some(Value::Object(out)));
}
let mut out = Map::new();
for (k, x) in o {
if let Some(found) = fill(x, s)? {
out.insert(k.clone(), found);
}
}
Ok(Some(Value::Object(out)))
}
#[cfg(test)]
mod tests {
use super::*;
fn tids() -> impl FnMut() -> String {
let mut n = 0;
move || {
n += 1;
format!("3k{n:011}")
}
}
/// A Grain gallery: a photo per photo, its camera's details where it has
/// some, the gallery, an item per photo pointing at both; the absent left
/// out.
#[test]
fn a_gallery_and_its_photos_at_once() {
let writes = json!([
{ "as": "photo", "each": "photos", "collection": "social.grain.photo", "record": {
"photo": { "$item": "blob" }, "alt": { "$item": "alt" }, "aspectRatio": { "$item": "aspectRatio" }, "createdAt": { "$now": true } } },
{ "each": "photos", "whenItem": "exif", "collection": "social.grain.photo.exif", "record": {
"$merge": [{ "$item": "exif" }, { "photo": { "$uri": "photo" }, "createdAt": { "$now": true } }] } },
{ "as": "gallery", "collection": "social.grain.gallery", "record": {
"title": { "$value": "title" }, "description": { "$value": "description" }, "facets": { "$facets": "description" },
"location": { "$when": ["place"], "value": { "name": { "$value": "place.name" }, "value": { "$value": "place.value" } } },
"createdAt": { "$now": true } } },
{ "each": "photos", "collection": "social.grain.gallery.item", "record": {
"gallery": { "$uri": "gallery" }, "item": { "$uri": "photo" }, "position": { "$index": true }, "createdAt": { "$now": true } } },
]);
assert_eq!(problems(&writes, None), Vec::<String>::new());
let values = json!({ "title": "nyc", "photos": [
{ "blob": { "ref": "a" }, "alt": "skyline", "aspectRatio": { "width": 3, "height": 4 }, "exif": { "iSO": 400 } },
{ "blob": { "ref": "b" }, "alt": "", "aspectRatio": { "width": 4, "height": 3 } },
] });
let made = expand(
&writes,
values.as_object().unwrap(),
&[],
"did:plc:me",
"2026-11-18T00:00:00.000Z",
tids(),
)
.unwrap();
let kinds: Vec<&str> = made.iter().map(|m| m.collection.as_str()).collect();
assert_eq!(
kinds,
[
"social.grain.photo",
"social.grain.photo",
"social.grain.photo.exif",
"social.grain.gallery",
"social.grain.gallery.item",
"social.grain.gallery.item"
]
);
let photo = |n: usize| format!("at://did:plc:me/social.grain.photo/{}", made[n].rkey);
assert_eq!(
made[2].record,
json!({ "iSO": 400, "photo": photo(0), "createdAt": "2026-11-18T00:00:00.000Z" })
);
// No description, no place: left out; the facets left for create.
assert_eq!(
made[3].record,
json!({ "title": "nyc", "facets": { "$facets": "description" }, "createdAt": "2026-11-18T00:00:00.000Z" })
);
let gallery = format!("at://did:plc:me/social.grain.gallery/{}", made[3].rkey);
assert_eq!(made[5].record["item"], photo(1));
assert_eq!(
(&made[5].record["gallery"], &made[5].record["position"]),
(&json!(gallery), &json!(1))
);
}
/// A Bluesky post: its embed the first that is there, its threadgate
/// made only when asked for, with the post's own record key.
#[test]
fn a_post_its_embed_and_its_threadgate() {
let images = json!({ "$type": "app.bsky.embed.images", "images": { "$each": "photos", "value": {
"image": { "$item": "blob" }, "alt": { "$item": "alt" } } } });
let writes = json!([
{ "as": "post", "collection": "app.bsky.feed.post", "record": {
"text": { "$value": "text" }, "langs": { "$value": "langs" }, "createdAt": { "$now": true },
"embed": { "$first": [
{ "$when": ["quote", "photos"], "value": { "$type": "app.bsky.embed.recordWithMedia", "record": { "record": { "$value": "quote" } }, "media": images } },
{ "$when": ["quote"], "value": { "$type": "app.bsky.embed.record", "record": { "$value": "quote" } } },
{ "$when": ["photos"], "value": images },
] } } },
{ "when": ["gate"], "rkey": { "$rkey": "post" }, "collection": "app.bsky.feed.threadgate", "record": {
"post": { "$uri": "post" }, "allow": { "$value": "gate" }, "createdAt": { "$now": true } } },
]);
assert!(problems(&writes, None).is_empty());
let send = |values: Value| {
expand(
&writes,
values.as_object().unwrap(),
&[],
"did:plc:me",
"t",
tids(),
)
.unwrap()
};
let plain = send(json!({ "text": "hi" }));
assert_eq!(plain.len(), 1);
assert_eq!(plain[0].record, json!({ "text": "hi", "createdAt": "t" }));
let quote = json!({ "uri": "at://did:plc:a/app.bsky.feed.post/1", "cid": "bafy" });
let both = send(
json!({ "text": "look", "quote": quote, "photos": [{ "blob": { "ref": "a" }, "alt": "" }], "gate": [] }),
);
assert_eq!(
both[0].record["embed"]["$type"],
"app.bsky.embed.recordWithMedia"
);
assert_eq!(
both[0].record["embed"]["media"]["images"][0]["image"],
json!({ "ref": "a" })
);
// Nobody may reply (an empty allow is a value), the gate keyed as its post.
assert_eq!(both[1].rkey, both[0].rkey);
assert_eq!(both[1].record["allow"], json!([]));
assert_eq!(
both[1].record["post"],
format!("at://did:plc:me/app.bsky.feed.post/{}", both[0].rkey)
);
}
#[test]
fn templates_checked() {
let names = vec!["text".to_string()];
let bad = json!([
{ "collection": "not an nsid", "record": { "a": { "$item": "x" }, "b": { "$value": "nope" }, "c": { "$uri": "gone" }, "d": { "$oops": 1 } }, "extra": 1 },
]);
assert_eq!(
problems(&bad, Some(&names)),
[
"writes[0].extra: a write has no extra",
"writes[0].collection: required: an NSID",
"writes[0].record.a: $item reads an element, within each or $each alone",
"writes[0].record.b: {\"$value\": path} has the key alone, a path whose first key names a value",
"writes[0].record.c: {\"$uri\": as} has the key alone, a write's as",
"writes[0].record.d: $oops: a key starting with $ is $type, or $value's, $item's, $index's, $each's, $when's, $first's, $merge's, $uri's, $rkey's, $stored's, $now's or $facets' alone",
]
);
assert!(!problems(&json!([]), None).is_empty());
let too_many: Vec<Value> = (0..=MAX_TEMPLATE)
.map(|_| json!({ "collection": "a.b.c", "record": { "x": 1 } }))
.collect();
assert!(!problems(&Value::Array(too_many), None).is_empty());
// A record of nothing is refused as sent.
let empty = json!([{ "collection": "a.b.c", "record": { "x": { "$value": "text" } } }]);
assert_eq!(
expand(&empty, &Map::new(), &[], "did:plc:me", "t", tids()).unwrap_err(),
"writes[0]: its record holds nothing"
);
}
/// Each way a write and its record's operators can be wrong, named
/// where it is.
#[test]
fn every_template_problem_named() {
let names = vec!["text".to_string(), "photos".to_string()];
let mut deep = json!(1);
for _ in 0..12 {
deep = json!({ "a": deep });
}
let writes = json!([
"a write",
{ "collection": "a.b.c", "as": "Bad Name", "each": "nope", "when": [],
"rkey": { "$rkey": "zzz" }, "record": 1 },
{ "collection": "a.b.c", "whenItem": "x", "record": {
"$type": 5, "list": [1, "two"], "deep": deep, "i": { "$index": true },
"n": { "$now": 1 }, "f": { "$facets": 1 }, "e": { "$each": "nope", "value": 1 },
"w": { "$when": [], "value": 1 }, "fi": { "$first": [1] } } },
{ "collection": "a.b.c", "each": "photos", "record": { "x": { "$item": "a..b" } } },
]);
let mut got = problems(&writes, Some(&names));
let mut want = vec![
"writes[0]: must be an object".to_string(),
"writes[1].as: a name, once among the writes".into(),
"writes[1].each: names a value given or written".into(),
"writes[1].when: 1 to 4 names of values".into(),
"writes[1].rkey: {\"$rkey\": as}, another write's".into(),
"writes[1].record: required: an object".into(),
"writes[2].whenItem: a path within each element, with each".into(),
"writes[2].record.$type: must be a string".into(),
format!(
"writes[2].record.deep{}: a template nests at most 12 deep",
".a".repeat(11)
),
"writes[2].record.i: {\"$index\": true} alone, within each or $each".into(),
"writes[2].record.n: {\"$now\": true} has the key $now alone, true".into(),
"writes[2].record.f: {\"$facets\": key} has the key alone, the field holding the text"
.into(),
"writes[2].record.e: {\"$each\": name, \"value\": template}, a value's name".into(),
"writes[2].record.w: {\"$when\": [names], \"value\": template}, 1 to 4 values' names"
.into(),
"writes[2].record.fi: {\"$first\": [templates]} has the key alone, 2 to 4 templates"
.into(),
"writes[3].record.x: {\"$item\": path} has the key alone, a path or \".\"".into(),
];
got.sort();
want.sort();
assert_eq!(got, want);
// expand refuses a template with a problem, by its first.
assert_eq!(
expand(&json!([1]), &Map::new(), &[], "did:plc:me", "t", tids()).unwrap_err(),
"writes[0]: must be an object"
);
}
/// What is not there left out: an array's elements, a merge's parts
/// that are not objects, an `$each` of nothing, the at-uri of a write
/// not made; another write's record key, where one is.
#[test]
fn what_is_not_there_left_out() {
let writes = json!([
{ "as": "post", "collection": "a.b.c", "record": { "x": 1 } },
{ "as": "gate", "when": ["gate"], "collection": "a.b.d", "record": { "x": 1 } },
{ "collection": "a.b.e", "record": {
"list": [{ "$value": "text" }, { "$value": "missing" }, 3],
"merged": { "$merge": [{ "$value": "text" }, { "a": 1 }] },
"each": { "$each": "missing", "value": 1 },
"gate": { "$uri": "gate" },
"key": { "$rkey": "post" } } },
{ "each": "tags", "whenItem": ".", "collection": "a.b.f", "record": { "tag": { "$item": "." } } },
]);
assert!(problems(&writes, None).is_empty());
// An element that is null is no element: none made for it.
let values = json!({ "text": "hi", "tags": ["a", null] });
let made = expand(
&writes,
values.as_object().unwrap(),
&[],
"did:plc:me",
"t",
tids(),
)
.unwrap();
assert_eq!(made.len(), 3);
assert_eq!(
made[1].record,
json!({ "list": ["hi", 3], "merged": { "a": 1 }, "key": made[0].rkey })
);
assert_eq!(made[2].record, json!({ "tag": "a" }));
}
#[test]
fn sends_held_to_their_bounds() {
// More records than one send makes.
let writes = json!([{ "each": "photos", "collection": "a.b.c", "record": { "i": { "$index": true } } }]);
let photos: Vec<Value> = (0..=MAX_WRITES).map(|i| json!(i)).collect();
let values = json!({ "photos": photos });
assert_eq!(
expand(
&writes,
values.as_object().unwrap(),
&[],
"did:plc:me",
"t",
tids()
)
.unwrap_err(),
"33 records, more than the 32 one send makes"
);
// A key shared with a write not made.
let writes = json!([
{ "as": "post", "when": ["gate"], "collection": "a.b.c", "record": { "x": 1 } },
{ "rkey": { "$rkey": "post" }, "collection": "a.b.d", "record": { "y": 1 } },
]);
assert_eq!(
expand(&writes, &Map::new(), &[], "did:plc:me", "t", tids()).unwrap_err(),
"writes[1].rkey: no record of writes[0] to share a key with"
);
}
/// Grain's profile, edited: one record of its own key, `self`,
/// replacing the one stored; its picture kept where no new one is
/// picked, its description taken out where it was cleared, what the
/// form does not name kept; created where there is none yet.
#[test]
fn a_profile_updated_over_its_stored_record() {
let writes = json!([{ "collection": "social.grain.actor.profile", "update": "self", "record": {
"displayName": { "$value": "name" },
"description": { "$value": "description" },
"avatar": { "$first": [{ "$value": "avatar.0.blob" }, { "$stored": "avatar" }] },
"createdAt": { "$first": [{ "$stored": "createdAt" }, { "$now": true }] } } }]);
let names = vec!["name".into(), "description".into(), "avatar".into()];
assert_eq!(problems(&writes, Some(&names)), Vec::<String>::new());
assert_eq!(
updated(&writes, &Map::new()).unwrap(),
[Some(("social.grain.actor.profile".into(), "self".into()))]
);
let old = json!({ "$type": "blob", "ref": { "$link": "old" }, "mimeType": "image/jpeg", "size": 9 });
let stored = json!({ "$type": "social.grain.actor.profile", "displayName": "Ana",
"description": "photos", "avatar": old, "createdAt": "2025-01-01T00:00:00.000Z", "pronouns": "she/her" });
let send = |values: Value, stored: Option<Value>| {
let made = expand(
&writes,
values.as_object().unwrap(),
&[stored],
"did:plc:me",
"t",
tids(),
)
.unwrap();
assert_eq!((made.len(), made[0].rkey.as_str()), (1, "self"), "{made:?}");
let update = made[0].update.clone().unwrap();
let replaces = update.stored.is_some();
(update.over(made[0].record.clone()), replaces)
};
// A new name, the description cleared, no new picture: the stored
// one's blob ref kept, and what the form does not name.
let (written, replaces) = send(json!({ "name": "Ana B" }), Some(stored.clone()));
assert!(replaces);
assert_eq!(
written,
json!({ "$type": "social.grain.actor.profile", "displayName": "Ana B", "avatar": old,
"createdAt": "2025-01-01T00:00:00.000Z", "pronouns": "she/her" })
);
// A new picture replaces it.
let new = json!({ "$type": "blob", "ref": { "$link": "new" }, "mimeType": "image/jpeg", "size": 7 });
let (written, _) = send(
json!({ "name": "Ana", "avatar": [{ "blob": new, "alt": "" }] }),
Some(stored),
);
assert_eq!(written["avatar"], new);
// None stored yet: created, now.
let (written, replaces) = send(json!({ "description": "hi" }), None);
assert!(!replaces);
assert_eq!(written, json!({ "description": "hi", "createdAt": "t" }));
// A write that is no update reads nothing; one with a problem is refused.
let both = json!([
{ "collection": "a.b.c", "record": { "x": 1 } },
{ "collection": "a.b.d", "update": "self", "record": { "y": { "$stored": "y" } } },
]);
assert_eq!(
updated(&both, &Map::new()).unwrap(),
[None, Some(("a.b.d".into(), "self".into()))]
);
assert_eq!(
updated(&json!([1]), &Map::new()).unwrap_err(),
"writes[0]: must be an object"
);
}
/// Each way an update and `$stored` can be wrong.
#[test]
fn every_update_problem_named() {
let names = vec!["photos".to_string()];
let writes = json!([
{ "as": "a", "collection": "a.b.c", "update": true, "record": { "x": 1 } },
{ "collection": "a.b.c", "update": "a/b", "record": { "x": 1 } },
{ "collection": "a.b.c", "each": "photos", "update": "self", "record": { "x": 1 } },
{ "collection": "a.b.c", "rkey": { "$rkey": "a" }, "update": "self", "record": { "x": 1 } },
{ "collection": "a.b.c", "update": "self", "record": { "$merge": [{ "x": 1 }, { "y": 2 }] } },
{ "collection": "a.b.c", "record": { "x": { "$stored": "x" } } },
{ "collection": "a.b.c", "update": "self", "record": { "x": { "$stored": 1 } } },
]);
let update = "the record key of the one record it replaces, or {\"$value\": name} holding it, with no each or rkey";
assert_eq!(
problems(&writes, Some(&names)),
[
format!("writes[0].update: {update}"),
format!("writes[1].update: {update}"),
format!("writes[2].update: {update}"),
format!("writes[3].update: {update}"),
"writes[4].record: an update's record names its fields, with no operator at its top".into(),
"writes[5].record.x: $stored reads the record an update replaces, within an update alone".into(),
"writes[6].record.x: {\"$stored\": path} has the key alone, a path or \".\"".into(),
]
);
// A key given: a value's name, alone.
let given = json!([
{ "collection": "a.b.c", "update": { "$value": "nope" }, "record": { "x": 1 } },
{ "collection": "a.b.c", "update": { "$value": "photos", "x": 1 }, "record": { "x": 1 } },
]);
assert_eq!(
problems(&given, Some(&names)),
[
format!("writes[0].update: {update}"),
format!("writes[1].update: {update}"),
]
);
}
/// A gallery edited: the record key it updates given (`{"$value":
/// "rkey"}`, the view's `$rkey` of the gallery's uri), read before it
/// is sent; one that holds no record key, or none, refused.
#[test]
fn an_update_whose_key_is_given() {
let writes = json!([{ "collection": "social.grain.gallery", "update": { "$value": "rkey" }, "record": {
"title": { "$value": "title" }, "description": { "$value": "description" },
"facets": { "$facets": "description" }, "updatedAt": { "$now": true } } }]);
let names = vec!["rkey".into(), "title".into(), "description".into()];
assert_eq!(problems(&writes, Some(&names)), Vec::<String>::new());
let values = json!({ "rkey": "3kgallery", "title": "Lisbon" });
let values = values.as_object().unwrap();
assert_eq!(
updated(&writes, values).unwrap(),
[Some(("social.grain.gallery".into(), "3kgallery".into()))]
);
let stored = json!({ "title": "Old", "description": "was", "createdAt": "2025-01-01T00:00:00.000Z",
"location": { "name": "Lisbon", "value": "8a2a1072b59ffff" } });
let made = expand(&writes, values, &[Some(stored)], "did:plc:me", "t", tids()).unwrap();
assert_eq!(made[0].rkey, "3kgallery");
let update = made[0].update.clone().unwrap();
// Its title set, its description cleared, its facets left for
// create, its place and createdAt kept.
assert_eq!(
update.over(made[0].record.clone()),
json!({ "title": "Lisbon", "facets": { "$facets": "description" }, "updatedAt": "t",
"createdAt": "2025-01-01T00:00:00.000Z", "location": { "name": "Lisbon", "value": "8a2a1072b59ffff" } })
);
let refused = "writes[0].update: the value it names holds no record key";
for values in [json!({ "rkey": "a/b" }), json!({ "rkey": 5 }), json!({})] {
let values = values.as_object().unwrap();
assert_eq!(updated(&writes, values).unwrap_err(), refused);
assert_eq!(
expand(&writes, values, &[], "did:plc:me", "t", tids()).unwrap_err(),
refused
);
}
}
/// A field's `value`, what it opens holding, is a binding, on a text,
/// a line or photos alone; photos drawn `round` (an avatar) say so with
/// true or false.
#[test]
fn a_fields_value_is_a_binding() {
let fields = json!([
{ "name": "a", "kind": "text", "max": 10, "value": { "$": "joins.profile.description" } },
{ "name": "b", "kind": "line", "max": 10, "value": { "$": ["x", "y"] } },
{ "name": "c", "kind": "photos", "max": 1, "maxBytes": 900000, "maxSide": 1000, "value": { "$": "avatar" }, "round": true },
{ "name": "d", "kind": "line", "max": 10, "value": "Ana" },
{ "name": "e", "kind": "text", "max": 10, "value": { "$": 1 } },
{ "name": "f", "kind": "langs", "value": { "$": "langs" } },
{ "name": "g", "kind": "photos", "max": 1, "maxBytes": 900000, "maxSide": 1000, "round": "yes" },
{ "name": "h", "kind": "line", "max": 10, "round": true },
]);
let bad = "a binding {\"$\": path} (a text or line's also {\"$join\": [parts]}), what it opens holding";
assert_eq!(
fields_problems(&fields, "f").0,
[
format!("f[3].value: {bad}"),
format!("f[4].value: {bad}"),
"f[5].value: a langs field takes no value".into(),
"f[6].round: true or false".into(),
"f[7].round: a line field takes no round".into(),
]
);
// A text or line's words joined, strings and bindings; not a photo's.
let joined = json!([
{ "name": "i", "kind": "text", "max": 10, "value": { "$join": ["@", { "$": "author.handle" }, " "] } },
{ "name": "j", "kind": "photos", "max": 1, "maxBytes": 900000, "maxSide": 1000, "value": { "$join": ["a"] } },
{ "name": "k", "kind": "line", "max": 10, "value": { "$join": [1] } },
]);
assert_eq!(
fields_problems(&joined, "f").0,
[format!("f[1].value: {bad}"), format!("f[2].value: {bad}")]
);
}
/// A photos field may offer the camera beside the library (`camera`,
/// true or false, a story's); no other kind takes it.
#[test]
fn a_photos_field_offers_the_camera() {
let fields = json!([
{ "name": "a", "kind": "photos", "max": 1, "maxBytes": 900000, "maxSide": 1000, "camera": true },
{ "name": "b", "kind": "photos", "max": 4, "maxBytes": 900000, "maxSide": 1000, "camera": false },
{ "name": "c", "kind": "photos", "max": 1, "maxBytes": 900000, "maxSide": 1000, "camera": "rear" },
{ "name": "d", "kind": "line", "max": 10, "camera": true },
]);
assert_eq!(
fields_problems(&fields, "f").0,
[
"f[2].camera: true or false",
"f[3].camera: a line field takes no camera"
]
);
}
/// A place fills itself from a photos field's first located photo
/// (`from`), where `locate` is not false; `exif` and `locate` are true
/// or false, or a binding (an account's preference).
#[test]
fn a_place_from_photos_and_preferences_bound() {
let pref = json!({ "$": "joins.prefs.preferences.@photoMetadataPref.includeExif" });
let fields = json!([
{ "name": "photos", "kind": "photos", "max": 4, "maxBytes": 900000, "maxSide": 1000, "exif": pref },
{ "name": "text", "kind": "text", "max": 10 },
{ "name": "place", "kind": "place", "from": "photos", "locate": { "$": "x" } },
{ "name": "here", "kind": "place", "from": "text", "locate": "yes" },
{ "name": "there", "kind": "place", "locate": true },
{ "name": "more", "kind": "photos", "max": 1, "maxBytes": 900000, "maxSide": 1000, "exif": 1 },
{ "name": "card", "kind": "card", "from": "photos" },
]);
let on = "true or false, or a binding {\"$\": path}, on unless false";
assert_eq!(
fields_problems(&fields, "f").0,
[
"f[3].from: names a photos field".to_string(),
format!("f[3].locate: {on}"),
format!("f[5].exif: {on}"),
"f[6].from: names a text field".into(),
]
);
}
#[test]
fn every_field_problem_named() {
assert_eq!(
fields_problems(&json!("x"), "f"),
(
vec!["f: must be an array of 1 to 10 fields".to_string()],
vec![]
)
);
let fields = json!([
"x",
{ "name": "Bad", "kind": "text", "max": 10 },
{ "name": "t", "kind": "text", "facets": "yes" },
{ "name": "t", "kind": "line", "max": 5 },
{ "name": "c", "kind": "card", "from": "nope" },
{ "name": "d", "kind": "card" },
{ "name": "ch", "kind": "choice" },
{ "name": "l", "kind": "labels", "options": [] },
{ "name": "p", "kind": "photos", "min": 5, "max": 2 },
{ "name": "s", "kind": "text", "max": 10, "suggest": { "method": "x" } },
]);
let (out, names) = fields_problems(&fields, "f");
let name = "a name (lowercase letters and digits), once among the fields";
assert_eq!(
out,
[
"f[0]: must be an object".to_string(),
format!("f[1].name: {name}"),
"f[2].facets: true or false".into(),
format!("f[3].name: {name}"),
"f[4].from: names a text field".into(),
"f[5].from: required: the text field whose link it shows".into(),
"f[6].options: required".into(),
"f[7].options: 1 to 8 options, each { label, value, only? }".into(),
"f[8].min: at most max".into(),
"f[8].maxBytes: required".into(),
"f[8].maxSide: required".into(),
"f[9].suggest: { method, service?, param, params? (literals), items, did, handle, name?, avatar? }, paths into its answer".into(),
]
);
assert_eq!(names, ["t", "c", "d", "ch", "l", "p", "s"]);
}
/// The writes of a gallery, a comment and a profile, and of a record
/// with no bundled lexicon, each property a field's value whole.
fn limited_writes() -> Value {
json!([
{ "collection": "social.grain.gallery", "record": { "title": { "$value": "title" }, "description": { "$value": "description" }, "createdAt": { "$now": true } } },
{ "collection": "social.grain.comment", "record": { "text": { "$value": "text" }, "subject": { "$value": "title" } } },
{ "collection": "social.grain.actor.profile", "record": { "displayName": { "$value": "both" } } },
{ "collection": "social.grain.comment", "record": { "text": { "$value": "both" } } },
{ "collection": "com.example.note", "record": { "note": { "$value": "note" } } },
{ "collection": "social.grain.comment", "record": { "$merge": [] } },
])
}
/// A field's limit is its record's lexicon's: a gallery's title 100
/// UTF-8 bytes (`maxLength`, no graphemes), a comment's text 300
/// graphemes and 3000 bytes; written into two, the narrower of each;
/// into a record with no bundled lexicon, or none, nothing.
#[test]
fn a_fields_limit_is_its_records_lexicons() {
let writes = limited_writes();
let of = |name: &str| limit(name, &writes);
let limit = |graphemes, bytes| Limit { graphemes, bytes };
assert_eq!(of("title"), limit(None, Some(100)));
assert_eq!(of("description"), limit(None, Some(1000)));
assert_eq!(of("text"), limit(Some(300), Some(3000)));
assert_eq!(of("both"), limit(Some(64), Some(640)));
assert_eq!(of("note"), Limit::default());
assert_eq!(of("other"), Limit::default());
assert_eq!(super::limit("text", &Value::Null), Limit::default());
}
/// A view's `max` only narrows its lexicon's: one wider than its
/// graphemes, or than its bytes (a grapheme is a byte at least), is
/// refused; and a text or line no lexicon limits needs its own.
#[test]
fn a_max_only_narrows_the_lexicons() {
let fields = json!([
{ "name": "title", "kind": "line" },
{ "name": "description", "kind": "text", "max": 1001 },
{ "name": "text", "kind": "text", "max": 301 },
{ "name": "both", "kind": "line", "max": 64 },
{ "name": "note", "kind": "text" },
{ "name": "other", "kind": "text", "max": 50 },
{ "name": "photos", "kind": "photos", "max": 1 },
{ "name": "title", "kind": "line", "max": 100 },
{ "name": "note", "kind": "line" },
{ "name": "other", "kind": "line", "max": 20 },
]);
assert_eq!(
limit_problems(&fields, &limited_writes()),
[
"fields[1].max: at most its record's lexicon's 1000 bytes",
"fields[2].max: at most its record's lexicon's 300 graphemes",
"fields[4].max: required: no lexicon of a record it is written into limits it",
"fields[8].max: required: no lexicon of a record it is written into limits it",
]
);
assert!(limit_problems(&json!("x"), &Value::Null).is_empty());
}
/// A field as the form asks it carries its limits: `max`, graphemes,
/// the view's narrowed by the lexicon's, and `maxBytes`, the lexicon's
/// UTF-8 bytes; a field of another kind as it was.
#[test]
fn a_field_carries_its_limits() {
let writes = limited_writes();
let made = |f: Value| limited(f, &writes);
assert_eq!(
made(json!({ "name": "title", "kind": "line" })),
json!({ "name": "title", "kind": "line", "maxBytes": 100 })
);
assert_eq!(
made(json!({ "name": "text", "kind": "text" })),
json!({ "name": "text", "kind": "text", "max": 300, "maxBytes": 3000 })
);
assert_eq!(
made(json!({ "name": "text", "kind": "text", "max": 200 })),
json!({ "name": "text", "kind": "text", "max": 200, "maxBytes": 3000 })
);
assert_eq!(
made(json!({ "name": "note", "kind": "text", "max": 10 })),
json!({ "name": "note", "kind": "text", "max": 10 })
);
let photos = json!({ "name": "photos", "kind": "photos", "max": 4, "maxBytes": 900000 });
assert_eq!(made(photos.clone()), photos);
}
}