ave_core/
error.rs

1//! Core API error types.
2//!
3//! These errors are exposed to end users through the API and should provide
4//! clear, actionable error messages.
5
6use thiserror::Error;
7
8/// Core API errors that may be returned to users.
9#[derive(Debug, Clone, Error)]
10pub enum Error {
11    // ========================================
12    // System Initialization Errors
13    // ========================================
14    /// System initialization failed.
15    #[error("System initialization failed: {0}")]
16    SystemInit(String),
17
18    /// Failed to create a required actor.
19    #[error("Failed to initialize {actor}: {reason}")]
20    ActorCreation { actor: String, reason: String },
21
22    /// Required helper or resource not found.
23    #[error("Required resource '{name}' not found: {reason}")]
24    MissingResource { name: String, reason: String },
25
26    // ========================================
27    // Network Errors
28    // ========================================
29    /// Network operation failed.
30    #[error("Network error: {0}")]
31    Network(String),
32
33    /// Unable to retrieve network state.
34    #[error("Unable to retrieve network state: {0}")]
35    NetworkState(String),
36
37    // ========================================
38    // Request Handling Errors
39    // ========================================
40    /// Request could not be processed.
41    #[error("Request processing failed: {0}")]
42    RequestProcessing(String),
43
44    /// Request signature is invalid or verification failed.
45    #[error("Invalid request signature: {0}")]
46    InvalidSignature(String),
47
48    /// Node was unable to sign the request.
49    #[error("Failed to sign request: {0}")]
50    SigningFailed(String),
51
52    /// Request not found in tracking system.
53    #[error("Request '{0}' not found")]
54    RequestNotFound(String),
55
56    /// Request is in an invalid state for this operation.
57    #[error("Request is in invalid state: {0}")]
58    InvalidRequestState(String),
59
60    // ========================================
61    // Approval Errors
62    // ========================================
63    /// Invalid approval state transition.
64    #[error("Invalid approval state: cannot set approval to '{0}'")]
65    InvalidApprovalState(String),
66
67    /// Approval not found for subject.
68    #[error("No approval request found for subject '{0}'")]
69    ApprovalNotFound(String),
70
71    /// Failed to update approval state.
72    #[error("Failed to update approval state: {0}")]
73    ApprovalUpdateFailed(String),
74
75    // ========================================
76    // Subject & Governance Errors
77    // ========================================
78    /// Subject not found.
79    #[error("Subject '{0}' not found")]
80    SubjectNotFound(String),
81
82    /// Subject is not active.
83    #[error("Subject '{0}' is not active")]
84    SubjectNotActive(String),
85
86    /// Governance not found.
87    #[error("Governance '{0}' not found")]
88    GovernanceNotFound(String),
89
90    /// Invalid subject identifier.
91    #[error("Invalid subject identifier: {0}")]
92    InvalidSubjectId(String),
93
94    // ========================================
95    // Authorization Errors
96    // ========================================
97    /// Authorization failed.
98    #[error("Authorization failed: {0}")]
99    Unauthorized(String),
100
101    /// Insufficient permissions for operation.
102    #[error("Insufficient permissions: {0}")]
103    Forbidden(String),
104
105    /// Authentication subject operation failed.
106    #[error("Authentication operation failed: {0}")]
107    AuthOperation(String),
108
109    /// Witnesses not found for subject.
110    #[error("No witnesses found for subject '{0}'")]
111    WitnessesNotFound(String),
112
113    // ========================================
114    // Query Errors
115    // ========================================
116    /// Query execution failed.
117    #[error("Query failed: {0}")]
118    QueryFailed(String),
119
120    /// No events found matching criteria.
121    #[error("No events found for subject '{0}'")]
122    NoEventsFound(String),
123
124    /// Event not found at specified sequence number.
125    #[error("Event not found for subject '{subject}' at sequence number {sn}")]
126    EventNotFound { subject: String, sn: u64 },
127
128    /// Invalid query parameters.
129    #[error("Invalid query parameters: {0}")]
130    InvalidQueryParams(String),
131
132    /// Database query error.
133    #[error("Database error: {0}")]
134    DatabaseError(String),
135
136    // ========================================
137    // Validation Errors
138    // ========================================
139    /// Request validation failed.
140    #[error("Validation failed: {0}")]
141    ValidationFailed(String),
142
143    /// Invalid event request format.
144    #[error("Invalid event request: {0}")]
145    InvalidEventRequest(String),
146
147    /// Schema validation failed.
148    #[error("Schema validation failed: {0}")]
149    SchemaValidation(String),
150
151    // ========================================
152    // Actor Communication Errors
153    // ========================================
154    /// Actor communication failed.
155    #[error("Internal communication error: failed to communicate with {actor}")]
156    ActorCommunication { actor: String },
157
158    /// Received unexpected response from actor.
159    #[error(
160        "Unexpected response from {actor}: expected {expected}, got {received}"
161    )]
162    UnexpectedResponse {
163        actor: String,
164        expected: String,
165        received: String,
166    },
167
168    /// Actor returned an error.
169    #[error("Operation failed: {0}")]
170    ActorError(String),
171
172    // ========================================
173    // Transfer Errors
174    // ========================================
175    /// Subject transfer operation failed.
176    #[error("Transfer operation failed: {0}")]
177    TransferFailed(String),
178
179    /// No pending transfers found.
180    #[error("No pending transfers found")]
181    NoPendingTransfers,
182
183    // ========================================
184    // Distribution Errors
185    // ========================================
186    /// Manual distribution failed.
187    #[error("Manual distribution failed for subject '{0}'")]
188    DistributionFailed(String),
189
190    /// Update operation failed.
191    #[error("Update failed for subject '{0}': {1}")]
192    UpdateFailed(String, String),
193
194    // ========================================
195    // Generic/Fallback Errors
196    // ========================================
197    /// Internal server error (catch-all for unexpected errors).
198    #[error("Internal error: {0}")]
199    Internal(String),
200
201    /// Operation timed out.
202    #[error("Operation timed out: {0}")]
203    Timeout(String),
204
205    /// Feature not implemented.
206    #[error("Feature not implemented: {0}")]
207    NotImplemented(String),
208}
209
210// Conversions from subsystem errors
211impl From<crate::system::SystemError> for Error {
212    fn from(err: crate::system::SystemError) -> Self {
213        Self::SystemInit(err.to_string())
214    }
215}
216
217impl From<ave_actors::ActorError> for Error {
218    fn from(err: ave_actors::ActorError) -> Self {
219        match err {
220            ave_actors::ActorError::NotFound { path } => {
221                Self::MissingResource {
222                    name: path.to_string(),
223                    reason: "Actor not found".to_string(),
224                }
225            }
226            ave_actors::ActorError::Functional { description } => {
227                Self::ActorError(description)
228            }
229            ave_actors::ActorError::FunctionalCritical { description } => {
230                Self::Internal(description)
231            }
232            _ => Self::Internal(err.to_string()),
233        }
234    }
235}
ave_core/error.rs

ave_core/
error.rs
