ave_actors_actor/
error.rs

1//! # Errors module
2//!
3//! This module defines error types for the actor system using `thiserror`.
4
5use crate::ActorPath;
6use thiserror::Error;
7
8/// Error type for the actor system.
9#[derive(Clone, Debug, Error, PartialEq, Eq)]
10pub enum Error {
11    // ===== Actor Lifecycle Errors =====
12    /// Actor already exists at the specified path.
13    ///
14    /// This error indicates an attempt to create an actor at a path
15    /// that is already occupied.
16    #[error("actor '{path}' already exists")]
17    Exists {
18        /// The path where the actor already exists.
19        path: ActorPath,
20    },
21
22    /// Actor not found at the specified path.
23    ///
24    /// This error indicates that no actor exists at the requested path.
25    #[error("actor '{path}' not found")]
26    NotFound {
27        /// The path where the actor was expected but not found.
28        path: ActorPath,
29    },
30
31    /// Actor creation was attempted while the system was stopping or already stopped.
32    #[error("actor system is stopping or stopped")]
33    SystemStopped,
34
35    // ===== Message Passing Errors =====
36    /// Failed to send a message to an actor.
37    ///
38    /// This error occurs when a message cannot be delivered to an actor's mailbox.
39    #[error("failed to send message: {reason}")]
40    Send {
41        /// The reason why message sending failed.
42        reason: String,
43    },
44
45    /// Actor returned an unexpected response type.
46    ///
47    /// This error occurs when an actor's response doesn't match the expected type.
48    #[error(
49        "actor '{path}' returned unexpected response, expected: {expected}"
50    )]
51    UnexpectedResponse {
52        /// The path of the actor that sent the unexpected response.
53        path: ActorPath,
54        /// Description of the expected response type.
55        expected: String,
56    },
57
58    /// Failed to send an event to the event bus.
59    ///
60    /// This error occurs when an event cannot be published to the event bus.
61    #[error("failed to send event to event bus: {reason}")]
62    SendEvent {
63        /// The reason why event sending failed.
64        reason: String,
65    },
66
67    /// A store operation failed.
68    ///
69    /// This error covers various store operations that don't fit into
70    /// more specific error categories.
71    #[error("store operation '{operation}' failed: {reason}")]
72    StoreOperation {
73        /// The operation that was being performed.
74        operation: String,
75        /// The reason why the operation failed.
76        reason: String,
77    },
78
79    // ===== Helper Errors =====
80    /// Failed to access a helper.
81    ///
82    /// This error occurs when a required helper cannot be accessed.
83    #[error("failed to access helper '{name}': {reason}")]
84    Helper {
85        /// The name of the helper that could not be accessed.
86        name: String,
87        /// The reason why helper access failed.
88        reason: String,
89    },
90
91    /// Maximum number of retry attempts reached.
92    ///
93    /// This error occurs when an operation has been retried the maximum
94    /// allowed number of times without success.
95    #[error("maximum retry attempts reached")]
96    Retry,
97
98    // ===== Shutdown Errors =====
99    /// The actor was stopped before processing this message.
100    ///
101    /// This error occurs when an actor is shutting down and discards
102    /// non-critical messages from its mailbox.
103    #[error("actor stopped before processing message")]
104    ActorStopped,
105
106    /// The ask request timed out before the actor responded.
107    #[error("ask timed out after {ms}ms")]
108    Timeout {
109        /// Duration waited in milliseconds.
110        ms: u128,
111    },
112
113    // ===== Functional Errors =====
114    /// A recoverable functional error.
115    ///
116    /// This error indicates a problem that doesn't compromise the system's
117    /// overall operation and may be recoverable.
118    #[error("{description}")]
119    Functional {
120        /// Description of the functional error.
121        description: String,
122    },
123
124    /// A critical functional error.
125    ///
126    /// This error indicates a problem that compromises the system's operation
127    /// and requires intervention.
128    #[error("{description}")]
129    FunctionalCritical {
130        /// Description of the critical error.
131        description: String,
132    },
133}
ave_actors_actor/error.rs

ave_actors_actor/
error.rs
