chore: atproto-lexicon error management

crates/atproto-lexicon/src/errors.rs

···
+//! Error types for the atproto-lexicon crate.
+//!
+//! This module defines all error types for lexicon operations including resolution,
+//! validation, and schema processing. All errors follow the project's error naming
+//! convention using globally unique identifiers.
+//!
+//! ## Error Categories
+//!
+//! - **`LexiconResolveError`** (lexicon-resolve-1 to lexicon-resolve-6): Errors during lexicon resolution
+//! - **`LexiconValidationError`** (lexicon-validation-1 to lexicon-validation-8): Validation errors for NSIDs and schemas
+//! - **`LexiconSchemaError`** (lexicon-schema-1 to lexicon-schema-4): Schema parsing and structure errors
+//!
+//! ## Error Format
+//!
+//! All errors follow the format: `error-atproto-lexicon-<domain>-<number> <message>: <details>`
+
+use thiserror::Error;
+use atproto_identity::errors::ResolveError;
+
+/// Errors that can occur during lexicon resolution operations.
+#[derive(Debug, Error)]
+pub enum LexiconResolveError {
+    /// No DIDs found when resolving a handle or identifier.
+    #[error("error-atproto-lexicon-resolve-1 No DIDs found for resolution")]
+    NoDIDsFound,
+
+    /// Multiple DIDs found when expecting exactly one.
+    #[error("error-atproto-lexicon-resolve-2 Multiple DIDs found: expected single DID")]
+    MultipleDIDsFound,
+
+    /// Invalid DID format encountered during resolution.
+    #[error("error-atproto-lexicon-resolve-3 Invalid DID format: {did}")]
+    InvalidDIDFormat {
+        /// The invalid DID string
+        did: String,
+    },
+
+    /// No PDS endpoint found in DID document.
+    #[error("error-atproto-lexicon-resolve-4 No PDS endpoint found in DID document")]
+    NoPDSEndpoint,
+
+    /// Failed to fetch lexicon from PDS.
+    #[error("error-atproto-lexicon-resolve-5 Failed to fetch lexicon from PDS: {details}")]
+    PDSFetchFailed {
+        /// Details about the fetch failure
+        details: String,
+    },
+
+    /// Error response from PDS when fetching lexicon.
+    #[error("error-atproto-lexicon-resolve-6 Error fetching lexicon for {nsid}: {message}")]
+    PDSErrorResponse {
+        /// The NSID being fetched
+        nsid: String,
+        /// Error message from PDS
+        message: String,
+    },
+}
+
+/// Errors that can occur during lexicon validation.
+#[derive(Debug, Error)]
+pub enum LexiconValidationError {
+    /// Invalid NSID format.
+    #[error("error-atproto-lexicon-validation-1 Invalid NSID format: {details}")]
+    InvalidNsidFormat {
+        /// Details about what makes the NSID invalid
+        details: String,
+    },
+
+    /// Invalid reference format.
+    #[error("error-atproto-lexicon-validation-2 Invalid reference format: {details}")]
+    InvalidReferenceFormat {
+        /// Details about what makes the reference invalid
+        details: String,
+    },
+
+    /// NSID has insufficient parts (requires at least 3).
+    #[error("error-atproto-lexicon-validation-3 NSID must have at least 3 parts: {nsid}")]
+    InsufficientNsidParts {
+        /// The NSID with insufficient parts
+        nsid: String,
+    },
+
+    /// Cannot convert NSID to DNS name.
+    #[error("error-atproto-lexicon-validation-4 Cannot convert NSID to DNS name: {nsid}")]
+    InvalidDnsNameConversion {
+        /// The NSID that couldn't be converted
+        nsid: String,
+    },
+
+    /// Empty NSID provided.
+    #[error("error-atproto-lexicon-validation-5 Empty NSID provided")]
+    EmptyNsid,
+
+    /// NSID contains empty parts.
+    #[error("error-atproto-lexicon-validation-6 NSID contains empty parts: {nsid}")]
+    EmptyNsidParts {
+        /// The NSID with empty parts
+        nsid: String,
+    },
+
+    /// Invalid NSID character.
+    #[error("error-atproto-lexicon-validation-7 Invalid character in NSID: {details}")]
+    InvalidNsidCharacter {
+        /// Details about the invalid character
+        details: String,
+    },
+
+    /// Invalid NSID in schema ID field.
+    #[error("error-atproto-lexicon-validation-8 Invalid NSID in schema ID field: {id}")]
+    InvalidSchemaId {
+        /// The invalid ID from the schema
+        id: String,
+    },
+}
+
+/// Errors that can occur when processing lexicon schemas.
+#[derive(Debug, Error)]
+pub enum LexiconSchemaError {
+    /// Lexicon schema must be an object.
+    #[error("error-atproto-lexicon-schema-1 Lexicon schema must be an object")]
+    NotAnObject,
+
+    /// Missing required 'lexicon' version field.
+    #[error("error-atproto-lexicon-schema-2 Missing 'lexicon' version field")]
+    MissingLexiconVersion,
+
+    /// Missing or invalid 'id' field.
+    #[error("error-atproto-lexicon-schema-3 Missing or invalid 'id' field")]
+    MissingOrInvalidId,
+
+    /// Missing or invalid 'defs' field.
+    #[error("error-atproto-lexicon-schema-4 Missing or invalid 'defs' field")]
+    MissingOrInvalidDefs,
+}
+
+/// Errors specific to recursive lexicon resolution.
+#[derive(Debug, Error)]
+pub enum LexiconRecursiveError {
+    /// Failed to resolve any lexicons during recursive resolution.
+    #[error("error-atproto-lexicon-recursive-1 Failed to resolve any lexicons")]
+    NoLexiconsResolved,
+}
+
+// Re-export the validation error for backwards compatibility during migration
+pub use LexiconValidationError as ValidationError;
+
+/// Implement conversion from ResolveError to LexiconResolveError.
+impl From<ResolveError> for LexiconResolveError {
+    fn from(err: ResolveError) -> Self {
+        match err {
+            ResolveError::NoDIDsFound => LexiconResolveError::NoDIDsFound,
+            ResolveError::MultipleDIDsFound => LexiconResolveError::MultipleDIDsFound,
+            _ => LexiconResolveError::PDSFetchFailed {
+                details: format!("DNS resolution error: {:?}", err),
+            },
+        }
+    }
+}

crates/atproto-lexicon/src/lib.rs

···
 #![forbid(unsafe_code)]
 #![warn(missing_docs)]
 
+pub mod errors;
 pub mod resolve;
 pub mod resolve_recursive;
 pub mod validation;

crates/atproto-lexicon/src/resolve.rs

···
 //! 4. Extract PDS endpoint from DID document
 //! 5. Make XRPC call to com.atproto.repo.getRecord to fetch lexicon
 
-use anyhow::{anyhow, Result};
+use anyhow::Result;
 use atproto_client::{
     client::Auth,
     com::atproto::repo::{get_record, GetRecordResponse},
 };
 use atproto_identity::{
-    errors::ResolveError,
     resolve::{DnsResolver, resolve_subject},
 };
 use serde_json::Value;
 use tracing::instrument;
 
-use crate::validation;
+use crate::{errors::LexiconResolveError, validation};
 
 /// Trait for lexicon resolution implementations.
 #[async_trait::async_trait]
···
 pub async fn resolve_lexicon_dns<R: DnsResolver + ?Sized>(
     dns_resolver: &R,
     lookup_dns: &str,
-) -> Result<String, ResolveError> {
+) -> Result<String, LexiconResolveError> {
     let txt_records = dns_resolver
         .resolve_txt(lookup_dns)
         .await?;
···
         .collect();
 
     if dids.is_empty() {
-        return Err(ResolveError::NoDIDsFound);
+        return Err(LexiconResolveError::NoDIDsFound);
     }
 
     if dids.len() > 1 {
-        return Err(ResolveError::MultipleDIDsFound);
+        return Err(LexiconResolveError::MultipleDIDsFound);
     }
 
     Ok(dids[0].clone())
···
         InputType::Web(did) => {
             web::query(http_client, &did).await?
         }
-        _ => return Err(anyhow!("Invalid DID format: {}", did)),
+        _ => return Err(LexiconResolveError::InvalidDIDFormat {
+            did: did.to_string(),
+        }.into()),
     };
 
     // Extract PDS endpoint from service array
···
         }
     }
 
-    Err(anyhow!("No PDS endpoint found in DID document"))
+    Err(LexiconResolveError::NoPDSEndpoint.into())
 }
 
 /// Fetch lexicon schema from PDS using XRPC.
···
         None,
     )
     .await
-    .map_err(|e| anyhow!("Failed to fetch lexicon from PDS: {}", e))?;
+    .map_err(|e| LexiconResolveError::PDSFetchFailed {
+        details: e.to_string(),
+    })?;
 
     // Extract the value from the response
     match response {
         GetRecordResponse::Record { value, .. } => Ok(value),
         GetRecordResponse::Error(err) => {
             let msg = err.message.or(err.error_description).or(err.error).unwrap_or_else(|| "Unknown error".to_string());
-            Err(anyhow!("Error fetching lexicon for {}: {}", nsid, msg))
+            Err(LexiconResolveError::PDSErrorResponse {
+                nsid: nsid.to_string(),
+                message: msg,
+            }.into())
         }
     }
 }

crates/atproto-lexicon/src/resolve_recursive.rs

···
 
 use std::collections::{HashMap, HashSet};
 
-use anyhow::{anyhow, Result};
+use anyhow::Result;
 use serde_json::Value;
 use tracing::instrument;
 
+use crate::errors::LexiconRecursiveError;
 use crate::resolve::LexiconResolver;
 use crate::validation::{absolute, extract_nsid_from_ref_object};
 
···
         }
 
         if resolved.is_empty() && self.config.include_entry {
-            return Err(anyhow!("Failed to resolve any lexicons"));
+            return Err(LexiconRecursiveError::NoLexiconsResolved.into());
         }
 
         Ok(resolved)

crates/atproto-lexicon/src/validation.rs

···
 
 use std::fmt;
 
-use anyhow::{anyhow, Result};
+use anyhow::Result;
 use serde_json::Value;
-use thiserror::Error;
 
-/// Errors that can occur during lexicon validation.
-#[derive(Error, Debug)]
-pub enum ValidationError {
-    /// Invalid NSID format.
-    #[error("Invalid NSID format: {0}")]
-    InvalidNsidFormat(String),
-
-    /// Invalid reference format.
-    #[error("Invalid reference format: {0}")]
-    InvalidReferenceFormat(String),
-
-    /// NSID has too few parts.
-    #[error("NSID must have at least 3 parts: {0}")]
-    InsufficientNsidParts(String),
-
-    /// Invalid DNS name conversion.
-    #[error("Cannot convert NSID to DNS name: {0}")]
-    InvalidDnsNameConversion(String),
-}
+use crate::errors::{LexiconSchemaError, LexiconValidationError};
 
 /// Components of a parsed NSID.
 #[derive(Debug, Clone, PartialEq)]
···
 }
 
 impl NsidParts {
-    /// Serializes the NSID parts back to a string.
-    ///
-    /// Joins the parts with dots and appends the fragment with '#' if present.
-    ///
-    /// # Examples
-    /// ```
-    /// use atproto_lexicon::validation::NsidParts;
-    ///
-    /// let parts = NsidParts {
-    ///     parts: vec!["app".to_string(), "bsky".to_string(), "feed".to_string(), "post".to_string()],
-    ///     fragment: None,
-    /// };
-    /// assert_eq!(parts.to_string(), "app.bsky.feed.post");
-    ///
-    /// let parts_with_fragment = NsidParts {
-    ///     parts: vec!["app".to_string(), "bsky".to_string(), "feed".to_string(), "post".to_string()],
-    ///     fragment: Some("reply".to_string()),
-    /// };
-    /// assert_eq!(parts_with_fragment.to_string(), "app.bsky.feed.post#reply");
-    /// ```
-    pub fn to_string(&self) -> String {
-        let base = self.parts.join(".");
-        match &self.fragment {
-            Some(fragment) => format!("{}#{}", base, fragment),
-            None => base,
-        }
-    }
 }
 
 impl fmt::Display for NsidParts {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "{}", self.to_string())
+        let base = self.parts.join(".");
+        match &self.fragment {
+            Some(fragment) => write!(f, "{}#{}", base, fragment),
+            None => write!(f, "{}", base),
+        }
     }
 }
 
···
 
     // Parse the NSID part
     if nsid_part.is_empty() {
-        return Err(ValidationError::InvalidNsidFormat("Empty NSID".to_string()).into());
+        return Err(LexiconValidationError::EmptyNsid.into());
     }
 
     let parts: Vec<String> = nsid_part.split('.').map(|s| s.to_string()).collect();
 
     // Validate parts (at least 3 components for a valid NSID)
     if parts.len() < 3 {
-        return Err(ValidationError::InsufficientNsidParts(nsid.to_string()).into());
+        return Err(LexiconValidationError::InsufficientNsidParts {
+            nsid: nsid.to_string(),
+        }.into());
     }
 
     if parts.iter().any(|p| p.is_empty()) {
-        return Err(ValidationError::InvalidNsidFormat(format!("NSID contains empty parts: {}", nsid)).into());
+        return Err(LexiconValidationError::EmptyNsidParts {
+            nsid: nsid.to_string(),
+        }.into());
     }
 
     // Handle fragment
···
 
     // Need at least 3 parts for a valid NSID (authority + name + record_type)
     if parsed.parts.len() < 3 {
-        return Err(ValidationError::InvalidNsidFormat(
-            format!("NSID must have at least 3 parts: {}", nsid)
-        ).into());
+        return Err(LexiconValidationError::InsufficientNsidParts {
+            nsid: nsid.to_string(),
+        }.into());
     }
 
     // Build DNS name: _lexicon.<name>.<reversed-authority>
···
 /// - Well-formed definitions
 pub fn validate_lexicon_schema(schema: &Value) -> Result<()> {
     let obj = schema.as_object()
-        .ok_or_else(|| anyhow!("Lexicon schema must be an object"))?;
+        .ok_or(LexiconSchemaError::NotAnObject)?;
 
     // Check lexicon version
     if !obj.contains_key("lexicon") {
-        return Err(anyhow!("Missing 'lexicon' version field"));
+        return Err(LexiconSchemaError::MissingLexiconVersion.into());
     }
 
     // Check and validate ID
     let id = obj.get("id")
         .and_then(|v| v.as_str())
-        .ok_or_else(|| anyhow!("Missing or invalid 'id' field"))?;
+        .ok_or(LexiconSchemaError::MissingOrInvalidId)?;
 
     if !is_valid_nsid(id) {
-        return Err(ValidationError::InvalidNsidFormat(id.to_string()).into());
+        return Err(LexiconValidationError::InvalidSchemaId {
+            id: id.to_string(),
+        }.into());
     }
 
     // Check defs exists and is an object
     obj.get("defs")
         .and_then(|v| v.as_object())
-        .ok_or_else(|| anyhow!("Missing or invalid 'defs' field"))?;
+        .ok_or(LexiconSchemaError::MissingOrInvalidDefs)?;
 
     Ok(())
 }