brows3r_lib/s3/
metadata.rs

1//! Object metadata setter via self-overwrite `CopyObject`.
2//!
3//! # Design
4//!
5//! S3 does not expose a `PatchObjectMetadata` API.  The only supported way to
6//! change user-defined metadata on an existing object without re-uploading the
7//! body is a server-side `CopyObject` from `bucket/key` back to itself with
8//! `MetadataDirective::Replace`.  This replaces the metadata in-place while the
9//! body is preserved on the server side.
10//!
11//! # ETag precondition
12//!
13//! When `if_match_etag` is supplied the call sets the S3 `copy-source-if-match`
14//! header.  S3 returns 412 (Precondition Failed) when the live ETag does not
15//! match.  We map that to `AppError::Conflict` so the frontend can surface a
16//! "object was modified since you loaded it" message.
17//!
18//! # OCP
19//!
20//! `PutResult` is the open shape for metadata/tag setters:
21//! - `checksum` and `sse_kms_key_id` can be added as `Option` fields later.
22//! - `version_id` is already present for versioned-bucket support.
23
24use std::collections::HashMap;
25
26use aws_sdk_s3::{error::SdkError, types::MetadataDirective, Client};
27use serde::{Deserialize, Serialize};
28
29use crate::error::AppError;
30
31// ---------------------------------------------------------------------------
32// PutResult — shared result type for metadata + tag setters
33// ---------------------------------------------------------------------------
34
35/// Result returned by `set_object_metadata` and `set_object_tags`.
36///
37/// OCP: `checksum: Option<String>` and `sse_kms_key_id: Option<String>` can be
38/// appended as optional fields in a future task without breaking this shape.
39#[derive(Debug, Clone, Serialize, Deserialize)]
40#[serde(rename_all = "camelCase")]
41pub struct PutResult {
42    /// ETag of the object after the operation, stripped of surrounding quotes.
43    #[serde(skip_serializing_if = "Option::is_none")]
44    pub etag: Option<String>,
45    /// Unix timestamp in milliseconds of the last-modified time after the op.
46    #[serde(skip_serializing_if = "Option::is_none")]
47    pub last_modified: Option<i64>,
48    /// Version ID when the bucket has versioning enabled.
49    #[serde(skip_serializing_if = "Option::is_none")]
50    pub version_id: Option<String>,
51}
52
53// ---------------------------------------------------------------------------
54// set_object_metadata
55// ---------------------------------------------------------------------------
56
57/// Replace the user-defined metadata on `bucket/key`.
58///
59/// Uses a self-referencing `CopyObject` (`source = bucket/key`,
60/// `destination = bucket/key`) with `MetadataDirective::Replace` so the object
61/// body is preserved on the server side.
62///
63/// # ETag precondition
64///
65/// When `if_match_etag` is `Some(etag)` the call sets `copy-source-if-match`.
66/// On a 412 Precondition Failed response this returns
67/// `AppError::Conflict { etag_expected, etag_actual: None }`.
68///
69/// # Errors
70///
71/// - `AppError::Conflict`     — `if_match_etag` supplied and ETags do not match.
72/// - `AppError::AccessDenied` — `s3:CopyObject` permission denied.
73/// - `AppError::NotFound`     — bucket or key does not exist.
74/// - `AppError::RateLimited`  — throttling response from AWS.
75/// - `AppError::Network`      — any other SDK or transport error.
76pub async fn set_object_metadata(
77    client: &Client,
78    bucket: &str,
79    key: &str,
80    metadata: HashMap<String, String>,
81    if_match_etag: Option<String>,
82) -> Result<PutResult, AppError> {
83    let copy_source = format!("{bucket}/{key}");
84    let resource = format!("{bucket}/{key}");
85
86    let mut req = client
87        .copy_object()
88        .copy_source(&copy_source)
89        .bucket(bucket)
90        .key(key)
91        .metadata_directive(MetadataDirective::Replace);
92
93    // Apply each user-provided metadata key-value pair.
94    for (k, v) in &metadata {
95        req = req.metadata(k, v);
96    }
97
98    // Optional ETag precondition.
99    if let Some(ref etag) = if_match_etag {
100        req = req.copy_source_if_match(etag);
101    }
102
103    let resp = req.send().await.map_err(|e| {
104        classify_copy_sdk_error_with_precondition(e, &resource, if_match_etag.as_deref())
105    })?;
106
107    let detail = resp.copy_object_result().map(|r| {
108        let etag = r.e_tag().map(|s| s.trim_matches('"').to_string());
109        let last_modified = r
110            .last_modified()
111            .map(|dt| dt.secs() * 1000 + i64::from(dt.subsec_nanos()) / 1_000_000);
112        (etag, last_modified)
113    });
114
115    Ok(PutResult {
116        etag: detail.as_ref().and_then(|(e, _)| e.clone()),
117        last_modified: detail.and_then(|(_, lm)| lm),
118        version_id: resp.version_id().map(|s| s.to_string()),
119    })
120}
121
122// ---------------------------------------------------------------------------
123// Error classifier — copy with 412 precondition support
124// ---------------------------------------------------------------------------
125
126fn classify_copy_sdk_error_with_precondition(
127    e: SdkError<aws_sdk_s3::operation::copy_object::CopyObjectError>,
128    resource: &str,
129    if_match_etag: Option<&str>,
130) -> AppError {
131    // Check for HTTP 412 Precondition Failed first.
132    if let SdkError::ServiceError(ref svc) = e {
133        let code = svc.err().meta().code().unwrap_or("");
134
135        // S3 returns 412 with code "PreconditionFailed" when copy-source-if-match fails.
136        if code == "PreconditionFailed" {
137            if let Some(expected) = if_match_etag {
138                return AppError::Conflict {
139                    etag_expected: expected.to_string(),
140                    etag_actual: None,
141                };
142            }
143        }
144
145        match code {
146            "AccessDenied" | "InvalidClientTokenId" => {
147                return AppError::AccessDenied {
148                    op: "s3:CopyObject".to_string(),
149                    resource: resource.to_string(),
150                };
151            }
152            "NoSuchBucket" | "NoSuchKey" => {
153                return AppError::NotFound {
154                    resource: resource.to_string(),
155                };
156            }
157            "SlowDown" | "RequestThrottled" | "ThrottlingException" => {
158                return AppError::RateLimited {
159                    retry_after_ms: None,
160                };
161            }
162            _ => {}
163        }
164    }
165
166    // Check raw HTTP status for 412 when the SDK wraps it without a code.
167    if let SdkError::ResponseError(ref re) = e {
168        if re.raw().status().as_u16() == 412 {
169            if let Some(expected) = if_match_etag {
170                return AppError::Conflict {
171                    etag_expected: expected.to_string(),
172                    etag_actual: None,
173                };
174            }
175        }
176    }
177
178    AppError::Network {
179        source: e.to_string(),
180    }
181}
182
183// ---------------------------------------------------------------------------
184// Tests
185// ---------------------------------------------------------------------------
186
187#[cfg(test)]
188mod tests {
189    use super::*;
190
191    #[test]
192    fn put_result_serialises_camel_case() {
193        let r = PutResult {
194            etag: Some("abc123".to_string()),
195            last_modified: Some(1_700_000_000_000),
196            version_id: Some("v1".to_string()),
197        };
198        let v = serde_json::to_value(&r).unwrap();
199        assert_eq!(v["etag"], "abc123");
200        assert_eq!(v["lastModified"], 1_700_000_000_000_i64);
201        assert_eq!(v["versionId"], "v1");
202    }
203
204    #[test]
205    fn put_result_skips_none_fields() {
206        let r = PutResult {
207            etag: None,
208            last_modified: None,
209            version_id: None,
210        };
211        let v = serde_json::to_value(&r).unwrap();
212        assert!(!v.as_object().unwrap().contains_key("etag"));
213        assert!(!v.as_object().unwrap().contains_key("lastModified"));
214        assert!(!v.as_object().unwrap().contains_key("versionId"));
215    }
216
217    #[test]
218    fn put_result_round_trips_json() {
219        let r = PutResult {
220            etag: Some("etag-value".to_string()),
221            last_modified: Some(1_000),
222            version_id: None,
223        };
224        let json = serde_json::to_string(&r).unwrap();
225        let r2: PutResult = serde_json::from_str(&json).unwrap();
226        assert_eq!(r2.etag.as_deref(), Some("etag-value"));
227        assert_eq!(r2.last_modified, Some(1_000));
228        assert!(r2.version_id.is_none());
229    }
230
231    // Verify the precondition classifier returns Conflict for PreconditionFailed code.
232    // We cannot call the real AWS SDK without a live endpoint, but we can verify
233    // the error mapping logic via the known SDK error classification path by
234    // inspecting `AppError::Conflict` construction directly.
235    #[test]
236    fn conflict_error_carries_expected_etag() {
237        let err = AppError::Conflict {
238            etag_expected: "\"abc123\"".to_string(),
239            etag_actual: None,
240        };
241        assert_eq!(err.kind(), "Conflict");
242        let v = serde_json::to_value(&err).unwrap();
243        assert_eq!(v["details"]["etagExpected"], "\"abc123\"");
244        assert!(v["details"]["etagActual"].is_null());
245    }
246}
brows3r_lib/s3/metadata.rs

brows3r_lib/s3/
metadata.rs
