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    /// An extension's interceptor failed, or made a change Alien refuses. The same request fails
270    /// the same way again, so it is final, unless the interceptor marked a failure before the
271    /// call was sent retryable, as a hook stopped at its deadline is.
272    #[error(
273        code = "INTERCEPTOR_FAILED",
274        message = "Extension '{extension}' failed the call: {message}",
275        retryable = "false",
276        internal = "false"
277    )]
278    InterceptorFailed {
279        /// The extension whose interceptor failed
280        extension: String,
281        /// What the interceptor did wrong
282        message: String,
283    },
284
285    /// A client with interceptors refused to send its credential to an origin other than its
286    /// own endpoint, such as one a rewritten response named.
287    #[error(
288        code = "DESTINATION_REFUSED",
289        message = "Refused to send a signed request to {url}: this client signs only for {endpoint}",
290        retryable = "false",
291        internal = "false"
292    )]
293    DestinationRefused {
294        /// Origin the request was addressed to
295        url: String,
296        /// Origin of the client's configured endpoint
297        endpoint: String,
298    },
299
300    /// Catch-all error
301    #[error(
302        code = "GENERIC_ERROR",
303        message = "{message}",
304        retryable = "true",
305        internal = "true"
306    )]
307    GenericError {
308        /// Human-readable description of the error
309        message: String,
310    },
311
312    /// Invalid or malformed input parameters provided to the operation.
313    #[error(
314        code = "INVALID_INPUT",
315        message = "Invalid input: {message}",
316        retryable = "false",
317        internal = "false"
318    )]
319    InvalidInput {
320        /// Human-readable description of what input was invalid
321        message: String,
322        /// Optional field name that was invalid
323        field_name: Option<String>,
324    },
325
326    /// Failed to serialize or deserialize data.
327    #[error(
328        code = "SERIALIZATION_ERROR",
329        message = "Serialization failed: {message}",
330        retryable = "false",
331        internal = "true"
332    )]
333    SerializationError {
334        /// Human-readable description of the serialization failure
335        message: String,
336    },
337
338    /// Failed to load or parse kubeconfig file.
339    #[error(
340        code = "KUBECONFIG_ERROR",
341        message = "Kubeconfig error: {message}",
342        retryable = "false",
343        internal = "false"
344    )]
345    KubeconfigError {
346        /// Human-readable description of the kubeconfig error
347        message: String,
348    },
349
350    /// Failed to load data from base64 or file.
351    #[error(
352        code = "DATA_LOAD_ERROR",
353        message = "Failed to load data: {message}",
354        retryable = "false",
355        internal = "false"
356    )]
357    DataLoadError {
358        /// Human-readable description of the data loading failure
359        message: String,
360    },
361}
362
363/// Convenient alias with default error type `ErrorData`. Allows callers to override the
364/// error type when needed while still accepting the common single-generic form `Result<T>`.
365pub type Result<T, E = ErrorData> = alien_error::Result<T, E>;
366
367/// Convenience alias representing a constructed AlienError with our `ErrorData` payload.
368pub type Error = alien_error::AlienError<ErrorData>;