//! The operator's apps (`HUD_APPS`): a directory of apps HUD serves beside //! its bundled views. Each app is a file at its top named for its domain, //! `.json`: its name, tabs and routes, each tab and route a tool //! call, as the app's clients draw it (they bundle their own copy), how //! its clients register a device for push (`push`), what HUD calls //! after a write of the app's records for its server to read them back at //! once (`refresh`, sent by `Hud::refresh_written`), and the permission //! sets sign-in asks for (`permissions`, `scope::including`). The views are //! `views/.json` beside the apps, each a `place.hud.view`, and the //! lexicons the apps ship, `lexicons/` (`lexicons_of`). A file at //! the top whose name holds no dot (`package.json`) is no app, so the //! directory can be a client's own. An app file may say which HUD //! versions it runs on (`hud`, a semver requirement as `>=0.2.0`), and //! one needing a newer HUD is refused before anything else is checked //! (`version_problem`). It may say the oldest kit its clients' builds //! still draw with (`kits.oldest`): the operator's views are read for what //! that kit would not draw, each a warning (`kit::warnings`). //! //! HUD trusts the operator's views as it does its bundled ones: their //! calls and query joins are sent. So it holds them, as it starts, to //! what the tests hold the bundled ones to, and refuses to start if any //! file falls short, naming every problem (`check`; `hud check` prints //! them): each parsed as a trusted view (its optional keys, `?key`, left //! out where they fall short, with a warning: `view::load`), its calls, //! query joins and profile section against the apps' lexicons and HUD's //! bundled ones (`view::trusted_problems`, `Views::lexicon_docs`), none //! drawing what another draws //! (`view::conflicts`), and each app's tabs and routes calling what a view //! draws, a tab's root chosen from the account's data (`first`) what //! `place.hud.tabFirst` describes, its push calls procedures HUD has //! lexicons for, its frame //! (how its clients' shells draw it) what `place.hud.frame` describes, //! and its pages each what `place.hud.page` does, at a path no other //! screen has, its Markdown's file there, and its sign-in screen //! (`signIn`) what `place.hud.signIn` does (`app_problems`, `pages_of`). //! An operator's view replaces the bundled view of its //! id, and any drawing what it draws (`view::Views::with`); an app's //! lexicon the bundled one of its NSID (`view::Views::lexicon`); an app's push //! calls are sent by `call_procedure` as a trusted view's are //! (`view::Views::with_pushes`); an app with a `signIn` has its web //! clients sent straight on to the account's server //! (`view::Views::sign_ins`); and an app's permission sets are asked for //! first at sign-in (`view::Views::sets`). use crate::catalog::FRAME_ICONS; use crate::scope::Include; use crate::view::{self, Views}; use atproto::lexicon::Lexicons; use serde_json::{Value, json}; use std::collections::BTreeSet; use std::path::{Path, PathBuf}; use std::sync::{Arc, LazyLock}; /// The values a push call's input binds, each `{"$…": true}`, which the /// client stamps as it registers: the device's token, the app's id (its /// bundle id) and its platform (`ios`). pub const PUSH_BINDINGS: [&str; 3] = ["$token", "$appId", "$platform"]; /// The operator's apps, checked: the trusted views with theirs, the apps' /// domains, the operator's views' ids, and what HUD warns of as it loads /// them (a view's optional keys it leaves out, `view::load`). #[derive(Debug)] pub struct Loaded { pub views: Views, pub apps: Vec, pub ids: Vec, pub warnings: Vec, } /// This HUD's version, which an app file's `hud` is held to. pub const VERSION: &str = env!("CARGO_PKG_VERSION"); /// A file's text, or why it can't be read, naming it. fn read(path: &Path) -> Result { std::fs::read_to_string(path).map_err(|e| format!("{}: {e}", path.display())) } /// A JSON file's document, or why it can't be read, naming it. fn read_json(path: &Path) -> Result { let text = read(path)?; serde_json::from_str(&text).map_err(|e| format!("{}: {e}", path.display())) } /// The `.json` files directly in `dir`, sorted, each with its name before /// `.json`; none where `dir` is no directory. fn json_files(dir: &Path) -> Vec<(String, PathBuf)> { let mut out: Vec<(String, PathBuf)> = std::fs::read_dir(dir) .into_iter() .flatten() .flatten() .map(|e| e.path()) .filter(|p| p.is_file() && p.extension().is_some_and(|x| x == "json")) .filter_map(|p| Some((p.file_stem()?.to_str()?.to_string(), p))) .collect(); out.sort(); out } /// The operator's apps in `dir`, checked against the lexicons they ship /// and HUD's and, with `bundled`, beside the bundled views, which they /// replace and add to; else alone, as an instance serving its operator's /// apps alone (no workspace) serves them. Or every problem, each naming /// its file and where in it. pub fn load(dir: &Path, bundled: bool) -> Result> { let version = semver::Version::parse(VERSION).expect("HUD's version is semver"); load_as(dir, bundled, &version) } /// `load`, as the HUD of `version`. fn load_as(dir: &Path, bundled: bool, version: &semver::Version) -> Result> { if let Err(e) = std::fs::read_dir(dir) { return Err(vec![format!("{}: {e}", dir.display())]); } let apps: Vec<(String, PathBuf)> = json_files(dir) .into_iter() .filter(|(name, _)| name.contains('.')) .collect(); let files = json_files(&dir.join("views")); if apps.is_empty() && files.is_empty() { return Err(vec![format!( "{}: no app (.json) and no view (views/.json)", dir.display() )]); } let mut problems = Vec::new(); let mut docs = Vec::new(); for (domain, path) in &apps { match read_json(path) { Ok(doc) => docs.push((domain, path.display().to_string(), doc)), Err(e) => problems.push(e), } } // An app needing a newer HUD is all there is to say: the rest of it // is written for that HUD. let newer: Vec = docs .iter() .filter_map(|(_, file, doc)| Some(format!("{file}: {}", version_problem(doc, version)?))) .collect(); if !newer.is_empty() { return Err(newer); } let (lexicons, wrong) = lexicons_of(&dir.join("lexicons")); problems.extend(wrong); let mut texts = Vec::new(); for (id, path) in &files { match read(path) { Ok(text) => texts.push((id, path.display().to_string(), text)), Err(e) => problems.push(e), } } let built = match bundled { true => Views::built_in(), false => Views::none(), }; let view_docs: Vec = texts .iter() .filter_map(|(_, _, text)| serde_json::from_str(text).ok()) .collect(); let mut services = view::services_of(&view_docs); services.extend_from_slice(built.services()); let (mut added, mut warnings) = (Vec::new(), Vec::new()); for (id, file, text) in texts { match view::load(file, id, &text, &services) { Ok((b, left_out)) => { added.push(b); warnings.extend(left_out); } Err(wrong) => problems.extend(wrong), } } let ids: Vec = added.iter().map(|b| b.id.clone()).collect(); let views = built.with(added).with_lexicons(lexicons); problems.extend(view::conflicts(views.all())); let lexicons = views.lexicon_docs(); for b in views.all().iter().filter(|b| ids.contains(&b.id)) { let wrong = view::trusted_problems(&b.view, &lexicons, &views); problems.extend(wrong.into_iter().map(|p| format!("{}: {p}", b.file))); } // An app's own collections, whose writes its `refresh` is called for: // those the operator's views write, or plan to delete. let mut own = views.written_by(&|b| ids.contains(&b.id)); let operators = views.all().iter().filter(|b| ids.contains(&b.id)); own.extend( operators .flat_map(|b| &b.view.plans) .flat_map(|p| p.collections.iter().cloned()), ); let (mut pushes, mut refreshes, mut pages) = (Vec::new(), Vec::new(), Vec::new()); let (mut sign_ins, mut sets) = (Vec::new(), Vec::new()); for (domain, file, doc) in &docs { let wrong = app_problems(doc, domain, &views); if !wrong.is_empty() { problems.extend(wrong.iter().map(|p| format!("{file}: {p}"))); continue; } pushes.extend(push_calls(doc)); refreshes.extend(refresh_of(doc, &own)); sets.extend(sets_of(doc)); match pages_of(doc, domain, dir) { Ok(found) => pages.extend(found), Err(e) => problems.push(format!("{file}: {e}")), } if doc.get("signIn").is_some() { sign_ins.push(domain.to_string()); } } if !problems.is_empty() { return Err(problems); } // What the oldest kit the apps serve would not draw, where they say. if let Some(oldest) = docs.iter().filter_map(|(_, _, doc)| oldest_kit(doc)).min() { for b in views.all().iter().filter(|b| ids.contains(&b.id)) { warnings.extend(crate::kit::warnings(&b.file, &b.view.doc, &oldest)); } } let apps = apps.into_iter().map(|(domain, _)| domain).collect(); let views = views .with_pushes(pushes) .with_refreshes(refreshes) .with_pages(pages) .with_sign_ins(sign_ins) .with_sets(sets); Ok(Loaded { views, apps, ids, warnings, }) } /// The oldest kit an app file's clients serve (`kits.oldest`), where it /// says. fn oldest_kit(doc: &Value) -> Option { semver::Version::parse(doc["kits"]["oldest"].as_str()?).ok() } /// What is wrong with an app file's `kits`: `{ oldest }`, the oldest kit /// (a HUD version, no older than `kit::OLDEST`) its clients still serve, /// which `hud check` holds its views to (`kit::warnings`). fn kits_problems(kits: &Value, out: &mut Vec) { let first = semver::Version::parse(crate::kit::OLDEST).expect("the oldest kit is semver"); let one = kits.as_object().is_some_and(|o| o.len() == 1); if !one || oldest_kit(&json!({ "kits": kits })).is_none_or(|v| v < first) { out.push(format!( "app.kits: must be {{ oldest }}, the oldest kit its clients still serve, a HUD version from {first}, as \"{first}\"" )); } } /// What is wrong with an app file's `hud`, the HUD versions it runs on, a /// semver requirement (`>=0.2.0`), for the HUD of `version`: one that is no /// requirement, or that this HUD doesn't meet. None where it names none. fn version_problem(doc: &Value, version: &semver::Version) -> Option { let need = doc.get("hud")?; let Some(req) = need .as_str() .and_then(|s| semver::VersionReq::parse(s).ok()) else { return Some("app.hud: must be the HUD versions the app runs on, as \">=0.2.0\"".into()); }; (!req.matches(version)).then(|| { format!("app.hud: the app needs HUD {req}, and this HUD is {version}: run a newer HUD") }) } /// The lexicons the operator's apps ship (`lexicons/`, `.json` files at /// any depth), each a lexicon document (`lexicon: 1`, its `id` an NSID, /// `defs`), one file of each NSID, none of HUD's own (`place.hud.*`); and /// what is wrong with the others, naming their files. HUD reads an app's /// lexicon in place of the bundled one of its NSID: its views were written /// against it. fn lexicons_of(dir: &Path) -> (Vec>, Vec) { let mut paths = Vec::new(); json_tree(dir, &mut paths); paths.sort(); let (mut docs, mut problems) = (Vec::>::new(), Vec::new()); for path in paths { let doc = match read_json(&path) { Ok(doc) => doc, Err(e) => { problems.push(e); continue; } }; let file = path.display(); let id = doc["id"].as_str().unwrap_or_default().to_string(); if !atproto::syntax::is_nsid(&id) || !crate::lexicon::is_document(&doc, &id) { problems.push(format!( "{file}: must be a lexicon document: lexicon 1, an NSID as its id, and defs" )); } else if id.starts_with("place.hud.") { problems.push(format!( "{file}: {id} is HUD's own lexicon, which no app ships" )); } else if docs.iter().any(|d| d["id"] == id.as_str()) { problems.push(format!("{file}: another file is {id} too")); } else { docs.push(Arc::new(doc)); } } (docs, problems) } /// Add to `out` the `.json` files under `dir`, at any depth; none where /// `dir` is no directory. fn json_tree(dir: &Path, out: &mut Vec) { let entries = std::fs::read_dir(dir).into_iter().flatten().flatten(); for path in entries.map(|e| e.path()) { if path.is_dir() { json_tree(&path, out); } else if path.extension().is_some_and(|x| x == "json") { out.push(path); } } } /// What is wrong with the app file of `domain`, as HUD reads it: an object /// naming its domain and its name, with one or more tabs, each a label and /// a call (and signed out, `guest`: another call, or "call" for the same; /// signed in, `first`, if any, `first_problems`), /// and routes, each a path, a call and the label of the tab it opens /// under, if any; each call drawing what a view among `views` draws; its /// `push`, if any (`push_problems`); its `head`, if any /// (`head_problems`); its `frame`, if any (`frame_problems`); its /// `pages`, if any (`pages_problems`); its `signIn`, if any /// (`sign_in_problems`); and its `permissions`, if any /// (`permissions_problems`). The /// rest (its look, a tab's icon and badge) is its clients' alone. pub fn app_problems(doc: &Value, domain: &str, views: &Views) -> Vec { let Some(o) = doc.as_object() else { return vec!["app: must be an object".into()]; }; let mut out = Vec::new(); if o.get("domain").and_then(Value::as_str) != Some(domain) { out.push(format!( "app.domain: must be {domain}, as its file is named" )); } if !o .get("name") .and_then(Value::as_str) .is_some_and(|n| !n.trim().is_empty()) { out.push("app.name: required".into()); } let tabs = o.get("tabs").and_then(Value::as_array); let tabs = tabs.map(Vec::as_slice).unwrap_or_default(); if tabs.is_empty() { out.push("app.tabs: must be a list of one or more tabs".into()); } let mut labels = Vec::new(); for (i, t) in tabs.iter().enumerate() { let at = format!("app.tabs[{i}]"); match t["label"].as_str() { Some(l) => labels.push(l), None => out.push(format!("{at}.label: required")), } drawn(&t["call"], &format!("{at}.call"), views, &mut out); if !t["guest"].is_null() && t["guest"] != "call" { drawn(&t["guest"], &format!("{at}.guest"), views, &mut out); } if let Some(first) = t.get("first") { first_problems(first, &format!("{at}.first"), &mut out); } } let routes = match o.get("routes") { None => &[][..], Some(Value::Array(r)) => r.as_slice(), Some(_) => { out.push("app.routes: must be a list of routes".into()); &[] } }; for (i, r) in routes.iter().enumerate() { let at = format!("app.routes[{i}]"); if !r["path"].as_str().is_some_and(|p| p.starts_with('/')) { out.push(format!("{at}.path: must be a path, starting with /")); } drawn(&r["call"], &format!("{at}.call"), views, &mut out); if !r["tab"].is_null() && !r["tab"].as_str().is_some_and(|t| labels.contains(&t)) { out.push(format!("{at}.tab: must be a tab's label")); } pager_problems(r, &at, routes, &mut out); } if let Some(push) = o.get("push") { push_problems(push, routes, views, &mut out); } if let Some(refresh) = o.get("refresh") { refresh_problems(refresh, &mut out); } if let Some(permissions) = o.get("permissions") { permissions_problems(permissions, &mut out); } if let Some(head) = o.get("head") { head_problems(head, &mut out); } if let Some(frame) = o.get("frame") { frame_problems(frame, &labels, views, &mut out); } if let Some(pages) = o.get("pages") { pages_problems(pages, tabs, routes, &mut out); } if let Some(sign_in) = o.get("signIn") { sign_in_problems(sign_in, &mut out); } if let Some(kits) = o.get("kits") { kits_problems(kits, &mut out); } out } /// The lexicon of a tab's `first`. const TAB_FIRST: &str = "place.hud.tabFirst"; /// The lexicon document of a tab's `first`, and its validator. static TAB_FIRST_LEXICON: LazyLock<(Arc, Lexicons)> = LazyLock::new(|| { let doc = crate::lexicon::bundled(TAB_FIRST).expect("schemas/place.hud.tabFirst.json is bundled"); let lexicons = Lexicons::new([(*doc).clone()]); (doc, lexicons) }); /// What is wrong with a tab's `first`, at `at`: where its clients choose /// its root from the account's data, signed in (Grain's Home, the first /// feed pinned). It must be what its lexicon (`place.hud.tabFirst`) /// describes, with no key it does not name; its call a query of a /// method's NSID (its answer is data, as a badge's is); its `at` and /// `path` dotted paths, no segment empty. Whether a listed path has a /// screen is the clients' to find, item by item, by the app's routes. fn first_problems(first: &Value, at: &str, out: &mut Vec) { let (doc, lexicons) = &*TAB_FIRST_LEXICON; unknown(&doc["defs"], "main", first, at, out); if let Err(e) = lexicons.validate(TAB_FIRST, first) { let rest = e.path.strip_prefix("object").unwrap_or(&e.path); out.push(format!("{at}{rest} {}", e.message)); return; } let call = &first["call"]; let method = call["args"]["method"].as_str().unwrap_or_default(); if call["name"] != "query" || !atproto::syntax::is_nsid(method) { out.push(format!("{at}.call: must be a query of a method's NSID")); } for key in ["at", "path"] { let path = first[key].as_str().unwrap_or_default(); if path.split('.').any(str::is_empty) { out.push(format!( "{at}.{key}: must be a dotted path, no segment empty" )); } } } /// The pages' lexicon, one page's. const PAGE: &str = "place.hud.page"; /// The page's lexicon document, and its validator. static PAGE_LEXICON: LazyLock<(Arc, Lexicons)> = LazyLock::new(|| { let doc = crate::lexicon::bundled(PAGE).expect("schemas/place.hud.page.json is bundled"); let lexicons = Lexicons::new([(*doc).clone()]); (doc, lexicons) }); /// The most pages an app file has. pub(crate) const PAGES: usize = 64; /// What is wrong with an app file's `pages`, its own pages: a list of at /// most `PAGES`, each what its lexicon (`place.hud.page`) describes, with /// no key it does not name; its `path` a plain path (`plain_path`) that no /// other page, no tab's `path` and no route's (`shadowed`) is; its /// `markdown` a `.md` file's path within the app file's directory, /// relative, never climbing out (`..`). Whether the file is there is /// `pages_of`'s to say. fn pages_problems(pages: &Value, tabs: &[Value], routes: &[Value], out: &mut Vec) { let Some(pages) = pages.as_array().filter(|p| p.len() <= PAGES) else { out.push(format!( "app.pages: must be a list of at most {PAGES} pages" )); return; }; let (doc, lexicons) = &*PAGE_LEXICON; let mut paths = Vec::new(); for (i, page) in pages.iter().enumerate() { let at = format!("app.pages[{i}]"); unknown(&doc["defs"], "main", page, &at, out); if let Err(e) = lexicons.validate(PAGE, page) { let rest = e.path.strip_prefix("object").unwrap_or(&e.path); out.push(format!("{at}{rest} {}", e.message)); continue; } let path = page["path"].as_str().unwrap_or_default(); let tab = tabs.iter().any(|t| t["path"] == path); if !plain_path(path) { out.push(format!( "{at}.path: must be a plain path, /segments of a-z, 0-9, - _ and ., no query or token" )); } else if paths.contains(&path) { out.push(format!("{at}.path: another page's too")); } else if tab || shadowed(path, routes) { out.push(format!("{at}.path: a tab's or a route's too")); } paths.push(path); let file = page["markdown"].as_str().unwrap_or_default(); let within = !file.starts_with('/') && !file.split(['/', '\\']).any(|s| s == ".."); if !within || !file.ends_with(".md") { out.push(format!( "{at}.markdown: must be a .md file's path within the app file's directory" )); } } } /// Whether `path` is a plain path: `/` and segments of lower-case ASCII /// letters, digits, `-`, `_` and `.`, none empty, `.` or `..`. fn plain_path(path: &str) -> bool { let ok = |b: u8| b.is_ascii_lowercase() || b.is_ascii_digit() || b"-_.".contains(&b); path.strip_prefix('/').is_some_and(|rest| { rest.split('/') .all(|s| !s.trim_matches('.').is_empty() && s.bytes().all(ok)) }) } /// Whether a route among `routes` has the plain path `path`, its tokens /// any segment, its query string aside. fn shadowed(path: &str, routes: &[Value]) -> bool { let want: Vec<&str> = path.split('/').collect(); let route = |r: &str| { let have: Vec<&str> = r.split('?').next().unwrap_or_default().split('/').collect(); have.len() == want.len() && have .iter() .zip(&want) .all(|(h, w)| h == w || (h.starts_with('{') && h.ends_with('}'))) }; routes.iter().filter_map(|r| r["path"].as_str()).any(route) } /// The pages of the app file `doc` of `domain`, checked by /// `pages_problems`, each read from its Markdown's file in `dir`, the app /// file's own, into blocks (`ui::page_blocks`); or why a file can't be /// read, naming it. fn pages_of(doc: &Value, domain: &str, dir: &Path) -> Result, String> { let pages = doc["pages"] .as_array() .map(Vec::as_slice) .unwrap_or_default(); let app = doc["name"].as_str().unwrap_or_default(); let mut out = Vec::new(); for (i, p) in pages.iter().enumerate() { let text = |k: &str| p[k].as_str().unwrap_or_default().to_string(); let found = read(&dir.join(text("markdown"))); let markdown = found.map_err(|e| format!("app.pages[{i}].markdown: {e}"))?; out.push(view::Page { domain: domain.to_string(), app: app.to_string(), path: text("path"), title: text("title"), description: p["description"].as_str().map(str::to_string), blocks: crate::ui::page_blocks(&markdown, domain), markdown, }); } Ok(out) } /// The frame's lexicon. const FRAME: &str = "place.hud.frame"; /// The frame's lexicon document, and its validator. static FRAME_LEXICON: LazyLock<(Arc, Lexicons)> = LazyLock::new(|| { let doc = crate::lexicon::bundled(FRAME).expect("schemas/place.hud.frame.json is bundled"); let lexicons = Lexicons::new([(*doc).clone()]); (doc, lexicons) }); /// What is wrong with an app file's `frame`: how its clients' shells draw /// the app around its screens. It must be what its lexicon /// (`place.hud.frame`) describes, with no key it does not name at any /// level; then `destinations`, if any, `tabs`; each call drawn by a view /// among `views` (the account's picture's a query, as a badge's is: it is /// data); the picture's `tab` one of the tabs' `labels` and its `at`, /// `name` and `handle` dotted paths (the last two, where given, the /// account's name and handle in the same answer, for its accounts' rows); /// each icon one of `catalog::FRAME_ICONS`; each of the /// account's items a screen (a label, an icon and a call) or one the host /// draws (`host`, signOut or signIn, at most one of each, `about` signIn's /// alone); each link's `href` a path or an https URL; `sizes.wide` no /// narrower than `sizes.content`, and `bands.sidebar` wider than /// `bands.rail`, either left out its lexicon's default. fn frame_problems(frame: &Value, labels: &[&str], views: &Views, out: &mut Vec) { let (doc, lexicons) = &*FRAME_LEXICON; let defs = &doc["defs"]; unknown(defs, "main", frame, "app.frame", out); if let Err(e) = lexicons.validate(FRAME, frame) { let rest = e.path.strip_prefix("object").unwrap_or(&e.path); out.push(format!("app.frame{rest} {}", e.message)); return; } if frame.get("destinations").is_some_and(|d| d != "tabs") { out.push("app.frame.destinations: must be \"tabs\", the app's tabs".into()); } if let Some(action) = frame.get("action") { icon(&action["icon"], "app.frame.action.icon", out); drawn(&action["call"], "app.frame.action.call", views, out); } let account = &frame["account"]; if let Some(picture) = account.get("picture") { let at = "app.frame.account.picture"; if !picture["tab"].as_str().is_some_and(|t| labels.contains(&t)) { out.push(format!("{at}.tab: must be a tab's label")); } let call = &picture["call"]; let method = call["args"]["method"].as_str().unwrap_or_default(); if call["name"] != "query" || !atproto::syntax::is_nsid(method) { out.push(format!("{at}.call: must be a query of a method's NSID")); } for key in ["at", "name", "handle"] { let path = picture.get(key).map_or(Some("given"), Value::as_str); if path.unwrap_or_default().split('.').any(str::is_empty) { out.push(format!( "{at}.{key}: must be a dotted path, no segment empty" )); } } } let items = account["items"].as_array().map(Vec::as_slice); let mut hosts = Vec::new(); for (i, item) in items.unwrap_or_default().iter().enumerate() { let at = format!("app.frame.account.items[{i}]"); icon(&item["icon"], &format!("{at}.icon"), out); match (item.get("call"), item["host"].as_str()) { (Some(call), None) => { for k in ["label", "icon"] .into_iter() .filter(|k| item.get(k).is_none()) { out.push(format!("{at}.{k}: required with a call")); } drawn(call, &format!("{at}.call"), views, out); } (None, Some(host @ ("signOut" | "signIn"))) if hosts.contains(&host) => { out.push(format!("{at}.host: at most one {host} item")); } (None, Some(host @ ("signOut" | "signIn"))) => hosts.push(host), (None, Some(_)) => out.push(format!("{at}.host: must be signOut or signIn")), (Some(_), Some(_)) => out.push(format!("{at}: takes a call or a host, not both")), (None, None) => out.push(format!("{at}: needs a call or a host")), } if item.get("about").is_some() && item["host"] != "signIn" { out.push(format!("{at}.about: a signIn item's alone")); } } let links = frame["links"].as_array().map(Vec::as_slice); for (i, link) in links.unwrap_or_default().iter().enumerate() { if !linkable(link["href"].as_str().unwrap_or_default()) { out.push(format!( "app.frame.links[{i}].href: must be a path starting with / or an https URL" )); } } if let Some(aside) = frame.get("aside") { drawn(&aside["call"], "app.frame.aside.call", views, out); } let size = |def: &str, k: &str| { let given = frame[def][k].as_i64(); given.or(defs[def]["properties"][k]["default"].as_i64()) }; let (content, wide) = (size("sizes", "content"), size("sizes", "wide")); if wide < content { out.push(format!( "app.frame.sizes.wide: must be no narrower than content ({})", content.unwrap_or_default() )); } let (rail, sidebar) = (size("bands", "rail"), size("bands", "sidebar")); if sidebar <= rail { out.push(format!( "app.frame.bands.sidebar: must be wider than rail ({})", rail.unwrap_or_default() )); } } /// Whether `href` is a path of the app's own site (starting with `/`, not /// `//`) or an https URL: where a link of an app file's may go. fn linkable(href: &str) -> bool { let https = url::Url::parse(href).is_ok_and(|u| u.scheme() == "https" && u.host().is_some()); let path = href.starts_with('/') && !href.starts_with("//"); path || https } /// The sign-in screen's lexicon. const SIGN_IN: &str = "place.hud.signIn"; /// The sign-in screen's lexicon document, and its validator. static SIGN_IN_LEXICON: LazyLock<(Arc, Lexicons)> = LazyLock::new(|| { let doc = crate::lexicon::bundled(SIGN_IN).expect("schemas/place.hud.signIn.json is bundled"); let lexicons = Lexicons::new([(*doc).clone()]); (doc, lexicons) }); /// The hrefs of the Markdown links (`[label](href)`) in `text`. fn hrefs(text: &str) -> impl Iterator { let after = text.split("](").skip(1); after.map(|rest| rest.split(')').next().unwrap_or_default()) } /// What is wrong with an app file's `signIn`: what its clients' own /// sign-in screen says, and where it finds accounts as a handle is typed. /// It must be what its lexicon (`place.hud.signIn`) describes, with no key /// it does not name at any level; each link in its `text` and `legal` /// (`[label](href)`) a path or an https URL; its typeahead's `url` an /// https origin (no path, query or fragment), its `params` an object of /// strings, numbers and booleans, and its paths dotted, no segment empty. fn sign_in_problems(sign_in: &Value, out: &mut Vec) { let (doc, lexicons) = &*SIGN_IN_LEXICON; unknown(&doc["defs"], "main", sign_in, "app.signIn", out); if let Err(e) = lexicons.validate(SIGN_IN, sign_in) { let rest = e.path.strip_prefix("object").unwrap_or(&e.path); out.push(format!("app.signIn{rest} {}", e.message)); return; } for key in ["text", "legal"] { let text = sign_in[key].as_str().unwrap_or_default(); if !hrefs(text).all(linkable) { out.push(format!( "app.signIn.{key}: each link must go to a path starting with / or an https URL" )); } } let Some(typeahead) = sign_in.get("typeahead") else { return; }; let at = "app.signIn.typeahead"; let url = url::Url::parse(typeahead["url"].as_str().unwrap_or_default()); let origin = url.is_ok_and(|u| { let bare = u.path() == "/" && u.query().is_none() && u.fragment().is_none(); u.scheme() == "https" && u.host().is_some() && u.username().is_empty() && bare }); if !origin { out.push(format!( "{at}.url: must be an https origin, as https://typeahead.waow.tech" )); } let scalar = |v: &Value| v.is_string() || v.is_number() || v.is_boolean(); let params = typeahead.get("params").map(Value::as_object); if params.is_some_and(|p| !p.is_some_and(|p| p.values().all(scalar))) { out.push(format!( "{at}.params: must be an object of strings, numbers and booleans" )); } for key in ["items", "did", "handle", "name", "avatar", "avatarFallback"] { let path = typeahead.get(key).map_or(Some("given"), Value::as_str); if path.unwrap_or_default().split('.').any(str::is_empty) { out.push(format!( "{at}.{key}: must be a dotted path, no segment empty" )); } } } /// Add to `out` the keys of `value` that the def `def` among the frame's /// lexicon's `defs` does not name, and those of the objects it holds, /// wherever they are, `at` saying where. fn unknown(defs: &Value, def: &str, value: &Value, at: &str, out: &mut Vec) { let Some(o) = value.as_object() else { return; }; for (k, v) in o { let p = &defs[def]["properties"][k.as_str()]; let of = p["ref"].as_str().or(p["items"]["ref"].as_str()); let of = of.map(|r| r.trim_start_matches('#')); match (p["type"].as_str(), of) { (None, _) => out.push(format!("{at}: unknown key \"{k}\"")), (Some("ref"), Some(r)) => unknown(defs, r, v, &format!("{at}.{k}"), out), (Some("array"), Some(r)) => { let each = v.as_array().map(Vec::as_slice).unwrap_or_default(); for (i, e) in each.iter().enumerate() { unknown(defs, r, e, &format!("{at}.{k}[{i}]"), out); } } _ => {} } } } /// Add to `out`, at `at`, that `v` is an icon no shell draws: none of /// `catalog::FRAME_ICONS`. fn icon(v: &Value, at: &str, out: &mut Vec) { if v.as_str().is_some_and(|i| !FRAME_ICONS.contains(&i)) { out.push(format!("{at}: must be one of catalog::FRAME_ICONS")); } } /// What an app file's `head` may say. pub(crate) const HEAD: [&str; 6] = [ "siteName", "title", "description", "image", "imageAlt", "twitter", ]; /// The most characters a text of an app file's `head` takes. pub(crate) const HEAD_TEXT: usize = 300; /// What is wrong with an app file's `head`: what a page of the app says in /// its HTML head where its view's head (`_meta.ui.head`) says nothing. Its /// site's name (`siteName`, required), the title and description of a page /// with none, each text of 1 to 300 characters; a picture, an absolute /// https URL, and its alt text; its X account (`twitter`), as `@name`. fn head_problems(head: &Value, out: &mut Vec) { let Some(o) = head.as_object() else { out.push("app.head: must be an object".into()); return; }; for k in o.keys().filter(|k| !HEAD.contains(&k.as_str())) { out.push(format!("app.head: unknown key \"{k}\"")); } if !o.contains_key("siteName") { out.push("app.head.siteName: required".into()); } let text = |v: &Value| { v.as_str() .is_some_and(|s| !s.trim().is_empty() && s.chars().count() <= HEAD_TEXT) }; for k in ["siteName", "title", "description", "imageAlt"] { if o.get(k).is_some_and(|v| !text(v)) { out.push(format!( "app.head.{k}: must be text of 1 to {HEAD_TEXT} characters" )); } } let https = |v: &Value| { v.as_str() .and_then(|s| url::Url::parse(s).ok()) .is_some_and(|u| u.scheme() == "https" && u.host().is_some()) }; if o.get("image").is_some_and(|v| !https(v)) { out.push("app.head.image: must be an https URL".into()); } let account = |v: &Value| { v.as_str() .and_then(|s| s.strip_prefix('@')) .is_some_and(|n| { (1..=15).contains(&n.len()) && n.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_') }) }; if o.get("twitter").is_some_and(|v| !account(v)) { out.push("app.head.twitter: must be an account, as @name".into()); } } /// The procedure call an app file's `push.register` or `push.unregister` /// is: its method, its service and its input, a template of /// `PUSH_BINDINGS`. fn call_of(c: &Value) -> view::Call { let text = |k: &str| c[k].as_str().unwrap_or_default().to_string(); view::Call { method: text("method"), service: text("service"), input: c["input"].clone(), deletes: false, } } /// The calls an app file, checked, makes for push: its `register` and /// `unregister`; none where it declares no push. fn push_calls(doc: &Value) -> Vec { let push = &doc["push"]; ["register", "unregister"] .into_iter() .filter(|k| push[k].is_object()) .map(|k| call_of(&push[k])) .collect() } /// An app file's `refresh`, checked, called after a write of one of /// `collections`; none where it names none. fn refresh_of(doc: &Value, collections: &BTreeSet) -> Option { let r = doc.get("refresh")?; Some(view::Refresh { method: r["method"].as_str().unwrap_or_default().to_string(), service: r["service"].as_str().unwrap_or_default().to_string(), collections: collections.clone(), }) } /// Add to `out` what is wrong with an app file's `refresh`: an object /// naming a procedure's `method` and the `service` it is of, and nothing /// else. HUD sends it `{"uris": [...]}`, the records just /// written, so it needs no lexicon bundled. fn refresh_problems(refresh: &Value, out: &mut Vec) { let Some(o) = refresh.as_object() else { out.push("app.refresh: must be an object, a procedure's method and service".into()); return; }; let method = o.get("method").and_then(Value::as_str).unwrap_or_default(); if !atproto::syntax::is_nsid(method) { out.push("app.refresh.method: must be a method's NSID".into()); } let service = o.get("service").and_then(Value::as_str).unwrap_or_default(); if let Err(why) = crate::xrpc::Service::parse(service) { out.push(format!("app.refresh.service: {why}")); } for k in o .keys() .filter(|k| !["method", "service"].contains(&k.as_str())) { out.push(format!("app.refresh.{k}: not a field of it")); } } /// The most permission sets an app file names. pub(crate) const SETS: usize = 8; /// The permission sets an app file, checked, names: what sign-in asks for /// first (`scope::including`); none where it names none. fn sets_of(doc: &Value) -> Vec { let named = doc["permissions"].as_array().map_or(&[][..], Vec::as_slice); let set = |p: &Value| Include { nsid: p["include"].as_str().unwrap_or_default().to_string(), service: p["service"].as_str().map(str::to_string), }; named.iter().map(set).collect() } /// Add to `out` what is wrong with an app file's `permissions`: a list of /// 1 to `SETS` permission sets, each an object naming the set's NSID /// (`include`) and, where its methods are called at a service, that /// service (`service`), whose audience its `rpc` permissions inherit; and /// nothing else. What each grants is the set's to say, as the account's /// server resolves it: checked against the views as HUD starts /// (`Hud::sets_ungranted`). fn permissions_problems(permissions: &Value, out: &mut Vec) { let named = permissions.as_array(); let Some(named) = named.filter(|n| (1..=SETS).contains(&n.len())) else { out.push(format!( "app.permissions: must be a list of 1 to {SETS} permission sets" )); return; }; for (i, p) in named.iter().enumerate() { let at = format!("app.permissions[{i}]"); let Some(o) = p.as_object() else { out.push(format!( "{at}: must be an object, a set's include and service" )); continue; }; let nsid = o.get("include").and_then(Value::as_str); if !nsid.is_some_and(atproto::syntax::is_nsid) { out.push(format!("{at}.include: must be a permission set's NSID")); } if let Some(s) = o.get("service") && let Err(why) = crate::xrpc::Service::parse(s.as_str().unwrap_or_default()) { out.push(format!("{at}.service: {why}")); } for k in o .keys() .filter(|k| !["include", "service"].contains(&k.as_str())) { out.push(format!("{at}.{k}: not a field of it")); } } } /// Add to `out` what is wrong with an app file's `push`: `register` and /// `unregister` each a procedure HUD has a lexicon of (an app's own or a /// bundled one, `Views::lexicon_docs`), of a service, /// its input what the lexicon takes and requires, binding the device's /// token and nothing but `PUSH_BINDINGS`; and `open`, if any, a list of /// what a tapped notification opens, each `when` (the payload's fields, as /// patterns of `{token}`s) and the `path` of one of the app's `routes` /// those tokens fill. fn push_problems(push: &Value, routes: &[Value], views: &Views, out: &mut Vec) { let Some(o) = push.as_object() else { out.push("app.push: must be an object".into()); return; }; let lexicons = views.lexicon_docs(); for k in ["register", "unregister"] { let at = format!("app.push.{k}"); let Some(c) = o.get(k).filter(|c| c.is_object()) else { out.push(format!( "{at}: required, a procedure's method, service and input" )); continue; }; let call = call_of(c); if !atproto::syntax::is_nsid(&call.method) { out.push(format!("{at}.method: must be a method's NSID")); continue; } if let Err(why) = crate::xrpc::Service::parse(&call.service) { out.push(format!("{at}.service: {why}")); } let problems = view::call_problems(&call, &lexicons); out.extend(problems.into_iter().map(|p| format!("{at}: {p}"))); let mut bound = Vec::new(); bindings(&call.input, &format!("{at}.input"), &mut bound, out); if !bound.contains(&"$token") { out.push(format!( "{at}.input: must hold the device's token, {{\"$token\": true}}" )); } } let open = match o.get("open") { None => &[][..], Some(Value::Array(open)) => open.as_slice(), Some(_) => { out.push("app.push.open: must be a list of what a notification opens".into()); &[] } }; for (i, e) in open.iter().enumerate() { opening_problems(e, &format!("app.push.open[{i}]"), routes, out); } } /// Add to `out` the bindings of an input template that are no /// `PUSH_BINDINGS`, and to `bound` those that are. fn bindings(v: &Value, at: &str, bound: &mut Vec<&'static str>, out: &mut Vec) { match v { Value::Object(o) => { for (k, x) in o.iter().filter(|(k, _)| k.starts_with('$')) { match PUSH_BINDINGS.into_iter().find(|b| b == k) { Some(b) if o.len() == 1 && *x == Value::Bool(true) => bound.push(b), _ => out.push(format!( "{at}: {k} is no binding of a push call, which binds {{\"$token\": true}}, {{\"$appId\": true}} and {{\"$platform\": true}}" )), } } for (k, x) in o.iter().filter(|(k, _)| !k.starts_with('$')) { bindings(x, &format!("{at}.{k}"), bound, out); } } Value::Array(a) => { for (i, x) in a.iter().enumerate() { bindings(x, &format!("{at}[{i}]"), bound, out); } } _ => {} } } /// The `{token}`s a pattern names, as routes write them (`{actor}`, /// `{actor:did}`), by name. fn tokens(pattern: &str) -> Vec<&str> { pattern .split('{') .skip(1) .filter_map(|piece| piece.split_once('}')) .map(|(token, _)| token.split(':').next().unwrap_or_default()) .collect() } /// Add to `out` what is wrong with route `r`'s `pager` and `under`, at /// `at`: `pager` is true where its screen is a story, opened as the one /// page of the clients' stories pager over where it is opened from; its /// `under`, a route's path whose tokens its own path binds, is the screen /// under it where its URL is loaded (a story's account's profile). fn pager_problems(r: &Value, at: &str, routes: &[Value], out: &mut Vec) { if !r["pager"].is_null() && r["pager"] != true { out.push(format!("{at}.pager: must be true")); } let Some(under) = r.get("under") else { return; }; let Some(path) = under.as_str().filter(|p| p.starts_with('/')) else { return out.push(format!("{at}.under: must be a path, starting with /")); }; if r["pager"] != true { out.push(format!("{at}.under: only a pager's route has one")); } let own = tokens(r["path"].as_str().unwrap_or_default()); for t in tokens(path).into_iter().filter(|t| !own.contains(t)) { out.push(format!("{at}.under: {{{t}}} is in no token of its path")); } if !routed(path, routes) { out.push(format!("{at}.under: no route's path is {path}")); } } /// Whether the path `open` (its tokens any segment) is the path of a /// route among `routes`, segment by segment, their query strings aside. fn routed(open: &str, routes: &[Value]) -> bool { let segments = |p: &str| -> Vec { let path = p.split('?').next().unwrap_or_default(); path.split('/').map(str::to_string).collect() }; let token = |s: &str| s.starts_with('{') && s.ends_with('}'); let want = segments(open); routes.iter().filter_map(|r| r["path"].as_str()).any(|r| { let have = segments(r); have.len() == want.len() && have .iter() .zip(&want) .all(|(h, w)| h == w || (token(h) && token(w))) }) } /// Add to `out` what is wrong with one of `push.open`, at `at`: `when`, an /// object of one or more of the payload's fields, each a pattern; and /// `path`, a route's path whose tokens `when` binds. fn opening_problems(e: &Value, at: &str, routes: &[Value], out: &mut Vec) { let when = e["when"].as_object(); let patterns: Vec<&str> = when .into_iter() .flatten() .filter_map(|(_, p)| p.as_str()) .collect(); if !when.is_some_and(|w| !w.is_empty() && w.len() == patterns.len()) { out.push(format!( "{at}.when: must be an object of the notification's fields, each a pattern" )); } let Some(path) = e["path"].as_str().filter(|p| p.starts_with('/')) else { out.push(format!("{at}.path: must be a path, starting with /")); return; }; let bound: Vec<&str> = patterns.iter().flat_map(|p| tokens(p)).collect(); for t in tokens(path).into_iter().filter(|t| !bound.contains(t)) { out.push(format!("{at}.path: {{{t}}} is in no pattern of when")); } if !routed(path, routes) { out.push(format!("{at}.path: no route's path is {path}")); } } /// Add to `out` what is wrong with the tool call `call`, at `at`: it must /// draw what a view among `views` draws, as a query of a method view's /// method, an app's page (`describe_app`), or a record (`get_record`, by /// its at-uri) or records (`list_records`) of a collection a view draws. fn drawn(call: &Value, at: &str, views: &Views, out: &mut Vec) { let args = &call["args"]; let text = |k: &str| args[k].as_str().unwrap_or_default(); let all = views.all().iter().map(|b| &b.view); let (what, found) = match call["name"].as_str() { Some("query") => { let m = text("method"); (m, all.clone().any(|v| v.method.as_deref() == Some(m))) } Some("describe_app") => { let d = text("domain"); let page = |v: &view::View| v.page.is_some() && v.domain.as_deref() == Some(d); (d, all.clone().any(page)) } Some("get_record") => { let c = text("uri").split('/').nth(3).unwrap_or_default(); let routed = |v: &view::View| v.records.iter().any(|r| r.collection == c); let found = all .clone() .any(|v| v.collection.as_deref() == Some(c) || routed(v)); (c, found) } Some("list_records") => { let c = text("collection"); (c, all.clone().any(|v| v.collection.as_deref() == Some(c))) } _ => { out.push(format!( "{at}: must be a call of query, describe_app, get_record or list_records" )); return; } }; if !found { out.push(format!("{at}: no view draws {what:?}")); } } #[cfg(test)] mod tests { use super::*; use serde_json::json; /// A new empty directory of this test's own. fn temp_dir(name: &str) -> PathBuf { let dir = std::env::temp_dir().join(format!("hud-operator-{name}-{}", std::process::id())); let _ = std::fs::remove_dir_all(&dir); std::fs::create_dir_all(dir.join("views")).unwrap(); dir } /// `dir` with `files` written in it, by their paths within it. fn write(dir: &Path, files: &[(&str, Value)]) { for (path, doc) in files { std::fs::write(dir.join(path), doc.to_string()).unwrap(); } } /// A method view of `method`, at Bluesky's AppView, calling `call`. fn method_view(method: &str, call: &str) -> Value { json!({ "method": method, "service": "did:web:api.bsky.app#bsky_appview", "description": "Lists", "query": { "items": "lists", "layout": { "component": "Action", "props": { "label": "Mute", "done": "Muted", "call": { "method": call, "service": "did:web:api.bsky.app#bsky_appview", "input": { "actor": { "$": "did" } } } } } } }) } /// An app of `example.test`: a tab and a route, each a query. fn app(method: &str) -> Value { json!({ "domain": "example.test", "name": "Example", "tabs": [{ "label": "Lists", "icon": "feed", "call": { "name": "query", "args": { "method": method } }, "guest": "call" }], "routes": [{ "path": "/lists/{actor}", "tab": "Lists", "call": { "name": "query", "args": { "method": method, "params": { "actor": "{actor}" } } } }] }) } /// A directory with a valid app and its view loads, its view trusted: /// its call is one the server sends, and no bundled view's is. #[test] fn an_app_and_its_view_load() { let dir = temp_dir("valid"); write( &dir, &[ ("example.test.json", app("app.bsky.graph.getLists")), ("package.json", json!({ "name": "a client" })), ( "views/example-lists.json", method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor"), ), ], ); let loaded = load(&dir, true).unwrap(); assert_eq!(loaded.apps, ["example.test"]); assert_eq!(loaded.ids, ["example-lists"]); let b = loaded .views .all() .iter() .find(|b| b.id == "example-lists") .unwrap(); assert_eq!( b.file, dir.join("views/example-lists.json").display().to_string() ); let mute = ( "social.grain.graph.muteActor", "did:web:api.bsky.app#bsky_appview", ); assert!(loaded.views.calls(mute.0, mute.1)); assert!(!Views::built_in().calls(mute.0, mute.1)); assert_eq!( loaded.views.service("app.bsky.graph.getLists"), Some(mute.1) ); // The bundled views are all there besides. assert_eq!(loaded.views.all().len(), Views::built_in().all().len() + 1); // Views alone, with no app, load too. std::fs::remove_file(dir.join("example.test.json")).unwrap(); assert_eq!(load(&dir, true).unwrap().apps, Vec::::new()); } /// An operator's view replaces the bundled view of its id, and any /// drawing what it draws. #[test] fn the_operators_view_wins() { let built = Views::built_in(); let bundled = built.all().iter().find(|b| b.id == "bsky-feed").unwrap(); let method = bundled.view.method.clone().unwrap(); let dir = temp_dir("wins"); let mut mine = method_view(&method, "social.grain.graph.muteActor"); mine["description"] = json!("The operator's feed"); write(&dir, &[("views/bsky-feed.json", mine.clone())]); let loaded = load(&dir, true).unwrap(); let of = |views: &Views| { let found = views .all() .iter() .filter(|b| b.view.method.as_deref() == Some(&method)); found .map(|b| (b.id.clone(), b.view.description.clone())) .collect::>() }; assert_eq!( of(&loaded.views), [("bsky-feed".to_string(), "The operator's feed".to_string())] ); // Under another id, it replaces the view drawing its method. let dir = temp_dir("wins-drawn"); write(&dir, &[("views/mine.json", mine)]); let loaded = load(&dir, true).unwrap(); assert_eq!( of(&loaded.views), [("mine".to_string(), "The operator's feed".to_string())] ); assert!(!loaded.views.all().iter().any(|b| b.id == "bsky-feed")); } /// What refuses startup, each naming its file. #[test] fn refusals_name_their_file() { let refused = |name: &str, files: &[(&str, Value)]| { let dir = temp_dir(name); write(&dir, files); (dir.clone(), load(&dir, true).unwrap_err().join("\n")) }; let lists = || method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor"); // A call to what is no procedure. let (dir, err) = refused( "query-call", &[( "views/v.json", method_view("app.bsky.graph.getLists", "app.bsky.graph.getList"), )], ); let file = dir.join("views/v.json").display().to_string(); assert_eq!( err, format!("{file}: app.bsky.graph.getList is a query, not a procedure") ); // A broken view. let (dir, err) = refused("broken", &[("views/v.json", json!({ "method": "a.b.c" }))]); assert!( err.starts_with(&format!("{}: ", dir.join("views/v.json").display())), "{err}" ); // A view that is not JSON, or not text. let dir = temp_dir("not-json"); std::fs::write(dir.join("views/v.json"), "{").unwrap(); assert!( load(&dir, true).unwrap_err()[0] .starts_with(&format!("{}: EOF", dir.join("views/v.json").display())) ); std::fs::write(dir.join("views/v.json"), [0xff, 0xfe]).unwrap(); assert!( load(&dir, true).unwrap_err()[0] .starts_with(&format!("{}: ", dir.join("views/v.json").display())) ); // A route naming a method no view draws. let mut bad = app("app.bsky.graph.getLists"); bad["routes"][0]["call"]["args"]["method"] = json!("app.bsky.graph.getStarterPacks"); let (dir, err) = refused( "route", &[("example.test.json", bad), ("views/v.json", lists())], ); assert_eq!( err, format!( "{}: app.routes[0].call: no view draws \"app.bsky.graph.getStarterPacks\"", dir.join("example.test.json").display() ) ); // An app file that is not JSON, or not text. let dir = temp_dir("app-json"); let path = dir.join("example.test.json"); std::fs::write(&path, "[").unwrap(); assert!(load(&dir, true).unwrap_err()[0].starts_with(&format!("{}: EOF", path.display()))); std::fs::write(&path, [0xff, 0xfe]).unwrap(); assert!(load(&dir, true).unwrap_err()[0].starts_with(&format!("{}: ", path.display()))); // A view drawing a collection a bundled view draws as its query. let mut posts = json!({ "collection": "app.bsky.feed.post", "description": "Posts", "list": { "layout": { "component": "Badge", "props": { "value": "x" } } }, "record": { "layout": { "component": "Badge", "props": { "value": "x" } } } }); let (dir, err) = refused("conflict", &[("views/posts.json", posts.clone())]); let thread = Views::built_in() .all() .iter() .find(|b| { b.view .records .iter() .any(|r| r.collection == "app.bsky.feed.post") }) .unwrap() .file .clone(); assert_eq!( err, format!( "{thread}: {} draws app.bsky.feed.post as records", dir.join("views/posts.json").display() ) ); // A trusted collection view draws both modes. posts["collection"] = json!("example.test.thing"); posts.as_object_mut().unwrap().remove("record"); let (dir, err) = refused("one-mode", &[("views/thing.json", posts)]); assert_eq!( err, format!( "{}: view: a trusted collection view draws a page of records (list) and one (record)", dir.join("views/thing.json").display() ) ); // No such directory, or nothing in it. let gone = std::env::temp_dir().join("hud-operator-none-such"); assert!(load(&gone, true).unwrap_err()[0].starts_with(&format!("{}: ", gone.display()))); let dir = temp_dir("empty"); assert_eq!( load(&dir, true).unwrap_err(), [format!( "{}: no app (.json) and no view (views/.json)", dir.display() )] ); } /// What a view's deletes may reach (`collections`) is what sign-in asks /// to delete alone (`repo:?action=delete`), but for a collection a /// view writes, which it asks to write, once. #[test] fn a_plans_collections_are_asked_to_delete() { let dir = temp_dir("plan-scope"); let mut view = method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor"); view["query"]["layout"] = json!({ "component": "Action", "props": { "label": "Delete all", "deletes": { "method": "social.grain.server.getAccountDeletionPlan", "service": "did:web:grain.social#grain_appview", "repeat": true, "collections": ["example.thing.one", "app.bsky.feed.like"] } } }); write(&dir, &[("views/example-lists.json", view)]); let loaded = load(&dir, true).unwrap(); let s = crate::scope::asked(&loaded.views, false, false); let tokens: Vec<&str> = s.split(' ').collect(); assert!( tokens.contains(&"repo:example.thing.one?action=delete"), "{s}" ); assert!(tokens.contains(&"repo:app.bsky.feed.like"), "{s}"); assert!(!s.contains("app.bsky.feed.like?action=delete"), "{s}"); } /// Grain's apps, as its repository serves them (`HUD_APPS`): its app /// file and its views load, each view's calls and query joins passing /// the checks against HUD's bundled lexicons, and the server sends /// their calls. #[test] fn grains_apps_load() { let loaded = load(Path::new(view::GRAIN_APPS), true).unwrap(); assert_eq!(loaded.apps, ["grain.social"]); assert_eq!(loaded.ids.len(), 17); assert!(loaded.ids.iter().all(|id| id.starts_with("grain-"))); let calls: Vec<&view::Call> = loaded .views .all() .iter() .filter(|b| loaded.ids.contains(&b.id)) .flat_map(|b| &b.view.calls) .collect(); assert!(!calls.is_empty()); assert!( calls.iter().any(|c| c.deletes), "a gallery deleted as planned" ); for c in calls { let sent = |v: &Views| match c.deletes { true => v.deletes(&c.method, &c.service), false => v.calls(&c.method, &c.service), }; assert!(sent(&loaded.views), "{}", c.method); assert!(!sent(&Views::built_in()), "{}", c.method); } // Its app file registers a device for push, which the server sends // as it sends a view's calls. let grain = "did:web:grain.social#grain_appview"; let pushes: Vec<&str> = loaded .views .pushes() .iter() .map(|c| c.method.as_str()) .collect(); assert_eq!( pushes, [ "social.grain.notification.registerPush", "social.grain.notification.unregisterPush" ] ); for m in pushes { assert!(loaded.views.calls(m, grain), "{m}"); assert!(!Views::built_in().calls(m, grain), "{m}"); } assert_eq!(loaded.views.with(Vec::new()).pushes().len(), 2); // Served alone, as an instance with no workspace serves them: its // views and pushes, and no bundled view. let alone = load(Path::new(view::GRAIN_APPS), false).unwrap(); let ids: Vec<&str> = alone.views.all().iter().map(|b| b.id.as_str()).collect(); assert_eq!(ids, loaded.ids); assert_eq!(alone.views.pushes(), loaded.views.pushes()); // Its app file names its refresh, called after a write of what // its views write, whose service sign-in asks to call. let refreshes = loaded.views.refreshes(); assert_eq!(refreshes.len(), 1); assert_eq!(refreshes[0].method, "social.grain.sync.indexRecords"); assert_eq!(refreshes[0].service, grain); assert!(refreshes[0].collections.contains("social.grain.comment")); assert!(refreshes[0].collections.contains("social.grain.favorite")); assert!( refreshes[0] .collections .iter() .all(|c| c.starts_with("social.grain.")) ); assert_eq!(alone.views.refreshes(), refreshes); assert_eq!(loaded.views.with(Vec::new()).refreshes(), refreshes); assert!(loaded.views.called().contains(grain)); assert!(Views::built_in().refreshes().is_empty()); // Its app file draws its own sign-in screen: its web clients are sent // straight on to the account's server. assert_eq!(loaded.views.sign_ins(), ["grain.social"]); assert_eq!(alone.views.sign_ins(), ["grain.social"]); assert_eq!(loaded.views.with(Vec::new()).sign_ins(), ["grain.social"]); assert!(Views::built_in().sign_ins().is_empty()); // Its app file names Grain's permission set, asked for first at // sign-in, its methods called at Grain's AppView. let set = Include { nsid: "social.grain.authFull".into(), service: Some(grain.into()), }; let sets = std::slice::from_ref(&set); assert_eq!(loaded.views.sets(), sets); assert_eq!(alone.views.sets(), sets); assert_eq!(loaded.views.with(Vec::new()).sets(), sets); assert!(Views::built_in().sets().is_empty()); } /// Grain's app file's own pages load, each read from its Markdown's /// file into blocks, its links to Grain's own paths opening them on /// grain.social; and an app file with none has none, as ever. #[test] fn grains_pages_load() { let loaded = load(Path::new(view::GRAIN_APPS), true).unwrap(); let terms = loaded.views.page("grain.social", "/support/terms").unwrap(); assert_eq!(terms.app, "Grain"); assert_eq!(terms.title, "Terms and Conditions"); assert!(terms.markdown.starts_with("*Last Updated: June 3, 2025*")); assert_eq!( terms.blocks[1], json!({ "kind": "heading", "level": 2, "runs": [{ "text": "Overview" }] }) ); let safety = loaded .views .page("grain.social", "/support/child-safety") .unwrap(); let said = serde_json::to_string(&safety.blocks).unwrap(); assert!(said.contains("\"link\":\"https://grain.social/support/terms\"")); assert!(said.contains("\"link\":\"mailto:support@grain.social\"")); assert!(loaded.views.page("grain.social", "/support/x").is_none()); assert!(loaded.views.page("bsky.app", "/support/terms").is_none()); // Kept as other views are added, and served alone too. let kept = loaded.views.with(Vec::new()); assert_eq!(kept.page("grain.social", "/support/terms"), Some(terms)); let alone = load(Path::new(view::GRAIN_APPS), false).unwrap(); assert!( alone .views .page("grain.social", "/support/privacy") .is_some() ); assert!( Views::built_in() .page("grain.social", "/support/terms") .is_none() ); // An app file with no pages loads as it did, with none. let dir = temp_dir("pageless"); write( &dir, &[ ("example.test.json", app("app.bsky.graph.getLists")), ( "views/example-lists.json", method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor"), ), ], ); let pageless = load(&dir, true).unwrap(); assert!(pageless.views.page("example.test", "/about").is_none()); // One with a page whose file is there loads it; one whose file is // not refuses startup, naming the app file and the page. let mut doc = app("app.bsky.graph.getLists"); doc["pages"] = json!([{ "path": "/about", "title": "About", "markdown": "pages/about.md" }]); write(&dir, &[("example.test.json", doc)]); let err = load(&dir, true).unwrap_err().join("\n"); let file = dir.join("example.test.json").display().to_string(); let md = dir.join("pages/about.md").display().to_string(); assert!( err.starts_with(&format!("{file}: app.pages[0].markdown: {md}: ")), "{err}" ); std::fs::create_dir_all(dir.join("pages")).unwrap(); std::fs::write( dir.join("pages/about.md"), "# About\n\nSee [terms](/terms).", ) .unwrap(); let about = load(&dir, true).unwrap(); let page = about.views.page("example.test", "/about").unwrap(); assert_eq!(page.description, None); assert_eq!(page.app, "Example"); assert_eq!( page.blocks[1]["runs"][1], json!({ "text": "terms", "link": "https://example.test/terms" }) ); } /// An app file's `pages`: a list, each page what its lexicon says, at /// a plain path no other page, tab or route has, its Markdown a `.md` /// file's path within the app's directory. #[test] fn app_pages_checked() { let views = view::views(); let text = std::fs::read_to_string(Path::new(view::GRAIN_APPS).join("grain.social.json")); let grain: Value = serde_json::from_str(&text.unwrap()).unwrap(); let check = |pages: Value| { let mut doc = grain.clone(); doc["pages"] = pages; app_problems(&doc, "grain.social", views) }; assert!(check(grain["pages"].clone()).is_empty()); let mut pageless = grain.clone(); pageless.as_object_mut().unwrap().remove("pages"); assert!(app_problems(&pageless, "grain.social", views).is_empty()); let too_many = json!(vec![ json!({ "path": "/a", "title": "A", "markdown": "a.md" }); 65 ]); for pages in [json!({}), too_many] { assert_eq!( check(pages), ["app.pages: must be a list of at most 64 pages"] ); } let page = |path: &str, markdown: &str| json!({ "path": path, "title": "A", "markdown": markdown }); let problems = check(json!([ { "path": "/a", "markdown": "a.md", "x": 1 }, page("/A", "a.md"), page("/a/", "a.md"), page("/a?b=c", "a.md"), page("/{x}", "a.md"), page("/..", "a.md"), page("support", "a.md"), page("/support/terms", "a.md"), page("/ok", "a.md"), page("/ok", "a.md"), page("/profile/about", "a.md"), page("/feeds/recent", "a.md"), page("/b", "../a.md"), page("/c", "/a.md"), page("/d", "pages/a.txt"), page("/e", "pages\\..\\a.md"), ])); let plain = "must be a plain path, /segments of a-z, 0-9, - _ and ., no query or token"; let within = "must be a .md file's path within the app file's directory"; assert_eq!( problems, [ "app.pages[0]: unknown key \"x\"".to_string(), "app.pages[0] must have the property \"title\"".to_string(), format!("app.pages[1].path: {plain}"), format!("app.pages[2].path: {plain}"), format!("app.pages[3].path: {plain}"), format!("app.pages[4].path: {plain}"), format!("app.pages[5].path: {plain}"), format!("app.pages[6].path: {plain}"), "app.pages[9].path: another page's too".to_string(), "app.pages[10].path: a tab's or a route's too".to_string(), "app.pages[11].path: a tab's or a route's too".to_string(), format!("app.pages[12].markdown: {within}"), format!("app.pages[13].markdown: {within}"), format!("app.pages[14].markdown: {within}"), format!("app.pages[15].markdown: {within}"), ] ); // A tab's own path is no page's. let mut tabbed = grain.clone(); tabbed["pages"] = json!([page("/home", "a.md")]); tabbed["tabs"][0]["path"] = json!("/home"); assert_eq!( app_problems(&tabbed, "grain.social", views), ["app.pages[0].path: a tab's or a route's too"] ); } /// An app file's `refresh`: a procedure's method and its service, /// nothing more. #[test] fn refresh_checked() { let views = view::views(); let app = |refresh: Value| { json!({ "domain": "grain.social", "name": "Grain", "tabs": [{ "label": "Home", "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed" } } }], "refresh": refresh }) }; let check = |refresh: Value| app_problems(&app(refresh), "grain.social", views); let fine = json!({ "method": "social.grain.sync.indexRecords", "service": "did:web:grain.social#grain_appview" }); assert!(check(fine).is_empty()); assert_eq!( check(json!("social.grain.sync.indexRecords")), ["app.refresh: must be an object, a procedure's method and service"] ); assert_eq!( check(json!({ "method": "refresh", "service": "grain", "input": {} })), [ "app.refresh.method: must be a method's NSID", "app.refresh.service: Not a service: grain (a DID with its service's #fragment, as did:web:api.bsky.app#bsky_appview)", "app.refresh.input: not a field of it", ] ); // An app with none refreshes nothing. assert_eq!(refresh_of(&json!({}), &BTreeSet::new()), None); } /// An app file's `permissions`: a list of sets, each its NSID and the /// service its methods are called at, if any, and nothing else. #[test] fn permissions_checked() { let views = view::views(); let app = |permissions: Value| { json!({ "domain": "grain.social", "name": "Grain", "tabs": [{ "label": "Home", "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed" } } }], "permissions": permissions }) }; let check = |p: Value| app_problems(&app(p), "grain.social", views); let fine = json!([ { "include": "social.grain.authFull", "service": "did:web:grain.social#grain_appview" }, { "include": "com.example.authBasic" }, ]); assert!(check(fine.clone()).is_empty()); assert_eq!( sets_of(&app(fine)), [ Include { nsid: "social.grain.authFull".into(), service: Some("did:web:grain.social#grain_appview".into()), }, Include { nsid: "com.example.authBasic".into(), service: None, }, ] ); let refused = "app.permissions: must be a list of 1 to 8 permission sets"; for bad in [ json!("social.grain.authFull"), json!([]), json!(vec![json!({ "include": "a.b.c" }); 9]), ] { assert_eq!(check(bad), [refused]); } assert_eq!( check(json!([ "social.grain.authFull", { "include": "authFull", "service": "grain", "aud": "did:web:grain.social" }, { "service": "did:web:grain.social#grain_appview" }, ])), [ "app.permissions[0]: must be an object, a set's include and service", "app.permissions[1].include: must be a permission set's NSID", "app.permissions[1].service: Not a service: grain (a DID with its service's #fragment, as did:web:api.bsky.app#bsky_appview)", "app.permissions[1].aud: not a field of it", "app.permissions[2].include: must be a permission set's NSID", ] ); assert!(sets_of(&json!({})).is_empty()); } /// An app file's shape, and each call drawing what a view draws. #[test] fn apps_checked() { let views = view::views(); let check = |doc: Value| app_problems(&doc, "grain.social", views); let call = |name: &str, args: Value| json!({ "name": name, "args": args }); let fine = json!({ "domain": "grain.social", "name": "Grain", "tabs": [ { "label": "Home", "call": call("query", json!({ "method": "social.grain.feed.getFeed" })) }, { "label": "Profile", "call": call("describe_app", json!({ "domain": "grain.social", "actor": "me" })), "guest": call("list_records", json!({ "actor": "x", "collection": "fm.plyr.list" })) }, ], "routes": [ { "path": "/g/{a}/{r}", "call": call("get_record", json!({ "uri": "at://{a}/social.grain.gallery/{r}" })) }, { "path": "/d/{a}/{r}", "tab": "Profile", "call": call("get_record", json!({ "uri": "at://{a}/site.standard.document/{r}" })) }, ] }); assert_eq!(check(fine.clone()), Vec::::new()); // Routes are for those apps that have them. let mut tabs_alone = fine.clone(); tabs_alone.as_object_mut().unwrap().remove("routes"); assert_eq!(check(tabs_alone), Vec::::new()); assert_eq!(check(json!([])), ["app: must be an object"]); assert_eq!( check(json!({ "domain": "example.test", "name": " ", "routes": {} })), [ "app.domain: must be grain.social, as its file is named", "app.name: required", "app.tabs: must be a list of one or more tabs", "app.routes: must be a list of routes", ] ); let mut bad = fine; bad["tabs"][0] = json!({ "call": call("describe_repo", json!({ "actor": "x" })), "guest": call("describe_app", json!({ "domain": "example.test" })) }); bad["tabs"][1]["guest"] = call("list_records", json!({ "collection": "a.b.c" })); bad["routes"][0]["path"] = json!("g"); bad["routes"][0]["call"]["args"]["uri"] = json!("at://x/a.b.c/r"); bad["routes"][1]["tab"] = json!("Home"); assert_eq!( check(bad), [ "app.tabs[0].label: required", "app.tabs[0].call: must be a call of query, describe_app, get_record or list_records", "app.tabs[0].guest: no view draws \"example.test\"", "app.tabs[1].guest: no view draws \"a.b.c\"", "app.routes[0].path: must be a path, starting with /", "app.routes[0].call: no view draws \"a.b.c\"", "app.routes[1].tab: must be a tab's label", ] ); } /// A story's route: opened in the stories pager (`pager`), over its /// account's screen (`under`, a route's path its own binds) where its /// URL is loaded. #[test] fn pager_routes_checked() { let views = view::views(); let call = json!({ "name": "get_record", "args": { "uri": "at://{a}/social.grain.gallery/{r}" } }); let check = |story: Value| { let home = json!({ "label": "Home", "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed" } } }); let routes = json!([{ "path": "/p/{a}", "call": call }, story]); app_problems( &json!({ "domain": "grain.social", "name": "Grain", "tabs": [home], "routes": routes }), "grain.social", views, ) }; let story = |extra: Value| { let mut route = json!({ "path": "/p/{a}/s/{r}", "call": call }); route .as_object_mut() .unwrap() .extend(extra.as_object().unwrap().clone()); route }; assert_eq!( check(story(json!({ "pager": true, "under": "/p/{a}" }))), Vec::::new() ); assert_eq!(check(story(json!({ "pager": true }))), Vec::::new()); assert_eq!( check(story(json!({ "pager": 1, "under": 2 }))), [ "app.routes[1].pager: must be true", "app.routes[1].under: must be a path, starting with /" ] ); assert_eq!( check(story(json!({ "under": "/q/{b}" }))), [ "app.routes[1].under: only a pager's route has one", "app.routes[1].under: {b} is in no token of its path", "app.routes[1].under: no route's path is /q/{b}", ] ); } /// A tab's `first`: a query of a method's NSID, the list's and each /// item's path dotted, and an NSID after which it is read again; no /// other key. #[test] fn tab_first_checked() { let views = view::views(); let prefs = json!({ "name": "query", "args": { "method": "social.grain.actor.getPreferences", "service": "did:web:grain.social#grain_appview", "params": {} } }); let first = json!({ "call": prefs, "at": "preferences.@pinnedFeedsPref.items", "path": "path", "after": "social.grain.actor.setPreference" }); let check = |first: Value| { let home = json!({ "label": "Home", "path": "/", "first": first, "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed" } } }); app_problems( &json!({ "domain": "grain.social", "name": "Grain", "tabs": [home] }), "grain.social", views, ) }; assert_eq!(check(first.clone()), Vec::::new()); let mut bare = first.clone(); bare.as_object_mut().unwrap().remove("after"); assert_eq!(check(bare), Vec::::new()); let mut bad = first.clone(); bad["call"]["name"] = json!("describe_app"); bad["at"] = json!("preferences..items"); bad["path"] = json!("path."); bad["also"] = json!(true); assert_eq!( check(bad), [ "app.tabs[0].first: unknown key \"also\"", "app.tabs[0].first.call: must be a query of a method's NSID", "app.tabs[0].first.at: must be a dotted path, no segment empty", "app.tabs[0].first.path: must be a dotted path, no segment empty", ] ); let mut unnamed = first.clone(); unnamed["call"]["args"]["method"] = json!("getPreferences"); assert_eq!( check(unnamed), ["app.tabs[0].first.call: must be a query of a method's NSID"] ); let mut missing = first.clone(); missing.as_object_mut().unwrap().remove("path"); assert_eq!( check(missing), ["app.tabs[0].first must have the property \"path\""] ); let mut after = first; after["after"] = json!("set preference"); assert_eq!( check(after), ["app.tabs[0].first.after must be a valid nsid"] ); assert_eq!( check(json!("first")), ["app.tabs[0].first must be an object"] ); } /// An app file's `head`: its site's name, its texts, an https picture /// and an account as @name; nothing else. #[test] fn app_head_checked() { let views = view::views(); let tabs = json!([{ "label": "Home", "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed" } } }]); let check = |head: Value| { let doc = json!({ "domain": "grain.social", "name": "Grain", "tabs": tabs, "head": head }); app_problems(&doc, "grain.social", views) }; let fine = json!({ "siteName": "Grain", "title": "Grain: photo sharing", "description": "Galleries.", "image": "https://grain.social/og.jpg", "imageAlt": "Photos", "twitter": "@grain_social" }); assert_eq!(check(fine), Vec::::new()); assert_eq!(check(json!({ "siteName": "Grain" })), Vec::::new()); assert_eq!(check(json!("Grain")), ["app.head: must be an object"]); assert_eq!( check( json!({ "title": " ", "description": "x".repeat(301), "imageAlt": 3, "image": "http://grain.social/og.jpg", "twitter": "grain", "x": 1 }) ), [ "app.head: unknown key \"x\"", "app.head.siteName: required", "app.head.title: must be text of 1 to 300 characters", "app.head.description: must be text of 1 to 300 characters", "app.head.imageAlt: must be text of 1 to 300 characters", "app.head.image: must be an https URL", "app.head.twitter: must be an account, as @name", ] ); for bad in ["@", "@a-b", "@abcdefghijklmnop", "not a url"] { let problems = check(json!({ "siteName": "Grain", "twitter": bad, "image": bad })); assert_eq!(problems.len(), 2, "{bad}: {problems:?}"); } } /// An app file's `frame`: what its lexicon describes, no key more at /// any level, its calls drawn, its icons a shell's, its picture on a /// tab, its hrefs paths or https, its sizes and bands in order. #[test] fn app_frame_checked() { let views = view::views(); let query = |method: &str| json!({ "name": "query", "args": { "method": method } }); let tabs = json!([{ "label": "Home", "call": query("social.grain.feed.getFeed") }, { "label": "Profile", "call": query("social.grain.actor.getPreferences") }]); let app = |frame: Option| { let mut doc = json!({ "domain": "grain.social", "name": "Grain", "tabs": tabs }); if let Some(frame) = frame { doc["frame"] = frame; } doc }; let check = |frame: Value| app_problems(&app(Some(frame)), "grain.social", views); // An app file with no frame is checked as ever. assert_eq!( app_problems(&app(None), "grain.social", views), Vec::::new() ); let fine = json!({ "destinations": "tabs", "action": { "label": "Create", "icon": "imagePlus", "call": query("social.grain.feed.getFeed") }, "account": { "picture": { "tab": "Profile", "call": query("social.grain.actor.getProfile"), "at": "avatar.url", "name": "displayName", "handle": "handle" }, "items": [ { "label": "Settings", "icon": "settings", "call": query("social.grain.actor.getPreferences") }, { "host": "signOut", "label": "Log out", "icon": "logOut" }, { "host": "signIn", "about": "Share your photography" }, ] }, "links": [{ "label": "Terms", "href": "https://grain.social/terms" }, { "label": "About", "href": "/about" }], "aside": { "call": query("social.grain.feed.getFeed"), "width": 320 }, "sizes": { "content": 600, "wide": 935 }, "bands": { "rail": 600, "sidebar": 1200 }, }); assert_eq!(check(fine.clone()), Vec::::new()); assert_eq!(check(json!({})), Vec::::new()); // Unknown keys, at the top and below, each named. let mut extra = fine.clone(); extra["x"] = json!(1); extra["account"]["items"][1]["y"] = json!(1); extra["sizes"]["z"] = json!(1); assert_eq!( check(extra), [ "app.frame.account.items[1]: unknown key \"y\"", "app.frame.sizes: unknown key \"z\"", "app.frame: unknown key \"x\"", ] ); // What its lexicon refuses, said where. assert_eq!(check(json!("tabs")), ["app.frame must be an object"]); let lexicon = |frame: Value| { let problems = check(frame); assert_eq!(problems.len(), 1, "{problems:?}"); problems[0].clone() }; for (frame, at) in [ ( json!({ "sizes": { "content": 319 } }), "app.frame.sizes.content", ), (json!({ "sizes": { "wide": 2401 } }), "app.frame.sizes.wide"), (json!({ "bands": { "rail": 100 } }), "app.frame.bands.rail"), ( json!({ "bands": { "sidebar": 4001 } }), "app.frame.bands.sidebar", ), ( json!({ "aside": { "call": query("social.grain.feed.getFeed"), "width": 100 } }), "app.frame.aside.width", ), ( json!({ "links": vec![json!({ "label": "a", "href": "/a" }); 13] }), "app.frame.links", ), ( json!({ "account": { "items": vec![json!({ "host": "signIn" }); 9] } }), "app.frame.account.items", ), ( json!({ "action": { "label": "", "icon": "plus", "call": query("social.grain.feed.getFeed") } }), "app.frame.action.label", ), ( json!({ "action": { "label": "Create" } }), "app.frame.action", ), ] { let said = lexicon(frame); assert!(said.starts_with(at), "{at}: {said}"); } // Its own rules. let mut bad = fine; bad["destinations"] = json!("pages"); bad["action"]["icon"] = json!("rocket"); bad["action"]["call"] = query("a.b.c"); bad["account"]["picture"] = json!({ "tab": "Home page", "call": query("not a method"), "at": "avatar..url", "name": ".displayName", "handle": "handle." }); bad["account"]["items"] = json!([ { "label": "Settings", "call": query("a.b.c") }, { "host": "signOut", "call": query("social.grain.feed.getFeed") }, { "label": "Help" }, { "host": "help" }, { "host": "signOut", "about": "Bye" }, { "host": "signOut" }, ]); bad["links"] = json!([{ "label": "a", "href": "//x" }, { "label": "b", "href": "http://x.test" }, { "label": "c", "href": "terms" }]); bad["aside"]["call"] = json!({ "name": "describe_repo", "args": {} }); bad["sizes"] = json!({ "content": 1000 }); bad["bands"] = json!({ "rail": 1200 }); assert_eq!( check(bad), [ "app.frame.destinations: must be \"tabs\", the app's tabs", "app.frame.action.icon: must be one of catalog::FRAME_ICONS", "app.frame.action.call: no view draws \"a.b.c\"", "app.frame.account.picture.tab: must be a tab's label", "app.frame.account.picture.call: must be a query of a method's NSID", "app.frame.account.picture.at: must be a dotted path, no segment empty", "app.frame.account.picture.name: must be a dotted path, no segment empty", "app.frame.account.picture.handle: must be a dotted path, no segment empty", "app.frame.account.items[0].icon: required with a call", "app.frame.account.items[0].call: no view draws \"a.b.c\"", "app.frame.account.items[1]: takes a call or a host, not both", "app.frame.account.items[2]: needs a call or a host", "app.frame.account.items[3].host: must be signOut or signIn", "app.frame.account.items[4].about: a signIn item's alone", "app.frame.account.items[5].host: at most one signOut item", "app.frame.links[0].href: must be a path starting with / or an https URL", "app.frame.links[1].href: must be a path starting with / or an https URL", "app.frame.links[2].href: must be a path starting with / or an https URL", "app.frame.aside.call: must be a call of query, describe_app, get_record or list_records", "app.frame.sizes.wide: must be no narrower than content (1000)", "app.frame.bands.sidebar: must be wider than rail (1200)", ] ); // A picture's call need not be a query a view draws, but a query. let mut picture = json!({ "account": { "picture": { "tab": "Home", "at": "avatar", "call": { "name": "get_record", "args": { "method": "a.b.c" } } } } }); assert_eq!( check(picture.clone()), ["app.frame.account.picture.call: must be a query of a method's NSID"] ); picture["account"]["picture"]["call"]["name"] = json!("query"); assert_eq!(check(picture), Vec::::new()); } /// An app file's `signIn`: what its lexicon describes, no key it does /// not name, its links paths or https URLs, its typeahead at an https /// origin with scalar params and dotted paths. #[test] fn app_sign_in_checked() { let views = view::views(); let query = json!({ "name": "query", "args": { "method": "social.grain.feed.getFeed" } }); let check = |sign_in: Value| { let doc = json!({ "domain": "grain.social", "name": "Grain", "tabs": [{ "label": "Home", "call": query }], "signIn": sign_in }); app_problems(&doc, "grain.social", views) }; let fine = json!({ "title": "Log in with your atmosphere account", "text": "[What is an atmosphere account?](https://atmosphereaccount.com/)", "placeholder": "e.g. user.bsky.social", "legal": "By signing in you agree to our [Terms](/support/terms) and [Privacy](/support/privacy).", "create": { "text": "Don't have an account?", "label": "Create one" }, "typeahead": { "url": "https://typeahead.waow.tech", "method": "tech.waow.typeahead.searchActors", "param": "q", "params": { "limit": 5, "x": "y", "z": true }, "items": "actors", "did": "did", "handle": "handle", "name": "displayName", "avatar": "avatar", "avatarFallback": "avatarFallback" }, }); assert_eq!(check(fine.clone()), Vec::::new()); assert_eq!(check(json!({ "title": "Sign in" })), Vec::::new()); // Unknown keys, at the top and below, each named. let mut extra = fine.clone(); extra["x"] = json!(1); extra["create"]["y"] = json!(1); extra["typeahead"]["z"] = json!(1); assert_eq!( check(extra), [ "app.signIn.create: unknown key \"y\"", "app.signIn.typeahead: unknown key \"z\"", "app.signIn: unknown key \"x\"", ] ); // What its lexicon refuses, said where. assert_eq!(check(json!("Sign in")), ["app.signIn must be an object"]); let mut untitled = fine.clone(); untitled.as_object_mut().unwrap().remove("title"); assert_eq!(check(untitled).len(), 1); // Its rules past the lexicon. let with = |key: &str, at: &str, v: Value| { let mut s = fine.clone(); match at { "" => s[key] = v, _ => s[at][key] = v, } check(s) }; for (key, text) in [ ("text", "[Here](javascript:alert(1))"), ("legal", "Our [Terms](//evil.test/terms)."), ("legal", "Our [Terms](http://grain.social/terms)."), ] { assert_eq!( with(key, "", json!(text)), [format!( "app.signIn.{key}: each link must go to a path starting with / or an https URL" )], "{text}" ); } for url in [ "http://typeahead.waow.tech", "https://typeahead.waow.tech/xrpc", "https://typeahead.waow.tech/?a=b", "https://typeahead.waow.tech/#a", "https://me@typeahead.waow.tech", ] { assert_eq!( with("url", "typeahead", json!(url)), [ "app.signIn.typeahead.url: must be an https origin, as https://typeahead.waow.tech" ], "{url}" ); } for params in [ json!([5]), json!({ "limit": { "n": 5 } }), json!({ "q": null }), ] { assert_eq!( with("params", "typeahead", params.clone()), ["app.signIn.typeahead.params: must be an object of strings, numbers and booleans"], "{params}" ); } for key in ["items", "did", "handle", "name", "avatar", "avatarFallback"] { assert_eq!( with(key, "typeahead", json!("a..b")), [format!( "app.signIn.typeahead.{key}: must be a dotted path, no segment empty" )] ); } // A typeahead's optional paths left out are no problem. let mut bare = fine.clone(); for key in ["params", "name", "avatar", "avatarFallback"] { bare["typeahead"].as_object_mut().unwrap().remove(key); } assert_eq!(check(bare), Vec::::new()); } /// An app file's `push`: its calls procedures HUD has lexicons of, /// binding the device's token, and what a notification opens a route's /// path its fields fill. #[test] fn push_checked() { let views = view::views(); let grain = "did:web:grain.social#grain_appview"; let device = json!({ "serviceDid": "did:web:grain.social", "token": { "$token": true }, "platform": { "$platform": true }, "appId": { "$appId": true } }); let procedure = |m: &str| json!({ "method": m, "service": grain, "input": device }); let app = |push: Value| { json!({ "domain": "grain.social", "name": "Grain", "tabs": [{ "label": "Home", "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed" } } }], "routes": [ { "path": "/profile/{actor}/gallery/{rkey}", "call": { "name": "get_record", "args": { "uri": "at://{actor}/social.grain.gallery/{rkey}" } } }, { "path": "/profile/{actor}?tab={tab}", "call": { "name": "describe_app", "args": { "domain": "grain.social", "actor": "{actor}" } } }, ], "push": push }) }; let check = |push: Value| app_problems(&app(push), "grain.social", views); let fine = json!({ "register": procedure("social.grain.notification.registerPush"), "unregister": procedure("social.grain.notification.unregisterPush"), "open": [ { "when": { "type": "gallery-favorite", "uri": "at://{actor}/social.grain.gallery/{rkey}" }, "path": "/profile/{actor}/gallery/{rkey}" }, { "when": { "did": "{actor:did}" }, "path": "/profile/{actor}" }, ] }); assert_eq!(check(fine.clone()), Vec::::new()); let call = |m: &str| view::Call { method: m.into(), service: grain.into(), input: device.clone(), deletes: false, }; assert_eq!( push_calls(&app(fine.clone())), [ call("social.grain.notification.registerPush"), call("social.grain.notification.unregisterPush") ] ); // An app with no push makes no push calls; one may open nothing. assert!(push_calls(&json!({})).is_empty()); let mut quiet = fine.clone(); quiet.as_object_mut().unwrap().remove("open"); assert_eq!(check(quiet), Vec::::new()); assert_eq!(check(json!([])), ["app.push: must be an object"]); assert_eq!( check(json!({ "register": "x", "open": {} })), [ "app.push.register: required, a procedure's method, service and input", "app.push.unregister: required, a procedure's method, service and input", "app.push.open: must be a list of what a notification opens", ] ); // A query is no procedure, and a method needs an NSID. let mut calls = fine.clone(); calls["register"]["method"] = json!("social.grain.notification.getUnreadCount"); calls["unregister"]["method"] = json!("unregister"); assert_eq!( check(calls), [ "app.push.register: social.grain.notification.getUnreadCount is a query, not a procedure", "app.push.unregister.method: must be a method's NSID", ] ); // A service, the lexicon's input, and bindings of the device alone. let mut inputs = fine.clone(); inputs["register"]["service"] = json!("grain"); inputs["register"]["input"] = json!({ "serviceDid": "did:web:grain.social", "token": "abc", "platform": { "$platform": true, "x": 1 }, "appId": [{ "$bundle": true }], "extra": 1 }); inputs["unregister"]["method"] = json!("example.test.unregister"); let binds = "is no binding of a push call, which binds {\"$token\": true}, {\"$appId\": true} and {\"$platform\": true}"; assert_eq!( check(inputs), [ "app.push.register.service: Not a service: grain (a DID with its service's #fragment, as did:web:api.bsky.app#bsky_appview)".to_string(), "app.push.register: social.grain.notification.registerPush: input.extra is not an input of it".into(), format!("app.push.register.input.platform: $platform {binds}"), format!("app.push.register.input.appId[0]: $bundle {binds}"), "app.push.register.input: must hold the device's token, {\"$token\": true}".into(), "app.push.unregister: example.test.unregister: no lexicon".into(), ] ); // What a notification opens: its fields' patterns, and a route's path they fill. let mut open = fine; open["open"] = json!([ { "when": { "uri": 5 }, "path": "profile" }, { "when": {}, "path": "/profile/{actor}/story/{rkey}" }, { "when": { "did": "{actor}" }, "path": "/profile/{who}/gallery/{rkey}" }, ]); assert_eq!( check(open), [ "app.push.open[0].when: must be an object of the notification's fields, each a pattern", "app.push.open[0].path: must be a path, starting with /", "app.push.open[1].when: must be an object of the notification's fields, each a pattern", "app.push.open[1].path: {actor} is in no pattern of when", "app.push.open[1].path: {rkey} is in no pattern of when", "app.push.open[1].path: no route's path is /profile/{actor}/story/{rkey}", "app.push.open[2].path: {who} is in no pattern of when", "app.push.open[2].path: {rkey} is in no pattern of when", ] ); assert_eq!(tokens("at://{a:did}/x/{r}/{open"), ["a", "r"]); } /// A file whose push falls short refuses startup, naming its file. #[test] fn a_bad_push_refuses_startup() { let dir = temp_dir("push"); let mut example = app("app.bsky.graph.getLists"); example["push"] = json!({ "register": {}, "unregister": {} }); write( &dir, &[ ("example.test.json", example), ( "views/v.json", method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor"), ), ], ); let file = dir.join("example.test.json").display().to_string(); assert_eq!( load(&dir, true).unwrap_err(), [ format!("{file}: app.push.register.method: must be a method's NSID"), format!("{file}: app.push.unregister.method: must be a method's NSID"), ] ); } /// Every problem at once, each naming its file and where in it, as /// `hud check` prints them: an app file that is no JSON, a lexicon that /// is none, a view's problems (each of them), a view that is no JSON, /// two views drawing one method, a call of what is no procedure, and an /// app file's problems. #[test] fn every_problem_is_named() { let dir = temp_dir("every"); let lists = method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor"); let mut example = app("app.bsky.graph.getLists"); example["routes"][0]["call"]["args"]["method"] = json!("app.bsky.graph.getStarterPacks"); example.as_object_mut().unwrap().remove("name"); std::fs::create_dir_all(dir.join("lexicons")).unwrap(); write( &dir, &[ ("example.test.json", example), ("views/a.json", lists.clone()), ("views/b.json", lists), ("views/broken.json", json!({ "method": "a.b.c", "nope": 1 })), ( "views/query.json", method_view("app.bsky.graph.getList", "app.bsky.graph.getList"), ), ("lexicons/bad.json", json!({ "lexicon": 1 })), ], ); std::fs::write(dir.join("views/json.json"), "{").unwrap(); std::fs::write(dir.join("other.test.json"), "[").unwrap(); let at = |f: &str| dir.join(f).display().to_string(); assert_eq!( load(&dir, true).unwrap_err(), [ format!( "{}: EOF while parsing a list at line 1 column 1", at("other.test.json") ), format!( "{}: must be a lexicon document: lexicon 1, an NSID as its id, and defs", at("lexicons/bad.json") ), format!("{}: view: unknown key \"nope\"", at("views/broken.json")), format!( "{}: view.description: must be one line of text, 200 characters at most", at("views/broken.json") ), format!( "{}: view.service: a method view names the service it calls", at("views/broken.json") ), format!( "{}: view: a method view needs its query mode", at("views/broken.json") ), format!( "{}: EOF while parsing an object at line 1 column 1", at("views/json.json") ), format!( "{}: {} draws app.bsky.graph.getLists too", at("views/b.json"), at("views/a.json") ), format!( "{}: app.bsky.graph.getList is a query, not a procedure", at("views/query.json") ), format!("{}: app.name: required", at("example.test.json")), format!( "{}: app.routes[0].call: no view draws \"app.bsky.graph.getStarterPacks\"", at("example.test.json") ), ] ); } /// An app file's `hud` is the HUD versions it runs on: a HUD older than /// it needs refuses it, saying so and nothing else, since the rest is /// written for a newer HUD; a HUD it runs on checks the rest and loads /// it. A `hud` that is no semver requirement is refused. #[test] fn an_app_needing_a_newer_hud_is_refused() { let dir = temp_dir("version"); let mut example = app("app.bsky.graph.getLists"); example["hud"] = json!(">=0.2.0"); let lists = method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor"); write( &dir, &[ ("example.test.json", example.clone()), ("views/v.json", lists), ("views/newer.json", json!({ "method": "a.b.c" })), ], ); let version = |v: &str| semver::Version::parse(v).unwrap(); let file = dir.join("example.test.json").display().to_string(); assert_eq!( load_as(&dir, true, &version("0.1.0")).unwrap_err(), [format!( "{file}: app.hud: the app needs HUD >=0.2.0, and this HUD is 0.1.0: run a newer HUD" )] ); let newer = dir.join("views/newer.json").display().to_string(); let problems = load_as(&dir, true, &version("0.2.0")).unwrap_err(); assert!( problems.iter().all(|p| p.starts_with(&newer)), "{problems:?}" ); std::fs::remove_file(&newer).unwrap(); let loaded = load_as(&dir, true, &version("0.3.1")).unwrap(); assert_eq!(loaded.apps, ["example.test"]); for wrong in [json!(2), json!("two")] { example["hud"] = wrong; write(&dir, &[("example.test.json", example.clone())]); assert_eq!( load(&dir, true).unwrap_err(), [format!( "{file}: app.hud: must be the HUD versions the app runs on, as \">=0.2.0\"" )] ); } } /// An app file's `kits.oldest` is the oldest kit its clients still /// serve, a HUD version from the oldest kit's; its views are read for /// what that kit would not draw (`kit::warnings`), a warning, never a /// refusal: nothing in the catalog is newer than it yet. #[test] fn an_app_says_the_oldest_kit_it_serves() { let dir = temp_dir("kits"); let mut example = app("app.bsky.graph.getLists"); example["kits"] = json!({ "oldest": crate::kit::OLDEST }); let lists = method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor"); write( &dir, &[ ("example.test.json", example.clone()), ("views/v.json", lists), ], ); let loaded = load(&dir, true).unwrap(); assert_eq!(loaded.apps, ["example.test"]); assert!(loaded.warnings.is_empty(), "{:?}", loaded.warnings); let file = dir.join("example.test.json").display().to_string(); for wrong in [ json!("0.2.0"), json!({}), json!({ "oldest": "soon" }), json!({ "oldest": "0.1.9" }), json!({ "oldest": "0.2.0", "newest": "1.0.0" }), ] { example["kits"] = wrong.clone(); write(&dir, &[("example.test.json", example.clone())]); assert_eq!( load(&dir, true).unwrap_err(), [format!( "{file}: app.kits: must be {{ oldest }}, the oldest kit its clients still serve, a HUD version from 0.2.0, as \"0.2.0\"" )], "{wrong}" ); } } /// An app's lexicons (`lexicons/`, at any depth): HUD checks its views' /// calls and its push against them, one in place of the bundled /// lexicon of its NSID, and reads them as it serves /// (`Views::lexicon`). A file that is no lexicon, one of HUD's own, or a /// second of one NSID is refused. #[test] fn an_app_ships_its_lexicons() { let dir = temp_dir("lexicons"); let thing = json!({ "lexicon": 1, "id": "example.test.doThing", "defs": { "main": { "type": "procedure", "input": { "encoding": "application/json", "schema": { "type": "object", "required": ["actor"], "properties": { "actor": { "type": "string" } } } } } } }); let register = json!({ "method": "example.test.doThing", "service": "did:web:api.bsky.app#bsky_appview", "input": { "actor": { "$token": true } } }); let mut example = app("app.bsky.graph.getLists"); example["push"] = json!({ "register": register, "unregister": register }); let lists = method_view("app.bsky.graph.getLists", "example.test.doThing"); write( &dir, &[("example.test.json", example), ("views/v.json", lists)], ); let at = |f: &str| dir.join(f).display().to_string(); assert_eq!( load(&dir, true).unwrap_err(), [ format!("{}: example.test.doThing: no lexicon", at("views/v.json")), format!( "{}: app.push.register: example.test.doThing: no lexicon", at("example.test.json") ), format!( "{}: app.push.unregister: example.test.doThing: no lexicon", at("example.test.json") ), ] ); std::fs::create_dir_all(dir.join("lexicons/example/test")).unwrap(); let mut mute = (*crate::lexicon::bundled("social.grain.graph.muteActor").unwrap()).clone(); mute["defs"]["main"]["input"]["schema"]["required"] = json!(["actor", "reason"]); write( &dir, &[ ("lexicons/example/test/doThing.json", thing.clone()), ("lexicons/mute.json", mute), ], ); let loaded = load(&dir, true).unwrap(); let views = &loaded.views; assert_eq!( views.lexicon("example.test.doThing").unwrap()["id"], "example.test.doThing" ); assert_eq!( views.lexicon("social.grain.graph.muteActor").unwrap()["defs"]["main"]["input"]["schema"] ["required"], json!(["actor", "reason"]) ); assert!(views.lexicon("app.bsky.graph.getLists").is_none()); let docs = views.lexicon_docs(); assert_eq!(docs.len(), crate::lexicon::all_bundled().count() + 1); assert_eq!(docs[0]["id"], "example.test.doThing"); // A view's call is checked against the app's lexicon of its NSID. let muting = method_view("app.bsky.graph.getList", "social.grain.graph.muteActor"); write(&dir, &[("views/w.json", muting)]); assert_eq!( load(&dir, true).unwrap_err(), [format!( "{}: social.grain.graph.muteActor: input.reason is required", at("views/w.json") )] ); std::fs::remove_file(dir.join("views/w.json")).unwrap(); // Files that are no lexicon of the app's own. let lexicon = |id: &str| json!({ "lexicon": 1, "id": id, "defs": {} }); write( &dir, &[ ("lexicons/a.json", lexicon("nope")), ("lexicons/b.json", lexicon("place.hud.view")), ("lexicons/c.json", thing), ], ); std::fs::write(dir.join("lexicons/d.json"), "{").unwrap(); std::fs::write(dir.join("lexicons/README.md"), "Not a lexicon").unwrap(); assert_eq!( load(&dir, true).unwrap_err(), [ format!( "{}: must be a lexicon document: lexicon 1, an NSID as its id, and defs", at("lexicons/a.json") ), format!( "{}: place.hud.view is HUD's own lexicon, which no app ships", at("lexicons/b.json") ), format!( "{}: EOF while parsing an object at line 1 column 1", at("lexicons/d.json") ), format!( "{}: another file is example.test.doThing too", at("lexicons/example/test/doThing.json") ), ] ); } }