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 remote asynchronous operation finished unsuccessfully; its handle cannot recover.
138    /// Retrying the issuing handler can reissue the operation, so preserve executor retries.
139    /// Callers that persist handles must recognize this variant and stop polling the old handle.
140    #[error(
141        code = "REMOTE_OPERATION_FAILED",
142        message = "{operation} for '{resource_name}' finished with status {status}: {message}",
143        retryable = "true",
144        internal = "true"
145    )]
146    RemoteOperationFailed {
147        /// Operation that finished unsuccessfully.
148        operation: String,
149        /// Resource associated with the operation.
150        resource_name: String,
151        /// Terminal status reported by the provider.
152        status: String,
153        /// Provider error code, when supplied.
154        provider_code: Option<String>,
155        /// Provider diagnostics, including its message and any nested error details.
156        message: String,
157    },
158
159    /// Network or request-level failure when sending HTTP request.
160    #[error(
161        code = "HTTP_REQUEST_FAILED",
162        message = "{message}",
163        retryable = "true",
164        internal = "false"
165    )]
166    HttpRequestFailed {
167        /// Human-readable description of the HTTP request failure
168        message: String,
169    },
170
171    /// Body cleanup failed after the service accepted the request.
172    #[error(
173        code = "HTTP_RESPONSE_BODY_READ_FAILED",
174        message = "HTTP {http_status} succeeded, but its response body could not be read",
175        retryable = "false",
176        internal = "false",
177        hint = "The request was already accepted. Check the remote state before retrying."
178    )]
179    HttpResponseBodyReadFailed {
180        /// Successful HTTP status received before the body read failed.
181        http_status: u16,
182    },
183
184    /// HTTP request succeeded but returned a non-success status code.
185    #[error(
186        code = "HTTP_RESPONSE_ERROR",
187        message = "{message}",
188        retryable = "true",
189        internal = "true"
190    )]
191    HttpResponseError {
192        /// Human-readable description of the HTTP response error
193        message: String,
194        /// The URL that returned the error
195        url: String,
196        /// HTTP status code returned
197        http_status: u16,
198        // Request body text
199        http_request_text: Option<String>,
200        /// Response body text if available
201        http_response_text: Option<String>,
202    },
203
204    /// The cloud service rejected the request and returned its own error code and message.
205    ///
206    /// Unlike [`ErrorData::HttpResponseError`], this is safe to show to users: it holds only the
207    /// service's code and message, never the request body or the raw response. Wrap the internal
208    /// `HttpResponseError` with it so those stay available for debugging. Retryability comes from
209    /// that source, because some rejections are transient (for example, an S3 bucket notification
210    /// whose target permission has not propagated yet). Only use it for a service whose error
211    /// messages don't echo submitted values; some APIs repeat request fields, including secrets.
212    #[error(
213        code = "REMOTE_REQUEST_REJECTED",
214        message = "{service} rejected the request ({provider_code}): {message}",
215        retryable = "inherit",
216        internal = "false"
217    )]
218    RemoteRequestRejected {
219        /// Cloud service that rejected the request (e.g. "S3")
220        service: String,
221        /// HTTP status code the service returned
222        http_status: u16,
223        /// The service's error code (e.g. "InvalidArgument")
224        provider_code: String,
225        /// The service's error message
226        message: String,
227    },
228
229    /// Failure during signing of an HTTP request (e.g., AWS SigV4).
230    #[error(
231        code = "REQUEST_SIGN_ERROR",
232        message = "Request signing failed: {message}",
233        retryable = "true",
234        internal = "true"
235    )]
236    RequestSignError {
237        /// Human-readable description of the signing failure
238        message: String,
239    },
240
241    /// Catch-all error
242    #[error(
243        code = "GENERIC_ERROR",
244        message = "{message}",
245        retryable = "true",
246        internal = "true"
247    )]
248    GenericError {
249        /// Human-readable description of the error
250        message: String,
251    },
252
253    /// Invalid or malformed input parameters provided to the operation.
254    #[error(
255        code = "INVALID_INPUT",
256        message = "Invalid input: {message}",
257        retryable = "false",
258        internal = "false"
259    )]
260    InvalidInput {
261        /// Human-readable description of what input was invalid
262        message: String,
263        /// Optional field name that was invalid
264        field_name: Option<String>,
265    },
266
267    /// Failed to serialize or deserialize data.
268    #[error(
269        code = "SERIALIZATION_ERROR",
270        message = "Serialization failed: {message}",
271        retryable = "false",
272        internal = "true"
273    )]
274    SerializationError {
275        /// Human-readable description of the serialization failure
276        message: String,
277    },
278
279    /// Failed to load or parse kubeconfig file.
280    #[error(
281        code = "KUBECONFIG_ERROR",
282        message = "Kubeconfig error: {message}",
283        retryable = "false",
284        internal = "false"
285    )]
286    KubeconfigError {
287        /// Human-readable description of the kubeconfig error
288        message: String,
289    },
290
291    /// Failed to load data from base64 or file.
292    #[error(
293        code = "DATA_LOAD_ERROR",
294        message = "Failed to load data: {message}",
295        retryable = "false",
296        internal = "false"
297    )]
298    DataLoadError {
299        /// Human-readable description of the data loading failure
300        message: String,
301    },
302}
303
304/// Convenient alias with default error type `ErrorData`. Allows callers to override the
305/// error type when needed while still accepting the common single-generic form `Result<T>`.
306pub type Result<T, E = ErrorData> = alien_error::Result<T, E>;
307
308/// Convenience alias representing a constructed AlienError with our `ErrorData` payload.
309pub type Error = alien_error::AlienError<ErrorData>;