tonic/transport/mod.rs
1/*
2 *
3 * Copyright 2025 gRPC authors.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to
7 * deal in the Software without restriction, including without limitation the
8 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
9 * sell copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
21 * IN THE SOFTWARE.
22 *
23 */
24
25//! Batteries included server and client.
26//!
27//! This module provides a set of batteries included, fully featured and
28//! fast set of HTTP/2 server and client's. These components each provide a
29//! `rustls` tls backend when the respective feature flag is enabled, and
30//! provides builders to configure transport behavior.
31//!
32//! # Features
33//!
34//! - TLS support via [rustls].
35//! - Load balancing
36//! - Timeouts
37//! - Concurrency Limits
38//! - Rate limiting
39//!
40//! # Examples
41//!
42//! ## Client
43//!
44//! ```no_run
45//! # #[cfg(feature = "rustls")]
46//! # use tonic::transport::{Channel, Certificate, ClientTlsConfig};
47//! # use std::time::Duration;
48//! # use tonic::client::GrpcService;;
49//! # use http::Request;
50//! # #[cfg(feature = "rustls")]
51//! # async fn do_thing() -> Result<(), Box<dyn std::error::Error>> {
52//! let cert = std::fs::read_to_string("ca.pem")?;
53//!
54//! let mut channel = Channel::from_static("https://example.com")
55//! .tls_config(ClientTlsConfig::new()
56//! .ca_certificate(Certificate::from_pem(&cert))
57//! .domain_name("example.com".to_string()))?
58//! .timeout(Duration::from_secs(5))
59//! .rate_limit(5, Duration::from_secs(1))
60//! .concurrency_limit(256)
61//! .connect()
62//! .await?;
63//!
64//! channel.call(Request::new(tonic::body::empty_body())).await?;
65//! # Ok(())
66//! # }
67//! ```
68//!
69//! ## Server
70//!
71//! ```no_run
72//! # use std::convert::Infallible;
73//! # #[cfg(feature = "rustls")]
74//! # use tonic::transport::{Server, Identity, ServerTlsConfig};
75//! # use tonic::body::Body;
76//! # use tower::Service;
77//! # #[cfg(feature = "rustls")]
78//! # async fn do_thing() -> Result<(), Box<dyn std::error::Error>> {
79//! # #[derive(Clone)]
80//! # pub struct Svc;
81//! # impl Service<hyper::Request<Body>> for Svc {
82//! # type Response = hyper::Response<Body>;
83//! # type Error = Infallible;
84//! # type Future = std::future::Ready<Result<Self::Response, Self::Error>>;
85//! # fn poll_ready(&mut self, _cx: &mut std::task::Context<'_>) -> std::task::Poll<Result<(), Self::Error>> {
86//! # Ok(()).into()
87//! # }
88//! # fn call(&mut self, _req: hyper::Request<Body>) -> Self::Future {
89//! # unimplemented!()
90//! # }
91//! # }
92//! # impl tonic::server::NamedService for Svc {
93//! # const NAME: &'static str = "some_svc";
94//! # }
95//! # let my_svc = Svc;
96//! let cert = std::fs::read_to_string("server.pem")?;
97//! let key = std::fs::read_to_string("server.key")?;
98//!
99//! let addr = "[::1]:50051".parse()?;
100//!
101//! Server::builder()
102//! .tls_config(ServerTlsConfig::new()
103//! .identity(Identity::from_pem(&cert, &key)))?
104//! .concurrency_limit_per_connection(256)
105//! .add_service(my_svc)
106//! .serve(addr)
107//! .await?;
108//!
109//! # Ok(())
110//! # }
111//! ```
112//!
113//! [rustls]: https://docs.rs/rustls/0.16.0/rustls/
114
115#[cfg(feature = "channel")]
116pub mod channel;
117#[cfg(feature = "server")]
118pub mod server;
119
120mod error;
121mod service;
122#[cfg(feature = "_tls-any")]
123mod tls;
124
125#[doc(inline)]
126#[cfg(feature = "channel")]
127pub use self::channel::{Channel, Endpoint};
128pub use self::error::Error;
129#[doc(inline)]
130#[cfg(feature = "server")]
131pub use self::server::Server;
132
133#[cfg(feature = "_tls-any")]
134pub use self::tls::Certificate;
135pub use hyper::{Uri, body::Body};
136#[cfg(feature = "_tls-any")]
137pub use tokio_rustls::rustls::pki_types::CertificateDer;
138
139#[cfg(all(feature = "channel", feature = "_tls-any"))]
140pub use self::channel::ClientTlsConfig;
141#[cfg(all(feature = "server", feature = "_tls-any"))]
142pub use self::server::ServerTlsConfig;
143#[cfg(feature = "_tls-any")]
144pub use self::tls::Identity;