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