//! HUD's work apart from HTTP: it reads public atproto records from any //! account's PDS and answers the MCP tools with them, and calls services' //! XRPC queries (`xrpc`). An account is //! resolved from its handle or DID to its PDS (`identity`), a record type //! to its lexicon (`lexicon`), and records are read straight from the PDS //! (`pds`), their blobs pointed at the server's own proxy (`blobs`). A view //! (`view`), bundled, its operator's (`operator`) or given inline, says //! how records are drawn: the //! joins that gather their related records (`join`), the summary the tools //! answer with (`summary`), and a layout of components from a fixed //! catalog (`catalog`). Counts of the records across the network that //! point at a record come from a backlink index (`backlinks`). With //! sign-in on (`oauth`), a person signs in with their atproto account, and //! calls made with HUD's token for them are theirs: records written to //! their repository (`writes`), and queries through their PDS; and their //! workspace's canvases, which they and their MCP clients fill (`canvas`), //! kept on the server or, where their PDS and sign-in allow, in spaces of //! their own there (`space`), their tiles marked with their apps' icons //! (`icons`), the workspace drawn in the theme they chose (`theme`). An app //! is the domain behind an NSID (`apps`): an account's profile shows the //! apps it uses. Kept are caches, in memory and on disk, and sign-in's //! sessions, the canvases and the themes chosen on disk; what is kept of a //! person, they may delete (`account`). What the server does is logged as //! JSON lines, each in its request's trace, and counted (`telemetry`), and //! with `HUD_LOGS` kept for its operators to read back (`logs`). #![forbid(unsafe_code)] pub mod account; pub mod apps; pub mod backlinks; pub mod blobcache; pub mod blobs; mod cache; pub mod canvas; pub mod cards; pub mod catalog; pub mod compose; pub mod config; pub mod feeds; pub mod icons; pub mod identity; pub mod interactions; pub mod join; pub mod kit; pub mod lexicon; pub mod logs; pub mod more; pub mod net; pub mod oauth; pub mod operator; pub mod pds; pub mod places; pub mod procedures; pub mod richtext; pub mod schema; pub mod scope; pub mod space; pub mod summary; pub mod telemetry; pub mod theme; pub mod tools; pub mod ui; pub mod uri; pub mod view; pub mod writes; pub mod xrpc; pub use config::Config; use cache::{Shared, Ttl}; use serde_json::Value; use std::sync::Arc; /// The server's state apart from HTTP: its configuration, the outbound /// client, sign-in's state, and the caches of what it looked up. pub struct Hud { pub config: Config, pub net: net::Net, /// Sign-in's state, when it is on. pub oauth: Option, /// Audio blobs on disk, for the proxy's `Range` answers. pub blob_cache: blobcache::BlobCache, /// Handles to the DIDs they resolve to, or why they do not. handles: Ttl>, /// DIDs to their documents, or why they cannot be read. docs: Ttl, String>>, /// Lexicons by NSID: each document, or none where it did not resolve. lexicons: Ttl>>, /// Each repository's records of a backlinks join's collection, by /// ` `, for a short while. members: Ttl>>, /// The backlink index counts come from, if any. backlinks: Option>, /// Targets' counts from it, or none where it failed, for a minute. counts: Ttl>>, /// Feed generators, by their record's at-uri: the service DID that /// takes their interactions and whether it does, for an hour. generators: Ttl, /// Each signed-in account's saved feeds, by its DID, for five minutes. saved_feeds: Ttl>>, /// Place searches' answers, by their words, for a day. places: Ttl>, /// Queries' answers and the hosts that gave them, by what was asked /// and who asked (`xrpc::Asking`), each asked once for all asking at /// once, for seconds. answers: Shared, /// The workspace's canvases, kept under `/canvas/`, or with /// `spaces` on, in people's own spaces where they can be. pub canvases: canvas::Canvases, /// Each person's theme, kept under `/theme/`. pub themes: theme::Choices, /// The lines logged, kept in `/logs.db` for the operators, /// with `HUD_LOGS` on. pub logs: Option>, } impl Hud { /// The server's state, with empty caches. Shared: what keeps canvases /// in spaces calls people's PDSes as them, from tasks of its own. pub fn new(config: Config) -> Result, String> { let net = net::Net::new(config.allow_private); let blob_cache = blobcache::BlobCache::new(config.cache_dir.join("blobs"), config.blob_cache_bytes); let backlinks = backlinks::index(&config.backlinks); let oauth = match config.oauth { true => { let mut auth = oauth::Auth::open( &config.public_origin, &config.oauth_scope, &config.data_dir, )?; auth.client = config.client.clone(); auth.include = config.oauth_include.clone(); Some(auth) } false => None, }; let files = canvas::store::FileStore::new(config.data_dir.join("canvas")); let logs = match config.logs { true => Some(Arc::new(logs::Logs::open( &config.data_dir.join("logs.db"), config.logs_keep, )?)), false => None, }; // Each cache's share of the bytes the caches hold together, in 32nds. let memory = config.cache_memory_bytes; let share = move |n: usize| memory / 32 * n; Ok(Arc::new_cyclic(|hud| { let store: Box = match config.spaces && oauth.is_some() { true => Box::new(canvas::space::SpaceStore::new(hud.clone(), files)), false => Box::new(files), }; Hud { handles: Ttl::new(50_000, share(1)), docs: Ttl::new(50_000, share(4)), lexicons: Ttl::new(10_000, share(6)), members: Ttl::new(1_000, share(9)), counts: Ttl::new(50_000, share(5)), generators: Ttl::new(10_000, share(1)), saved_feeds: Ttl::new(10_000, share(1)), places: Ttl::new(10_000, share(1)), answers: Shared::new(10_000, share(4)), themes: theme::Choices::new(config.data_dir.join("theme")), config, net, oauth, blob_cache, backlinks, canvases: canvas::Canvases::new(store), logs, } })) } /// Each in-memory cache by name: what it holds now, and its hits and /// misses since the start. fn tallies(&self) -> [(&'static str, cache::Held, (u64, u64)); 9] { macro_rules! of { ($($cache:ident),*) => { [$((stringify!($cache), self.$cache.held(), self.$cache.lookups())),*] }; } of!( handles, docs, lexicons, members, counts, generators, saved_feeds, places, answers ) } /// What each in-memory cache holds now, in a line: `name entries/bytes`. pub fn caches(&self) -> String { self.tallies() .iter() .map(|(name, held, _)| format!("{name} {}/{}", held.entries, held.bytes)) .collect::>() .join(", ") } /// Each in-memory cache's hits and misses since the start, by name, for /// `/metrics` and the summary each minute (`telemetry`). pub fn lookups(&self) -> Vec<(&'static str, u64, u64)> { self.tallies() .iter() .map(|(name, _, (hits, misses))| (*name, *hits, *misses)) .collect() } } #[cfg(test)] pub(crate) mod tests { use super::*; /// A server signed out, its files in a directory of its own, private /// addresses allowed, its PLC directory `plc`; its configuration /// changed by `with` first. pub(crate) fn hud_with(plc: &str, with: impl FnOnce(&mut Config)) -> Arc { let dir = std::env::temp_dir().join(format!("hud-test-{}", atproto::jose::random(6))); let mut config = Config { port: 0, bind: "::".parse().unwrap(), public_origin: "https://hud.test".into(), cache_dir: dir.join("cache"), blob_cache_bytes: 0, cache_memory_bytes: 1 << 24, data_dir: dir, oauth: false, oauth_scope: crate::scope::asked(crate::view::views(), true, false), oauth_include: None, workspace: true, sign_up_pds: crate::config::SIGN_UP_PDS.into(), client: Default::default(), spaces: false, plc_url: plc.into(), handle_resolver: None, allow_private: true, backlinks: backlinks::Backlinks::None, favicons: None, image_cdn: None, relay: None, operators: Vec::new(), logs: false, logs_keep: logs::KEEP, }; with(&mut config); Hud::new(config).unwrap() } /// `app` served on a loopback port: its URL. pub(crate) async fn serve(app: axum::Router) -> String { let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); let url = format!("http://{}", listener.local_addr().unwrap()); tokio::spawn(async move { axum::serve(listener, app).await.unwrap() }); url } /// The account tests sign in as. pub(crate) const ALICE: &str = "did:plc:alicealicealicealicealic"; /// A server with sign-in on, its PLC directory `plc`, and alice.test /// signed in at the PDS `pds`, as her account. pub(crate) fn signed_in(plc: &str, pds: &str) -> (Arc, oauth::Account) { let hud = hud_with(plc, |c| c.oauth = true); let auth = hud.oauth.as_ref().unwrap(); let token = auth.signed_in_offline_at(ALICE, Some("alice.test"), false, pds); let account = auth.account(&token).unwrap(); (hud, account) } #[tokio::test] async fn what_the_caches_hold() { let app = axum::Router::new().route( "/{did}", axum::routing::get(|| async { axum::Json(serde_json::json!({ "id": "did:plc:a" })) }), ); let hud = hud_with(&serve(app).await, |_| {}); assert_eq!( hud.caches(), "handles 0/0, docs 0/0, lexicons 0/0, members 0/0, counts 0/0, \ generators 0/0, saved_feeds 0/0, places 0/0, answers 0/0" ); hud.did_doc("did:plc:a").await.unwrap(); let docs = hud.docs.held(); assert_eq!(docs.entries, 1); assert!( hud.caches() .contains(&format!(", docs 1/{}, lexicons 0/0", docs.bytes)) ); // Read again, it is kept: a miss, then a hit. hud.did_doc("did:plc:a").await.unwrap(); assert_eq!(hud.lookups()[1], ("docs", 1, 1)); assert_eq!(hud.lookups()[0], ("handles", 0, 0)); } #[tokio::test] async fn no_sign_in_is_behind_where_sign_in_is_off() { let (_, account) = signed_in("http://127.0.0.1:1", "http://127.0.0.1:1"); let off = hud_with("http://127.0.0.1:1", |_| {}); assert!(!off.behind(&account).await); } }