alien_commands/
error.rs

1use alien_error::{AlienError, AlienErrorData};
2use serde::{Deserialize, Serialize};
3
4/// Errors that occur in the Alien Remote Call (ARC) protocol.
5#[derive(Debug, Clone, AlienErrorData, Serialize, Deserialize)]
6#[serde(rename_all = "camelCase")]
7pub enum ErrorData {
8    /// Command validation failed or contains invalid data.
9    #[error(
10        code = "INVALID_COMMAND",
11        message = "Invalid command: {message}",
12        retryable = "false",
13        internal = "false",
14        http_status_code = 400
15    )]
16    InvalidCommand {
17        /// Human-readable description of what makes the command invalid
18        message: String,
19    },
20
21    /// Requested ARC command ID was not found.
22    #[error(
23        code = "COMMAND_NOT_FOUND",
24        message = "Command '{command_id}' not found",
25        retryable = "false",
26        internal = "false",
27        http_status_code = 404
28    )]
29    CommandNotFound {
30        /// ID of the command that was not found
31        command_id: String,
32    },
33
34    /// Invalid state transition attempted on command.
35    #[error(
36        code = "INVALID_STATE_TRANSITION",
37        message = "Invalid state transition from '{from}' to '{to}'",
38        retryable = "false",
39        internal = "false",
40        http_status_code = 400
41    )]
42    InvalidStateTransition {
43        /// Current state of the command
44        from: String,
45        /// Attempted new state
46        to: String,
47    },
48
49    /// Command has expired and can no longer be processed.
50    #[error(
51        code = "COMMAND_EXPIRED",
52        message = "Command '{command_id}' has expired",
53        retryable = "false",
54        internal = "false",
55        http_status_code = 410
56    )]
57    CommandExpired {
58        /// ID of the expired command
59        command_id: String,
60    },
61
62    /// Storage backend operation failed.
63    #[error(
64        code = "STORAGE_OPERATION_FAILED",
65        message = "Storage operation failed: {message}",
66        retryable = "true",
67        internal = "false"
68    )]
69    StorageOperationFailed {
70        /// Human-readable description of the storage failure
71        message: String,
72        /// Storage operation type (upload, download, etc.)
73        operation: Option<String>,
74        /// Storage path or URL that failed
75        path: Option<String>,
76    },
77
78    /// Key-value store operation failed.
79    #[error(
80        code = "KV_OPERATION_FAILED",
81        message = "KV operation '{operation}' failed on key '{key}': {message}",
82        retryable = "true",
83        internal = "false"
84    )]
85    KvOperationFailed {
86        /// Type of KV operation that failed
87        operation: String,
88        /// Key that was being operated on
89        key: String,
90        /// Human-readable description of the failure
91        message: String,
92    },
93
94    /// Transport dispatch to agent failed.
95    #[error(
96        code = "TRANSPORT_DISPATCH_FAILED",
97        message = "Transport dispatch failed: {message}",
98        retryable = "true",
99        internal = "false"
100    )]
101    TransportDispatchFailed {
102        /// Human-readable description of the dispatch failure
103        message: String,
104        /// Transport type that failed
105        transport_type: Option<String>,
106        /// Target endpoint or agent identifier
107        target: Option<String>,
108    },
109
110    /// ARC envelope validation or parsing failed.
111    #[error(
112        code = "INVALID_ENVELOPE",
113        message = "Invalid ARC envelope: {message}",
114        retryable = "false",
115        internal = "false",
116        http_status_code = 400
117    )]
118    InvalidEnvelope {
119        /// Human-readable description of the envelope issue
120        message: String,
121        /// Envelope field that caused the validation failure
122        field: Option<String>,
123    },
124
125    /// Agent reported an error during command processing.
126    #[error(
127        code = "AGENT_ERROR",
128        message = "Agent error: {message}",
129        retryable = "true",
130        internal = "false"
131    )]
132    AgentError {
133        /// Human-readable description of the agent error
134        message: String,
135        /// Agent identifier if available
136        deployment_id: Option<String>,
137    },
138
139    /// Serialization or deserialization operation failed.
140    #[error(
141        code = "SERIALIZATION_FAILED",
142        message = "Serialization failed: {message}",
143        retryable = "false",
144        internal = "true"
145    )]
146    SerializationFailed {
147        /// Human-readable description of the serialization failure
148        message: String,
149        /// Data type that failed to serialize/deserialize
150        data_type: Option<String>,
151    },
152
153    /// HTTP operation failed during command processing.
154    #[error(
155        code = "HTTP_OPERATION_FAILED",
156        message = "HTTP operation failed: {message}",
157        retryable = "true",
158        internal = "false"
159    )]
160    HttpOperationFailed {
161        /// Human-readable description of the HTTP failure
162        message: String,
163        /// HTTP method if available
164        method: Option<String>,
165        /// URL that failed if available
166        url: Option<String>,
167    },
168
169    /// Operation is not supported by the current configuration.
170    #[error(
171        code = "OPERATION_NOT_SUPPORTED",
172        message = "Operation not supported: {message}",
173        retryable = "false",
174        internal = "false",
175        http_status_code = 501
176    )]
177    OperationNotSupported {
178        /// Human-readable description of what operation is not supported
179        message: String,
180        /// Operation type that was attempted
181        operation: Option<String>,
182    },
183
184    /// Resource conflict detected (e.g., concurrent modification).
185    #[error(
186        code = "CONFLICT",
187        message = "Conflict: {message}",
188        retryable = "true",
189        internal = "false",
190        http_status_code = 409
191    )]
192    Conflict {
193        /// Human-readable description of the conflict
194        message: String,
195        /// Resource identifier that has the conflict
196        resource_id: Option<String>,
197    },
198
199    /// Requested lease ID was not found.
200    #[error(
201        code = "LEASE_NOT_FOUND",
202        message = "Lease '{lease_id}' not found",
203        retryable = "false",
204        internal = "false",
205        http_status_code = 404
206    )]
207    LeaseNotFound {
208        /// ID of the lease that was not found
209        lease_id: String,
210    },
211
212    /// Generic ARC error for uncommon cases.
213    #[error(
214        code = "ARC_ERROR",
215        message = "ARC protocol error: {message}",
216        retryable = "true",
217        internal = "true"
218    )]
219    Other {
220        /// Human-readable description of the error
221        message: String,
222    },
223}
224
225pub type Error = AlienError<ErrorData>;
226pub type Result<T> = alien_error::Result<T, ErrorData>;
alien_commands/error.rs

alien_commands/
error.rs
