Skip to main content

rustfs_storage_api/
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 std::fmt;
16use std::sync::Arc;
17use std::time::Duration;
18
19use crate::replication::{
20    ReplicationState, ReplicationStatusType, VersionPurgeStatusType, replication_statuses_map, version_purge_statuses_map,
21};
22use time::OffsetDateTime;
23use uuid::Uuid;
24
25const NULL_VERSION_MARKER: &str = "null";
26
27#[derive(Debug, Default, Clone)]
28pub struct HTTPPreconditions {
29    pub if_match: Option<String>,
30    pub if_none_match: Option<String>,
31    pub if_modified_since: Option<OffsetDateTime>,
32    pub if_unmodified_since: Option<OffsetDateTime>,
33}
34
35impl HTTPPreconditions {
36    pub fn if_match_value(&self) -> Option<&str> {
37        non_empty_condition_value(self.if_match.as_deref())
38    }
39
40    pub fn if_none_match_value(&self) -> Option<&str> {
41        non_empty_condition_value(self.if_none_match.as_deref())
42    }
43}
44
45#[derive(Debug, Default, Clone)]
46pub struct ObjectLockRetentionOptions {
47    pub mode: Option<String>,
48    pub retain_until: Option<OffsetDateTime>,
49    pub bypass_governance: bool,
50}
51
52#[derive(Debug, Clone, Default)]
53pub struct ExpirationOptions {
54    pub expire: bool,
55}
56
57#[derive(Debug, Default, Clone)]
58pub struct ObjectLockDeleteOptions {
59    pub bypass_governance: bool,
60}
61
62#[derive(Debug, Default, Clone)]
63pub struct TransitionedObject {
64    pub name: String,
65    pub version_id: String,
66    pub tier: String,
67    pub free_version: bool,
68    pub status: String,
69}
70
71#[derive(Debug, Clone, Copy, PartialEq, Eq)]
72pub struct ObjectPreconditionPart {
73    pub number: usize,
74    pub exists: bool,
75}
76
77#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
78pub struct ObjectPreconditionState<'a> {
79    pub etag: Option<&'a str>,
80    pub mod_time: Option<OffsetDateTime>,
81    pub requested_part: Option<ObjectPreconditionPart>,
82}
83
84impl ObjectPreconditionState<'_> {
85    pub fn check(self, preconditions: Option<&HTTPPreconditions>) -> Result<(), ObjectPreconditionError> {
86        if let Some(part) = self.requested_part
87            && part.number > 1
88            && !part.exists
89        {
90            return Err(ObjectPreconditionError::InvalidPartNumber(part.number));
91        }
92
93        let Some(preconditions) = preconditions else {
94            return Ok(());
95        };
96
97        let has_valid_mod_time = self.mod_time.is_some_and(|t| t != OffsetDateTime::UNIX_EPOCH);
98        let if_none_match = preconditions.if_none_match_value();
99        let if_match = preconditions.if_match_value();
100
101        if let Some(if_none_match) = if_none_match
102            && let Some(etag) = self.etag
103            && etag_matches(etag, if_none_match)
104        {
105            return Err(ObjectPreconditionError::NotModified);
106        }
107
108        if has_valid_mod_time
109            && let Some(if_modified_since) = &preconditions.if_modified_since
110            && let Some(mod_time) = &self.mod_time
111            && !is_modified_since(mod_time, if_modified_since)
112        {
113            return Err(ObjectPreconditionError::NotModified);
114        }
115
116        if let Some(if_match) = if_match {
117            if let Some(etag) = self.etag {
118                if !etag_matches(etag, if_match) {
119                    return Err(ObjectPreconditionError::PreconditionFailed);
120                }
121            } else {
122                return Err(ObjectPreconditionError::PreconditionFailed);
123            }
124        }
125
126        if has_valid_mod_time
127            && if_match.is_none()
128            && let Some(if_unmodified_since) = &preconditions.if_unmodified_since
129            && let Some(mod_time) = &self.mod_time
130            && is_modified_since(mod_time, if_unmodified_since)
131        {
132            return Err(ObjectPreconditionError::PreconditionFailed);
133        }
134
135        Ok(())
136    }
137}
138
139#[derive(Debug, Clone, Copy, PartialEq, Eq)]
140pub enum ObjectPreconditionError {
141    InvalidPartNumber(usize),
142    NotModified,
143    PreconditionFailed,
144}
145
146impl fmt::Display for ObjectPreconditionError {
147    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
148        match self {
149            Self::InvalidPartNumber(part_number) => write!(f, "invalid part number {part_number}"),
150            Self::NotModified => f.write_str("object not modified"),
151            Self::PreconditionFailed => f.write_str("object precondition failed"),
152        }
153    }
154}
155
156impl std::error::Error for ObjectPreconditionError {}
157
158#[derive(Debug, Clone, Copy, PartialEq, Eq)]
159pub enum VersionMarker {
160    Null,
161    Version(Uuid),
162}
163
164impl VersionMarker {
165    pub fn parse(marker: impl AsRef<str>) -> Result<Self, uuid::Error> {
166        let marker = marker.as_ref();
167        if marker == NULL_VERSION_MARKER {
168            Ok(Self::Null)
169        } else {
170            let version = Uuid::parse_str(marker)?;
171            // Older releases advertised the null version as a nil UUID
172            // (issue #6745); a stored null version has no UUID, so resuming
173            // by `Version(nil)` could never match. Fold it into `Null`.
174            if version.is_nil() {
175                Ok(Self::Null)
176            } else {
177                Ok(Self::Version(version))
178            }
179        }
180    }
181}
182
183#[derive(Clone, Default, PartialEq, Eq)]
184pub enum WalkVersionsSortOrder {
185    #[default]
186    Ascending,
187    Descending,
188}
189
190/// In-memory compare-and-set identity for a queued exact-version delete.
191///
192/// `version_id` identifies the S3 version while these fields identify the
193/// concrete generation observed before the delete was queued. This matters for
194/// the reusable null version ID in versioning-suspended buckets.
195#[derive(Debug, Clone, Copy, PartialEq, Eq)]
196pub struct ObjectToDeleteIdentity {
197    pub data_dir: Option<Uuid>,
198    pub mod_time: Option<OffsetDateTime>,
199    pub delete_marker: bool,
200}
201
202#[derive(Debug, Default, Clone)]
203pub struct ObjectToDelete {
204    pub object_name: String,
205    pub version_id: Option<Uuid>,
206    /// RustFS-only precondition checked under the object write lock.
207    #[doc(hidden)]
208    pub expected_identity: Option<ObjectToDeleteIdentity>,
209    pub synthetic_version_id: bool,
210    pub delete_marker_replication_status: Option<String>,
211    pub version_purge_status: Option<VersionPurgeStatusType>,
212    pub version_purge_statuses: Option<String>,
213    pub replicate_decision_str: Option<String>,
214}
215
216impl ObjectToDelete {
217    pub fn with_expected_identity(
218        mut self,
219        data_dir: Option<Uuid>,
220        mod_time: Option<OffsetDateTime>,
221        delete_marker: bool,
222    ) -> Self {
223        self.expected_identity = Some(ObjectToDeleteIdentity {
224            data_dir,
225            mod_time,
226            delete_marker,
227        });
228        self
229    }
230
231    pub fn replication_state(&self) -> ReplicationState {
232        ReplicationState {
233            replication_status_internal: self.delete_marker_replication_status.clone(),
234            version_purge_status_internal: self.version_purge_statuses.clone(),
235            replicate_decision_str: self.replicate_decision_str.clone().unwrap_or_default(),
236            targets: replication_statuses_map(self.delete_marker_replication_status.as_deref().unwrap_or_default()),
237            purge_targets: version_purge_statuses_map(self.version_purge_statuses.as_deref().unwrap_or_default()),
238            ..Default::default()
239        }
240    }
241}
242
243#[derive(Debug, Default, Clone)]
244pub struct DeletedObject {
245    pub delete_marker: bool,
246    /// True when the delete plan looked the target up and found no such
247    /// object or version.
248    ///
249    /// The lookup only runs when the plan needs the source (Object Lock
250    /// check, replication decision, tier journal, or an expected identity),
251    /// so this proves absence and never proves presence: it stays false when
252    /// no lookup ran. Callers that must not announce a delete that removed
253    /// nothing need this, because the disk layer treats an absent version as
254    /// an idempotent success and reports `found` regardless.
255    pub source_missing: bool,
256    pub delete_marker_version_id: Option<Uuid>,
257    pub object_name: String,
258    pub version_id: Option<Uuid>,
259    pub delete_marker_mtime: Option<OffsetDateTime>,
260    pub replication_state: Option<ReplicationState>,
261    pub found: bool,
262    pub force_delete: bool,
263    pub force_delete_id: Option<Uuid>,
264    pub force_delete_target_arns: Vec<String>,
265    pub force_delete_generation: Option<i64>,
266}
267
268/// Accounting identity returned by the internal commit-time delete path.
269///
270/// This is carried separately from [`DeletedObject`] so adding quota details
271/// does not change the source shape of the public S3 delete result contract.
272#[derive(Debug, Default, Clone, PartialEq, Eq)]
273pub struct DeleteAccounting {
274    pub size: Option<u64>,
275    pub version_id: Option<Uuid>,
276    pub removed_current_object: bool,
277}
278
279impl DeletedObject {
280    pub fn version_purge_status(&self) -> VersionPurgeStatusType {
281        self.replication_state
282            .as_ref()
283            .map(|v| v.composite_version_purge_status())
284            .unwrap_or(VersionPurgeStatusType::Empty)
285    }
286
287    pub fn delete_marker_replication_status(&self) -> ReplicationStatusType {
288        self.replication_state
289            .as_ref()
290            .map(|v| v.composite_replication_status())
291            .unwrap_or(ReplicationStatusType::Empty)
292    }
293}
294
295#[derive(Clone)]
296pub struct WalkOptions<Filter> {
297    pub filter: Option<Filter>,
298    pub marker: Option<String>,
299    pub latest_only: bool,
300    pub ask_disks: String,
301    pub versions_sort: WalkVersionsSortOrder,
302    pub limit: usize,
303    pub include_free_versions: bool,
304    pub walkdir_timeout: Option<Duration>,
305    pub walkdir_stall_timeout: Option<Duration>,
306}
307
308impl<Filter> Default for WalkOptions<Filter> {
309    fn default() -> Self {
310        Self {
311            filter: None,
312            marker: None,
313            latest_only: false,
314            ask_disks: String::new(),
315            versions_sort: WalkVersionsSortOrder::default(),
316            limit: 0,
317            include_free_versions: false,
318            walkdir_timeout: None,
319            walkdir_stall_timeout: None,
320        }
321    }
322}
323
324impl<Filter> WalkOptions<Filter> {
325    pub fn with_walkdir_timeouts(mut self, timeout: Duration) -> Self {
326        self.walkdir_timeout = Some(timeout);
327        self.walkdir_stall_timeout = Some(timeout);
328        self
329    }
330}
331
332#[async_trait::async_trait]
333pub trait ObjectIO: Send + Sync + fmt::Debug + 'static {
334    type Error: std::error::Error + Send + Sync + 'static;
335    type RangeSpec: Send + 'static;
336    type HeaderMap: Send + 'static;
337    type ObjectOptions: Send + Sync + 'static;
338    type ObjectInfo: Send + 'static;
339    type GetObjectReader: Send + 'static;
340    type PutObjectReader: Send + 'static;
341
342    async fn get_object_reader(
343        &self,
344        bucket: &str,
345        object: &str,
346        range: Option<Self::RangeSpec>,
347        h: Self::HeaderMap,
348        opts: &Self::ObjectOptions,
349    ) -> Result<Self::GetObjectReader, Self::Error>;
350
351    async fn put_object(
352        &self,
353        bucket: &str,
354        object: &str,
355        data: &mut Self::PutObjectReader,
356        opts: &Self::ObjectOptions,
357    ) -> Result<Self::ObjectInfo, Self::Error>;
358}
359
360#[async_trait::async_trait]
361#[allow(clippy::too_many_arguments)]
362pub trait ObjectOperations: Send + Sync + fmt::Debug {
363    type Error: std::error::Error + Send + Sync + 'static;
364    type ObjectInfo: Send + 'static;
365    type ObjectOptions: Send + Sync + 'static;
366    type FileInfo: Send + Sync + 'static;
367    type ObjectToDelete: Send + 'static;
368    type DeletedObject: Send + 'static;
369
370    async fn get_object_info(
371        &self,
372        bucket: &str,
373        object: &str,
374        opts: &Self::ObjectOptions,
375    ) -> Result<Self::ObjectInfo, Self::Error>;
376    async fn verify_object_integrity(&self, bucket: &str, object: &str, opts: &Self::ObjectOptions) -> Result<(), Self::Error>;
377    async fn copy_object(
378        &self,
379        src_bucket: &str,
380        src_object: &str,
381        dst_bucket: &str,
382        dst_object: &str,
383        src_info: &mut Self::ObjectInfo,
384        src_opts: &Self::ObjectOptions,
385        dst_opts: &Self::ObjectOptions,
386    ) -> Result<Self::ObjectInfo, Self::Error>;
387    async fn delete_object_version(
388        &self,
389        bucket: &str,
390        object: &str,
391        fi: &Self::FileInfo,
392        force_del_marker: bool,
393    ) -> Result<(), Self::Error>;
394    async fn delete_object(&self, bucket: &str, object: &str, opts: Self::ObjectOptions)
395    -> Result<Self::ObjectInfo, Self::Error>;
396    async fn delete_objects(
397        &self,
398        bucket: &str,
399        objects: Vec<Self::ObjectToDelete>,
400        opts: Self::ObjectOptions,
401    ) -> (Vec<Self::DeletedObject>, Vec<Option<Self::Error>>);
402    /// Delete objects and optionally return commit-time accounting identities.
403    /// The default preserves the ordinary delete contract for implementations
404    /// that do not expose storage-level accounting details.
405    async fn delete_objects_with_accounting(
406        &self,
407        bucket: &str,
408        objects: Vec<Self::ObjectToDelete>,
409        opts: Self::ObjectOptions,
410    ) -> (Vec<Self::DeletedObject>, Vec<Option<Self::Error>>, Vec<Option<DeleteAccounting>>) {
411        let object_count = objects.len();
412        let (deleted, errors) = self.delete_objects(bucket, objects, opts).await;
413        (deleted, errors, vec![None; object_count])
414    }
415    async fn put_object_metadata(
416        &self,
417        bucket: &str,
418        object: &str,
419        opts: &Self::ObjectOptions,
420    ) -> Result<Self::ObjectInfo, Self::Error>;
421    async fn get_object_tags(&self, bucket: &str, object: &str, opts: &Self::ObjectOptions) -> Result<String, Self::Error>;
422    async fn put_object_tags(
423        &self,
424        bucket: &str,
425        object: &str,
426        tags: &str,
427        opts: &Self::ObjectOptions,
428    ) -> Result<Self::ObjectInfo, Self::Error>;
429    async fn delete_object_tags(
430        &self,
431        bucket: &str,
432        object: &str,
433        opts: &Self::ObjectOptions,
434    ) -> Result<Self::ObjectInfo, Self::Error>;
435    async fn add_partial(&self, bucket: &str, object: &str, version_id: &str) -> Result<(), Self::Error>;
436    async fn transition_object(&self, bucket: &str, object: &str, opts: &Self::ObjectOptions) -> Result<(), Self::Error>;
437    async fn restore_transitioned_object(
438        self: Arc<Self>,
439        bucket: &str,
440        object: &str,
441        opts: &Self::ObjectOptions,
442    ) -> Result<(), Self::Error>;
443}
444
445#[async_trait::async_trait]
446#[allow(clippy::too_many_arguments)]
447pub trait ListOperations: Send + Sync + fmt::Debug {
448    type Error: std::error::Error + Send + Sync + 'static;
449    type ListObjectsV2Info: Send + 'static;
450    type ListObjectVersionsInfo: Send + 'static;
451    type ObjectInfoOrErr: Send + 'static;
452    type WalkOptions: Send + 'static;
453    type WalkCancellation: Send + 'static;
454    type WalkResultSender: Send + 'static;
455
456    async fn list_objects_v2(
457        self: Arc<Self>,
458        bucket: &str,
459        prefix: &str,
460        continuation_token: Option<String>,
461        delimiter: Option<String>,
462        max_keys: i32,
463        fetch_owner: bool,
464        start_after: Option<String>,
465        incl_deleted: bool,
466    ) -> Result<Self::ListObjectsV2Info, Self::Error>;
467
468    async fn list_object_versions(
469        self: Arc<Self>,
470        bucket: &str,
471        prefix: &str,
472        marker: Option<String>,
473        version_marker: Option<String>,
474        delimiter: Option<String>,
475        max_keys: i32,
476    ) -> Result<Self::ListObjectVersionsInfo, Self::Error>;
477
478    async fn walk(
479        self: Arc<Self>,
480        rx: Self::WalkCancellation,
481        bucket: &str,
482        prefix: &str,
483        result: Self::WalkResultSender,
484        opts: Self::WalkOptions,
485    ) -> Result<(), Self::Error>;
486}
487
488#[async_trait::async_trait]
489#[allow(clippy::too_many_arguments)]
490pub trait MultipartOperations: Send + Sync + fmt::Debug {
491    type Error: std::error::Error + Send + Sync + 'static;
492    type ObjectInfo: Send + 'static;
493    type ObjectOptions: Send + Sync + 'static;
494    type PutObjectReader: Send + 'static;
495    type CompletePart: Send + 'static;
496    type ListMultipartsInfo: Send + 'static;
497    type MultipartUploadResult: Send + 'static;
498    type PartInfo: Send + 'static;
499    type MultipartInfo: Send + 'static;
500    type ListPartsInfo: Send + 'static;
501
502    async fn list_multipart_uploads(
503        &self,
504        bucket: &str,
505        prefix: &str,
506        key_marker: Option<String>,
507        upload_id_marker: Option<String>,
508        delimiter: Option<String>,
509        max_uploads: usize,
510    ) -> Result<Self::ListMultipartsInfo, Self::Error>;
511    async fn new_multipart_upload(
512        &self,
513        bucket: &str,
514        object: &str,
515        opts: &Self::ObjectOptions,
516    ) -> Result<Self::MultipartUploadResult, Self::Error>;
517    async fn copy_object_part(
518        &self,
519        src_bucket: &str,
520        src_object: &str,
521        dst_bucket: &str,
522        dst_object: &str,
523        upload_id: &str,
524        part_id: usize,
525        start_offset: i64,
526        length: i64,
527        src_info: &Self::ObjectInfo,
528        src_opts: &Self::ObjectOptions,
529        dst_opts: &Self::ObjectOptions,
530    ) -> Result<(), Self::Error>;
531    async fn put_object_part(
532        &self,
533        bucket: &str,
534        object: &str,
535        upload_id: &str,
536        part_id: usize,
537        data: &mut Self::PutObjectReader,
538        opts: &Self::ObjectOptions,
539    ) -> Result<Self::PartInfo, Self::Error>;
540    async fn get_multipart_info(
541        &self,
542        bucket: &str,
543        object: &str,
544        upload_id: &str,
545        opts: &Self::ObjectOptions,
546    ) -> Result<Self::MultipartInfo, Self::Error>;
547    async fn list_object_parts(
548        &self,
549        bucket: &str,
550        object: &str,
551        upload_id: &str,
552        part_number_marker: Option<usize>,
553        max_parts: usize,
554        opts: &Self::ObjectOptions,
555    ) -> Result<Self::ListPartsInfo, Self::Error>;
556    async fn abort_multipart_upload(
557        &self,
558        bucket: &str,
559        object: &str,
560        upload_id: &str,
561        opts: &Self::ObjectOptions,
562    ) -> Result<(), Self::Error>;
563    async fn complete_multipart_upload(
564        self: Arc<Self>,
565        bucket: &str,
566        object: &str,
567        upload_id: &str,
568        uploaded_parts: Vec<Self::CompletePart>,
569        opts: &Self::ObjectOptions,
570    ) -> Result<Self::ObjectInfo, Self::Error>;
571}
572
573#[async_trait::async_trait]
574pub trait HealOperations: Send + Sync + fmt::Debug {
575    type Error: std::error::Error + Send + Sync + 'static;
576    type HealResultItem: Send + 'static;
577    type HealOptions: Send + Sync + 'static;
578
579    async fn heal_format(&self, dry_run: bool) -> Result<(Self::HealResultItem, Option<Self::Error>), Self::Error>;
580    async fn heal_bucket(&self, bucket: &str, opts: &Self::HealOptions) -> Result<Self::HealResultItem, Self::Error>;
581    async fn heal_object(
582        &self,
583        bucket: &str,
584        object: &str,
585        version_id: &str,
586        opts: &Self::HealOptions,
587    ) -> Result<(Self::HealResultItem, Option<Self::Error>), Self::Error>;
588    async fn get_pool_and_set(&self, id: &str) -> Result<(Option<usize>, Option<usize>, Option<usize>), Self::Error>;
589    async fn check_abandoned_parts(&self, bucket: &str, object: &str, opts: &Self::HealOptions) -> Result<(), Self::Error>;
590}
591
592#[async_trait::async_trait]
593pub trait NamespaceLocking: Send + Sync + fmt::Debug + 'static {
594    type Error: std::error::Error + Send + Sync + 'static;
595    type NamespaceLock: Send + 'static;
596
597    async fn new_ns_lock(&self, bucket: &str, object: &str) -> Result<Self::NamespaceLock, Self::Error>;
598}
599
600#[derive(Debug, Default)]
601pub struct ListObjectsInfo<ObjectItem> {
602    pub is_truncated: bool,
603    pub next_marker: Option<String>,
604    pub objects: Vec<ObjectItem>,
605    pub prefixes: Vec<String>,
606}
607
608#[derive(Debug, Default)]
609pub struct ListObjectsV2Info<ObjectItem> {
610    pub is_truncated: bool,
611    pub continuation_token: Option<String>,
612    pub next_continuation_token: Option<String>,
613    pub objects: Vec<ObjectItem>,
614    pub prefixes: Vec<String>,
615}
616
617#[derive(Debug, Default, Clone)]
618pub struct ListObjectVersionsInfo<ObjectItem> {
619    pub is_truncated: bool,
620    pub next_marker: Option<String>,
621    pub next_version_idmarker: Option<String>,
622    pub objects: Vec<ObjectItem>,
623    pub prefixes: Vec<String>,
624}
625
626#[derive(Debug)]
627pub struct ObjectInfoOrErr<ObjectItem, ListError> {
628    pub item: Option<ObjectItem>,
629    pub err: Option<ListError>,
630}
631
632#[derive(Debug, Clone, PartialEq, Eq)]
633pub enum HTTPRangeError {
634    InvalidRangeSpec(String),
635}
636
637impl fmt::Display for HTTPRangeError {
638    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
639        match self {
640            Self::InvalidRangeSpec(message) => f.write_str(message),
641        }
642    }
643}
644
645impl std::error::Error for HTTPRangeError {}
646
647#[derive(Debug, Clone)]
648pub struct HTTPRangeSpec {
649    pub is_suffix_length: bool,
650    pub start: i64,
651    pub end: i64,
652}
653
654impl HTTPRangeSpec {
655    pub fn from_part_sizes(object_size: i64, part_number: usize, part_sizes: impl IntoIterator<Item = i64>) -> Option<Self> {
656        if object_size == 0 || part_number == 0 {
657            return None;
658        }
659
660        let mut start = 0_i64;
661        let mut end = -1_i64;
662        let mut parts = part_sizes.into_iter();
663        for _ in 0..part_number {
664            let part_size = parts.next()?;
665            start = end.checked_add(1)?;
666            end = start.checked_add(part_size)?.checked_sub(1)?;
667        }
668
669        Some(Self {
670            is_suffix_length: false,
671            start,
672            end,
673        })
674    }
675
676    pub fn get_offset_length(&self, res_size: i64) -> Result<(usize, i64), HTTPRangeError> {
677        let len = self.get_length(res_size)?;
678
679        let mut start = self.start;
680        if self.is_suffix_length {
681            let suffix_len = if self.start < 0 {
682                self.start
683                    .checked_neg()
684                    .ok_or_else(|| HTTPRangeError::InvalidRangeSpec("range value invalid: suffix length overflow".to_string()))?
685            } else {
686                self.start
687            };
688            start = res_size - suffix_len;
689            if start < 0 {
690                start = 0;
691            }
692        }
693        let offset = usize::try_from(start)
694            .map_err(|_| HTTPRangeError::InvalidRangeSpec("range value invalid: start offset overflow".to_string()))?;
695        Ok((offset, len))
696    }
697
698    pub fn get_length(&self, res_size: i64) -> Result<i64, HTTPRangeError> {
699        if res_size < 0 {
700            return Err(HTTPRangeError::InvalidRangeSpec("The requested range is not satisfiable".to_string()));
701        }
702
703        if self.is_suffix_length {
704            let specified_len = if self.start < 0 {
705                self.start
706                    .checked_neg()
707                    .ok_or_else(|| HTTPRangeError::InvalidRangeSpec("range value invalid: suffix length overflow".to_string()))?
708            } else {
709                self.start
710            };
711            let mut range_length = specified_len;
712
713            if specified_len > res_size {
714                range_length = res_size;
715            }
716
717            return Ok(range_length);
718        }
719
720        if self.start >= res_size {
721            return Err(HTTPRangeError::InvalidRangeSpec("The requested range is not satisfiable".to_string()));
722        }
723
724        if self.end > -1 {
725            let mut end = self.end;
726            if res_size <= end {
727                end = res_size - 1;
728            }
729
730            let range_length = end - self.start + 1;
731            return Ok(range_length);
732        }
733
734        if self.end == -1 {
735            let range_length = res_size - self.start;
736            return Ok(range_length);
737        }
738
739        Err(HTTPRangeError::InvalidRangeSpec(format!(
740            "range value invalid: start={}, end={}, expected start <= end and end >= -1",
741            self.start, self.end
742        )))
743    }
744}
745
746fn non_empty_condition_value(value: Option<&str>) -> Option<&str> {
747    value.map(str::trim).filter(|value| !value.is_empty())
748}
749
750fn etag_matches(object_etag: &str, condition_etag: &str) -> bool {
751    let object_etag = object_etag.trim_matches('"');
752    let condition_etag = condition_etag.trim_matches('"');
753    condition_etag == "*" || object_etag == condition_etag
754}
755
756fn is_modified_since(mod_time: &OffsetDateTime, given_time: &OffsetDateTime) -> bool {
757    mod_time.unix_timestamp() > given_time.unix_timestamp()
758}
759
760#[cfg(test)]
761mod tests {
762    use super::*;
763
764    #[test]
765    fn version_marker_parse_folds_null_and_nil_uuid_into_null() {
766        assert_eq!(VersionMarker::parse("null"), Ok(VersionMarker::Null));
767        // Older releases advertised the null version as a nil UUID
768        // (issue #6745); it must resume as the null marker, not a UUID no
769        // stored version carries.
770        assert_eq!(VersionMarker::parse(Uuid::nil().to_string()), Ok(VersionMarker::Null));
771
772        let version = Uuid::from_u128(7);
773        assert_eq!(VersionMarker::parse(version.to_string()), Ok(VersionMarker::Version(version)));
774        assert!(VersionMarker::parse("not-a-version").is_err());
775    }
776
777    #[test]
778    fn http_preconditions_ignore_empty_etag_headers() {
779        let opts = HTTPPreconditions {
780            if_match: Some("  ".to_owned()),
781            if_none_match: Some(" * ".to_owned()),
782            ..Default::default()
783        };
784
785        assert_eq!(opts.if_match_value(), None);
786        assert_eq!(opts.if_none_match_value(), Some("*"));
787    }
788
789    #[test]
790    fn object_lock_retention_defaults_preserve_false_bypass() {
791        let opts = ObjectLockRetentionOptions::default();
792
793        assert!(opts.mode.is_none());
794        assert!(opts.retain_until.is_none());
795        assert!(!opts.bypass_governance);
796    }
797
798    #[test]
799    fn object_precondition_state_rejects_missing_requested_part() {
800        let state = ObjectPreconditionState {
801            requested_part: Some(ObjectPreconditionPart {
802                number: 3,
803                exists: false,
804            }),
805            ..Default::default()
806        };
807
808        assert_eq!(state.check(None), Err(ObjectPreconditionError::InvalidPartNumber(3)));
809    }
810
811    #[test]
812    fn object_precondition_state_keeps_existing_etag_priority() {
813        let preconditions = HTTPPreconditions {
814            if_match: Some("\"other\"".to_owned()),
815            if_none_match: Some("\"abc\"".to_owned()),
816            ..Default::default()
817        };
818        let state = ObjectPreconditionState {
819            etag: Some("\"abc\""),
820            ..Default::default()
821        };
822
823        assert_eq!(state.check(Some(&preconditions)), Err(ObjectPreconditionError::NotModified));
824    }
825
826    #[test]
827    fn object_precondition_state_requires_etag_for_if_match() {
828        let preconditions = HTTPPreconditions {
829            if_match: Some("\"abc\"".to_owned()),
830            ..Default::default()
831        };
832
833        assert_eq!(
834            ObjectPreconditionState::default().check(Some(&preconditions)),
835            Err(ObjectPreconditionError::PreconditionFailed)
836        );
837    }
838
839    #[test]
840    fn object_precondition_state_checks_modification_dates() {
841        let mod_time = OffsetDateTime::UNIX_EPOCH + time::Duration::seconds(100);
842        let preconditions = HTTPPreconditions {
843            if_modified_since: Some(OffsetDateTime::UNIX_EPOCH + time::Duration::seconds(100)),
844            ..Default::default()
845        };
846        let state = ObjectPreconditionState {
847            mod_time: Some(mod_time),
848            ..Default::default()
849        };
850
851        assert_eq!(state.check(Some(&preconditions)), Err(ObjectPreconditionError::NotModified));
852
853        let preconditions = HTTPPreconditions {
854            if_unmodified_since: Some(OffsetDateTime::UNIX_EPOCH + time::Duration::seconds(99)),
855            ..Default::default()
856        };
857
858        assert_eq!(state.check(Some(&preconditions)), Err(ObjectPreconditionError::PreconditionFailed));
859    }
860
861    #[test]
862    fn version_marker_parses_null_and_uuid_markers() {
863        assert_eq!(VersionMarker::parse("null").expect("null marker should parse"), VersionMarker::Null);
864
865        let marker = "550e8400-e29b-41d4-a716-446655440000";
866        assert_eq!(
867            VersionMarker::parse(marker).expect("uuid marker should parse"),
868            VersionMarker::Version(Uuid::parse_str(marker).expect("test uuid should parse"))
869        );
870    }
871
872    #[test]
873    fn walk_versions_sort_order_defaults_to_ascending() {
874        assert!(matches!(WalkVersionsSortOrder::default(), WalkVersionsSortOrder::Ascending));
875    }
876
877    #[test]
878    fn walk_options_defaults_preserve_existing_contract() {
879        type TestFilter = fn(&str) -> bool;
880
881        let opts = WalkOptions::<TestFilter>::default();
882
883        assert!(opts.filter.is_none());
884        assert!(opts.marker.is_none());
885        assert!(!opts.latest_only);
886        assert!(opts.ask_disks.is_empty());
887        assert!(matches!(opts.versions_sort, WalkVersionsSortOrder::Ascending));
888        assert_eq!(opts.limit, 0);
889        assert!(!opts.include_free_versions);
890    }
891
892    #[test]
893    fn object_to_delete_builds_replication_state() {
894        let object = ObjectToDelete {
895            object_name: "photo.jpg".to_owned(),
896            delete_marker_replication_status: Some("PENDING".to_owned()),
897            version_purge_statuses: Some("arn:minio:replication:::target=PENDING".to_owned()),
898            replicate_decision_str: Some("arn:minio:replication:::target=PENDING".to_owned()),
899            ..Default::default()
900        };
901
902        let state = object.replication_state();
903
904        assert_eq!(state.replication_status_internal.as_deref(), Some("PENDING"));
905        assert_eq!(
906            state.version_purge_status_internal.as_deref(),
907            Some("arn:minio:replication:::target=PENDING")
908        );
909        assert_eq!(state.replicate_decision_str, "arn:minio:replication:::target=PENDING");
910    }
911
912    #[test]
913    fn deleted_object_status_helpers_default_to_empty() {
914        let object = DeletedObject::default();
915
916        assert_eq!(object.version_purge_status(), VersionPurgeStatusType::Empty);
917        assert_eq!(object.delete_marker_replication_status(), ReplicationStatusType::Empty);
918    }
919
920    #[test]
921    fn lifecycle_helper_defaults_preserve_existing_contracts() {
922        let expiration = ExpirationOptions::default();
923        let transitioned = TransitionedObject::default();
924
925        assert!(!expiration.expire);
926        assert!(transitioned.name.is_empty());
927        assert!(transitioned.version_id.is_empty());
928        assert!(transitioned.tier.is_empty());
929        assert!(!transitioned.free_version);
930        assert!(transitioned.status.is_empty());
931    }
932
933    #[derive(Debug)]
934    struct TestListBackend;
935
936    #[derive(Debug)]
937    struct TestListError;
938
939    impl fmt::Display for TestListError {
940        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
941            f.write_str("test list error")
942        }
943    }
944
945    impl std::error::Error for TestListError {}
946
947    #[async_trait::async_trait]
948    impl ListOperations for TestListBackend {
949        type Error = TestListError;
950        type ListObjectsV2Info = ListObjectsV2Info<&'static str>;
951        type ListObjectVersionsInfo = ListObjectVersionsInfo<&'static str>;
952        type ObjectInfoOrErr = ObjectInfoOrErr<&'static str, TestListError>;
953        type WalkOptions = WalkOptions<fn(&str) -> bool>;
954        type WalkCancellation = ();
955        type WalkResultSender = ();
956
957        async fn list_objects_v2(
958            self: Arc<Self>,
959            bucket: &str,
960            prefix: &str,
961            continuation_token: Option<String>,
962            delimiter: Option<String>,
963            max_keys: i32,
964            fetch_owner: bool,
965            start_after: Option<String>,
966            incl_deleted: bool,
967        ) -> Result<Self::ListObjectsV2Info, Self::Error> {
968            assert_eq!(bucket, "bucket");
969            assert_eq!(prefix, "photos/");
970            assert_eq!(continuation_token.as_deref(), Some("token"));
971            assert_eq!(delimiter.as_deref(), Some("/"));
972            assert_eq!(max_keys, 10);
973            assert!(fetch_owner);
974            assert_eq!(start_after.as_deref(), Some("photos/0001.jpg"));
975            assert!(!incl_deleted);
976
977            Ok(ListObjectsV2Info {
978                is_truncated: true,
979                continuation_token,
980                next_continuation_token: Some("next".to_owned()),
981                objects: vec!["photos/0002.jpg"],
982                prefixes: vec!["photos/2024/".to_owned()],
983            })
984        }
985
986        async fn list_object_versions(
987            self: Arc<Self>,
988            bucket: &str,
989            prefix: &str,
990            marker: Option<String>,
991            version_marker: Option<String>,
992            delimiter: Option<String>,
993            max_keys: i32,
994        ) -> Result<Self::ListObjectVersionsInfo, Self::Error> {
995            assert_eq!(bucket, "bucket");
996            assert_eq!(prefix, "photos/");
997            assert_eq!(marker.as_deref(), Some("photos/0001.jpg"));
998            assert_eq!(version_marker.as_deref(), Some("version"));
999            assert_eq!(delimiter.as_deref(), Some("/"));
1000            assert_eq!(max_keys, 10);
1001
1002            Ok(ListObjectVersionsInfo {
1003                is_truncated: false,
1004                next_marker: None,
1005                next_version_idmarker: None,
1006                objects: vec!["photos/0001.jpg"],
1007                prefixes: Vec::new(),
1008            })
1009        }
1010
1011        async fn walk(
1012            self: Arc<Self>,
1013            _rx: Self::WalkCancellation,
1014            bucket: &str,
1015            prefix: &str,
1016            _result: Self::WalkResultSender,
1017            opts: Self::WalkOptions,
1018        ) -> Result<(), Self::Error> {
1019            assert_eq!(bucket, "bucket");
1020            assert_eq!(prefix, "photos/");
1021            assert_eq!(opts.marker.as_deref(), Some("photos/0001.jpg"));
1022            Ok(())
1023        }
1024    }
1025
1026    #[tokio::test]
1027    async fn list_operations_trait_exposes_generic_list_contract() -> Result<(), TestListError> {
1028        let backend = Arc::new(TestListBackend);
1029
1030        let listed = backend
1031            .clone()
1032            .list_objects_v2(
1033                "bucket",
1034                "photos/",
1035                Some("token".to_owned()),
1036                Some("/".to_owned()),
1037                10,
1038                true,
1039                Some("photos/0001.jpg".to_owned()),
1040                false,
1041            )
1042            .await?;
1043        assert!(listed.is_truncated);
1044        assert_eq!(listed.objects, vec!["photos/0002.jpg"]);
1045        assert_eq!(listed.next_continuation_token.as_deref(), Some("next"));
1046
1047        let versions = backend
1048            .clone()
1049            .list_object_versions(
1050                "bucket",
1051                "photos/",
1052                Some("photos/0001.jpg".to_owned()),
1053                Some("version".to_owned()),
1054                Some("/".to_owned()),
1055                10,
1056            )
1057            .await?;
1058        assert_eq!(versions.objects, vec!["photos/0001.jpg"]);
1059
1060        let opts = WalkOptions::<fn(&str) -> bool> {
1061            marker: Some("photos/0001.jpg".to_owned()),
1062            ..Default::default()
1063        };
1064        backend.walk((), "bucket", "photos/", (), opts).await?;
1065
1066        Ok(())
1067    }
1068
1069    #[test]
1070    fn object_list_response_contracts_default_to_empty_collections() {
1071        let v1 = ListObjectsInfo::<()>::default();
1072        assert!(!v1.is_truncated);
1073        assert!(v1.next_marker.is_none());
1074        assert!(v1.objects.is_empty());
1075        assert!(v1.prefixes.is_empty());
1076
1077        let v2 = ListObjectsV2Info::<()>::default();
1078        assert!(!v2.is_truncated);
1079        assert!(v2.continuation_token.is_none());
1080        assert!(v2.next_continuation_token.is_none());
1081        assert!(v2.objects.is_empty());
1082        assert!(v2.prefixes.is_empty());
1083
1084        let versions = ListObjectVersionsInfo::<()>::default();
1085        assert!(!versions.is_truncated);
1086        assert!(versions.next_marker.is_none());
1087        assert!(versions.next_version_idmarker.is_none());
1088        assert!(versions.objects.is_empty());
1089        assert!(versions.prefixes.is_empty());
1090    }
1091
1092    #[test]
1093    fn object_info_or_err_keeps_optional_item_and_error_slots() {
1094        let item = ObjectInfoOrErr::<usize, &str> {
1095            item: Some(7),
1096            err: None,
1097        };
1098
1099        assert_eq!(item.item, Some(7));
1100        assert!(item.err.is_none());
1101    }
1102
1103    #[test]
1104    fn http_range_spec_offset_length_handles_suffix_and_bounds() {
1105        let range = HTTPRangeSpec {
1106            is_suffix_length: false,
1107            start: 5,
1108            end: 10,
1109        };
1110
1111        assert_eq!(range.get_offset_length(20).expect("range should fit"), (5, 6));
1112
1113        let suffix = HTTPRangeSpec {
1114            is_suffix_length: true,
1115            start: -5,
1116            end: -1,
1117        };
1118
1119        assert_eq!(suffix.get_offset_length(20).expect("suffix range should fit"), (15, 5));
1120    }
1121
1122    #[test]
1123    fn http_range_spec_from_part_sizes_keeps_part_boundaries() {
1124        let spec = HTTPRangeSpec::from_part_sizes(100, 3, [10, 15, 20]).expect("third part should exist");
1125
1126        assert_eq!(spec.start, 25);
1127        assert_eq!(spec.end, 44);
1128        assert!(HTTPRangeSpec::from_part_sizes(100, 0, [10]).is_none());
1129        assert!(HTTPRangeSpec::from_part_sizes(100, 2, [10]).is_none());
1130    }
1131}