Skip to main content

rustfs_replication/
object.rs

1// Copyright 2024 RustFS Team
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use crate::filemeta::{ReplicationAction, ReplicationType};
16use crate::http::{
17    AMZ_OBJECT_LOCK_LEGAL_HOLD, AMZ_OBJECT_LOCK_MODE, AMZ_OBJECT_LOCK_RETAIN_UNTIL_DATE, AMZ_OBJECT_TAGGING,
18    AMZ_WEBSITE_REDIRECT_LOCATION, CACHE_CONTROL, CONTENT_DISPOSITION, CONTENT_ENCODING, CONTENT_LANGUAGE, EXPIRES,
19    has_prefix_fold, trim_etag,
20};
21use crate::tagging::ReplicationTagFilter;
22use std::collections::HashMap;
23use time::OffsetDateTime;
24
25const AMZ_META_PREFIX: &str = "X-Amz-Meta-";
26const CONTENT_ENCODING_LOWER: &str = "content-encoding";
27const REPLICATION_METADATA_COMPARE_KEYS: [&str; 9] = [
28    EXPIRES,
29    CACHE_CONTROL,
30    CONTENT_LANGUAGE,
31    CONTENT_DISPOSITION,
32    AMZ_OBJECT_LOCK_MODE,
33    AMZ_OBJECT_LOCK_RETAIN_UNTIL_DATE,
34    AMZ_OBJECT_LOCK_LEGAL_HOLD,
35    AMZ_WEBSITE_REDIRECT_LOCATION,
36    AMZ_META_PREFIX,
37];
38
39#[derive(Debug, Clone)]
40pub struct ReplicationSourceObject<'a> {
41    pub mod_time: Option<OffsetDateTime>,
42    pub version_id: Option<String>,
43    pub etag: Option<&'a str>,
44    pub actual_size: i64,
45    pub delete_marker: bool,
46    pub content_type: Option<&'a str>,
47    pub content_encoding: Option<&'a str>,
48    pub user_tags: &'a str,
49    pub user_defined: &'a HashMap<String, String>,
50}
51
52#[derive(Debug, Clone)]
53pub struct ReplicationTargetObject<'a> {
54    pub last_modified: Option<OffsetDateTime>,
55    pub version_id: Option<&'a str>,
56    pub etag: Option<&'a str>,
57    pub content_length: i64,
58    pub delete_marker: bool,
59    pub content_type: Option<&'a str>,
60    pub metadata: Option<&'a HashMap<String, String>>,
61    pub tag_count: i32,
62}
63
64pub fn content_matches_by_etag(source: &ReplicationSourceObject<'_>, target: &ReplicationTargetObject<'_>) -> bool {
65    replication_etags_match(source.etag, target.etag)
66}
67
68pub fn replication_etags_match(source: Option<&str>, target: Option<&str>) -> bool {
69    let source_etag = source.map(trim_etag);
70    let target_etag = target.map(trim_etag);
71    source_etag.is_some() && source_etag == target_etag
72}
73
74fn is_plain_single_part_md5(etag: &str) -> bool {
75    etag.len() == 32 && etag.bytes().all(|b| b.is_ascii_hexdigit())
76}
77
78/// How a replication PutObject that carries Object Lock parameters satisfies
79/// the target-side rule that such a request must also carry `Content-MD5` or
80/// an `x-amz-checksum-*` header (AWS S3, MinIO and most compatible stores
81/// enforce it; rustfs#7082).
82#[derive(Debug, Clone, PartialEq, Eq)]
83pub enum ObjectLockIntegrity {
84    /// No Object Lock parameters, or an integrity header is already present.
85    NotRequired,
86    /// Send `Content-MD5` computed from this hex MD5: the source ETag is the
87    /// MD5 of exactly the bytes going on the wire, so no body pass and no
88    /// change of payload framing is needed.
89    ContentMd5Hex(String),
90    /// The source ETag is not the MD5 of the wire bytes (multipart layout,
91    /// or an encrypted object whose ETag does not describe the plaintext);
92    /// let the SDK compute a checksum instead.
93    SdkChecksum,
94}
95
96/// Decide the integrity header for a locked replication PUT.
97///
98/// `plaintext_end_to_end` is false when the request announces any server-side
99/// encryption or carries SSE-C ciphertext passthrough headers: the source
100/// ETag then does not describe the bytes on the wire and must not be turned
101/// into a `Content-MD5` the target would reject with `BadDigest`.
102pub fn object_lock_put_integrity(
103    lock_params: bool,
104    has_integrity_header: bool,
105    plaintext_end_to_end: bool,
106    source_etag: Option<&str>,
107) -> ObjectLockIntegrity {
108    if !lock_params || has_integrity_header {
109        return ObjectLockIntegrity::NotRequired;
110    }
111    match source_etag.map(trim_etag) {
112        Some(etag) if plaintext_end_to_end && is_plain_single_part_md5(&etag) => {
113            ObjectLockIntegrity::ContentMd5Hex(etag.to_ascii_lowercase())
114        }
115        _ => ObjectLockIntegrity::SdkChecksum,
116    }
117}
118
119/// Whether the ETag the target returned for a single-part replica proves the
120/// stored bytes differ from what the source sent — e.g. a target that does not
121/// decode `aws-chunked` framing stores the frames verbatim and returns their
122/// ETag. Only a plain single-part MD5 ETag on both sides is decidable; a
123/// multipart or opaque (encrypted) ETag, or a withheld replica ETag, returns
124/// `false` because no corruption can be concluded from it.
125pub fn single_part_replica_etag_mismatch(source_etag: Option<&str>, replica_etag: Option<&str>) -> bool {
126    let Some(source) = source_etag.map(trim_etag) else {
127        return false;
128    };
129    if !is_plain_single_part_md5(&source) {
130        return false;
131    }
132    let Some(replica) = replica_etag.map(trim_etag) else {
133        return false;
134    };
135    if !is_plain_single_part_md5(&replica) {
136        return false;
137    }
138    !source.eq_ignore_ascii_case(&replica)
139}
140
141pub fn target_is_newer_than_source_null_version(
142    source: &ReplicationSourceObject<'_>,
143    target: &ReplicationTargetObject<'_>,
144) -> bool {
145    target
146        .last_modified
147        .is_some_and(|target_mod_time| target_mod_time > source.mod_time.unwrap_or(OffsetDateTime::UNIX_EPOCH))
148        && source.version_id.is_none()
149}
150
151pub fn replication_action_for_target(
152    source: &ReplicationSourceObject<'_>,
153    target: &ReplicationTargetObject<'_>,
154    op_type: ReplicationType,
155) -> ReplicationAction {
156    if op_type == ReplicationType::ExistingObject && target_is_newer_than_source_null_version(source, target) {
157        return ReplicationAction::None;
158    }
159
160    if source.etag.map(trim_etag) != target.etag.map(trim_etag)
161        || source.version_id.as_deref() != target.version_id
162        || source.actual_size != target.content_length
163        || source.delete_marker != target.delete_marker
164        || source.mod_time != target.last_modified
165    {
166        return ReplicationAction::All;
167    }
168
169    if source.content_type != target.content_type {
170        return ReplicationAction::Metadata;
171    }
172
173    if content_encoding_differs(source, target) {
174        return ReplicationAction::Metadata;
175    }
176
177    if tag_metadata_differs(source, target) {
178        return ReplicationAction::Metadata;
179    }
180
181    if comparable_metadata(Some(source.user_defined)) != comparable_metadata(target.metadata) {
182        return ReplicationAction::Metadata;
183    }
184
185    ReplicationAction::None
186}
187
188fn content_encoding_differs(source: &ReplicationSourceObject<'_>, target: &ReplicationTargetObject<'_>) -> bool {
189    if let Some(content_encoding) = source.content_encoding {
190        return target
191            .metadata
192            .and_then(|metadata| {
193                metadata
194                    .get(CONTENT_ENCODING)
195                    .or_else(|| metadata.get(CONTENT_ENCODING_LOWER))
196            })
197            .is_none_or(|enc| enc != content_encoding);
198    }
199    false
200}
201
202fn tag_metadata_differs(source: &ReplicationSourceObject<'_>, target: &ReplicationTargetObject<'_>) -> bool {
203    let source_tags = ReplicationTagFilter::decode_tags_to_map(source.user_tags);
204    let target_tagging = target
205        .metadata
206        .and_then(|metadata| metadata.get(AMZ_OBJECT_TAGGING).map(String::as_str))
207        .unwrap_or_default();
208    let target_tags = ReplicationTagFilter::decode_tags_to_map(target_tagging);
209    let source_tag_count = i32::try_from(source_tags.len()).unwrap_or(i32::MAX);
210
211    (target.tag_count > 0 && source_tags != target_tags) || target.tag_count != source_tag_count
212}
213
214fn comparable_metadata(metadata: Option<&HashMap<String, String>>) -> HashMap<String, String> {
215    let mut comparable = HashMap::new();
216    for (key, value) in metadata.into_iter().flatten() {
217        if REPLICATION_METADATA_COMPARE_KEYS
218            .iter()
219            .any(|prefix| has_prefix_fold(key, prefix))
220        {
221            comparable.insert(key.to_lowercase(), value.clone());
222        }
223    }
224    comparable
225}
226
227/// Runtime half of the P1-19 version-identity contract (the explicit probe
228/// lives in replication-check's VersionFidelity phase): every replication PUT
229/// response reveals whether the target adopted the source version id. A
230/// target minting its own ids silently breaks version-addressed deletes and
231/// heal, so surface it — once per target — instead of letting the divergence
232/// accumulate unseen.
233/// Pure drift judgment: the contract only applies when the source addressed a
234/// real (non-nil) version uuid, and drift means the target answered with
235/// anything else — including nothing at all.
236pub fn version_identity_drifted(source_version_id: &str, assigned_version_id: Option<&str>) -> bool {
237    version_identity_capability_from_put(source_version_id, assigned_version_id) == Some(VersionIdentityCapability::MintsOwn)
238}
239
240/// Whether a replication target adopts the source version id it is handed on
241/// PutObject / CompleteMultipartUpload, or mints its own.
242///
243/// A target that mints its own ids (AWS S3, Wasabi, Impossible Cloud) still
244/// stores the bytes, but every later version-addressed request from the
245/// source names an id the target never had. Its HEAD then answers 404 —
246/// indistinguishable from a replica that is really missing — so a heal, MRF
247/// retry or existing-object resync re-drive would PUT the object again and
248/// mint yet another target version (rustfs/backlog#2340). The replication
249/// worker learns the verdict from each PUT response (and replication-check's
250/// VersionFidelity phase) and, once `MintsOwn` is known, locates a replica by
251/// exact key and ETag before concluding that it is missing. The verdict cache
252/// is owned by the runtime's bucket target system; this crate owns only the
253/// vocabulary and the judgment.
254#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
255pub enum VersionIdentityCapability {
256    #[default]
257    Unknown,
258    Adopts,
259    MintsOwn,
260}
261
262impl VersionIdentityCapability {
263    /// True when a 404 from a version-addressed HEAD on this target cannot be
264    /// read as "replica missing": the source-side id was never the target's.
265    pub fn version_addressing_unreliable(self) -> bool {
266        self == VersionIdentityCapability::MintsOwn
267    }
268}
269
270/// Judge the identity contract from one replication write: `None` when no
271/// contract applies (the source addressed no real version — an empty or nil
272/// uuid travels as the literal "null", unversioned-source semantics),
273/// otherwise whether the target echoed the source id or answered with
274/// anything else — including nothing at all.
275pub fn version_identity_capability_from_put(
276    source_version_id: &str,
277    assigned_version_id: Option<&str>,
278) -> Option<VersionIdentityCapability> {
279    if source_version_id.is_empty() {
280        return None;
281    }
282    if uuid::Uuid::parse_str(source_version_id)
283        .map(|uuid| uuid.is_nil())
284        .unwrap_or(true)
285    {
286        return None;
287    }
288    Some(if assigned_version_id == Some(source_version_id) {
289        VersionIdentityCapability::Adopts
290    } else {
291        VersionIdentityCapability::MintsOwn
292    })
293}
294
295const REPLICATION_TARGET_OFFLINE_ERROR_MARKERS: &[&str] = &[
296    "dispatch failure",
297    "timeouterror",
298    "timed out",
299    "connection refused",
300    "connection reset",
301    "connection closed",
302    "connection aborted",
303    "broken pipe",
304    "dns error",
305    "failed to lookup address",
306    "name or service not known",
307    "deadline has elapsed",
308    "tcp connect error",
309];
310
311/// True when a target operation error reads as a network/transport failure —
312/// the only class of error that should mark a replication target offline.
313pub fn is_replication_target_offline_error(err: &(impl std::fmt::Display + ?Sized)) -> bool {
314    let message = err.to_string().to_ascii_lowercase();
315    REPLICATION_TARGET_OFFLINE_ERROR_MARKERS
316        .iter()
317        .any(|marker| message.contains(marker))
318}
319
320/// Whether a replication target preserves the SSE-C passthrough transport
321/// headers (`X-Rustfs-Replication-*`) end to end.
322///
323/// A target that silently drops those headers (MinIO, generic S3) stores the
324/// forwarded ciphertext without its decryption material — an unreadable
325/// replica that used to report COMPLETED. The replication worker audits the
326/// first passthrough PUT per target (HEAD-back for SSE-C evidence) and caches
327/// the verdict; a fresh `Unsupported` fails SSE-C replication closed before
328/// any PUT is sent. The verdict cache (per-ARN map, lifecycle, and TTL) is
329/// owned by the runtime's bucket target system; this crate owns only the
330/// verdict vocabulary and the gate policy below.
331#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
332pub enum SsecPassthroughCapability {
333    #[default]
334    Unknown,
335    Supported,
336    Unsupported,
337}
338
339/// Fail-closed decision for an SSE-C passthrough replication attempt, derived
340/// from the target's cached [`SsecPassthroughCapability`]. Pure so the policy
341/// can migrate with the worker (M2) without dragging the cache along; the
342/// caller computes `expired` from the cache record's age (see the runtime's
343/// `SSEC_PASSTHROUGH_CAPABILITY_TTL`).
344#[derive(Debug, Clone, Copy, PartialEq, Eq)]
345pub enum SsecPassthroughGate {
346    /// Not an SSE-C object, or the target has a fresh proof that it preserves
347    /// the passthrough transport headers: replicate without a HEAD-back audit.
348    Proceed,
349    /// No usable verdict — first SSE-C attempt since the target was (re)built,
350    /// or the recorded verdict (in either direction) aged out: PUT, then HEAD
351    /// the replica back and require SSE-C evidence before reporting COMPLETED.
352    ProceedWithAudit,
353    /// The target was recently proven to drop the passthrough headers: do not
354    /// send the PUT, report FAILED (the object stays on the normal MRF retry
355    /// channel and re-audits once the verdict expires).
356    FailClosed,
357}
358
359pub fn ssec_passthrough_gate(ssec: bool, capability: SsecPassthroughCapability, expired: bool) -> SsecPassthroughGate {
360    if !ssec {
361        return SsecPassthroughGate::Proceed;
362    }
363    // An expired verdict — Supported or Unsupported — must be re-earned: a
364    // stale Unsupported would otherwise stick forever after a target upgrade,
365    // and a stale Supported would fail open after a backend swap behind the
366    // same endpoint.
367    if expired {
368        return SsecPassthroughGate::ProceedWithAudit;
369    }
370    match capability {
371        SsecPassthroughCapability::Supported => SsecPassthroughGate::Proceed,
372        SsecPassthroughCapability::Unknown => SsecPassthroughGate::ProceedWithAudit,
373        SsecPassthroughCapability::Unsupported => SsecPassthroughGate::FailClosed,
374    }
375}
376
377/// True when a replication-check HEAD of the replica proves the SSE-C
378/// material survived passthrough: a RustFS target restores the transport
379/// headers into the stored SSE-C keys and its HEAD echoes
380/// `x-amz-server-side-encryption-customer-algorithm` (the replication-check
381/// exemption skips key validation but not the metadata echo). A target that
382/// dropped the headers stored a plain object and echoes nothing. The caller
383/// extracts the echoed customer-algorithm value from its HEAD response type.
384pub fn ssec_passthrough_evidence_present(sse_customer_algorithm: Option<&str>) -> bool {
385    sse_customer_algorithm.is_some_and(|algo| !algo.is_empty())
386}
387
388#[cfg(test)]
389mod tests {
390    use super::{ObjectLockIntegrity, object_lock_put_integrity};
391
392    const SOURCE_MD5: &str = "9a0364b9e99bb480dd25e1f0284c8555";
393    const FRAMED_MD5: &str = "0f343b0931126a20f133d67c2b018a3b";
394
395    #[test]
396    fn single_part_replica_mismatch_is_only_decided_on_plain_md5_pairs() {
397        // The #6853 shape: the target stored aws-chunked frames verbatim and
398        // returned the framed bytes' ETag.
399        assert!(single_part_replica_etag_mismatch(Some(SOURCE_MD5), Some(FRAMED_MD5)));
400        assert!(single_part_replica_etag_mismatch(
401            Some(&format!("\"{SOURCE_MD5}\"")),
402            Some(&format!("\"{FRAMED_MD5}\""))
403        ));
404
405        // A faithful replica, quoted or not, passes; hex case must not matter
406        // (a target may return the same MD5 uppercased).
407        assert!(!single_part_replica_etag_mismatch(Some(SOURCE_MD5), Some(SOURCE_MD5)));
408        assert!(!single_part_replica_etag_mismatch(Some(&format!("\"{SOURCE_MD5}\"")), Some(SOURCE_MD5)));
409        assert!(!single_part_replica_etag_mismatch(
410            Some(SOURCE_MD5),
411            Some(&SOURCE_MD5.to_ascii_uppercase())
412        ));
413
414        // Not decidable: multipart source, opaque replica ETag, or either side
415        // missing must never be reported as corruption.
416        assert!(!single_part_replica_etag_mismatch(Some(&format!("{SOURCE_MD5}-3")), Some(FRAMED_MD5)));
417        assert!(!single_part_replica_etag_mismatch(Some(SOURCE_MD5), Some(&format!("{FRAMED_MD5}-3"))));
418        assert!(!single_part_replica_etag_mismatch(Some(SOURCE_MD5), None));
419        assert!(!single_part_replica_etag_mismatch(None, Some(FRAMED_MD5)));
420    }
421
422    use super::{
423        ReplicationSourceObject, ReplicationTargetObject, SsecPassthroughCapability, SsecPassthroughGate,
424        VersionIdentityCapability, content_matches_by_etag, is_replication_target_offline_error, replication_action_for_target,
425        replication_etags_match, single_part_replica_etag_mismatch, ssec_passthrough_evidence_present, ssec_passthrough_gate,
426        target_is_newer_than_source_null_version, version_identity_capability_from_put, version_identity_drifted,
427    };
428    use crate::filemeta::{ReplicationAction, ReplicationType};
429    use crate::http::AMZ_OBJECT_LOCK_MODE;
430    use std::collections::HashMap;
431    use time::{Duration, OffsetDateTime};
432
433    fn source_object(user_defined: &HashMap<String, String>) -> ReplicationSourceObject<'_> {
434        ReplicationSourceObject {
435            mod_time: Some(OffsetDateTime::UNIX_EPOCH + Duration::seconds(10)),
436            version_id: Some("source-version".to_string()),
437            etag: Some("\"abc\""),
438            actual_size: 10,
439            delete_marker: false,
440            content_type: Some("text/plain"),
441            content_encoding: None,
442            user_tags: "a=1",
443            user_defined,
444        }
445    }
446
447    fn target_object(metadata: &HashMap<String, String>) -> ReplicationTargetObject<'_> {
448        ReplicationTargetObject {
449            last_modified: Some(OffsetDateTime::UNIX_EPOCH + Duration::seconds(10)),
450            version_id: Some("source-version"),
451            etag: Some("abc"),
452            content_length: 10,
453            delete_marker: false,
454            content_type: Some("text/plain"),
455            metadata: Some(metadata),
456            tag_count: 1,
457        }
458    }
459
460    #[test]
461    fn content_matches_by_etag_ignores_version_ids() {
462        let source_metadata = HashMap::new();
463        let target_metadata = HashMap::new();
464        let source = ReplicationSourceObject {
465            version_id: Some("source-version".to_string()),
466            etag: Some("\"abc\""),
467            user_defined: &source_metadata,
468            ..source_object(&source_metadata)
469        };
470        let target = ReplicationTargetObject {
471            version_id: Some("different-version"),
472            etag: Some("abc"),
473            metadata: Some(&target_metadata),
474            ..target_object(&target_metadata)
475        };
476
477        assert!(content_matches_by_etag(&source, &target));
478        assert!(replication_etags_match(source.etag, target.etag));
479    }
480
481    #[test]
482    fn target_newer_null_version_skips_existing_object_replication() {
483        let source_metadata = HashMap::new();
484        let target_metadata = HashMap::new();
485        let source = ReplicationSourceObject {
486            version_id: None,
487            ..source_object(&source_metadata)
488        };
489        let target = ReplicationTargetObject {
490            last_modified: Some(OffsetDateTime::UNIX_EPOCH + Duration::seconds(20)),
491            ..target_object(&target_metadata)
492        };
493
494        assert!(target_is_newer_than_source_null_version(&source, &target));
495        assert_eq!(
496            replication_action_for_target(&source, &target, ReplicationType::ExistingObject),
497            ReplicationAction::None
498        );
499    }
500
501    #[test]
502    fn replication_action_detects_content_and_metadata_differences() {
503        let mut source_metadata = HashMap::new();
504        source_metadata.insert("Cache-Control".to_string(), "max-age=1".to_string());
505        let mut target_metadata = HashMap::new();
506        target_metadata.insert("X-Amz-Tagging".to_string(), "a=1".to_string());
507        target_metadata.insert("Cache-Control".to_string(), "max-age=1".to_string());
508
509        let source = source_object(&source_metadata);
510        let target = target_object(&target_metadata);
511        assert_eq!(
512            replication_action_for_target(&source, &target, ReplicationType::ExistingObject),
513            ReplicationAction::None
514        );
515
516        let changed_content = ReplicationTargetObject {
517            content_length: 11,
518            ..target_object(&target_metadata)
519        };
520        assert_eq!(
521            replication_action_for_target(&source, &changed_content, ReplicationType::ExistingObject),
522            ReplicationAction::All
523        );
524
525        let mut changed_target_metadata = target_metadata.clone();
526        changed_target_metadata.insert("Cache-Control".to_string(), "max-age=2".to_string());
527        let changed_metadata = target_object(&changed_target_metadata);
528        assert_eq!(
529            replication_action_for_target(&source, &changed_metadata, ReplicationType::ExistingObject),
530            ReplicationAction::Metadata
531        );
532    }
533
534    /// P1-19 runtime spot-check exemption matrix: drift only applies when the
535    /// source addressed a real version uuid.
536    #[test]
537    fn test_version_identity_drift_judgment() {
538        let source = "6fa459ea-ee8a-3ca4-894e-db77e160355e";
539        for (sent, got, expected) in [
540            (source, Some(source), false),
541            (source, Some("0e304ce5-33e9-4b8a-9b12-9e40a53e6ded"), true),
542            (source, None, true),
543            ("", None, false),
544            ("null", Some("anything"), false),
545            ("00000000-0000-0000-0000-000000000000", Some("anything"), false),
546        ] {
547            assert_eq!(
548                version_identity_drifted(sent, got),
549                expected,
550                "sent {sent:?} got {got:?} must judge drift = {expected}"
551            );
552        }
553    }
554
555    #[test]
556    fn version_identity_capability_is_judged_only_for_real_source_versions() {
557        let source = "8e4d2f4c-2d5c-4f1b-9d0a-9c8b7a6f5e4d";
558        assert_eq!(
559            version_identity_capability_from_put(source, Some(source)),
560            Some(VersionIdentityCapability::Adopts)
561        );
562        // Wasabi / AWS shape: a minted id, or no id at all, both mean the
563        // source-side id is not addressable on the target.
564        assert_eq!(
565            version_identity_capability_from_put(source, Some("001788697733811332140-fR6j6uXKV-")),
566            Some(VersionIdentityCapability::MintsOwn)
567        );
568        assert_eq!(
569            version_identity_capability_from_put(source, None),
570            Some(VersionIdentityCapability::MintsOwn)
571        );
572        // No contract for an unversioned source write.
573        assert_eq!(version_identity_capability_from_put("", Some("anything")), None);
574        assert_eq!(version_identity_capability_from_put("00000000-0000-0000-0000-000000000000", None), None);
575        assert_eq!(version_identity_capability_from_put("null", Some("null")), None);
576        assert!(VersionIdentityCapability::MintsOwn.version_addressing_unreliable());
577        assert!(!VersionIdentityCapability::Adopts.version_addressing_unreliable());
578        assert!(!VersionIdentityCapability::Unknown.version_addressing_unreliable());
579    }
580
581    #[test]
582    fn replication_target_offline_error_classifier_is_network_scoped() {
583        assert!(is_replication_target_offline_error("put_object dispatch failure: connector error"));
584        assert!(is_replication_target_offline_error("request TimeoutError after retry"));
585        assert!(is_replication_target_offline_error("tcp connect error: connection refused"));
586        assert!(!is_replication_target_offline_error("put_object failed: AccessDenied: denied"));
587        assert!(!is_replication_target_offline_error("put_object failed: NoSuchBucket"));
588    }
589
590    /// N2 fail-closed policy: SSE-C replication may only proceed silently
591    /// against a target with a FRESH proof that it preserves the passthrough
592    /// transport headers. Unknown targets must be audited; freshly-flagged
593    /// dropping targets must never receive the PUT; an expired verdict in
594    /// EITHER direction must be re-earned through the audit — a sticky
595    /// Unsupported would outlive a target upgrade, and a sticky Supported
596    /// would fail open after a backend swap behind the same endpoint.
597    #[test]
598    fn ssec_passthrough_gate_is_fail_closed_and_ttl_bounded() {
599        for capability in [
600            SsecPassthroughCapability::Unknown,
601            SsecPassthroughCapability::Supported,
602            SsecPassthroughCapability::Unsupported,
603        ] {
604            for expired in [false, true] {
605                assert_eq!(
606                    ssec_passthrough_gate(false, capability, expired),
607                    SsecPassthroughGate::Proceed,
608                    "non-SSE-C objects must never be gated on the passthrough capability"
609                );
610            }
611        }
612        assert_eq!(
613            ssec_passthrough_gate(true, SsecPassthroughCapability::Supported, false),
614            SsecPassthroughGate::Proceed
615        );
616        assert_eq!(
617            ssec_passthrough_gate(true, SsecPassthroughCapability::Unknown, false),
618            SsecPassthroughGate::ProceedWithAudit
619        );
620        assert_eq!(
621            ssec_passthrough_gate(true, SsecPassthroughCapability::Unsupported, false),
622            SsecPassthroughGate::FailClosed
623        );
624        // Expiry flips both directions back to the audit.
625        assert_eq!(
626            ssec_passthrough_gate(true, SsecPassthroughCapability::Unsupported, true),
627            SsecPassthroughGate::ProceedWithAudit,
628            "an expired Unsupported verdict must allow a re-audit (upgraded target recovers without operator action)"
629        );
630        assert_eq!(
631            ssec_passthrough_gate(true, SsecPassthroughCapability::Supported, true),
632            SsecPassthroughGate::ProceedWithAudit,
633            "an expired Supported verdict must be re-proven (backend swap behind the same endpoint must not fail open)"
634        );
635    }
636
637    #[test]
638    fn ssec_passthrough_evidence_requires_customer_algorithm_echo() {
639        assert!(ssec_passthrough_evidence_present(Some("AES256")));
640        assert!(
641            !ssec_passthrough_evidence_present(Some("")),
642            "an empty echo is not evidence of preserved SSE-C material"
643        );
644        assert!(
645            !ssec_passthrough_evidence_present(None),
646            "a plain HEAD response must classify the target as having dropped the material"
647        );
648    }
649
650    #[test]
651    fn replication_action_detects_tags_and_object_lock_metadata_differences() {
652        let mut source_metadata = HashMap::new();
653        source_metadata.insert(AMZ_OBJECT_LOCK_MODE.to_string(), "GOVERNANCE".to_string());
654        let source = ReplicationSourceObject {
655            user_tags: "a=1&b=2",
656            user_defined: &source_metadata,
657            ..source_object(&source_metadata)
658        };
659
660        let target_metadata = HashMap::new();
661        let target = ReplicationTargetObject {
662            tag_count: 1,
663            metadata: Some(&target_metadata),
664            ..target_object(&target_metadata)
665        };
666
667        assert_eq!(
668            replication_action_for_target(&source, &target, ReplicationType::Metadata),
669            ReplicationAction::Metadata
670        );
671    }
672
673    #[test]
674    fn locked_put_uses_the_plain_source_md5_as_content_md5() {
675        assert_eq!(
676            object_lock_put_integrity(true, false, true, Some("\"9A0364B9E99BB480DD25E1F0284C8555\"")),
677            ObjectLockIntegrity::ContentMd5Hex("9a0364b9e99bb480dd25e1f0284c8555".to_string())
678        );
679    }
680
681    #[test]
682    fn locked_put_without_a_usable_etag_falls_back_to_the_sdk_checksum() {
683        // Multipart layout: the ETag is not the MD5 of the body.
684        assert_eq!(
685            object_lock_put_integrity(true, false, true, Some("9a0364b9e99bb480dd25e1f0284c8555-2")),
686            ObjectLockIntegrity::SdkChecksum
687        );
688        // Encrypted end to end: the ETag does not describe the wire bytes.
689        assert_eq!(
690            object_lock_put_integrity(true, false, false, Some("9a0364b9e99bb480dd25e1f0284c8555")),
691            ObjectLockIntegrity::SdkChecksum
692        );
693        assert_eq!(object_lock_put_integrity(true, false, true, None), ObjectLockIntegrity::SdkChecksum);
694        assert_eq!(object_lock_put_integrity(true, false, true, Some("")), ObjectLockIntegrity::SdkChecksum);
695    }
696
697    #[test]
698    fn integrity_is_not_added_without_lock_params_or_when_already_present() {
699        assert_eq!(
700            object_lock_put_integrity(false, false, true, Some("9a0364b9e99bb480dd25e1f0284c8555")),
701            ObjectLockIntegrity::NotRequired
702        );
703        assert_eq!(
704            object_lock_put_integrity(true, true, true, Some("9a0364b9e99bb480dd25e1f0284c8555")),
705            ObjectLockIntegrity::NotRequired
706        );
707    }
708}