google_cloud_iam_v1/client.rs
1// Copyright 2024 Google LLC
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// https://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//
15// Code generated by sidekick. DO NOT EDIT.
16#![allow(rustdoc::bare_urls)]
17#![allow(rustdoc::broken_intra_doc_links)]
18#![allow(rustdoc::invalid_html_tags)]
19#![allow(rustdoc::redundant_explicit_links)]
20
21/// Implements a client for the IAM Meta API.
22///
23/// # Example
24/// ```
25/// # use google_cloud_iam_v1::client::IAMPolicy;
26/// async fn sample(
27/// ) -> anyhow::Result<()> {
28/// let client = IAMPolicy::builder().build().await?;
29/// let response = client.set_iam_policy()
30/// /* set fields */
31/// .send().await?;
32/// println!("response {:?}", response);
33/// Ok(())
34/// }
35/// ```
36///
37/// # Service Description
38///
39/// API Overview
40///
41/// Manages Identity and Access Management (IAM) policies.
42///
43/// Any implementation of an API that offers access control features
44/// implements the google.iam.v1.IAMPolicy interface.
45///
46/// ## Data model
47///
48/// Access control is applied when a principal (user or service account), takes
49/// some action on a resource exposed by a service. Resources, identified by
50/// URI-like names, are the unit of access control specification. Service
51/// implementations can choose the granularity of access control and the
52/// supported permissions for their resources.
53/// For example one database service may allow access control to be
54/// specified only at the Table level, whereas another might allow access control
55/// to also be specified at the Column level.
56///
57/// ## Policy Structure
58///
59/// See google.iam.v1.Policy
60///
61/// This is intentionally not a CRUD style API because access control policies
62/// are created and deleted implicitly with the resources to which they are
63/// attached.
64///
65/// # Configuration
66///
67/// To configure `IAMPolicy` use the `with_*` methods in the type returned
68/// by [builder()][IAMPolicy::builder]. The default configuration should
69/// work for most applications. Common configuration changes include
70///
71/// * [with_endpoint()]: by default this client uses the global default endpoint
72/// (`https://iam-meta-api.googleapis.com`). Applications using regional
73/// endpoints or running in restricted networks (e.g. a network configured
74/// with [Private Google Access with VPC Service Controls]) may want to
75/// override this default.
76/// * [with_credentials()]: by default this client uses
77/// [Application Default Credentials]. Applications using custom
78/// authentication may need to override this default.
79///
80/// [with_endpoint()]: super::builder::iam_policy::ClientBuilder::with_endpoint
81/// [with_credentials()]: super::builder::iam_policy::ClientBuilder::with_credentials
82/// [Private Google Access with VPC Service Controls]: https://cloud.google.com/vpc-service-controls/docs/private-connectivity
83/// [Application Default Credentials]: https://cloud.google.com/docs/authentication#adc
84///
85/// # Pooling and Cloning
86///
87/// `IAMPolicy` holds a connection pool internally, it is advised to
88/// create one and reuse it. You do not need to wrap `IAMPolicy` in
89/// an [Rc](std::rc::Rc) or [Arc](std::sync::Arc) to reuse it, because it
90/// already uses an `Arc` internally.
91#[derive(Clone, Debug)]
92pub struct IAMPolicy {
93 inner: std::sync::Arc<dyn super::stub::dynamic::IAMPolicy>,
94}
95
96impl IAMPolicy {
97 /// Returns a builder for [IAMPolicy].
98 ///
99 /// ```
100 /// # async fn sample() -> google_cloud_gax::client_builder::Result<()> {
101 /// # use google_cloud_iam_v1::client::IAMPolicy;
102 /// let client = IAMPolicy::builder().build().await?;
103 /// # Ok(()) }
104 /// ```
105 pub fn builder() -> super::builder::iam_policy::ClientBuilder {
106 crate::new_client_builder(super::builder::iam_policy::client::Factory)
107 }
108
109 /// Creates a new client from the provided stub.
110 ///
111 /// The most common case for calling this function is in tests mocking the
112 /// client's behavior.
113 pub fn from_stub<T>(stub: impl Into<std::sync::Arc<T>>) -> Self
114 where
115 T: super::stub::IAMPolicy + 'static,
116 {
117 Self { inner: stub.into() }
118 }
119
120 pub(crate) async fn new(
121 config: gaxi::options::ClientConfig,
122 ) -> crate::ClientBuilderResult<Self> {
123 let inner = Self::build_inner(config).await?;
124 Ok(Self { inner })
125 }
126
127 async fn build_inner(
128 conf: gaxi::options::ClientConfig,
129 ) -> crate::ClientBuilderResult<std::sync::Arc<dyn super::stub::dynamic::IAMPolicy>> {
130 if gaxi::options::tracing_enabled(&conf) {
131 return Ok(std::sync::Arc::new(Self::build_with_tracing(conf).await?));
132 }
133 Ok(std::sync::Arc::new(Self::build_transport(conf).await?))
134 }
135
136 async fn build_transport(
137 conf: gaxi::options::ClientConfig,
138 ) -> crate::ClientBuilderResult<impl super::stub::IAMPolicy> {
139 super::transport::IAMPolicy::new(conf).await
140 }
141
142 async fn build_with_tracing(
143 conf: gaxi::options::ClientConfig,
144 ) -> crate::ClientBuilderResult<impl super::stub::IAMPolicy> {
145 Self::build_transport(conf)
146 .await
147 .map(super::tracing::IAMPolicy::new)
148 }
149
150 /// Sets the access control policy on the specified resource. Replaces any
151 /// existing policy.
152 ///
153 /// Can return `NOT_FOUND`, `INVALID_ARGUMENT`, and `PERMISSION_DENIED` errors.
154 ///
155 /// # Example
156 /// ```
157 /// # use google_cloud_iam_v1::client::IAMPolicy;
158 /// use google_cloud_iam_v1::Result;
159 /// async fn sample(
160 /// client: &IAMPolicy
161 /// ) -> Result<()> {
162 /// let response = client.set_iam_policy()
163 /// /* set fields */
164 /// .send().await?;
165 /// println!("response {:?}", response);
166 /// Ok(())
167 /// }
168 /// ```
169 pub fn set_iam_policy(&self) -> super::builder::iam_policy::SetIamPolicy {
170 super::builder::iam_policy::SetIamPolicy::new(self.inner.clone())
171 }
172
173 /// Gets the access control policy for a resource.
174 /// Returns an empty policy if the resource exists and does not have a policy
175 /// set.
176 ///
177 /// # Example
178 /// ```
179 /// # use google_cloud_iam_v1::client::IAMPolicy;
180 /// use google_cloud_iam_v1::Result;
181 /// async fn sample(
182 /// client: &IAMPolicy
183 /// ) -> Result<()> {
184 /// let response = client.get_iam_policy()
185 /// /* set fields */
186 /// .send().await?;
187 /// println!("response {:?}", response);
188 /// Ok(())
189 /// }
190 /// ```
191 pub fn get_iam_policy(&self) -> super::builder::iam_policy::GetIamPolicy {
192 super::builder::iam_policy::GetIamPolicy::new(self.inner.clone())
193 }
194
195 /// Returns permissions that a caller has on the specified resource.
196 /// If the resource does not exist, this will return an empty set of
197 /// permissions, not a `NOT_FOUND` error.
198 ///
199 /// Note: This operation is designed to be used for building permission-aware
200 /// UIs and command-line tools, not for authorization checking. This operation
201 /// may "fail open" without warning.
202 ///
203 /// # Example
204 /// ```
205 /// # use google_cloud_iam_v1::client::IAMPolicy;
206 /// use google_cloud_iam_v1::Result;
207 /// async fn sample(
208 /// client: &IAMPolicy
209 /// ) -> Result<()> {
210 /// let response = client.test_iam_permissions()
211 /// /* set fields */
212 /// .send().await?;
213 /// println!("response {:?}", response);
214 /// Ok(())
215 /// }
216 /// ```
217 pub fn test_iam_permissions(&self) -> super::builder::iam_policy::TestIamPermissions {
218 super::builder::iam_policy::TestIamPermissions::new(self.inner.clone())
219 }
220}