qcs_api_client_grpc/
lib.rs

1// Copyright 2022 Rigetti Computing
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// http://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//! This crate provides an autogenerated gRPC client for the QCS API, along with helper utilities for automatically loading
16//! credentials from a user's QCS config and keeping authentication tokens refreshed.
17//!
18//! - [`get_channel`]: create a [`Channel`](tonic::transport::Channel) to the given gRPC endpoint with QCS authentication automatically set up.
19//! - [`wrap_channel`]: wrap an existing [`Channel`](tonic::transport::Channel) with QCS authentication.
20//!
21//! ## Quick Start
22//!
23//! ```rust
24//! use qcs_api_client_grpc::get_channel;
25//! use qcs_api_client_grpc::services::controller::controller_client::ControllerClient;
26//! use qcs_api_client_grpc::services::translation::translation_client::TranslationClient;
27//!
28//! async fn controller_request() {
29//!     let uri = "example.per-qpu.rigetti.com:50000".parse().unwrap();
30//!     let channel = get_channel(uri).unwrap();
31//!     let mut client = ControllerClient::new(channel);
32//!     // Use the client
33//! }
34//!
35//! fn translation_request() {
36//!     let uri = "example.translation.rigetti.com:50000".parse().unwrap();
37//!     let channel = get_channel(uri).unwrap();
38//!     let mut client = TranslationClient::new(channel);
39//!     // Use the client
40//! }
41//! ```
42//!
43//! # Crate features
44//!
45//! * `server`: include the generated server code for both Controller Service
46//!   and Translation Service
47//! * `regen`: regenerate the protobuf code and store it in `./src/gen`
48//!
49//! By default, both features are disabled.
50
51/// Utilities for creating and working with [`Channel`]s.
52///
53/// This module contains helper code for wrapping a [`Channel`] so that QCS credentials are
54/// automatically used and refreshed as necessary.
55///
56/// Most users will want to use [`get_channel`], [`get_wrapped_channel`], or [`wrap_channel`].
57///
58/// # Generics
59///
60/// The functions for wrapping channels use generics `C: GrpcService<BoxBody>` to accept not only
61/// bare [`Channel`]s but also channels wrapped in middleware like [`RefreshService`] or
62/// [`RetryService`]
63///
64/// # Example
65///
66/// To create a channel that automatically retries on certain errors and refreshes QCS credentials
67/// when authentication fails:
68///
69/// ```no_run
70/// # #[tokio::main]
71/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
72/// use qcs_api_client_grpc::tonic::parse_uri;
73/// use qcs_api_client_grpc::tonic::get_channel;
74/// use qcs_api_client_grpc::tonic::wrap_channel;
75/// use qcs_api_client_grpc::tonic::wrap_channel_with_retry;
76///
77/// let uri = parse_uri("https://api.qcs.rigetti.com")?;
78/// let channel = get_channel(uri)?;
79/// let with_creds = wrap_channel(channel)?;
80/// let with_creds_and_retry = wrap_channel_with_retry(with_creds);
81/// // Use with_creds_and_retry as a gRPC client
82/// # Ok(())
83/// # }
84/// ```
85pub mod tonic;
86
87pub use crate::tonic::{
88    get_channel, get_channel_with_timeout, get_endpoint, get_endpoint_with_timeout,
89    get_wrapped_channel, wrap_channel,
90};
91pub use qcs_api_client_common::configuration as client_configuration;
92
93#[allow(clippy::derive_partial_eq_without_eq)]
94#[allow(clippy::needless_borrow)]
95pub mod models {
96    pub mod controller {
97        include!("gen/models.controller.rs");
98        include!("gen/models.controller.serde.rs");
99    }
100    pub mod translation {
101        include!("gen/models.translation.rs");
102        include!("gen/models.translation.serde.rs");
103    }
104}
105#[allow(clippy::derive_partial_eq_without_eq)]
106pub mod services {
107    pub mod controller {
108        include!("gen/services.controller.rs");
109        include!("gen/services.controller.serde.rs");
110    }
111    pub mod translation {
112        include!("gen/services.translation.rs");
113        include!("gen/services.translation.serde.rs");
114    }
115}
qcs_api_client_grpc/lib.rs

qcs_api_client_grpc/
lib.rs
