google_cloud_shell_v1/
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// Code generated by sidekick. DO NOT EDIT.
16#![allow(rustdoc::redundant_explicit_links)]
17#![allow(rustdoc::broken_intra_doc_links)]
18
19/// Implements a client for the Cloud Shell API.
20///
21/// # Example
22/// ```
23/// # use google_cloud_shell_v1::client::CloudShellService;
24/// # async fn sample() -> Result<(), Box<dyn std::error::Error>> {
25///     let client = CloudShellService::builder().build().await?;
26///     let name = "name_value";
27///     let response = client.get_environment()
28///         .set_name(name)
29///         .send().await?;
30///     println!("response {:?}", response);
31/// # Ok(()) }
32/// ```
33///
34/// # Service Description
35///
36/// API for interacting with Google Cloud Shell. Each user of Cloud Shell has at
37/// least one environment, which has the ID "default". Environment consists of a
38/// Docker image defining what is installed on the environment and a home
39/// directory containing the user's data that will remain across sessions.
40/// Clients use this API to start and fetch information about their environment,
41/// which can then be used to connect to that environment via a separate SSH
42/// client.
43///
44/// # Configuration
45///
46/// To configure `CloudShellService` use the `with_*` methods in the type returned
47/// by [builder()][CloudShellService::builder]. The default configuration should
48/// work for most applications. Common configuration changes include
49///
50/// * [with_endpoint()]: by default this client uses the global default endpoint
51///   (`https://cloudshell.googleapis.com`). Applications using regional
52///   endpoints or running in restricted networks (e.g. a network configured
53//    with [Private Google Access with VPC Service Controls]) may want to
54///   override this default.
55/// * [with_credentials()]: by default this client uses
56///   [Application Default Credentials]. Applications using custom
57///   authentication may need to override this default.
58///
59/// [with_endpoint()]: super::builder::cloud_shell_service::ClientBuilder::with_endpoint
60/// [with_credentials()]: super::builder::cloud_shell_service::ClientBuilder::with_credentials
61/// [Private Google Access with VPC Service Controls]: https://cloud.google.com/vpc-service-controls/docs/private-connectivity
62/// [Application Default Credentials]: https://cloud.google.com/docs/authentication#adc
63///
64/// # Pooling and Cloning
65///
66/// `CloudShellService` holds a connection pool internally, it is advised to
67/// create one and reuse it. You do not need to wrap `CloudShellService` in
68/// an [Rc](std::rc::Rc) or [Arc](std::sync::Arc) to reuse it, because it
69/// already uses an `Arc` internally.
70#[derive(Clone, Debug)]
71pub struct CloudShellService {
72    inner: std::sync::Arc<dyn super::stub::dynamic::CloudShellService>,
73}
74
75impl CloudShellService {
76    /// Returns a builder for [CloudShellService].
77    ///
78    /// ```
79    /// # async fn sample() -> google_cloud_gax::client_builder::Result<()> {
80    /// # use google_cloud_shell_v1::client::CloudShellService;
81    /// let client = CloudShellService::builder().build().await?;
82    /// # Ok(()) }
83    /// ```
84    pub fn builder() -> super::builder::cloud_shell_service::ClientBuilder {
85        crate::new_client_builder(super::builder::cloud_shell_service::client::Factory)
86    }
87
88    /// Creates a new client from the provided stub.
89    ///
90    /// The most common case for calling this function is in tests mocking the
91    /// client's behavior.
92    pub fn from_stub<T>(stub: T) -> Self
93    where
94        T: super::stub::CloudShellService + 'static,
95    {
96        Self {
97            inner: std::sync::Arc::new(stub),
98        }
99    }
100
101    pub(crate) async fn new(
102        config: gaxi::options::ClientConfig,
103    ) -> crate::ClientBuilderResult<Self> {
104        let inner = Self::build_inner(config).await?;
105        Ok(Self { inner })
106    }
107
108    async fn build_inner(
109        conf: gaxi::options::ClientConfig,
110    ) -> crate::ClientBuilderResult<std::sync::Arc<dyn super::stub::dynamic::CloudShellService>>
111    {
112        if gaxi::options::tracing_enabled(&conf) {
113            return Ok(std::sync::Arc::new(Self::build_with_tracing(conf).await?));
114        }
115        Ok(std::sync::Arc::new(Self::build_transport(conf).await?))
116    }
117
118    async fn build_transport(
119        conf: gaxi::options::ClientConfig,
120    ) -> crate::ClientBuilderResult<impl super::stub::CloudShellService> {
121        super::transport::CloudShellService::new(conf).await
122    }
123
124    async fn build_with_tracing(
125        conf: gaxi::options::ClientConfig,
126    ) -> crate::ClientBuilderResult<impl super::stub::CloudShellService> {
127        Self::build_transport(conf)
128            .await
129            .map(super::tracing::CloudShellService::new)
130    }
131
132    /// Gets an environment. Returns NOT_FOUND if the environment does not exist.
133    ///
134    /// # Example
135    /// ```
136    /// # use google_cloud_shell_v1::client::CloudShellService;
137    /// use google_cloud_shell_v1::Result;
138    /// async fn sample(
139    ///    client: &CloudShellService, name: &str
140    /// ) -> Result<()> {
141    ///     let response = client.get_environment()
142    ///         .set_name(name)
143    ///         .send().await?;
144    ///     println!("response {:?}", response);
145    ///     Ok(())
146    /// }
147    /// ```
148    pub fn get_environment(&self) -> super::builder::cloud_shell_service::GetEnvironment {
149        super::builder::cloud_shell_service::GetEnvironment::new(self.inner.clone())
150    }
151
152    /// Starts an existing environment, allowing clients to connect to it. The
153    /// returned operation will contain an instance of StartEnvironmentMetadata in
154    /// its metadata field. Users can wait for the environment to start by polling
155    /// this operation via GetOperation. Once the environment has finished starting
156    /// and is ready to accept connections, the operation will contain a
157    /// StartEnvironmentResponse in its response field.
158    ///
159    /// # Long running operations
160    ///
161    /// This method is used to start, and/or poll a [long-running Operation].
162    /// The [Working with long-running operations] chapter in the [user guide]
163    /// covers these operations in detail.
164    ///
165    /// [long-running operation]: https://google.aip.dev/151
166    /// [user guide]: https://googleapis.github.io/google-cloud-rust/
167    /// [working with long-running operations]: https://googleapis.github.io/google-cloud-rust/working_with_long_running_operations.html
168    ///
169    /// # Example
170    /// ```
171    /// # use google_cloud_shell_v1::client::CloudShellService;
172    /// use google_cloud_lro::Poller;
173    /// use google_cloud_shell_v1::Result;
174    /// async fn sample(
175    ///    client: &CloudShellService
176    /// ) -> Result<()> {
177    ///     let response = client.start_environment()
178    ///         /* set fields */
179    ///         .poller().until_done().await?;
180    ///     println!("response {:?}", response);
181    ///     Ok(())
182    /// }
183    /// ```
184    pub fn start_environment(&self) -> super::builder::cloud_shell_service::StartEnvironment {
185        super::builder::cloud_shell_service::StartEnvironment::new(self.inner.clone())
186    }
187
188    /// Sends OAuth credentials to a running environment on behalf of a user. When
189    /// this completes, the environment will be authorized to run various Google
190    /// Cloud command line tools without requiring the user to manually
191    /// authenticate.
192    ///
193    /// # Long running operations
194    ///
195    /// This method is used to start, and/or poll a [long-running Operation].
196    /// The [Working with long-running operations] chapter in the [user guide]
197    /// covers these operations in detail.
198    ///
199    /// [long-running operation]: https://google.aip.dev/151
200    /// [user guide]: https://googleapis.github.io/google-cloud-rust/
201    /// [working with long-running operations]: https://googleapis.github.io/google-cloud-rust/working_with_long_running_operations.html
202    ///
203    /// # Example
204    /// ```
205    /// # use google_cloud_shell_v1::client::CloudShellService;
206    /// use google_cloud_lro::Poller;
207    /// use google_cloud_shell_v1::Result;
208    /// async fn sample(
209    ///    client: &CloudShellService
210    /// ) -> Result<()> {
211    ///     let response = client.authorize_environment()
212    ///         /* set fields */
213    ///         .poller().until_done().await?;
214    ///     println!("response {:?}", response);
215    ///     Ok(())
216    /// }
217    /// ```
218    pub fn authorize_environment(
219        &self,
220    ) -> super::builder::cloud_shell_service::AuthorizeEnvironment {
221        super::builder::cloud_shell_service::AuthorizeEnvironment::new(self.inner.clone())
222    }
223
224    /// Adds a public SSH key to an environment, allowing clients with the
225    /// corresponding private key to connect to that environment via SSH. If a key
226    /// with the same content already exists, this will error with ALREADY_EXISTS.
227    ///
228    /// # Long running operations
229    ///
230    /// This method is used to start, and/or poll a [long-running Operation].
231    /// The [Working with long-running operations] chapter in the [user guide]
232    /// covers these operations in detail.
233    ///
234    /// [long-running operation]: https://google.aip.dev/151
235    /// [user guide]: https://googleapis.github.io/google-cloud-rust/
236    /// [working with long-running operations]: https://googleapis.github.io/google-cloud-rust/working_with_long_running_operations.html
237    ///
238    /// # Example
239    /// ```
240    /// # use google_cloud_shell_v1::client::CloudShellService;
241    /// use google_cloud_lro::Poller;
242    /// use google_cloud_shell_v1::Result;
243    /// async fn sample(
244    ///    client: &CloudShellService
245    /// ) -> Result<()> {
246    ///     let response = client.add_public_key()
247    ///         /* set fields */
248    ///         .poller().until_done().await?;
249    ///     println!("response {:?}", response);
250    ///     Ok(())
251    /// }
252    /// ```
253    pub fn add_public_key(&self) -> super::builder::cloud_shell_service::AddPublicKey {
254        super::builder::cloud_shell_service::AddPublicKey::new(self.inner.clone())
255    }
256
257    /// Removes a public SSH key from an environment. Clients will no longer be
258    /// able to connect to the environment using the corresponding private key.
259    /// If a key with the same content is not present, this will error with
260    /// NOT_FOUND.
261    ///
262    /// # Long running operations
263    ///
264    /// This method is used to start, and/or poll a [long-running Operation].
265    /// The [Working with long-running operations] chapter in the [user guide]
266    /// covers these operations in detail.
267    ///
268    /// [long-running operation]: https://google.aip.dev/151
269    /// [user guide]: https://googleapis.github.io/google-cloud-rust/
270    /// [working with long-running operations]: https://googleapis.github.io/google-cloud-rust/working_with_long_running_operations.html
271    ///
272    /// # Example
273    /// ```
274    /// # use google_cloud_shell_v1::client::CloudShellService;
275    /// use google_cloud_lro::Poller;
276    /// use google_cloud_shell_v1::Result;
277    /// async fn sample(
278    ///    client: &CloudShellService
279    /// ) -> Result<()> {
280    ///     let response = client.remove_public_key()
281    ///         /* set fields */
282    ///         .poller().until_done().await?;
283    ///     println!("response {:?}", response);
284    ///     Ok(())
285    /// }
286    /// ```
287    pub fn remove_public_key(&self) -> super::builder::cloud_shell_service::RemovePublicKey {
288        super::builder::cloud_shell_service::RemovePublicKey::new(self.inner.clone())
289    }
290
291    /// Provides the [Operations][google.longrunning.Operations] service functionality in this service.
292    ///
293    /// [google.longrunning.Operations]: google-cloud-longrunning::client::Operations
294    ///
295    /// # Example
296    /// ```
297    /// # use google_cloud_shell_v1::client::CloudShellService;
298    /// use google_cloud_shell_v1::Result;
299    /// async fn sample(
300    ///    client: &CloudShellService
301    /// ) -> Result<()> {
302    ///     let response = client.get_operation()
303    ///         /* set fields */
304    ///         .send().await?;
305    ///     println!("response {:?}", response);
306    ///     Ok(())
307    /// }
308    /// ```
309    pub fn get_operation(&self) -> super::builder::cloud_shell_service::GetOperation {
310        super::builder::cloud_shell_service::GetOperation::new(self.inner.clone())
311    }
312}
google_cloud_shell_v1/client.rs

google_cloud_shell_v1/
client.rs
