google_cloud_storage/control/
client.rs

1// Copyright 2025 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//! Contains the StorageControl client and related types.
16
17/// Implements a client for the Cloud Storage API.
18///
19/// # Example
20/// ```
21/// # tokio_test::block_on(async {
22/// # use google_cloud_storage::client::StorageControl;
23/// let client = StorageControl::builder().build().await?;
24/// // use `client` to make requests to Cloud Storage.
25/// # gax::client_builder::Result::<()>::Ok(()) });
26/// ```
27///
28/// # Configuration
29///
30/// To configure `StorageControl` use the `with_*` methods in the type returned
31/// by [builder()][StorageControl::builder]. The default configuration should
32/// work for most applications. Common configuration changes include
33///
34/// * [with_endpoint()]: by default this client uses the global default endpoint
35///   (`https://storage.googleapis.com`). Applications using regional
36///   endpoints or running in restricted networks (e.g. a network configured
37//    with [Private Google Access with VPC Service Controls]) may want to
38///   override this default.
39/// * [with_credentials()]: by default this client uses
40///   [Application Default Credentials]. Applications using custom
41///   authentication may need to override this default.
42///
43/// # Pooling and Cloning
44///
45/// `StorageControl` holds a connection pool internally, it is advised to
46/// create one and the reuse it.  You do not need to wrap `StorageControl` in
47/// an [Rc](std::rc::Rc) or [Arc](std::sync::Arc) to reuse it, because it
48/// already uses an `Arc` internally.
49///
50/// # Service Description
51///
52/// The Cloud Storage API allows applications to read and write data through
53/// the abstractions of buckets and objects. For a description of these
54/// abstractions please see <https://cloud.google.com/storage/docs>.
55///
56/// This client is used to perform metadata operations, such as creating
57/// buckets, deleting objects, listing objects, etc. It does not expose any
58/// functions to write or read data in objects.
59///
60/// Resources are named as follows:
61///
62/// - Projects are referred to as they are defined by the Resource Manager API,
63///   using strings like `projects/123456` or `projects/my-string-id`.
64///
65/// - Buckets are named using string names of the form:
66///   `projects/{project}/buckets/{bucket}`
67///   For globally unique buckets, `_` may be substituted for the project.
68///
69/// - Objects are uniquely identified by their name along with the name of the
70///   bucket they belong to, as separate strings in this API. For example:
71///   ```no_rust
72///   bucket = "projects/_/buckets/my-bucket"
73///   object = "my-object/with/a/folder-like/name"
74///   ```
75///   Note that object names can contain `/` characters, which are treated as
76///   any other character (no special directory semantics).
77///
78/// [with_endpoint()]: ClientBuilder::with_endpoint
79/// [with_credentials()]: ClientBuilder::with_credentials
80/// [Private Google Access with VPC Service Controls]: https://cloud.google.com/vpc-service-controls/docs/private-connectivity
81/// [Application Default Credentials]: https://cloud.google.com/docs/authentication#adc
82#[derive(Clone, Debug)]
83pub struct StorageControl {
84    pub(crate) storage: crate::generated::gapic::client::StorageControl,
85    pub(crate) control: crate::generated::gapic_control::client::StorageControl,
86}
87
88// Note that the `impl` is defined in `generated/client.rs`
89
90/// A builder for [StorageControl].
91///
92/// ```
93/// # tokio_test::block_on(async {
94/// # use google_cloud_storage::*;
95/// # use builder::storage_control::ClientBuilder;
96/// # use client::StorageControl;
97/// let builder : ClientBuilder = StorageControl::builder();
98/// let client = builder
99///     .with_endpoint("https://storage.googleapis.com")
100///     .build().await?;
101/// # gax::client_builder::Result::<()>::Ok(()) });
102/// ```
103pub type ClientBuilder =
104    gax::client_builder::ClientBuilder<client_builder::Factory, gaxi::options::Credentials>;
105
106pub(crate) mod client_builder {
107    use super::StorageControl;
108    pub struct Factory;
109    impl gax::client_builder::internal::ClientFactory for Factory {
110        type Client = StorageControl;
111        type Credentials = gaxi::options::Credentials;
112        async fn build(
113            self,
114            config: gaxi::options::ClientConfig,
115        ) -> gax::client_builder::Result<Self::Client> {
116            Self::Client::new(config).await
117        }
118    }
119}
120
121#[cfg(test)]
122mod tests {
123    use super::StorageControl;
124
125    #[tokio::test]
126    async fn builder() -> anyhow::Result<()> {
127        let _ = StorageControl::builder()
128            .with_credentials(auth::credentials::testing::test_credentials())
129            .build()
130            .await?;
131        Ok(())
132    }
133}
google_cloud_storage/control/client.rs

google_cloud_storage/control/
client.rs
