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

google_cloud_shell_v1/
client.rs
