tonic/transport/mod.rs
1//! Batteries included server and client.
2//!
3//! This module provides a set of batteries included, fully featured and
4//! fast set of HTTP/2 server and client's. These components each provide a
5//! `rustls` tls backend when the respective feature flag is enabled, and
6//! provides builders to configure transport behavior.
7//!
8//! # Features
9//!
10//! - TLS support via [rustls].
11//! - Load balancing
12//! - Timeouts
13//! - Concurrency Limits
14//! - Rate limiting
15//!
16//! # Examples
17//!
18//! ## Client
19//!
20//! ```no_run
21//! # #[cfg(feature = "rustls")]
22//! # use tonic::transport::{Channel, Certificate, ClientTlsConfig};
23//! # use std::time::Duration;
24//! # use tonic::body::BoxBody;
25//! # use tonic::client::GrpcService;;
26//! # use http::Request;
27//! # #[cfg(feature = "rustls")]
28//! # async fn do_thing() -> Result<(), Box<dyn std::error::Error>> {
29//! let cert = std::fs::read_to_string("ca.pem")?;
30//!
31//! let mut channel = Channel::from_static("https://example.com")
32//! .tls_config(ClientTlsConfig::new()
33//! .ca_certificate(Certificate::from_pem(&cert))
34//! .domain_name("example.com".to_string()))?
35//! .timeout(Duration::from_secs(5))
36//! .rate_limit(5, Duration::from_secs(1))
37//! .concurrency_limit(256)
38//! .connect()
39//! .await?;
40//!
41//! channel.call(Request::new(tonic::body::empty_body())).await?;
42//! # Ok(())
43//! # }
44//! ```
45//!
46//! ## Server
47//!
48//! ```no_run
49//! # use std::convert::Infallible;
50//! # #[cfg(feature = "rustls")]
51//! # use tonic::transport::{Server, Identity, ServerTlsConfig};
52//! # use tonic::body::BoxBody;
53//! # use tower::Service;
54//! # #[cfg(feature = "rustls")]
55//! # async fn do_thing() -> Result<(), Box<dyn std::error::Error>> {
56//! # #[derive(Clone)]
57//! # pub struct Svc;
58//! # impl Service<hyper::Request<BoxBody>> for Svc {
59//! # type Response = hyper::Response<BoxBody>;
60//! # type Error = Infallible;
61//! # type Future = std::future::Ready<Result<Self::Response, Self::Error>>;
62//! # fn poll_ready(&mut self, _cx: &mut std::task::Context<'_>) -> std::task::Poll<Result<(), Self::Error>> {
63//! # Ok(()).into()
64//! # }
65//! # fn call(&mut self, _req: hyper::Request<BoxBody>) -> Self::Future {
66//! # unimplemented!()
67//! # }
68//! # }
69//! # impl tonic::server::NamedService for Svc {
70//! # const NAME: &'static str = "some_svc";
71//! # }
72//! # let my_svc = Svc;
73//! let cert = std::fs::read_to_string("server.pem")?;
74//! let key = std::fs::read_to_string("server.key")?;
75//!
76//! let addr = "[::1]:50051".parse()?;
77//!
78//! Server::builder()
79//! .tls_config(ServerTlsConfig::new()
80//! .identity(Identity::from_pem(&cert, &key)))?
81//! .concurrency_limit_per_connection(256)
82//! .add_service(my_svc)
83//! .serve(addr)
84//! .await?;
85//!
86//! # Ok(())
87//! # }
88//! ```
89//!
90//! [rustls]: https://docs.rs/rustls/0.16.0/rustls/
91
92#[cfg(feature = "channel")]
93pub mod channel;
94#[cfg(feature = "server")]
95pub mod server;
96
97mod error;
98mod service;
99#[cfg(feature = "tls")]
100mod tls;
101
102#[doc(inline)]
103#[cfg(feature = "channel")]
104pub use self::channel::{Channel, Endpoint};
105pub use self::error::Error;
106#[doc(inline)]
107#[cfg(feature = "server")]
108pub use self::server::Server;
109/// Deprecated. Please use [`crate::status::TimeoutExpired`] instead.
110pub use crate::status::TimeoutExpired;
111
112#[cfg(feature = "tls")]
113pub use self::tls::Certificate;
114pub use hyper::{body::Body, Uri};
115#[cfg(feature = "tls")]
116pub use tokio_rustls::rustls::pki_types::CertificateDer;
117
118#[cfg(all(feature = "channel", feature = "tls"))]
119pub use self::channel::ClientTlsConfig;
120#[cfg(all(feature = "server", feature = "tls"))]
121pub use self::server::ServerTlsConfig;
122#[cfg(feature = "tls")]
123pub use self::tls::Identity;