didbot_lookup/

record.rs

//! How one record in somebody else's repository is addressed.

use std::fmt;

/// What a reader addresses: a DID, a collection, and either one record key
/// or the whole collection.
///
/// The authority is a DID and never a handle. A handle moves between
/// accounts and a preference or a gate belongs to the account rather than
/// to the name it currently answers to, so the cache is keyed by DID
/// throughout and a caller holding a handle resolves it before it gets
/// here.
///
/// A reference with no `rkey` reads the collection, which is what a
/// policy's lookup naming no record key asks for.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct RecordRef {
    /// The repository's DID.
    pub did: String,
    /// The collection (NSID) the record is in.
    pub collection: String,
    /// The record key, or `None` for every record in the collection.
    pub rkey: Option<String>,
}

/// Why a string is not a record this reader can address.
#[derive(Debug, thiserror::Error, Clone, PartialEq, Eq)]
pub enum RefError {
    /// Not an `at://` URI at all.
    #[error("{0:?} does not begin with at://")]
    NotAnAtUri(String),
    /// An `at://` URI naming something other than a record or a
    /// collection: a repository, or a record with something after it.
    #[error(
        "{0:?} names neither a record nor a collection: at://<did>/<collection>/<rkey> is one \
         record, at://<did>/<collection> is a collection"
    )]
    NotOneRecord(String),
    /// The authority is a handle, or something that is not a DID.
    #[error("{0:?} is a handle rather than a DID; resolve it before reading a record at it")]
    NotADid(String),
    /// A segment this reader needs is empty.
    #[error("{0:?} has an empty {1}")]
    Empty(String, &'static str),
}

impl RecordRef {
    /// A reference to `rkey` in `collection` in `did`'s repository.
    pub fn new(
        did: impl Into<String>,
        collection: impl Into<String>,
        rkey: impl Into<String>,
    ) -> Self {
        Self {
            did: did.into(),
            collection: collection.into(),
            rkey: Some(rkey.into()),
        }
    }

    /// A reference to every record in `collection` in `did`'s repository.
    pub fn collection(did: impl Into<String>, collection: impl Into<String>) -> Self {
        Self {
            did: did.into(),
            collection: collection.into(),
            rkey: None,
        }
    }

    /// Whether this names the whole collection rather than one record.
    #[must_use]
    pub fn is_collection(&self) -> bool {
        self.rkey.is_none()
    }

    /// The record, or the collection, an `at://` URI names.
    ///
    /// # Errors
    ///
    /// See [`RefError`]: anything that is neither
    /// `at://<did>/<collection>/<rkey>` nor `at://<did>/<collection>`.
    pub fn parse(at_uri: &str) -> Result<Self, RefError> {
        let rest = at_uri
            .strip_prefix("at://")
            .ok_or_else(|| RefError::NotAnAtUri(at_uri.to_owned()))?;
        let mut parts = rest.split('/');
        let (Some(authority), Some(collection), rkey, None) =
            (parts.next(), parts.next(), parts.next(), parts.next())
        else {
            return Err(RefError::NotOneRecord(at_uri.to_owned()));
        };
        if !authority.starts_with("did:") {
            return Err(RefError::NotADid(at_uri.to_owned()));
        }
        for (segment, name) in [(authority, "did"), (collection, "collection")]
            .into_iter()
            .chain(rkey.map(|rkey| (rkey, "rkey")))
        {
            if segment.is_empty() {
                return Err(RefError::Empty(at_uri.to_owned(), name));
            }
        }
        Ok(Self {
            did: authority.to_owned(),
            collection: collection.to_owned(),
            rkey: rkey.map(str::to_owned),
        })
    }

    /// The `at://` URI for this reference, which is also its cache key.
    pub fn at_uri(&self) -> String {
        self.to_string()
    }
}

impl fmt::Display for RecordRef {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "at://{}/{}", self.did, self.collection)?;
        match &self.rkey {
            Some(rkey) => write!(f, "/{rkey}"),
            None => Ok(()),
        }
    }
}

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

    #[test]
    fn an_at_uri_round_trips_through_a_reference() {
        let uri = "at://did:plc:abcdefghijklmnopqrstuvwx/app.bsky.feed.threadgate/3kabc";
        let parsed = RecordRef::parse(uri).expect("one record");
        assert_eq!(parsed.did, "did:plc:abcdefghijklmnopqrstuvwx");
        assert_eq!(parsed.collection, "app.bsky.feed.threadgate");
        assert_eq!(parsed.rkey.as_deref(), Some("3kabc"));
        assert_eq!(parsed.at_uri(), uri);
        assert!(!parsed.is_collection());
    }

    /// A two-segment at-uri is the collection, which is a different request
    /// to a different XRPC method -- not a record at an empty key.
    #[test]
    fn a_collection_uri_round_trips_through_a_reference() {
        let uri = "at://did:plc:abcdefghijklmnopqrstuvwx/community.lexicon.preference.ai";
        let parsed = RecordRef::parse(uri).expect("one collection");
        assert_eq!(parsed.rkey, None);
        assert!(parsed.is_collection());
        assert_eq!(parsed.at_uri(), uri);
        assert_eq!(
            RecordRef::collection(
                "did:plc:abcdefghijklmnopqrstuvwx",
                "community.lexicon.preference.ai"
            ),
            parsed
        );
    }

    /// Each of these names neither a record nor a collection, and the
    /// reader has to tell them apart from something it could go and fetch.
    #[test]
    fn nothing_but_one_record_or_collection_parses() {
        for (uri, expected) in [
            (
                "https://example.test/x",
                RefError::NotAnAtUri("https://example.test/x".to_owned()),
            ),
            (
                "at://did:plc:abc/app.bsky.feed.post/3k/extra",
                RefError::NotOneRecord("at://did:plc:abc/app.bsky.feed.post/3k/extra".to_owned()),
            ),
            (
                "at://alice.example/app.bsky.feed.post/3k",
                RefError::NotADid("at://alice.example/app.bsky.feed.post/3k".to_owned()),
            ),
            (
                "at://did:plc:abc/app.bsky.feed.post/",
                RefError::Empty("at://did:plc:abc/app.bsky.feed.post/".to_owned(), "rkey"),
            ),
        ] {
            assert_eq!(RecordRef::parse(uri), Err(expected), "{uri}");
        }
    }
}