cloud_storage/resources/
default_object_access_control.rs

1#![allow(unused_imports)]
2
3pub use crate::resources::common::{Entity, ProjectTeam, Role};
4use crate::{error::GoogleResponse, resources::common::ListResponse};
5
6/// The DefaultObjectAccessControls resources represent the Access Control Lists (ACLs) applied to a
7/// new object within Google Cloud Storage when no ACL was provided for that object. ACLs let you
8/// specify who has access to your data and to what extent.
9#[derive(Debug, PartialEq, serde::Serialize, serde::Deserialize)]
10#[serde(rename_all = "camelCase")]
11pub struct DefaultObjectAccessControl {
12    /// The kind of item this is. For object access control entries, this is always
13    /// storage#objectAccessControl.
14    pub kind: String,
15    /// The entity holding the permission, in one of the following forms:
16    ///
17    /// * `user-userId`
18    /// * `user-email`
19    /// * `group-groupId`
20    /// * `group-email`
21    /// * `domain-domain`
22    /// * `project-team-projectId`
23    /// * `allUsers`
24    /// * `allAuthenticatedUsers`
25    ///
26    /// Examples:
27    ///
28    /// * The user liz@example.com would be user-liz@example.com.
29    /// * The group example@googlegroups.com would be group-example@googlegroups.com.
30    /// * To refer to all members of the G Suite for Business domain example.com, the entity would
31    /// be domain-example.com.
32    pub entity: Entity,
33    /// The access permission for the entity.
34    pub role: Role,
35    /// The email address associated with the entity, if any.
36    pub email: Option<String>,
37    /// The ID for the entity, if any.
38    pub entity_id: Option<String>,
39    /// The domain associated with the entity, if any.
40    pub domain: Option<String>,
41    /// The project team associated with the entity, if any.
42    pub project_team: Option<ProjectTeam>,
43    /// HTTP 1.1 Entity tag for the access-control entry.
44    pub etag: String,
45    /// The bucket this resource belongs to.
46    #[serde(default)]
47    pub bucket: String, // this field is not returned by Google, but we populate it manually for the
48                        // convenience of the end user.
49}
50
51/// Model that can be used to create a new DefaultObjectAccessControl object.
52#[derive(Debug, PartialEq, serde::Serialize, serde::Deserialize)]
53#[serde(rename_all = "camelCase")]
54pub struct NewDefaultObjectAccessControl {
55    /// The entity holding the permission, in one of the following forms:
56    ///
57    /// * `user-userId`
58    /// * `user-email`
59    /// * `group-groupId`
60    /// * `group-email`
61    /// * `domain-domain`
62    /// * `project-team-projectId`
63    /// * `allUsers`
64    /// * `allAuthenticatedUsers`
65    ///
66    /// Examples:
67    ///
68    /// * The user liz@example.com would be user-liz@example.com.
69    /// * The group example@googlegroups.com would be group-example@googlegroups.com.
70    /// * To refer to all members of the G Suite for Business domain example.com, the entity would
71    /// be domain-example.com.
72    pub entity: Entity,
73    /// The access permission for the entity.
74    pub role: Role,
75}
76
77impl DefaultObjectAccessControl {
78    /// Create a new `DefaultObjectAccessControl` entry on the specified bucket.
79    /// ### Important
80    /// Important: This method fails with a `400 Bad Request` response for buckets with uniform
81    /// bucket-level access enabled. Use `Bucket::get_iam_policy` and `Bucket::set_iam_policy` to
82    /// control access instead.
83    /// ### Example
84    /// ```no_run
85    /// # #[tokio::main]
86    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
87    /// use cloud_storage::default_object_access_control::{
88    ///     DefaultObjectAccessControl, NewDefaultObjectAccessControl, Role, Entity,
89    /// };
90    ///
91    /// let new_acl = NewDefaultObjectAccessControl {
92    ///     entity: Entity::AllAuthenticatedUsers,
93    ///     role: Role::Reader,
94    /// };
95    /// let default_acl = DefaultObjectAccessControl::create("mybucket", &new_acl).await?;
96    /// # default_acl.delete().await?;
97    /// # Ok(())
98    /// # }
99    /// ```
100    #[cfg(feature = "global-client")]
101    pub async fn create(
102        bucket: &str,
103        new_acl: &NewDefaultObjectAccessControl,
104    ) -> crate::Result<Self> {
105        crate::CLOUD_CLIENT
106            .default_object_access_control()
107            .create(bucket, new_acl)
108            .await
109    }
110
111    /// The synchronous equivalent of `DefautObjectAccessControl::create`.
112    ///
113    /// ### Features
114    /// This function requires that the feature flag `sync` is enabled in `Cargo.toml`.
115    #[cfg(all(feature = "global-client", feature = "sync"))]
116    pub fn create_sync(
117        bucket: &str,
118        new_acl: &NewDefaultObjectAccessControl,
119    ) -> crate::Result<Self> {
120        crate::runtime()?.block_on(Self::create(bucket, new_acl))
121    }
122
123    /// Retrieves default object ACL entries on the specified bucket.
124    /// ### Important
125    /// Important: This method fails with a `400 Bad Request` response for buckets with uniform
126    /// bucket-level access enabled. Use `Bucket::get_iam_policy` and `Bucket::set_iam_policy` to
127    /// control access instead.
128    /// ### Example
129    /// ```no_run
130    /// # #[tokio::main]
131    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
132    /// use cloud_storage::default_object_access_control::DefaultObjectAccessControl;
133    ///
134    /// let default_acls = DefaultObjectAccessControl::list("mybucket").await?;
135    /// # Ok(())
136    /// # }
137    /// ```
138    #[cfg(feature = "global-client")]
139    pub async fn list(bucket: &str) -> crate::Result<Vec<Self>> {
140        crate::CLOUD_CLIENT
141            .default_object_access_control()
142            .list(bucket)
143            .await
144    }
145
146    /// The synchronous equivalent of `DefautObjectAccessControl::list`.
147    ///
148    /// ### Features
149    /// This function requires that the feature flag `sync` is enabled in `Cargo.toml`.
150    #[cfg(all(feature = "global-client", feature = "sync"))]
151    pub fn list_sync(bucket: &str) -> crate::Result<Vec<Self>> {
152        crate::runtime()?.block_on(Self::list(bucket))
153    }
154
155    /// Read a single `DefaultObjectAccessControl`.
156    /// The `bucket` argument is the name of the bucket whose `DefaultObjectAccessControl` is to be
157    /// read, and the `entity` argument is the entity holding the permission. Options are
158    /// Can be "user-`userId`", "user-`email_address`", "group-`group_id`", "group-`email_address`",
159    /// "allUsers", or "allAuthenticatedUsers".
160    /// ### Important
161    /// Important: This method fails with a `400 Bad Request` response for buckets with uniform
162    /// bucket-level access enabled. Use `Bucket::get_iam_policy` and `Bucket::set_iam_policy` to
163    /// control access instead.
164    /// ### Example
165    /// ```no_run
166    /// # #[tokio::main]
167    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
168    /// use cloud_storage::default_object_access_control::{DefaultObjectAccessControl, Entity};
169    ///
170    /// let default_acl = DefaultObjectAccessControl::read("mybucket", &Entity::AllUsers).await?;
171    /// # Ok(())
172    /// # }
173    /// ```
174    #[cfg(feature = "global-client")]
175    pub async fn read(bucket: &str, entity: &Entity) -> crate::Result<Self> {
176        crate::CLOUD_CLIENT
177            .default_object_access_control()
178            .read(bucket, entity)
179            .await
180    }
181
182    /// The synchronous equivalent of `DefautObjectAccessControl::read`.
183    ///
184    /// ### Features
185    /// This function requires that the feature flag `sync` is enabled in `Cargo.toml`.
186    #[cfg(all(feature = "global-client", feature = "sync"))]
187    pub fn read_sync(bucket: &str, entity: &Entity) -> crate::Result<Self> {
188        crate::runtime()?.block_on(Self::read(bucket, entity))
189    }
190
191    /// Update the current `DefaultObjectAccessControl`.
192    /// ### Important
193    /// Important: This method fails with a `400 Bad Request` response for buckets with uniform
194    /// bucket-level access enabled. Use `Bucket::get_iam_policy` and `Bucket::set_iam_policy` to
195    /// control access instead.
196    /// ### Example
197    /// ```no_run
198    /// # #[tokio::main]
199    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
200    /// use cloud_storage::default_object_access_control::{DefaultObjectAccessControl, Entity};
201    ///
202    /// let mut default_acl = DefaultObjectAccessControl::read("my_bucket", &Entity::AllUsers).await?;
203    /// default_acl.entity = Entity::AllAuthenticatedUsers;
204    /// default_acl.update().await?;
205    /// # Ok(())
206    /// # }
207    /// ```
208    #[cfg(feature = "global-client")]
209    pub async fn update(&self) -> crate::Result<Self> {
210        crate::CLOUD_CLIENT
211            .default_object_access_control()
212            .update(self)
213            .await
214    }
215
216    /// The synchronous equivalent of `DefautObjectAccessControl::update`.
217    ///
218    /// ### Features
219    /// This function requires that the feature flag `sync` is enabled in `Cargo.toml`.
220    #[cfg(all(feature = "global-client", feature = "sync"))]
221    pub fn update_sync(&self) -> crate::Result<Self> {
222        crate::runtime()?.block_on(self.update())
223    }
224
225    /// Delete this 'DefaultObjectAccessControl`.
226    /// ### Important
227    /// Important: This method fails with a `400 Bad Request` response for buckets with uniform
228    /// bucket-level access enabled. Use `Bucket::get_iam_policy` and `Bucket::set_iam_policy` to
229    /// control access instead.
230    /// ### Example
231    /// ```no_run
232    /// # #[tokio::main]
233    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
234    /// use cloud_storage::default_object_access_control::{DefaultObjectAccessControl, Entity};
235    ///
236    /// let mut default_acl = DefaultObjectAccessControl::read("my_bucket", &Entity::AllUsers).await?;
237    /// default_acl.delete().await?;
238    /// # Ok(())
239    /// # }
240    /// ```
241    #[cfg(feature = "global-client")]
242    pub async fn delete(self) -> Result<(), crate::Error> {
243        crate::CLOUD_CLIENT
244            .default_object_access_control()
245            .delete(self)
246            .await
247    }
248
249    /// The synchronous equivalent of `DefautObjectAccessControl::delete`.
250    ///
251    /// ### Features
252    /// This function requires that the feature flag `sync` is enabled in `Cargo.toml`.
253    #[cfg(all(feature = "global-client", feature = "sync"))]
254    pub fn delete_sync(self) -> Result<(), crate::Error> {
255        crate::runtime()?.block_on(self.delete())
256    }
257}
258
259#[cfg(all(test, feature = "global-client"))]
260mod tests {
261    use super::*;
262
263    #[tokio::test]
264    async fn create() -> Result<(), Box<dyn std::error::Error>> {
265        let bucket = crate::read_test_bucket().await;
266        let new_acl = NewDefaultObjectAccessControl {
267            entity: Entity::AllUsers,
268            role: Role::Reader,
269        };
270        DefaultObjectAccessControl::create(&bucket.name, &new_acl).await?;
271        Ok(())
272    }
273
274    #[tokio::test]
275    async fn read() -> Result<(), Box<dyn std::error::Error>> {
276        let bucket = crate::read_test_bucket().await;
277        NewDefaultObjectAccessControl {
278            entity: Entity::AllUsers,
279            role: Role::Reader,
280        };
281        DefaultObjectAccessControl::read(&bucket.name, &Entity::AllUsers).await?;
282        Ok(())
283    }
284
285    #[tokio::test]
286    async fn list() -> Result<(), Box<dyn std::error::Error>> {
287        let bucket = crate::read_test_bucket().await;
288        DefaultObjectAccessControl::list(&bucket.name).await?;
289        Ok(())
290    }
291
292    #[tokio::test]
293    async fn update() -> Result<(), Box<dyn std::error::Error>> {
294        let bucket = crate::read_test_bucket().await;
295        let new_acl = NewDefaultObjectAccessControl {
296            entity: Entity::AllUsers,
297            role: Role::Reader,
298        };
299        let mut default_acl = DefaultObjectAccessControl::create(&bucket.name, &new_acl).await?;
300        default_acl.entity = Entity::AllAuthenticatedUsers;
301        default_acl.update().await?;
302        Ok(())
303    }
304
305    #[tokio::test]
306    async fn delete() -> Result<(), Box<dyn std::error::Error>> {
307        let bucket = crate::read_test_bucket().await;
308        let default_acl =
309            DefaultObjectAccessControl::read(&bucket.name, &Entity::AllAuthenticatedUsers).await?;
310        default_acl.delete().await?;
311        Ok(())
312    }
313
314    #[cfg(all(feature = "global-client", feature = "sync"))]
315    mod sync {
316        use super::*;
317
318        #[test]
319        fn create() -> Result<(), Box<dyn std::error::Error>> {
320            let bucket = crate::read_test_bucket_sync();
321            let new_acl = NewDefaultObjectAccessControl {
322                entity: Entity::AllUsers,
323                role: Role::Reader,
324            };
325            DefaultObjectAccessControl::create_sync(&bucket.name, &new_acl)?;
326            Ok(())
327        }
328
329        #[test]
330        fn read() -> Result<(), Box<dyn std::error::Error>> {
331            let bucket = crate::read_test_bucket_sync();
332            let new_acl = NewDefaultObjectAccessControl {
333                entity: Entity::AllUsers,
334                role: Role::Reader,
335            };
336            DefaultObjectAccessControl::create_sync(&bucket.name, &new_acl)?;
337            DefaultObjectAccessControl::read_sync(&bucket.name, &Entity::AllUsers)?;
338            Ok(())
339        }
340
341        #[test]
342        fn list() -> Result<(), Box<dyn std::error::Error>> {
343            let bucket = crate::read_test_bucket_sync();
344            DefaultObjectAccessControl::list_sync(&bucket.name)?;
345            Ok(())
346        }
347
348        #[test]
349        fn update() -> Result<(), Box<dyn std::error::Error>> {
350            let bucket = crate::read_test_bucket_sync();
351            let new_acl = NewDefaultObjectAccessControl {
352                entity: Entity::AllUsers,
353                role: Role::Reader,
354            };
355            let mut default_acl = DefaultObjectAccessControl::create_sync(&bucket.name, &new_acl)?;
356            default_acl.entity = Entity::AllAuthenticatedUsers;
357            default_acl.update_sync()?;
358            Ok(())
359        }
360
361        #[test]
362        fn delete() -> Result<(), Box<dyn std::error::Error>> {
363            let bucket = crate::read_test_bucket_sync();
364            let new_acl = NewDefaultObjectAccessControl {
365                entity: Entity::AllUsers,
366                role: Role::Reader,
367            };
368            let acl = DefaultObjectAccessControl::create_sync(&bucket.name, &new_acl)?;
369            acl.delete_sync()?;
370            Ok(())
371        }
372    }
373}
cloud_storage/resources/default_object_access_control.rs

cloud_storage/resources/
default_object_access_control.rs
