didbot_schema/

aturi.rs

//! `at://` URIs: the names records answer to.
//!
//! `didbot-pds` stores records and `didbot-serve` hands out URIs for them,
//! and this module reads one back. An AT-URI's three parts belong to three
//! different validators, and this crate is the one that depends on all of
//! them.
//!
//! | Part | Owner |
//! | --- | --- |
//! | authority — a DID or a handle | [`didbot_identity`] |
//! | collection — an NSID | [`didbot_lexicon::nsid_syntax`] |
//! | record key | [`crate::record_key::validate_record_key`] |
//!
//! # Only the restricted form
//!
//! atproto specifies a permissive AT-URI grammar and a restricted one. The
//! restricted form drops query strings and fragments and demands that the
//! collection be a real NSID and the record key a real record key, and it is
//! the only form that appears in lexicons or in repository data. This parser
//! implements that one. A fragment is meaningful when an AT-URI points into a
//! *lexicon* rather than at a record, which nothing here does yet; when that
//! changes it wants its own type, not a looser version of this one.

use didbot_identity::{validate_did, validate_handle};
use didbot_lexicon::nsid_syntax;

use crate::record_key::{validate_record_key, RecordKeyError};

/// The scheme every AT-URI starts with, lowercase and exact.
const AT_SCHEME: &str = "at://";

/// Hard cap on an AT-URI's length, from the atproto specification.
pub const MAX_ATURI_LENGTH: usize = 8 * 1024;

/// Why a string is not a usable `at://` URI.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum AtUriError {
    /// Over [`MAX_ATURI_LENGTH`] bytes.
    #[error("at-uri is {0} bytes, over the limit of {MAX_ATURI_LENGTH}")]
    TooLong(usize),
    /// Does not start with the exact lowercase `at://`.
    #[error("at-uri does not start with `at://`")]
    NotAtScheme,
    /// The authority is neither a valid DID nor a valid handle.
    #[error("at-uri authority {0:?} is neither a did nor a handle")]
    BadAuthority(String),
    /// The collection segment is not a valid NSID.
    #[error("at-uri collection {collection:?} is not an nsid: {source}")]
    BadCollection {
        /// The segment as written.
        collection: String,
        /// Why it is not an NSID.
        #[source]
        source: nsid_syntax::NsidError,
    },
    /// The record key segment is not a valid record key.
    #[error("at-uri record key {rkey:?} is not usable: {source}")]
    BadRecordKey {
        /// The segment as written.
        rkey: String,
        /// Why it is not a record key.
        #[source]
        source: RecordKeyError,
    },
    /// More path segments than `collection/rkey`, or a trailing slash, or an
    /// empty segment. All three arrive here as an empty or extra segment.
    #[error("at-uri has a malformed path: {0:?}")]
    BadPath(String),
    /// A query string or fragment, neither of which the restricted form has.
    #[error("at-uri carries a query or fragment, which the restricted form does not allow")]
    QueryOrFragment,
}

/// A parsed `at://` URI in its restricted form.
///
/// The parts are borrowed from the input, so an `AtUri` never re-renders the
/// string it came from and cannot disagree with it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct AtUri<'a> {
    authority: &'a str,
    collection: Option<&'a str>,
    rkey: Option<&'a str>,
}

impl<'a> AtUri<'a> {
    /// The repository this URI names: a DID or a handle, as written.
    pub fn authority(self) -> &'a str {
        self.authority
    }

    /// The collection, if the URI names one.
    pub fn collection(self) -> Option<&'a str> {
        self.collection
    }

    /// The record key, if the URI names a single record.
    ///
    /// A URI with a collection but no record key names the collection itself,
    /// which is a listing rather than a record.
    pub fn rkey(self) -> Option<&'a str> {
        self.rkey
    }

    /// Parses an `at://` URI.
    ///
    /// ```
    /// use didbot_schema::aturi::AtUri;
    /// let uri = AtUri::parse("at://did:plc:asdf123/com.atproto.feed.post/record")?;
    /// assert_eq!(uri.authority(), "did:plc:asdf123");
    /// assert_eq!(uri.rkey(), Some("record"));
    ///
    /// assert!(AtUri::parse("at://did:plc:asdf123/").is_err()); // trailing slash
    /// assert!(AtUri::parse("at://did:plc:asdf123#").is_err()); // fragment
    /// # Ok::<(), didbot_schema::aturi::AtUriError>(())
    /// ```
    pub fn parse(uri: &'a str) -> Result<Self, AtUriError> {
        if uri.len() > MAX_ATURI_LENGTH {
            return Err(AtUriError::TooLong(uri.len()));
        }
        let rest = uri.strip_prefix(AT_SCHEME).ok_or(AtUriError::NotAtScheme)?;
        // Checked over the whole remainder rather than per segment: a `#` in
        // the authority and a `#` after the record key are the same mistake,
        // and both are excluded from the restricted form outright.
        if rest.contains('#') || rest.contains('?') {
            return Err(AtUriError::QueryOrFragment);
        }

        let mut segments = rest.split('/');
        let authority = segments.next().unwrap_or_default();
        if validate_did(authority).is_err() && validate_handle(authority).is_err() {
            return Err(AtUriError::BadAuthority(authority.to_owned()));
        }

        let collection = segments.next();
        let rkey = segments.next();
        if segments.next().is_some() {
            return Err(AtUriError::BadPath(rest.to_owned()));
        }
        // An empty segment is a trailing slash or a `//`, and neither is a
        // shorter URI that happens to have punctuation on the end: they are
        // different strings naming the same thing, which is what makes a URI
        // stop being an identifier.
        if collection.is_some_and(str::is_empty) || rkey.is_some_and(str::is_empty) {
            return Err(AtUriError::BadPath(rest.to_owned()));
        }

        if let Some(collection) = collection {
            nsid_syntax::validate(collection).map_err(|source| AtUriError::BadCollection {
                collection: collection.to_owned(),
                source,
            })?;
        }
        if let Some(rkey) = rkey {
            validate_record_key(rkey).map_err(|source| AtUriError::BadRecordKey {
                rkey: rkey.to_owned(),
                source,
            })?;
        }

        Ok(Self {
            authority,
            collection,
            rkey,
        })
    }
}