1 //! A Rust implementation of [gRPC], a high performance, open source, general 2 //! RPC framework that puts mobile and HTTP/2 first. 3 //! 4 //! [`tonic`] is a gRPC over HTTP/2 implementation focused on **high 5 //! performance**, **interoperability**, and **flexibility**. This library was 6 //! created to have first class support of async/await and to act as a core building 7 //! block for production systems written in Rust. 8 //! 9 //! # Examples 10 //! 11 //! Examples can be found in the [`tonic-examples`] crate. 12 //! 13 //! # Getting Started 14 //! 15 //! Follow the instructions in the [`tonic-build`] crate documentation. 16 //! 17 //! # Feature Flags 18 //! 19 //! - `transport`: Enables the fully featured, batteries included client and server 20 //! implementation based on [`hyper`], [`tower`] and [`tokio`]. Enabled by default. 21 //! - `channel`: Enables just the full featured channel/client portion of the `transport` 22 //! feature. 23 //! - `codegen`: Enables all the required exports and optional dependencies required 24 //! for [`tonic-build`]. Enabled by default. 25 //! - `tls`: Enables the `rustls` based TLS options for the `transport` feature. Not 26 //! enabled by default. 27 //! - `tls-roots`: Adds system trust roots to `rustls`-based gRPC clients using the 28 //! `rustls-native-certs` crate. Not enabled by default. `tls` must be enabled to use 29 //! `tls-roots`. 30 //! - `tls-webpki-roots`: Add the standard trust roots from the `webpki-roots` crate to 31 //! `rustls`-based gRPC clients. Not enabled by default. 32 //! - `prost`: Enables the [`prost`] based gRPC [`Codec`] implementation. 33 //! - `gzip`: Enables compressing requests, responses, and streams. 34 //! Depends on [flate2]. Not enabled by default. 35 //! Replaces the `compression` flag from earlier versions of `tonic` (<= 0.7). 36 //! 37 //! # Structure 38 //! 39 //! ## Generic implementation 40 //! 41 //! The main goal of [`tonic`] is to provide a generic gRPC implementation over HTTP/2 42 //! framing. This means at the lowest level this library provides the ability to use 43 //! a generic HTTP/2 implementation with different types of gRPC encodings formats. Generally, 44 //! some form of codegen should be used instead of interacting directly with the items in 45 //! [`client`] and [`server`]. 46 //! 47 //! ## Transport 48 //! 49 //! The [`transport`] module contains a fully featured HTTP/2.0 [`Channel`] (gRPC terminology) 50 //! and [`Server`]. These implementations are built on top of [`tokio`], [`hyper`] and [`tower`]. 51 //! It also provides many of the features that the core gRPC libraries provide such as load balancing, 52 //! tls, timeouts, and many more. This implementation can also be used as a reference implementation 53 //! to build even more feature rich clients and servers. This module also provides the ability to 54 //! enable TLS using [`rustls`], via the `tls` feature flag. 55 //! 56 //! # Code generated client/server configuration 57 //! 58 //! ## Max Message Size 59 //! 60 //! Currently, both servers and clients can be configured to set the max message encoding and 61 //! decoding size. This will ensure that an incoming gRPC message will not exhaust the systems 62 //! memory. By default, the decoding message limit is `4MB` and the encoding limit is `usize::MAX`. 63 //! 64 //! [gRPC]: https://grpc.io 65 //! [`tonic`]: https://github.com/hyperium/tonic 66 //! [`tokio`]: https://docs.rs/tokio 67 //! [`prost`]: https://docs.rs/prost 68 //! [`hyper`]: https://docs.rs/hyper 69 //! [`tower`]: https://docs.rs/tower 70 //! [`tonic-build`]: https://docs.rs/tonic-build 71 //! [`tonic-examples`]: https://github.com/hyperium/tonic/tree/master/examples 72 //! [`Codec`]: codec/trait.Codec.html 73 //! [`Channel`]: transport/struct.Channel.html 74 //! [`Server`]: transport/struct.Server.html 75 //! [`rustls`]: https://docs.rs/rustls 76 //! [`client`]: client/index.html 77 //! [`transport`]: transport/index.html 78 //! [flate2]: https://crates.io/crates/flate2 79 80 #![recursion_limit = "256"] 81 #![allow(clippy::inconsistent_struct_constructor)] 82 #![warn( 83 missing_debug_implementations, 84 missing_docs, 85 rust_2018_idioms, 86 unreachable_pub 87 )] 88 #![deny(rustdoc::broken_intra_doc_links)] 89 #![doc( 90 html_logo_url = "https://raw.githubusercontent.com/tokio-rs/website/master/public/img/icons/tonic.svg" 91 )] 92 #![doc(html_root_url = "https://docs.rs/tonic/0.11.0")] 93 #![doc(issue_tracker_base_url = "https://github.com/hyperium/tonic/issues/")] 94 #![doc(test(no_crate_inject, attr(deny(rust_2018_idioms))))] 95 #![cfg_attr(docsrs, feature(doc_cfg))] 96 97 pub mod body; 98 pub mod client; 99 pub mod codec; 100 pub mod metadata; 101 pub mod server; 102 pub mod service; 103 104 #[cfg(feature = "transport")] 105 #[cfg_attr(docsrs, doc(cfg(feature = "transport")))] 106 pub mod transport; 107 108 mod extensions; 109 mod macros; 110 mod request; 111 mod response; 112 mod status; 113 mod util; 114 115 /// A re-export of [`async-trait`](https://docs.rs/async-trait) for use with codegen. 116 #[cfg(feature = "codegen")] 117 #[cfg_attr(docsrs, doc(cfg(feature = "codegen")))] 118 pub use async_trait::async_trait; 119 120 #[doc(inline)] 121 pub use codec::Streaming; 122 pub use extensions::{Extensions, GrpcMethod}; 123 pub use request::{IntoRequest, IntoStreamingRequest, Request}; 124 pub use response::Response; 125 pub use status::{Code, Status}; 126 127 pub(crate) type Error = Box<dyn std::error::Error + Send + Sync>; 128 129 #[doc(hidden)] 130 #[cfg(feature = "codegen")] 131 #[cfg_attr(docsrs, doc(cfg(feature = "codegen")))] 132 pub mod codegen; 133 134 /// `Result` is a type that represents either success ([`Ok`]) or failure ([`Err`]). 135 /// By default, the Err value is of type [`Status`] but this can be overridden if desired. 136 pub type Result<T, E = Status> = std::result::Result<T, E>; 137
