Expand description
A Rust implementation of gRPC, a high performance, open source, general RPC framework that puts mobile and HTTP/2 first.
tonic
is a gRPC over HTTP/2 implementation focused on high
performance, interoperability, and flexibility. This library was
created to have first class support of async/await and to act as a core building
block for production systems written in Rust.
§Examples
Examples can be found in the tonic-examples
crate.
§Getting Started
Follow the instructions in the tonic-build
crate documentation.
§Feature Flags
transport
: Enables the fully featured, batteries included client and server implementation based onhyper
,tower
andtokio
. Enabled by default.channel
: Enables just the full featured channel/client portion of thetransport
feature.codegen
: Enables all the required exports and optional dependencies required fortonic-build
. Enabled by default.tls
: Enables therustls
based TLS options for thetransport
feature. Not enabled by default.tls-roots
: Adds system trust roots torustls
-based gRPC clients using therustls-native-certs
crate. Not enabled by default.tls
must be enabled to usetls-roots
.tls-webpki-roots
: Add the standard trust roots from thewebpki-roots
crate torustls
-based gRPC clients. Not enabled by default.prost
: Enables theprost
based gRPCCodec
implementation.gzip
: Enables compressing requests, responses, and streams. Depends on flate2. Not enabled by default. Replaces thecompression
flag from earlier versions oftonic
(<= 0.7).
§Structure
§Generic implementation
The main goal of tonic
is to provide a generic gRPC implementation over HTTP/2
framing. This means at the lowest level this library provides the ability to use
a generic HTTP/2 implementation with different types of gRPC encodings formats. Generally,
some form of codegen should be used instead of interacting directly with the items in
client
and server
.
§Transport
The transport
module contains a fully featured HTTP/2.0 Channel
(gRPC terminology)
and Server
. These implementations are built on top of tokio
, hyper
and tower
.
It also provides many of the features that the core gRPC libraries provide such as load balancing,
tls, timeouts, and many more. This implementation can also be used as a reference implementation
to build even more feature rich clients and servers. This module also provides the ability to
enable TLS using rustls
, via the tls
feature flag.
§Code generated client/server configuration
§Max Message Size
Currently, both servers and clients can be configured to set the max message encoding and
decoding size. This will ensure that an incoming gRPC message will not exhaust the systems
memory. By default, the decoding message limit is 4MB
and the encoding limit is usize::MAX
.
Modules§
- HTTP specific body utilities.
- Generic client implementation.
- Generic encoding and decoding.
- Contains data structures and utilities for handling gRPC custom metadata.
- Generic server implementation.
- Utilities for using Tower services with Tonic.
- Batteries included server and client.
Macros§
- Include an encoded
prost_types::FileDescriptorSet
as a&'static [u8]
. The parameter must be the stem of the filename passed tofile_descriptor_set_path
for thetonic-build::Builder
, excluding the.bin
extension. - Include generated proto server and client items.
Structs§
- A type map of protocol extensions.
- A gRPC Method info extension.
- A gRPC request and metadata from an RPC call.
- A gRPC response and metadata from an RPC call.
- A gRPC status describing the result of an RPC call.
- Streaming requests and responses.
Enums§
- gRPC status codes used by
Status
.
Traits§
- Trait implemented by RPC request types.
- Trait implemented by RPC streaming request types.
Type Aliases§
Attribute Macros§
- A re-export of
async-trait
for use with codegen.