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>;