Skip to main content

alien_core/
presigned.rs

1use std::collections::HashMap;
2#[cfg(feature = "local")]
3use std::path::Path as StdPath;
4
5use alien_error::{AlienError, Context, IntoAlienError};
6use bytes::Bytes;
7use chrono::{DateTime, Utc};
8use serde::{Deserialize, Serialize};
9#[cfg(feature = "local")]
10use tokio::{fs, io::AsyncReadExt};
11
12#[cfg(feature = "openapi")]
13use utoipa::ToSchema;
14
15use crate::error::{ErrorData, Result};
16
17/// Stable message used when a bounded presigned GET exceeds its caller's
18/// explicit limit. This uses the existing generic error variant so adding the
19/// bounded API does not add a variant to the exhaustively matchable public
20/// [`ErrorData`] enum.
21pub const PRESIGNED_RESPONSE_TOO_LARGE_MESSAGE: &str =
22    "presigned response exceeded the caller's maximum size";
23
24/// The client HTTP presigned requests run on. WebAssembly builds of alien-core carry no HTTP
25/// client, so an HTTP presigned request fails there.
26#[cfg(not(target_arch = "wasm32"))]
27type HttpClient = reqwest::Client;
28
29#[cfg(target_arch = "wasm32")]
30struct HttpClient;
31
32#[cfg(target_arch = "wasm32")]
33impl HttpClient {
34    fn new() -> Self {
35        HttpClient
36    }
37}
38
39/// A presigned request that can be serialized, stored, and executed later.
40/// Hides implementation details for different storage backends.
41#[derive(Eq, PartialEq, Debug, Clone, Serialize, Deserialize)]
42#[serde(rename_all = "camelCase")]
43#[cfg_attr(feature = "openapi", derive(ToSchema))]
44pub struct PresignedRequest {
45    /// The storage backend this request targets
46    pub backend: PresignedRequestBackend,
47    /// When this presigned request expires
48    pub expiration: DateTime<Utc>,
49    /// The operation this request performs
50    pub operation: PresignedOperation,
51    /// The path this request operates on
52    pub path: String,
53}
54
55/// Storage backend representation for different presigned request types
56#[derive(Eq, PartialEq, Debug, Clone, Serialize, Deserialize)]
57#[serde(tag = "type", rename_all = "camelCase")]
58#[cfg_attr(feature = "openapi", derive(ToSchema))]
59pub enum PresignedRequestBackend {
60    /// HTTP-based request (AWS S3, GCP GCS, Azure Blob)
61    #[serde(rename_all = "camelCase")]
62    Http {
63        url: String,
64        method: String,
65        headers: HashMap<String, String>,
66    },
67    /// Local filesystem operation
68    #[serde(rename_all = "camelCase")]
69    Local {
70        file_path: String,
71        operation: LocalOperation,
72    },
73}
74
75/// The type of operation a presigned request performs
76#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
77#[serde(rename_all = "camelCase")]
78#[cfg_attr(feature = "openapi", derive(ToSchema))]
79pub enum PresignedOperation {
80    /// Upload/put operation
81    Put,
82    /// Download/get operation
83    Get,
84    /// Delete operation
85    Delete,
86}
87
88/// Local filesystem operations
89#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
90#[serde(rename_all = "camelCase")]
91#[cfg_attr(feature = "openapi", derive(ToSchema))]
92pub enum LocalOperation {
93    Put,
94    Get,
95    Delete,
96}
97
98/// Response from executing a presigned request
99#[derive(Debug)]
100pub struct PresignedResponse {
101    /// HTTP status code (200, 404, etc.) or equivalent
102    pub status_code: u16,
103    /// Response headers
104    pub headers: HashMap<String, String>,
105    /// Response body (for GET operations)
106    pub body: Option<Bytes>,
107}
108
109/// Remove credentials from a URL before storing it in an error or log record.
110///
111/// Presigned storage URLs and command response URLs carry bearer-equivalent
112/// query values. User info, query parameters, and fragments are therefore
113/// never safe diagnostic context; the origin and path are enough to identify
114/// the failed endpoint.
115pub fn redact_url_for_error(raw: &str) -> String {
116    if let Ok(mut parsed) = url::Url::parse(raw) {
117        let _ = parsed.set_username("");
118        let _ = parsed.set_password(None);
119        parsed.set_query(None);
120        parsed.set_fragment(None);
121        return parsed.to_string();
122    }
123
124    if raw.starts_with('/') && !raw.starts_with("//") {
125        return raw
126            .split(['?', '#'])
127            .next()
128            .filter(|value| !value.is_empty())
129            .unwrap_or("<invalid-url>")
130            .to_string();
131    }
132
133    "<invalid-url>".to_string()
134}
135
136impl PresignedRequest {
137    /// Create a new HTTP-based presigned request
138    pub fn new_http(
139        url: String,
140        method: String,
141        headers: HashMap<String, String>,
142        operation: PresignedOperation,
143        path: String,
144        expiration: DateTime<Utc>,
145    ) -> Self {
146        Self {
147            backend: PresignedRequestBackend::Http {
148                url,
149                method,
150                headers,
151            },
152            expiration,
153            operation,
154            path,
155        }
156    }
157
158    /// Create a new local filesystem presigned request
159    pub fn new_local(
160        file_path: String,
161        operation: PresignedOperation,
162        path: String,
163        expiration: DateTime<Utc>,
164    ) -> Self {
165        let local_op = match operation {
166            PresignedOperation::Put => LocalOperation::Put,
167            PresignedOperation::Get => LocalOperation::Get,
168            PresignedOperation::Delete => LocalOperation::Delete,
169        };
170
171        Self {
172            backend: PresignedRequestBackend::Local {
173                file_path,
174                operation: local_op,
175            },
176            expiration,
177            operation,
178            path,
179        }
180    }
181
182    /// Execute this presigned request with optional body data.
183    /// For PUT operations, body should contain the data to upload.
184    /// For GET/DELETE operations, body is typically None.
185    pub async fn execute(&self, body: Option<Bytes>) -> Result<PresignedResponse> {
186        self.execute_with_client_inner(&HttpClient::new(), body, None)
187            .await
188    }
189
190    /// Execute this request while bounding a GET response body before it is
191    /// buffered. PUT and DELETE requests do not have response bodies.
192    pub async fn execute_with_response_limit(
193        &self,
194        body: Option<Bytes>,
195        max_response_bytes: usize,
196    ) -> Result<PresignedResponse> {
197        self.execute_with_client_inner(&HttpClient::new(), body, Some(max_response_bytes))
198            .await
199    }
200
201    /// Execute this presigned request with a caller-owned HTTP client.
202    ///
203    /// Multi-step protocols should use this form so retries and adjacent HTTP
204    /// operations share one connection pool. Local requests ignore the client.
205    #[cfg(not(target_arch = "wasm32"))]
206    pub async fn execute_with_client(
207        &self,
208        client: &reqwest::Client,
209        body: Option<Bytes>,
210    ) -> Result<PresignedResponse> {
211        self.execute_with_client_inner(client, body, None).await
212    }
213
214    async fn execute_with_client_inner(
215        &self,
216        client: &HttpClient,
217        body: Option<Bytes>,
218        max_response_bytes: Option<usize>,
219    ) -> Result<PresignedResponse> {
220        match &self.backend {
221            PresignedRequestBackend::Http {
222                url,
223                method,
224                headers,
225            } => {
226                #[cfg(not(target_arch = "wasm32"))]
227                {
228                    self.execute_http(client, url, method, headers, body, max_response_bytes)
229                        .await
230                }
231                #[cfg(target_arch = "wasm32")]
232                {
233                    let _ = (client, url, headers, body, max_response_bytes);
234                    Err(AlienError::new(ErrorData::OperationNotSupported {
235                        operation: format!("HTTP {method} of a presigned request"),
236                        reason: "WebAssembly builds of Alien have no HTTP client".to_string(),
237                    }))
238                }
239            }
240            PresignedRequestBackend::Local {
241                file_path,
242                operation,
243            } => {
244                #[cfg(feature = "local")]
245                {
246                    self.execute_local(file_path, *operation, body, max_response_bytes)
247                        .await
248                }
249                #[cfg(not(feature = "local"))]
250                {
251                    let _ = (file_path, operation);
252                    Err(AlienError::new(ErrorData::FeatureNotEnabled {
253                        feature: "local".to_string(),
254                    }))
255                }
256            }
257        }
258    }
259
260    /// Get a URL representation of this presigned request.
261    /// For local storage, returns a local:// URL.
262    /// For cloud storage, returns the actual presigned URL.
263    pub fn url(&self) -> String {
264        match &self.backend {
265            PresignedRequestBackend::Http { url, .. } => url.clone(),
266            PresignedRequestBackend::Local { file_path, .. } => {
267                format!("local://{}", file_path)
268            }
269        }
270    }
271
272    /// Check if this presigned request has expired
273    pub fn is_expired(&self) -> bool {
274        Utc::now() > self.expiration
275    }
276
277    /// Get the HTTP method for this request (PUT, GET, DELETE)
278    pub fn method(&self) -> &str {
279        match &self.backend {
280            PresignedRequestBackend::Http { method, .. } => method,
281            PresignedRequestBackend::Local { operation, .. } => match operation {
282                LocalOperation::Put => "PUT",
283                LocalOperation::Get => "GET",
284                LocalOperation::Delete => "DELETE",
285            },
286        }
287    }
288
289    /// Get any headers that should be included with this request
290    pub fn headers(&self) -> HashMap<String, String> {
291        match &self.backend {
292            PresignedRequestBackend::Http { headers, .. } => headers.clone(),
293            _ => HashMap::new(),
294        }
295    }
296
297    #[cfg(not(target_arch = "wasm32"))]
298    async fn execute_http(
299        &self,
300        client: &reqwest::Client,
301        url: &str,
302        method: &str,
303        headers: &HashMap<String, String>,
304        body: Option<Bytes>,
305        max_response_bytes: Option<usize>,
306    ) -> Result<PresignedResponse> {
307        if self.is_expired() {
308            return Err(AlienError::new(ErrorData::PresignedRequestExpired {
309                path: self.path.clone(),
310                expired_at: self.expiration,
311            }));
312        }
313
314        let mut request = match method {
315            "PUT" => client.put(url),
316            "GET" => client.get(url),
317            "DELETE" => client.delete(url),
318            _ => {
319                return Err(AlienError::new(ErrorData::OperationNotSupported {
320                    operation: format!("HTTP method: {}", method),
321                    reason: "Only PUT, GET, and DELETE are supported".to_string(),
322                }))
323            }
324        };
325
326        // Add headers
327        for (key, value) in headers {
328            request = request.header(key, value);
329        }
330
331        // Add body for PUT requests
332        if let Some(data) = body {
333            request = request.body(data);
334        }
335
336        let safe_url = redact_url_for_error(url);
337        let mut response = request
338            .send()
339            .await
340            .map_err(reqwest::Error::without_url)
341            .into_alien_error()
342            .context(ErrorData::HttpRequestFailed {
343                url: safe_url.clone(),
344                method: method.to_string(),
345            })?;
346
347        let status_code = response.status().as_u16();
348        let response_headers = response
349            .headers()
350            .iter()
351            .map(|(k, v)| (k.to_string(), v.to_str().unwrap_or("").to_string()))
352            .collect();
353
354        let response_body = if max_response_bytes.is_some() && !(200..300).contains(&status_code) {
355            // Bounded consumers need the status, not an untrusted error body.
356            // Do not buffer error responses that cannot be valid GET data.
357            None
358        } else if matches!(self.operation, PresignedOperation::Get) {
359            if let Some(max_bytes) = max_response_bytes {
360                if response
361                    .content_length()
362                    .is_some_and(|length| length > max_bytes as u64)
363                {
364                    return Err(presigned_response_too_large());
365                }
366
367                let mut bytes = Vec::with_capacity(
368                    response
369                        .content_length()
370                        .unwrap_or_default()
371                        .min(max_bytes as u64) as usize,
372                );
373                while let Some(chunk) = response
374                    .chunk()
375                    .await
376                    .map_err(reqwest::Error::without_url)
377                    .into_alien_error()
378                    .context(ErrorData::HttpRequestFailed {
379                        url: safe_url.clone(),
380                        method: method.to_string(),
381                    })?
382                {
383                    if chunk.len() > max_bytes.saturating_sub(bytes.len()) {
384                        return Err(presigned_response_too_large());
385                    }
386                    bytes.extend_from_slice(&chunk);
387                }
388                Some(Bytes::from(bytes))
389            } else {
390                Some(
391                    response
392                        .bytes()
393                        .await
394                        .map_err(reqwest::Error::without_url)
395                        .into_alien_error()
396                        .context(ErrorData::HttpRequestFailed {
397                            url: safe_url,
398                            method: method.to_string(),
399                        })?,
400                )
401            }
402        } else {
403            None
404        };
405
406        Ok(PresignedResponse {
407            status_code,
408            headers: response_headers,
409            body: response_body,
410        })
411    }
412
413    #[cfg(feature = "local")]
414    async fn execute_local(
415        &self,
416        file_path: &str,
417        operation: LocalOperation,
418        body: Option<Bytes>,
419        max_response_bytes: Option<usize>,
420    ) -> Result<PresignedResponse> {
421        if self.is_expired() {
422            return Err(AlienError::new(ErrorData::PresignedRequestExpired {
423                path: self.path.clone(),
424                expired_at: self.expiration,
425            }));
426        }
427
428        let path = StdPath::new(file_path);
429
430        match operation {
431            LocalOperation::Put => {
432                let data = body.ok_or_else(|| {
433                    AlienError::new(ErrorData::OperationNotSupported {
434                        operation: "Local PUT without body".to_string(),
435                        reason: "PUT operations require body data".to_string(),
436                    })
437                })?;
438
439                // Create parent directories if needed
440                if let Some(parent) = path.parent() {
441                    fs::create_dir_all(parent)
442                        .await
443                        .into_alien_error()
444                        .context(ErrorData::LocalFilesystemError {
445                            path: file_path.to_string(),
446                            operation: "create_parent_dirs".to_string(),
447                        })?;
448                }
449
450                let write_result: std::io::Result<()> = fs::write(path, data.as_ref()).await;
451                write_result
452                    .into_alien_error()
453                    .context(ErrorData::LocalFilesystemError {
454                        path: file_path.to_string(),
455                        operation: "write".to_string(),
456                    })?;
457
458                Ok(PresignedResponse {
459                    status_code: 200,
460                    headers: HashMap::new(),
461                    body: None,
462                })
463            }
464            LocalOperation::Get => {
465                let data = if let Some(max_bytes) = max_response_bytes {
466                    let file = fs::File::open(path).await.into_alien_error().context(
467                        ErrorData::LocalFilesystemError {
468                            path: file_path.to_string(),
469                            operation: "open".to_string(),
470                        },
471                    )?;
472                    let mut data = Vec::with_capacity(max_bytes.min(64 * 1024));
473                    file.take(max_bytes.saturating_add(1) as u64)
474                        .read_to_end(&mut data)
475                        .await
476                        .into_alien_error()
477                        .context(ErrorData::LocalFilesystemError {
478                            path: file_path.to_string(),
479                            operation: "read".to_string(),
480                        })?;
481                    if data.len() > max_bytes {
482                        return Err(presigned_response_too_large());
483                    }
484                    data
485                } else {
486                    fs::read(path).await.into_alien_error().context(
487                        ErrorData::LocalFilesystemError {
488                            path: file_path.to_string(),
489                            operation: "read".to_string(),
490                        },
491                    )?
492                };
493
494                Ok(PresignedResponse {
495                    status_code: 200,
496                    headers: HashMap::new(),
497                    body: Some(Bytes::from(data)),
498                })
499            }
500            LocalOperation::Delete => {
501                fs::remove_file(path).await.into_alien_error().context(
502                    ErrorData::LocalFilesystemError {
503                        path: file_path.to_string(),
504                        operation: "delete".to_string(),
505                    },
506                )?;
507
508                Ok(PresignedResponse {
509                    status_code: 200,
510                    headers: HashMap::new(),
511                    body: None,
512                })
513            }
514        }
515    }
516}
517
518fn presigned_response_too_large() -> AlienError<ErrorData> {
519    AlienError::new(ErrorData::GenericError {
520        message: PRESIGNED_RESPONSE_TOO_LARGE_MESSAGE.to_string(),
521    })
522}
523
524#[cfg(test)]
525mod tests {
526    use super::redact_url_for_error;
527
528    #[test]
529    fn redacts_query_fragment_and_user_info_from_diagnostic_urls() {
530        let secret = "do-not-log-this-token";
531        let sanitized = redact_url_for_error(&format!(
532            "https://user:{secret}@storage.example.com/object?X-Amz-Signature={secret}#fragment"
533        ));
534
535        assert_eq!(sanitized, "https://storage.example.com/object");
536        assert!(!sanitized.contains(secret));
537    }
538
539    #[test]
540    fn redacts_query_from_relative_urls() {
541        assert_eq!(
542            redact_url_for_error("/v1/commands/cmd/response?response_token=secret"),
543            "/v1/commands/cmd/response"
544        );
545    }
546
547    #[test]
548    fn does_not_echo_unparseable_urls() {
549        let secret = "do-not-log-this-token";
550        assert_eq!(
551            redact_url_for_error(&format!("not a URL containing {secret}")),
552            "<invalid-url>"
553        );
554    }
555}