cloud_storage/sync/bucket.rs
1use crate::{
2 bucket::{IamPolicy, TestIamPermission},
3 Bucket, NewBucket,
4};
5
6/// Operations on [`Bucket`]()s.
7#[derive(Debug)]
8pub struct BucketClient<'a>(pub(super) &'a super::Client);
9
10impl<'a> BucketClient<'a> {
11 /// Creates a new `Bucket`. There are many options that you can provide for creating a new
12 /// bucket, so the `NewBucket` resource contains all of them. Note that `NewBucket` implements
13 /// `Default`, so you don't have to specify the fields you're not using. And error is returned
14 /// if that bucket name is already taken.
15 /// ### Example
16 /// ```
17 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
18 /// use cloud_storage::sync::Client;
19 /// use cloud_storage::bucket::{Bucket, NewBucket};
20 /// use cloud_storage::bucket::{Location, MultiRegion};
21 ///
22 /// let client = Client::new()?;
23 /// let new_bucket = NewBucket {
24 /// name: "cloud-storage-rs-doc-1".to_string(), // this is the only mandatory field
25 /// location: Location::Multi(MultiRegion::Eu),
26 /// ..Default::default()
27 /// };
28 /// let bucket = client.bucket().create(&new_bucket)?;
29 /// # client.bucket().delete(bucket)?;
30 /// # Ok(())
31 /// # }
32 /// ```
33 pub fn create(&self, new_bucket: &NewBucket) -> crate::Result<Bucket> {
34 self.0
35 .runtime
36 .block_on(self.0.client.bucket().create(new_bucket))
37 }
38
39 /// Returns all `Bucket`s within this project.
40 ///
41 /// ### Note
42 /// When using incorrect permissions, this function fails silently and returns an empty list.
43 ///
44 /// ### Example
45 /// ```
46 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
47 /// use cloud_storage::sync::Client;
48 /// use cloud_storage::Bucket;
49 ///
50 /// let client = Client::new()?;
51 /// let buckets = client.bucket().list()?;
52 /// # Ok(())
53 /// # }
54 /// ```
55 pub fn list(&self) -> crate::Result<Vec<Bucket>> {
56 self.0.runtime.block_on(self.0.client.bucket().list())
57 }
58
59 /// Returns a single `Bucket` by its name. If the Bucket does not exist, an error is returned.
60 /// ### Example
61 /// ```
62 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
63 /// use cloud_storage::sync::Client;
64 /// use cloud_storage::Bucket;
65 ///
66 /// let client = Client::new()?;
67 /// # use cloud_storage::bucket::NewBucket;
68 /// # let new_bucket = NewBucket {
69 /// # name: "cloud-storage-rs-doc-2".to_string(),
70 /// # ..Default::default()
71 /// # };
72 /// # let _ = client.bucket().create(&new_bucket)?;
73 ///
74 /// let bucket = client.bucket().read("cloud-storage-rs-doc-2")?;
75 /// # client.bucket().delete(bucket)?;
76 /// # Ok(())
77 /// # }
78 /// ```
79 pub fn read(&self, name: &str) -> crate::Result<Bucket> {
80 self.0.runtime.block_on(self.0.client.bucket().read(name))
81 }
82
83 /// Update an existing `Bucket`. If you declare you bucket as mutable, you can edit its fields.
84 /// You can then flush your changes to Google Cloud Storage using this method.
85 /// ### Example
86 /// ```
87 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
88 /// use cloud_storage::sync::Client;
89 /// use cloud_storage::bucket::{Bucket, RetentionPolicy};
90 ///
91 /// let client = Client::new()?;
92 /// # use cloud_storage::bucket::NewBucket;
93 /// # let new_bucket = NewBucket {
94 /// # name: "cloud-storage-rs-doc-3".to_string(),
95 /// # ..Default::default()
96 /// # };
97 /// # let _ = client.bucket().create(&new_bucket)?;
98 ///
99 /// let mut bucket = client.bucket().read("cloud-storage-rs-doc-3")?;
100 /// bucket.retention_policy = Some(RetentionPolicy {
101 /// retention_period: 50,
102 /// effective_time: chrono::Utc::now() + chrono::Duration::seconds(50),
103 /// is_locked: Some(false),
104 /// });
105 /// client.bucket().update(&bucket)?;
106 /// # client.bucket().delete(bucket)?;
107 /// # Ok(())
108 /// # }
109 /// ```
110 pub fn update(&self, bucket: &Bucket) -> crate::Result<Bucket> {
111 self.0
112 .runtime
113 .block_on(self.0.client.bucket().update(bucket))
114 }
115
116 /// Delete an existing `Bucket`. This permanently removes a bucket from Google Cloud Storage.
117 /// An error is returned when you don't have sufficient permissions, or when the
118 /// `retention_policy` prevents you from deleting your Bucket.
119 /// ### Example
120 /// ```no_run
121 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
122 /// use cloud_storage::sync::Client;
123 /// use cloud_storage::Bucket;
124 ///
125 /// let client = Client::new()?;
126 /// # use cloud_storage::bucket::NewBucket;
127 /// # let new_bucket = NewBucket {
128 /// # name: "unnecessary-bucket".to_string(),
129 /// # ..Default::default()
130 /// # };
131 /// # let _ = client.bucket().create(&new_bucket)?;
132 ///
133 /// let bucket = client.bucket().read("unnecessary-bucket")?;
134 /// client.bucket().delete(bucket)?;
135 /// # Ok(())
136 /// # }
137 /// ```
138 pub fn delete(&self, bucket: Bucket) -> crate::Result<()> {
139 self.0
140 .runtime
141 .block_on(self.0.client.bucket().delete(bucket))
142 }
143
144 /// Returns the [IAM Policy](https://cloud.google.com/iam/docs/) for this bucket.
145 /// ### Example
146 /// ```
147 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
148 /// use cloud_storage::sync::Client;
149 /// use cloud_storage::Bucket;
150 ///
151 /// let client = Client::new()?;
152 /// # use cloud_storage::bucket::NewBucket;
153 /// # let new_bucket = NewBucket {
154 /// # name: "cloud-storage-rs-doc-4".to_string(),
155 /// # ..Default::default()
156 /// # };
157 /// # let _ = client.bucket().create(&new_bucket)?;
158 ///
159 /// let bucket = client.bucket().read("cloud-storage-rs-doc-4")?;
160 /// let policy = client.bucket().get_iam_policy(&bucket)?;
161 /// # client.bucket().delete(bucket)?;
162 /// # Ok(())
163 /// # }
164 /// ```
165 pub fn get_iam_policy(&self, bucket: &Bucket) -> crate::Result<IamPolicy> {
166 self.0
167 .runtime
168 .block_on(self.0.client.bucket().get_iam_policy(bucket))
169 }
170
171 /// Updates the [IAM Policy](https://cloud.google.com/iam/docs/) for this bucket.
172 /// ### Example
173 /// ```
174 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
175 /// use cloud_storage::sync::Client;
176 /// use cloud_storage::Bucket;
177 /// use cloud_storage::bucket::{IamPolicy, Binding, IamRole, StandardIamRole, Entity};
178 ///
179 /// let client = Client::new()?;
180 /// # use cloud_storage::bucket::NewBucket;
181 /// # let new_bucket = NewBucket {
182 /// # name: "cloud-storage-rs-doc-5".to_string(),
183 /// # ..Default::default()
184 /// # };
185 /// # let _ = client.bucket().create(&new_bucket)?;
186 ///
187 /// let bucket = client.bucket().read("cloud-storage-rs-doc-5")?;
188 /// let iam_policy = IamPolicy {
189 /// version: 1,
190 /// bindings: vec![
191 /// Binding {
192 /// role: IamRole::Standard(StandardIamRole::ObjectViewer),
193 /// members: vec!["allUsers".to_string()],
194 /// condition: None,
195 /// }
196 /// ],
197 /// ..Default::default()
198 /// };
199 /// let policy = client.bucket().set_iam_policy(&bucket, &iam_policy)?;
200 /// # client.bucket().delete(bucket)?;
201 /// # Ok(())
202 /// # }
203 /// ```
204 pub fn set_iam_policy(&self, bucket: &Bucket, iam: &IamPolicy) -> crate::Result<IamPolicy> {
205 self.0
206 .runtime
207 .block_on(self.0.client.bucket().set_iam_policy(bucket, iam))
208 }
209
210 /// Checks whether the user provided in the service account has this permission.
211 /// ### Example
212 /// ```no_run
213 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
214 /// use cloud_storage::sync::Client;
215 /// use cloud_storage::Bucket;
216 ///
217 /// let client = Client::new()?;
218 /// let bucket = client.bucket().read("my-bucket")?;
219 /// client.bucket().test_iam_permission(&bucket, "storage.buckets.get")?;
220 /// # Ok(())
221 /// # }
222 /// ```
223 pub fn test_iam_permission(
224 &self,
225 bucket: &Bucket,
226 permission: &str,
227 ) -> crate::Result<TestIamPermission> {
228 self.0.runtime.block_on(
229 self.0
230 .client
231 .bucket()
232 .test_iam_permission(bucket, permission),
233 )
234 }
235}