1 2 3A rust implementation of [gRPC], a high performance, open source, general 4RPC framework that puts mobile and HTTP/2 first. 5 6[`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. 7 8[](https://crates.io/crates/tonic) 9[](https://docs.rs/tonic) 10[](LICENSE) 11 12 13[Examples] | [Website] | [Docs] | [Chat] 14 15## Overview 16 17[`tonic`] is composed of three main components: the generic gRPC implementation, the high performance HTTP/2 18implementation and the codegen powered by [`prost`]. The generic implementation can support any HTTP/2 19implementation and any encoding via a set of generic traits. The HTTP/2 implementation is based on [`hyper`], 20a fast HTTP/1.1 and HTTP/2 client and server built on top of the robust [`tokio`] stack. The codegen 21contains the tools to build clients and servers from [`protobuf`] definitions. 22 23## Features 24 25- Bi-directional streaming 26- High performance async io 27- Interoperability 28- TLS backed by [`rustls`] 29- Load balancing 30- Custom metadata 31- Authentication 32- Health Checking 33 34## Getting Started 35 36Examples can be found in [`examples`] and for more complex scenarios [`interop`] 37may be a good resource as it shows examples of many of the gRPC features. 38 39If you're using [rust-analyzer] we recommend you set `"rust-analyzer.cargo.loadOutDirsFromCheck": true` to correctly load 40the generated code. 41 42### Rust Version 43 44`tonic` currently works on rust `1.39` and above as it requires support for the `async_await` 45feature. 46 47```bash 48$ rustup update 49$ rustup component add rustfmt 50$ cargo build 51``` 52 53### Tutorials 54 55- The [`helloworld`][helloworld-tutorial] tutorial provides a basic example of using `tonic`, perfect for first time users! 56- The [`routeguide`][routeguide-tutorial] tutorial provides a complete example of using `tonic` and all its 57features. 58 59## Getting Help 60 61First, see if the answer to your question can be found in the API documentation. 62If the answer is not there, there is an active community in 63the [Tonic Discord channel][chat]. We would be happy to try to answer your 64question. If that doesn't work, try opening an [issue] with the question. 65 66[chat]: https://discord.gg/6yGkFeN 67[issue]: https://github.com/hyperium/tonic/issues/new 68 69## Project Layout 70 71- [`tonic`](https://github.com/hyperium/tonic/tree/master/tonic): Generic gRPC and HTTP/2 client/server 72implementation. 73- [`tonic-build`](https://github.com/hyperium/tonic/tree/master/tonic-build): [`prost`] based service codegen. 74- [`tonic-types`](https://github.com/hyperium/tonic/tree/master/tonic-types): [`prost`] based grpc utility types 75 including support for gRPC Well Known Types. 76- [`tonic-health`](https://github.com/hyperium/tonic/tree/master/tonic-health): Implementation of the standard [gRPC 77health checking service][healthcheck]. Also serves as an example of both unary and response streaming. 78- [`tonic-reflection`](https://github.com/hyperium/tonic/tree/master/tonic-reflection): A tonic based gRPC 79reflection implementation. 80- [`examples`](https://github.com/hyperium/tonic/tree/master/examples): Example gRPC implementations showing off 81tls, load balancing and bi-directional streaming. 82- [`interop`](https://github.com/hyperium/tonic/tree/master/interop): Interop tests implementation. 83 84## Contributing 85 86:balloon: Thanks for your help improving the project! We are so happy to have 87you! We have a [contributing guide][guide] to help you get involved in the Tonic 88project. 89 90[guide]: CONTRIBUTING.md 91 92## License 93 94This project is licensed under the [MIT license](LICENSE). 95 96### Contribution 97 98Unless you explicitly state otherwise, any contribution intentionally submitted 99for inclusion in Tonic by you, shall be licensed as MIT, without any additional 100terms or conditions. 101 102 103[gRPC]: https://grpc.io 104[`tonic`]: https://github.com/hyperium/tonic 105[`tokio`]: https://github.com/tokio-rs/tokio 106[`hyper`]: https://github.com/hyperium/hyper 107[`prost`]: https://github.com/danburkert/prost 108[`protobuf`]: https://developers.google.com/protocol-buffers 109[`rustls`]: https://github.com/ctz/rustls 110[`examples`]: https://github.com/hyperium/tonic/tree/master/examples 111[`interop`]: https://github.com/hyperium/tonic/tree/master/interop 112[Examples]: https://github.com/hyperium/tonic/tree/master/examples 113[Website]: https://github.com/hyperium/tonic 114[Docs]: https://docs.rs/tonic 115[Chat]: https://discord.gg/6yGkFeN 116[routeguide-tutorial]: https://github.com/hyperium/tonic/blob/master/examples/routeguide-tutorial.md 117[helloworld-tutorial]: https://github.com/hyperium/tonic/blob/master/examples/helloworld-tutorial.md 118[healthcheck]: https://github.com/grpc/grpc/blob/master/doc/health-checking.md 119[rust-analyzer]: https://rust-analyzer.github.io 120
){kind=link}
){kind=link}