1<p align="center" style="height:80%;"> 2 <img src="https://github.com/LucioFranco/tonic/raw/master/.github/assets/tonic_ghbanner.png" alt="Vector"> 3</p> 4 5A rust implementation of [gRPC], a high performance, open source, general 6RPC framework that puts mobile and HTTP/2 first. 7 8[`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. 9 10[Examples] | [Website] | [Docs] | [Chat] 11 12## Overview 13 14[`tonic`] is composed of three main components the generic gRPC implementation, the high performance HTTP/2 15implementation and the codegen powered by [`prost`]. The generic implementation can support any HTTP/2 16implementation and any encoding via a set of generic traits. The HTTP/2 implementation is based on [`hyper`] 17which is a fast HTTP/1.1 and HTTP/2 client and server built on top of the robust [`tokio`] stack. The codegen 18contains the tools to build clients and servers from [`protobuf`] definitions. 19 20### Features 21 22- Bi-directional streaming 23- High performance async io 24- Interoperability 25- TLS backed via either [`openssl`] or [`rustls`] 26- Load balancing 27- Custom metadata 28- Authentication 29 30## Getting Started 31 32Examples can be found in [`tonic-examples`] and for more complex scenarios [`tonic-interop`] 33may be a good resource as it shows examples of many of the gRPC features. 34 35### Examples 36 37#### Client 38 39```rust 40pub mod hello_world { 41 include!(concat!(env!("OUT_DIR"), "/helloworld.rs")); 42} 43 44use hello_world::{client::GreeterClient, HelloRequest}; 45 46#[tokio::main] 47async fn main() -> Result<(), Box<dyn std::error::Error>> { 48 let mut client = GreeterClient::connect("http://[::1]:50051")?; 49 50 let request = tonic::Request::new(HelloRequest { 51 name: "hello".into(), 52 }); 53 54 let response = client.say_hello(request).await?; 55 56 println!("RESPONSE={:?}", response); 57 58 Ok(()) 59} 60``` 61 62#### Server 63 64```rust 65use tonic::{transport::Server, Request, Response, Status}; 66 67pub mod hello_world { 68 include!(concat!(env!("OUT_DIR"), "/helloworld.rs")); 69} 70 71use hello_world::{ 72 server::{Greeter, GreeterServer}, 73 HelloReply, HelloRequest, 74}; 75 76#[derive(Default)] 77pub struct MyGreeter { 78 data: String, 79} 80 81#[tonic::async_trait] 82impl Greeter for MyGreeter { 83 async fn say_hello( 84 &self, 85 request: Request<HelloRequest>, 86 ) -> Result<Response<HelloReply>, Status> { 87 println!("Got a request: {:?}", request); 88 89 let string = &self.data; 90 91 println!("My data: {:?}", string); 92 93 let reply = hello_world::HelloReply { 94 message: "Zomg, it works!".into(), 95 }; 96 Ok(Response::new(reply)) 97 } 98} 99 100#[tokio::main] 101async fn main() -> Result<(), Box<dyn std::error::Error>> { 102 let addr = "[::1]:50051".parse().unwrap(); 103 let greeter = MyGreeter::default(); 104 105 Server::builder() 106 .serve(addr, GreeterServer::new(greeter)) 107 .await?; 108 109 Ok(()) 110} 111``` 112 113## Getting Help 114 115First, see if the answer to your question can be found in the API documentation. 116If the answer is not there, there is an active community in 117the [Tonic Discord channel][chat]. We would be happy to try to answer your 118question. Last, if that doesn't work, try opening an [issue] with the question. 119 120[chat]: https://discord.gg/6yGkFeN 121[issue]: https://github.com/hyperium/tonic/issues/new 122 123## Project Layout 124 125- [`tonic`](https://github.com/hyperium/tonic/tree/master/tonic): Generic gRPC and HTTP/2 client/server 126implementation. 127- [`tonic-build`](https://github.com/hyperium/tonic/tree/master/tonic): [`prost`] based service codegen. 128 129## Contributing 130 131:balloon: Thanks for your help improving the project! We are so happy to have 132you! We have a [contributing guide][guide] to help you get involved in the Tracing 133project. 134 135[guide]: CONTRIBUTING.md 136 137## License 138 139This project is licensed under the [MIT license](LICENSE). 140 141### Contribution 142 143Unless you explicitly state otherwise, any contribution intentionally submitted 144for inclusion in Tracing by you, shall be licensed as MIT, without any additional 145terms or conditions. 146 147 148[gRPC]: https://grpc.io 149[`tonic`]: https://github.com/hyperium/tonic 150[`tokio`]: https://github.com/tokio-rs/tokio 151[`hyper`]: https://github.com/hyperium/hyper 152[`prost`]: https://github.com/danburkert/prost 153[`protobuf`]: https://developers.google.com/protocol-buffers 154[`rustls`]: https://github.com/ctz/rustls 155[`openssl`]: https://www.openssl.org/ 156[Examples]: https://github.com/hyperium/tonic/tree/master/tonic-examples 157[Website]: https://tokio.rs 158[Docs]: https://docs.rs/tonic 159[Chat]: https://discord.gg/6yGkFeN 160
