Skip to main content

rustfs_storage_api/
bucket.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::Debug;
16
17use serde::{Deserialize, Serialize};
18use time::OffsetDateTime;
19
20/// Namespace-lock object reserved for bucket lifecycle generation fencing.
21/// Empty S3 object keys are invalid, so this cannot collide with an object lock.
22pub const BUCKET_LIFECYCLE_LOCK_OBJECT: &str = "";
23
24/// Options for creating a new bucket.
25#[derive(Debug, Default, Serialize, Deserialize)]
26pub struct MakeBucketOptions {
27    /// Enable object lock for the bucket.
28    pub lock_enabled: bool,
29    /// Enable versioning for the bucket.
30    pub versioning_enabled: bool,
31    /// Force creation even if bucket already exists.
32    pub force_create: bool,
33    /// Optional creation timestamp.
34    pub created_at: Option<OffsetDateTime>,
35    /// Skip acquiring namespace lock.
36    pub no_lock: bool,
37}
38
39/// Operation to perform on a bucket during site replication delete.
40#[derive(Debug, Default, Clone, PartialEq, Serialize, Deserialize)]
41pub enum SRBucketDeleteOp {
42    /// No operation.
43    #[default]
44    NoOp,
45    /// Mark the bucket for deletion.
46    MarkDelete,
47    /// Purge the bucket and all its contents.
48    Purge,
49}
50
51/// Options for deleting a bucket.
52#[derive(Debug, Default, Clone, Serialize, Deserialize)]
53pub struct DeleteBucketOptions {
54    /// Skip acquiring namespace lock.
55    pub no_lock: bool,
56    /// Do not recreate bucket on failure.
57    pub no_recreate: bool,
58    /// Force deletion even if bucket is not empty.
59    pub force: bool,
60    /// Delete empty directory remnants after the local peer verifies no object metadata exists.
61    pub force_if_empty: bool,
62    /// Site replication delete operation.
63    pub srdelete_op: SRBucketDeleteOp,
64}
65
66/// Options for querying bucket information.
67#[derive(Debug, Default, Serialize, Deserialize)]
68pub struct BucketOptions {
69    /// Include deleted buckets in results.
70    pub deleted: bool,
71    /// Use cached bucket information.
72    pub cached: bool,
73    /// Skip loading bucket metadata.
74    pub no_metadata: bool,
75}
76
77/// Information about a bucket.
78#[derive(Debug, Clone, Serialize, Deserialize, Default)]
79pub struct BucketInfo {
80    /// Bucket name.
81    pub name: String,
82    /// Creation timestamp.
83    pub created: Option<OffsetDateTime>,
84    /// Deletion timestamp (if deleted).
85    pub deleted: Option<OffsetDateTime>,
86    /// Whether versioning is enabled.
87    pub versioning: bool,
88    /// Whether object locking is enabled.
89    pub object_locking: bool,
90}
91
92/// Bucket-level storage operations.
93#[async_trait::async_trait]
94pub trait BucketOperations: Send + Sync + Debug {
95    type Error: std::error::Error + Send + Sync + 'static;
96
97    async fn make_bucket(&self, bucket: &str, opts: &MakeBucketOptions) -> Result<(), Self::Error>;
98    async fn get_bucket_info(&self, bucket: &str, opts: &BucketOptions) -> Result<BucketInfo, Self::Error>;
99    async fn list_bucket(&self, opts: &BucketOptions) -> Result<Vec<BucketInfo>, Self::Error>;
100    async fn delete_bucket(&self, bucket: &str, opts: &DeleteBucketOptions) -> Result<(), Self::Error>;
101}
102
103#[cfg(test)]
104mod tests {
105    use super::*;
106
107    #[test]
108    fn bucket_info_serializes_with_existing_fields() {
109        let bucket = BucketInfo {
110            name: "photos".to_owned(),
111            created: Some(OffsetDateTime::UNIX_EPOCH),
112            deleted: None,
113            versioning: true,
114            object_locking: false,
115        };
116
117        let encoded = serde_json::to_string(&bucket).expect("serialize BucketInfo to JSON");
118        let decoded: BucketInfo = serde_json::from_str(&encoded).expect("deserialize BucketInfo from JSON");
119
120        assert_eq!(decoded.name, "photos");
121        assert_eq!(decoded.created, Some(OffsetDateTime::UNIX_EPOCH));
122        assert!(decoded.versioning);
123        assert!(!decoded.object_locking);
124    }
125
126    #[test]
127    fn default_bucket_options_preserve_false_flags() {
128        let opts = BucketOptions::default();
129
130        assert!(!opts.deleted);
131        assert!(!opts.cached);
132        assert!(!opts.no_metadata);
133    }
134
135    #[test]
136    fn default_delete_bucket_options_use_noop_site_replication() {
137        let opts = DeleteBucketOptions::default();
138
139        assert_eq!(opts.srdelete_op, SRBucketDeleteOp::NoOp);
140        assert!(!opts.no_lock);
141        assert!(!opts.no_recreate);
142        assert!(!opts.force);
143    }
144}