~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
308 lines · 11.7 KB Raw History
//! 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);
    }
}