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

google_cloud_shell_v1/
client.rs
