Skip to main content

alien_client_core/
error.rs

1use alien_error::AlienErrorData;
2use serde::{Deserialize, Serialize};
3
4/// Represents common infrastructure errors across multiple cloud platforms.
5#[derive(Debug, Clone, AlienErrorData, Serialize, Deserialize)]
6#[serde(rename_all = "camelCase")]
7pub enum ErrorData {
8    /// Invalid or malformed platform configuration.
9    #[error(
10        code = "INVALID_client_config",
11        message = "Invalid platform configuration: {message}",
12        retryable = "false",
13        internal = "false"
14    )]
15    InvalidClientConfig {
16        /// Human-readable description of the configuration issue
17        message: String,
18        /// Additional error details if available
19        errors: Option<String>,
20    },
21
22    /// Authentication with cloud provider failed.
23    #[error(
24        code = "AUTHENTICATION_ERROR",
25        message = "Authentication failed: {message}",
26        retryable = "true",
27        internal = "false"
28    )]
29    AuthenticationError {
30        /// Human-readable description of the authentication failure
31        message: String,
32    },
33
34    /// The manager answered a runtime credential exchange with a refusal (a 4xx status).
35    ///
36    /// Unlike a transport failure or a server error, asking again gives the same answer until an
37    /// operator changes the grant, so it is not retried.
38    #[error(
39        code = "RUNTIME_AUTHORITY_REFUSED",
40        message = "Runtime authority refused: {message}",
41        retryable = "false",
42        internal = "false"
43    )]
44    RuntimeAuthorityRefused {
45        /// What the manager answered
46        message: String,
47    },
48
49    /// The requested resource does not exist.
50    #[error(
51        code = "REMOTE_RESOURCE_NOT_FOUND",
52        message = "{resource_type} '{resource_name}' not found",
53        retryable = "true",
54        internal = "false",
55        http_status_code = 404
56    )]
57    RemoteResourceNotFound {
58        /// Type of the resource that was not found
59        resource_type: String,
60        /// Name of the resource that was not found
61        resource_name: String,
62    },
63
64    /// An existing cloud object does not belong to the runtime resource being written.
65    #[error(
66        code = "EXISTING_CLOUD_RESOURCE_NOT_OWNED",
67        message = "{object} is not managed by this deployment's runtime resource '{resource_id}'; reconcile ownership in setup before changing it.",
68        retryable = "false",
69        internal = "false",
70        http_status_code = 409
71    )]
72    ExistingCloudResourceNotOwned { resource_id: String, object: String },
73
74    /// Operation conflicts with current resource state (e.g., resource already exists, concurrent modifications, etag mismatch).
75    #[error(
76        code = "REMOTE_RESOURCE_CONFLICT",
77        message = "Conflict with {resource_type} '{resource_name}': {message}",
78        retryable = "true",
79        internal = "false"
80    )]
81    RemoteResourceConflict {
82        /// Type of the resource that has a conflict
83        resource_type: String,
84        /// Name of the resource that has a conflict
85        resource_name: String,
86        /// Human-readable description of the specific conflict
87        message: String,
88    },
89
90    /// Access denied due to insufficient permissions.
91    #[error(
92        code = "REMOTE_ACCESS_DENIED",
93        message = "Access denied to {resource_type} '{resource_name}'",
94        retryable = "true",
95        internal = "false"
96    )]
97    RemoteAccessDenied {
98        /// Type of the resource access was denied to
99        resource_type: String,
100        /// Name of the resource access was denied to
101        resource_name: String,
102    },
103
104    /// Request rate limit exceeded.
105    #[error(
106        code = "RATE_LIMIT_EXCEEDED",
107        message = "Rate limit exceeded: {message}",
108        retryable = "true",
109        internal = "false"
110    )]
111    RateLimitExceeded {
112        /// Human-readable description of the rate limit context
113        message: String,
114    },
115
116    /// Operation exceeded the allowed timeout.
117    #[error(
118        code = "TIMEOUT",
119        message = "Operation timed out: {message}",
120        retryable = "true",
121        internal = "false"
122    )]
123    Timeout {
124        /// Human-readable description of what operation timed out
125        message: String,
126    },
127
128    /// Service is temporarily unavailable.
129    #[error(
130        code = "REMOTE_SERVICE_UNAVAILABLE",
131        message = "Service unavailable: {message}",
132        retryable = "true",
133        internal = "false"
134    )]
135    RemoteServiceUnavailable {
136        /// Human-readable description of the service unavailability
137        message: String,
138    },
139
140    /// Quota or resource limits have been exceeded.
141    #[error(
142        code = "QUOTA_EXCEEDED",
143        message = "Quota exceeded: {message}",
144        retryable = "true",
145        internal = "false"
146    )]
147    QuotaExceeded {
148        /// Human-readable description of what quota was exceeded
149        message: String,
150    },
151
152    /// A resource reached the provider's cap on how many versions it can hold. Waiting does not
153    /// clear it: a version has to be deleted, so a blind retry only repeats the refusal.
154    #[error(
155        code = "VERSION_LIMIT_EXCEEDED",
156        message = "Version limit reached: {message}",
157        retryable = "false",
158        internal = "false"
159    )]
160    VersionLimitExceeded {
161        /// Human-readable description of the limit and the resource that reached it
162        message: String,
163    },
164
165    /// A remote asynchronous operation finished unsuccessfully; its handle cannot recover.
166    /// Retrying the issuing handler can reissue the operation, so preserve executor retries.
167    /// Callers that persist handles must recognize this variant and stop polling the old handle.
168    #[error(
169        code = "REMOTE_OPERATION_FAILED",
170        message = "{operation} for '{resource_name}' finished with status {status}: {message}",
171        retryable = "true",
172        internal = "true"
173    )]
174    RemoteOperationFailed {
175        /// Operation that finished unsuccessfully.
176        operation: String,
177        /// Resource associated with the operation.
178        resource_name: String,
179        /// Terminal status reported by the provider.
180        status: String,
181        /// Provider error code, when supplied.
182        provider_code: Option<String>,
183        /// Provider diagnostics, including its message and any nested error details.
184        message: String,
185    },
186
187    /// Network or request-level failure when sending HTTP request.
188    #[error(
189        code = "HTTP_REQUEST_FAILED",
190        message = "{message}",
191        retryable = "true",
192        internal = "false"
193    )]
194    HttpRequestFailed {
195        /// Human-readable description of the HTTP request failure
196        message: String,
197    },
198
199    /// Body cleanup failed after the service accepted the request.
200    #[error(
201        code = "HTTP_RESPONSE_BODY_READ_FAILED",
202        message = "HTTP {http_status} succeeded, but its response body could not be read",
203        retryable = "false",
204        internal = "false",
205        hint = "The request was already accepted. Check the remote state before retrying."
206    )]
207    HttpResponseBodyReadFailed {
208        /// Successful HTTP status received before the body read failed.
209        http_status: u16,
210    },
211
212    /// HTTP request succeeded but returned a non-success status code.
213    #[error(
214        code = "HTTP_RESPONSE_ERROR",
215        message = "{message}",
216        retryable = "true",
217        internal = "true"
218    )]
219    HttpResponseError {
220        /// Human-readable description of the HTTP response error
221        message: String,
222        /// The URL that returned the error
223        url: String,
224        /// HTTP status code returned
225        http_status: u16,
226        // Request body text
227        http_request_text: Option<String>,
228        /// Response body text if available
229        http_response_text: Option<String>,
230    },
231
232    /// The cloud service rejected the request and returned its own error code and message.
233    ///
234    /// Unlike [`ErrorData::HttpResponseError`], this is safe to show to users: it holds only the
235    /// service's code and message, never the request body or the raw response. Wrap the internal
236    /// `HttpResponseError` with it so those stay available for debugging. Retryability comes from
237    /// that source, because some rejections are transient (for example, an S3 bucket notification
238    /// whose target permission has not propagated yet). Only use it for a service whose error
239    /// messages don't echo submitted values; some APIs repeat request fields, including secrets.
240    #[error(
241        code = "REMOTE_REQUEST_REJECTED",
242        message = "{service} rejected the request ({provider_code}): {message}",
243        retryable = "inherit",
244        internal = "false"
245    )]
246    RemoteRequestRejected {
247        /// Cloud service that rejected the request (e.g. "S3")
248        service: String,
249        /// HTTP status code the service returned
250        http_status: u16,
251        /// The service's error code (e.g. "InvalidArgument")
252        provider_code: String,
253        /// The service's error message
254        message: String,
255    },
256
257    /// Failure during signing of an HTTP request (e.g., AWS SigV4).
258    #[error(
259        code = "REQUEST_SIGN_ERROR",
260        message = "Request signing failed: {message}",
261        retryable = "true",
262        internal = "true"
263    )]
264    RequestSignError {
265        /// Human-readable description of the signing failure
266        message: String,
267    },
268
269    /// Catch-all error
270    #[error(
271        code = "GENERIC_ERROR",
272        message = "{message}",
273        retryable = "true",
274        internal = "true"
275    )]
276    GenericError {
277        /// Human-readable description of the error
278        message: String,
279    },
280
281    /// Invalid or malformed input parameters provided to the operation.
282    #[error(
283        code = "INVALID_INPUT",
284        message = "Invalid input: {message}",
285        retryable = "false",
286        internal = "false"
287    )]
288    InvalidInput {
289        /// Human-readable description of what input was invalid
290        message: String,
291        /// Optional field name that was invalid
292        field_name: Option<String>,
293    },
294
295    /// Failed to serialize or deserialize data.
296    #[error(
297        code = "SERIALIZATION_ERROR",
298        message = "Serialization failed: {message}",
299        retryable = "false",
300        internal = "true"
301    )]
302    SerializationError {
303        /// Human-readable description of the serialization failure
304        message: String,
305    },
306
307    /// Failed to load or parse kubeconfig file.
308    #[error(
309        code = "KUBECONFIG_ERROR",
310        message = "Kubeconfig error: {message}",
311        retryable = "false",
312        internal = "false"
313    )]
314    KubeconfigError {
315        /// Human-readable description of the kubeconfig error
316        message: String,
317    },
318
319    /// Failed to load data from base64 or file.
320    #[error(
321        code = "DATA_LOAD_ERROR",
322        message = "Failed to load data: {message}",
323        retryable = "false",
324        internal = "false"
325    )]
326    DataLoadError {
327        /// Human-readable description of the data loading failure
328        message: String,
329    },
330}
331
332/// Convenient alias with default error type `ErrorData`. Allows callers to override the
333/// error type when needed while still accepting the common single-generic form `Result<T>`.
334pub type Result<T, E = ErrorData> = alien_error::Result<T, E>;
335
336/// Convenience alias representing a constructed AlienError with our `ErrorData` payload.
337pub type Error = alien_error::AlienError<ErrorData>;