atlas_common/
error.rs

1//! Error types for Atlas Core
2//!
3//! This module defines the error types used throughout the Atlas Core library.
4//! All errors are unified under a single `Error` enum for consistent error handling.
5use thiserror::Error;
6
7/// Main error type for Atlas Core operations
8///
9/// This enum represents all possible errors that can occur in the Atlas Core library.
10/// It uses the `thiserror` crate for automatic `Error` trait implementation.
11#[derive(Error, Debug)]
12pub enum Error {
13    /// I/O operation error
14    #[error("IO error: {0}")]
15    Io(#[from] std::io::Error),
16
17    /// Storage backend error
18    #[error("Storage error: {0}")]
19    Storage(String),
20
21    /// Validation error for invalid data or formats
22    #[error("Validation error: {0}")]
23    Validation(String),
24
25    /// Hash operation or verification error
26    #[error("Hash error: {0}")]
27    Hash(String),
28
29    /// Serialization/deserialization error
30    #[error("Serialization error: {0}")]
31    Serialization(String),
32
33    /// Hex decoding error (only with `hash` feature)
34    #[cfg(feature = "hash")]
35    #[error("Hex decode error: {0}")]
36    HexDecode(#[from] hex::FromHexError),
37
38    /// JSON processing error
39    #[error("JSON error: {0}")]
40    Json(#[from] serde_json::Error),
41
42    /// Time/datetime related error
43    #[error("Time error: {0}")]
44    Time(String),
45
46    /// Resource not found error
47    #[error("Not found: {0}")]
48    NotFound(String),
49
50    /// Resource already exists error
51    #[error("Already exists: {0}")]
52    AlreadyExists(String),
53
54    /// Invalid format error
55    #[error("Invalid format: {0}")]
56    InvalidFormat(String),
57
58    /// Unsupported operation error
59    #[error("Unsupported operation: {0}")]
60    Unsupported(String),
61}
62
63/// Result type alias for Atlas Core operations
64///
65/// This type alias provides a convenient way to return results from Atlas Core functions.
66///
67/// # Example
68///
69/// ```rust
70/// use atlas_common::Result;
71///
72/// fn process_data() -> Result<String> {
73///     Ok("processed".to_string())
74/// }
75/// ```
76pub type Result<T> = std::result::Result<T, Error>;
77
78impl Error {
79    /// Check if the error is retriable
80    ///
81    /// Returns `true` for transient errors that might succeed on retry,
82    /// such as I/O or storage errors.
83    ///
84    /// # Example
85    ///
86    /// ```rust
87    /// use atlas_common::Error;
88    ///
89    /// let error = Error::Io(std::io::Error::new(
90    ///     std::io::ErrorKind::TimedOut,
91    ///     "timeout"
92    /// ));
93    /// assert!(error.is_retriable());
94    /// ```
95    pub fn is_retriable(&self) -> bool {
96        matches!(self, Error::Io(_) | Error::Storage(_))
97    }
98
99    /// Get a stable error code for API responses
100    ///
101    /// Returns a constant string identifier for each error variant,
102    /// useful for API error responses.
103    ///
104    /// # Example
105    ///
106    /// ```rust
107    /// use atlas_common::Error;
108    ///
109    /// let error = Error::NotFound("manifest".to_string());
110    /// assert_eq!(error.error_code(), "NOT_FOUND");
111    /// ```
112    pub fn error_code(&self) -> &'static str {
113        match self {
114            Error::Io(_) => "IO_ERROR",
115            Error::Storage(_) => "STORAGE_ERROR",
116            Error::Validation(_) => "VALIDATION_ERROR",
117            Error::Hash(_) => "HASH_ERROR",
118            Error::Serialization(_) => "SERIALIZATION_ERROR",
119            #[cfg(feature = "hash")]
120            Error::HexDecode(_) => "HEX_DECODE_ERROR",
121            Error::Json(_) => "JSON_ERROR",
122            Error::Time(_) => "TIME_ERROR",
123            Error::NotFound(_) => "NOT_FOUND",
124            Error::AlreadyExists(_) => "ALREADY_EXISTS",
125            Error::InvalidFormat(_) => "INVALID_FORMAT",
126            Error::Unsupported(_) => "UNSUPPORTED",
127        }
128    }
129}
atlas_common/error.rs

atlas_common/
error.rs
