tonic/
lib.rs

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//! - `codegen`: Enables all the required exports and optional dependencies required
22//! for [`tonic-build`]. Enabled by default.
23//! - `tls`: Enables the `rustls` based TLS options for the `transport` feature. Not
24//! enabled by default.
25//! - `tls-roots`: Adds system trust roots to `rustls`-based gRPC clients using the
26//! `rustls-native-certs` crate. Not enabled by default. `tls` must be enabled to use
27//! `tls-roots`.
28//! - `tls-webpki-roots`: Add the standard trust roots from the `webpki-roots` crate to
29//! `rustls`-based gRPC clients. Not enabled by default.
30//! - `prost`: Enables the [`prost`] based gRPC [`Codec`] implementation.
31//! - `compression`: Enables compressing requests, responses, and streams. Note
32//! that you must enable the `compression` feature on both `tonic` and
33//! `tonic-build` to use it. Depends on [flate2]. Not enabled by default.
34//!
35//! # Structure
36//!
37//! ## Generic implementation
38//!
39//! The main goal of [`tonic`] is to provide a generic gRPC implementation over HTTP/2
40//! framing. This means at the lowest level this library provides the ability to use
41//! a generic HTTP/2 implementation with different types of gRPC encodings formats. Generally,
42//! some form of codegen should be used instead of interacting directly with the items in
43//! [`client`] and [`server`].
44//!
45//! ## Transport
46//!
47//! The [`transport`] module contains a fully featured HTTP/2.0 [`Channel`] (gRPC terminology)
48//! and [`Server`]. These implementations are built on top of [`tokio`], [`hyper`] and [`tower`].
49//! It also provides many of the features that the core gRPC libraries provide such as load balancing,
50//! tls, timeouts, and many more. This implementation can also be used as a reference implementation
51//! to build even more feature rich clients and servers. This module also provides the ability to
52//! enable TLS using [`rustls`], via the `tls` feature flag.
53//!
54//! [gRPC]: https://grpc.io
55//! [`tonic`]: https://github.com/hyperium/tonic
56//! [`tokio`]: https://docs.rs/tokio
57//! [`prost`]: https://docs.rs/prost
58//! [`hyper`]: https://docs.rs/hyper
59//! [`tower`]: https://docs.rs/tower
60//! [`tonic-build`]: https://docs.rs/tonic-build
61//! [`tonic-examples`]: https://github.com/hyperium/tonic/tree/master/examples
62//! [`Codec`]: codec/trait.Codec.html
63//! [`Channel`]: transport/struct.Channel.html
64//! [`Server`]: transport/struct.Server.html
65//! [`rustls`]: https://docs.rs/rustls
66//! [`client`]: client/index.html
67//! [`transport`]: transport/index.html
68//! [flate2]: https://crates.io/crates/flate2
69
70#![recursion_limit = "256"]
71#![allow(clippy::inconsistent_struct_constructor)]
72#![warn(
73    missing_debug_implementations,
74    missing_docs,
75    rust_2018_idioms,
76    unreachable_pub
77)]
78#![deny(broken_intra_doc_links)]
79#![doc(
80    html_logo_url = "https://raw.githubusercontent.com/tokio-rs/website/master/public/img/icons/tonic.svg"
81)]
82#![doc(html_root_url = "https://docs.rs/tonic/0.6.2")]
83#![doc(issue_tracker_base_url = "https://github.com/hyperium/tonic/issues/")]
84#![doc(test(no_crate_inject, attr(deny(rust_2018_idioms))))]
85#![cfg_attr(docsrs, feature(doc_cfg))]
86
87pub mod body;
88pub mod client;
89pub mod codec;
90pub mod metadata;
91pub mod server;
92pub mod service;
93
94#[cfg(feature = "transport")]
95#[cfg_attr(docsrs, doc(cfg(feature = "transport")))]
96pub mod transport;
97
98mod extensions;
99mod macros;
100mod request;
101mod response;
102mod status;
103mod util;
104
105/// A re-export of [`async-trait`](https://docs.rs/async-trait) for use with codegen.
106#[cfg(feature = "codegen")]
107#[cfg_attr(docsrs, doc(cfg(feature = "codegen")))]
108pub use async_trait::async_trait;
109
110#[doc(inline)]
111pub use codec::Streaming;
112pub use extensions::Extensions;
113pub use request::{IntoRequest, IntoStreamingRequest, Request};
114pub use response::Response;
115pub use status::{Code, Status};
116
117pub(crate) type Error = Box<dyn std::error::Error + Send + Sync>;
118
119#[doc(hidden)]
120#[cfg(feature = "codegen")]
121#[cfg_attr(docsrs, doc(cfg(feature = "codegen")))]
122pub mod codegen;
tonic/lib.rs

tonic/
lib.rs
