chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.4.0 Latest 5 packages
0
0
//! 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<oauth::Auth>,
/// 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<String, Result<String, String>>,
/// DIDs to their documents, or why they cannot be read.
docs: Ttl<String, Result<Arc<Value>, String>>,
/// Lexicons by NSID: each document, or none where it did not resolve.
lexicons: Ttl<String, Option<Arc<Value>>>,
/// Each repository's records of a backlinks join's collection, by
/// `<did> <collection>`, for a short while.
members: Ttl<String, Arc<Vec<pds::Record>>>,
/// The backlink index counts come from, if any.
backlinks: Option<Box<dyn backlinks::Index>>,
/// Targets' counts from it, or none where it failed, for a minute.
counts: Ttl<String, Option<Arc<backlinks::Counts>>>,
/// Feed generators, by their record's at-uri: the service DID that
/// takes their interactions and whether it does, for an hour.
generators: Ttl<String, interactions::Generator>,
/// Each signed-in account's saved feeds, by its DID, for five minutes.
saved_feeds: Ttl<String, Arc<Vec<feeds::SavedFeed>>>,
/// Place searches' answers, by their words, for a day.
places: Ttl<String, Arc<Value>>,
/// 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<xrpc::Asking, (Value, String), tools::Refusal>,
/// The workspace's canvases, kept under `<data_dir>/canvas/`, or with
/// `spaces` on, in people's own spaces where they can be.
pub canvases: canvas::Canvases,
/// Each person's theme, kept under `<data_dir>/theme/`.
pub themes: theme::Choices,
/// The lines logged, kept in `<data_dir>/logs.db` for the operators,
/// with `HUD_LOGS` on.
pub logs: Option<Arc<logs::Logs>>,
}
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<Arc<Hud>, 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<dyn canvas::store::Store> = 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::<Vec<_>>()
.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<Hud> {
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<Hud>, 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);
}
}