didbot_lexicon/

lexicon.rs

//! The lexicon documents this project defines, embedded in the binary.
//!
//! The JSON under `lexicons/` is the source of truth for the record shapes
//! this project defines and for the `bot.did.*` XRPC methods its server
//! answers. It is compiled in with [`include_str!`] rather than read from disk so that a
//! deployed binary cannot disagree with the schemas it was built from, and so
//! that the consistency checks below run as ordinary unit tests.
//!
//! This module deliberately does not validate *records* or *responses*. It
//! validates that the schema documents themselves are well formed and that
//! their identifiers agree with their paths and with [`crate::nsid`]. Record
//! validation belongs with the repository layer, against a real lexicon
//! resolver; a route's answer is checked against its document by
//! `crates/didbot/tests/conformance/bot_did.rs`.

use serde::{Deserialize, Deserializer};

use crate::nsid_syntax;

/// A lexicon document as published under `lexicons/`.
#[derive(Debug, Clone, Deserialize)]
pub struct LexiconDoc {
    /// Lexicon language version. Always `1` today.
    pub lexicon: u32,
    /// The NSID this document defines.
    ///
    /// Checked against [`nsid_syntax::validate`] while deserializing, so a
    /// `LexiconDoc` that exists at all names something that could be a
    /// lexicon somewhere in atproto. Upstream's `lexicon-invalid.json`
    /// carries `"id": "one-two-three"` for exactly this.
    #[serde(deserialize_with = "nsid_id")]
    pub id: String,
    /// Human-readable description of the document as a whole.
    #[serde(default)]
    pub description: Option<String>,
    /// The definitions in this document, keyed by name. `main` is the primary.
    pub defs: serde_json::Map<String, serde_json::Value>,
}

/// Deserializes a document `id`, refusing anything that is not an NSID.
fn nsid_id<'de, D: Deserializer<'de>>(deserializer: D) -> Result<String, D::Error> {
    let id = String::deserialize(deserializer)?;
    nsid_syntax::validate(&id).map_err(serde::de::Error::custom)?;
    Ok(id)
}

impl LexiconDoc {
    /// The primary definition, if this document has one.
    pub fn main(&self) -> Option<&serde_json::Value> {
        self.defs.get("main")
    }

    /// The `type` of the primary definition, for example `record` or `query`.
    pub fn main_type(&self) -> Option<&str> {
        self.main()?.get("type")?.as_str()
    }

    /// The record key strategy, for a document whose primary def is a record.
    pub fn record_key(&self) -> Option<&str> {
        self.main()?.get("key")?.as_str()
    }
}

/// Failure to load one of the embedded lexicon documents.
#[derive(Debug, thiserror::Error)]
pub enum LexiconError {
    /// The document is not valid JSON, or does not match [`LexiconDoc`].
    #[error("lexicon {path} did not parse: {source}")]
    Parse {
        /// Path the document was embedded from.
        path: &'static str,
        /// The underlying serde error.
        #[source]
        source: serde_json::Error,
    },
}

/// One embedded lexicon: the path it came from and its raw JSON text.
#[derive(Debug, Clone, Copy)]
pub struct Embedded {
    /// Repository-relative path, used in error messages and path/id checks.
    pub path: &'static str,
    /// The raw document text.
    pub source: &'static str,
}

impl Embedded {
    /// Parses this document.
    pub fn parse(&self) -> Result<LexiconDoc, LexiconError> {
        serde_json::from_str(self.source).map_err(|source| LexiconError::Parse {
            path: self.path,
            source,
        })
    }
}

macro_rules! embed {
    ($($path:literal),* $(,)?) => {
        /// Every lexicon document this project defines.
        pub const EMBEDDED: &[Embedded] = &[
            $(Embedded { path: concat!("lexicons/", $path), source: include_str!(concat!("../../../lexicons/", $path)) }),*
        ];
    };
}

embed! {
    "bot/did/registration.json",
    "bot/did/operator.json",
    "bot/did/credential.json",
    "bot/did/policy.json",
    "bot/did/policyBinding.json",
    "bot/did/activateAccount.json",
    "bot/did/approveAuthorization.json",
    "bot/did/createAccount.json",
    "bot/did/createBrowserSignIn.json",
    "bot/did/createSession.json",
    "bot/did/deactivateAccount.json",
    "bot/did/declineAuthorization.json",
    "bot/did/deleteAccount.json",
    "bot/did/describeParkedKey.json",
    "bot/did/freezeAccount.json",
    "bot/did/getAccountLedger.json",
    "bot/did/getAuthorization.json",
    "bot/did/listAccountLedgers.json",
    "bot/did/listAccounts.json",
    "bot/did/listPendingAuthorizations.json",
    "bot/did/parkKey.json",
    "bot/did/pollOperatorClaim.json",
    "bot/did/stats.json",
    "bot/did/unfreezeAccount.json",
    "bot/did/updateCredentials.json",
}

/// Parses every embedded document.
///
/// ```
/// let docs = didbot_lexicon::lexicon::load_all().expect("embedded lexicons parse");
/// assert_eq!(docs.len(), 25);
/// ```
pub fn load_all() -> Result<Vec<LexiconDoc>, LexiconError> {
    EMBEDDED.iter().map(Embedded::parse).collect()
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::nsid;

    fn docs() -> Vec<LexiconDoc> {
        load_all().expect("every embedded lexicon parses")
    }

    #[test]
    fn every_document_declares_lexicon_version_one() {
        for doc in docs() {
            assert_eq!(doc.lexicon, 1, "{} declares an unexpected version", doc.id);
        }
    }

    #[test]
    fn document_id_matches_its_path() {
        // lexicons/bot/did/operator.json must declare
        // id = bot.did.operator. A mismatch here is the failure
        // mode where a resolver fetches one schema and gets another.
        for embedded in EMBEDDED {
            let doc = embedded.parse().expect("parses");
            let expected = embedded
                .path
                .trim_start_matches("lexicons/")
                .trim_end_matches(".json")
                .replace('/', ".");
            assert_eq!(doc.id, expected, "id/path mismatch at {}", embedded.path);
        }
    }

    #[test]
    fn every_document_id_is_a_known_nsid() {
        let mut ids: Vec<String> = docs().into_iter().map(|d| d.id).collect();
        ids.sort();
        let mut known: Vec<String> = nsid::ALL
            .iter()
            .chain(nsid::METHODS)
            .map(|s| s.to_string())
            .collect();
        known.sort();
        assert_eq!(
            ids, known,
            "lexicons/ and nsid::ALL + nsid::METHODS disagree"
        );
    }

    #[test]
    fn every_document_has_a_main_definition() {
        for doc in docs() {
            assert!(doc.main().is_some(), "{} has no main def", doc.id);
        }
    }

    #[test]
    fn every_primary_def_is_a_record_a_query_or_a_procedure() {
        for doc in docs() {
            let kind = doc
                .main_type()
                .unwrap_or_else(|| panic!("{} has no primary type", doc.id));
            assert!(
                matches!(kind, "record" | "query" | "procedure"),
                "{} is a {kind}, which this project does not define",
                doc.id
            );
        }
    }

    #[test]
    fn every_record_declares_a_known_key_strategy() {
        for doc in docs()
            .iter()
            .filter(|doc| doc.main_type() == Some("record"))
        {
            let key = doc
                .record_key()
                .unwrap_or_else(|| panic!("{} has no key", doc.id));
            assert!(
                key == "tid" || key == "any" || key.starts_with("literal:"),
                "{} uses an unrecognized record key strategy: {key}",
                doc.id
            );
        }
    }

    /// A method document's `id` is what a route is reached at, and the
    /// verb decides whether the route is a GET or a POST. Both are read
    /// off the document by `crates/didbot/tests/conformance/bot_did.rs`,
    /// so a document whose kind disagrees with its route drives the wrong
    /// request there; this is the same fact checked without a server.
    #[test]
    fn every_method_document_is_one_of_the_method_nsids() {
        let mut ids: Vec<String> = docs()
            .iter()
            .filter(|doc| matches!(doc.main_type(), Some("query" | "procedure")))
            .map(|doc| doc.id.clone())
            .collect();
        ids.sort();
        let mut known: Vec<String> = nsid::METHODS.iter().map(|s| s.to_string()).collect();
        known.sort();
        assert_eq!(ids, known);
    }

    /// Every schema a definition carries that can hold properties: a
    /// record's body, a method's parameters, its request and its response,
    /// and a plain definition, which is a schema itself.
    fn schemas_of(def: &serde_json::Value) -> Vec<&serde_json::Value> {
        let body = |name: &str| def.get(name).and_then(|body| body.get("schema"));
        [
            def.get("record"),
            def.get("parameters"),
            body("input"),
            body("output"),
        ]
        .into_iter()
        .flatten()
        .chain(def.get("properties").map(|_| def))
        .collect()
    }

    /// Every property of `schema`, and of every object nested in it, carries
    /// a description.
    fn describes_every_property(id: &str, def: &str, schema: &serde_json::Value) {
        let Some(properties) = schema.get("properties").and_then(|p| p.as_object()) else {
            return;
        };
        for (field, property) in properties {
            assert!(
                property
                    .get("description")
                    .and_then(|d| d.as_str())
                    .is_some(),
                "{id}#{def}.{field} has no description"
            );
            if let Some(items) = property.get("items") {
                describes_every_property(id, def, items);
            }
            describes_every_property(id, def, property);
        }
    }

    #[test]
    fn every_definition_and_every_field_is_described() {
        // Descriptions are what a consent screen and an external reader see.
        // An undescribed field is a field nobody outside this repo can use.
        // The top-level `description` is optional in the specification and is
        // not required here; the primary def carries the document's meaning.
        for doc in docs() {
            for (name, def) in &doc.defs {
                assert!(
                    def.get("description").and_then(|d| d.as_str()).is_some(),
                    "{}#{name} has no description",
                    doc.id
                );
                for schema in schemas_of(def) {
                    describes_every_property(&doc.id, name, schema);
                }
            }
        }
    }

    #[test]
    fn the_singleton_records_use_literal_self() {
        // A registration is one-per-account by design. A tid key there would
        // silently permit two of them.
        for doc in docs() {
            if doc.id == nsid::REGISTRATION {
                assert_eq!(doc.record_key(), Some("literal:self"), "{}", doc.id);
            }
        }
    }
}