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 or
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(BoxBody::empty())).await?;
42 //! # Ok(())
43 //! # }
44 //! ```
45 //!
46 //! ## Server
47 //!
48 //! ```no_run
49 //! # #[cfg(feature = "rustls")]
50 //! # use tonic::transport::{Server, Identity, ServerTlsConfig};
51 //! # use tower::Service;
52 //! # #[cfg(feature = "rustls")]
53 //! # async fn do_thing() -> Result<(), Box<dyn std::error::Error>> {
54 //! # #[derive(Clone)]
55 //! # pub struct Svc;
56 //! # impl Service<hyper::Request<hyper::Body>> for Svc {
57 //! #   type Response = hyper::Response<tonic::body::BoxBody>;
58 //! #   type Error = tonic::Status;
59 //! #   type Future = std::future::Ready<Result<Self::Response, Self::Error>>;
60 //! #   fn poll_ready(&mut self, _cx: &mut std::task::Context<'_>) -> std::task::Poll<Result<(), Self::Error>> {
61 //! #       Ok(()).into()
62 //! #  }
63 //! #   fn call(&mut self, _req: hyper::Request<hyper::Body>) -> Self::Future {
64 //! #       unimplemented!()
65 //! #   }
66 //! # }
67 //! # impl tonic::server::NamedService for Svc {
68 //! # const NAME: &'static str = "some_svc";
69 //! # }
70 //! # let my_svc = Svc;
71 //! let cert = std::fs::read_to_string("server.pem")?;
72 //! let key = std::fs::read_to_string("server.key")?;
73 //!
74 //! let addr = "[::1]:50051".parse()?;
75 //!
76 //! Server::builder()
77 //!     .tls_config(ServerTlsConfig::new()
78 //!         .identity(Identity::from_pem(&cert, &key)))?
79 //!     .concurrency_limit_per_connection(256)
80 //!     .add_service(my_svc)
81 //!     .serve(addr)
82 //!     .await?;
83 //!
84 //! # Ok(())
85 //! # }
86 //! ```
87 //!
88 //! [rustls]: https://docs.rs/rustls/0.16.0/rustls/
89 
90 pub mod channel;
91 pub mod server;
92 
93 mod error;
94 mod service;
95 #[cfg(feature = "tls")]
96 mod tls;
97 
98 #[doc(inline)]
99 #[cfg(feature = "channel")]
100 #[cfg_attr(docsrs, doc(cfg(feature = "channel")))]
101 pub use self::channel::{Channel, Endpoint};
102 pub use self::error::Error;
103 #[doc(inline)]
104 pub use self::server::Server;
105 #[doc(inline)]
106 pub use self::service::grpc_timeout::TimeoutExpired;
107 #[cfg(feature = "tls")]
108 #[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
109 pub use self::tls::Certificate;
110 pub use axum::{body::BoxBody as AxumBoxBody, Router as AxumRouter};
111 pub use hyper::{Body, Uri};
112 
113 pub(crate) use self::service::executor::Executor;
114 
115 #[cfg(feature = "tls")]
116 #[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
117 pub use self::channel::ClientTlsConfig;
118 #[cfg(feature = "tls")]
119 #[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
120 pub use self::server::ServerTlsConfig;
121 #[cfg(feature = "tls")]
122 #[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
123 pub use self::tls::Identity;
124 
125 type BoxFuture<'a, T> = std::pin::Pin<Box<dyn std::future::Future<Output = T> + Send + 'a>>;
126