Repository files navigation

gRPC-rs is a Rust wrapper ofgRPC Core.gRPC is a high performance, open source universal RPC framework that puts mobile and HTTP/2 first.

This project is still under development. The following features with the check marks are supported:

• Basic asynchronous unary/steaming call
• SSL
• Generic call
• Connection level compression
• Interoperability test
• QPS benchmark
• Custom metadata
• Health check
• Reflection
• Authentication
• Load balance, client side is fully supported, server side load report is not implemented yet.

• CMake >= 3.8.0
• Rust >= 1.36.0
• binutils >= 2.22
• LLVM and Clang >= 3.9 if you need to generate bindings at compile time.

For Linux and MacOS, you also need to install gcc 7.3+ (or clang 6+) too.

Bindings are pre-generated for x86_64/arm64 Linux. For other platforms, bindings are generated at compile time.

For Windows, you also need to install following software:

• Active State Perl
• yasm
• Visual Studio 2015+

$ cargo xtask submodule # if you just cloned the repository$ cargo build

If you're getting linker errors when building your project usinggRPC-rs, headdown to theopenssl feature section for a possible fix.

To generate the sources from proto files:

1. Install the protobuf compiler:

$ cargo install protobuf-codegen

2. Install the gRPC compiler:

$ cargo install grpcio-compiler

3. Generate the sources:

$ protoc --rust_out=. --grpc_out=. --plugin=protoc-gen-grpc=`which grpc_rust_plugin` example.proto

Programmatic generation can be used to generate Rust modules from proto filesvia yourbuild.rs by usingprotoc-grpcio.

For more information and examples seeREADME.

To include this project as a dependency:

[dependencies]grpcio = "0.13"

boringssl feature enables support for TLS encryption and some authenticationmechanism. When you do not need it, for example when working in intranet,you can disable it by using the following configuration:

[dependencies]grpcio = { version = "0.13", default-features = false, features = ["protobuf-codec"] }

gRPC-rs usesprotobuf crate by default. If you want to useprost instead, you can enableprost-codec feature. You probably only want to enable only one of the two features. Thoughgrpcio is completely fine with both features enabled at the same time, grpcio-compilerwill not going to work as expected.

gRPC-rs comes vendored withgRPC Core, which by default uses BoringSSLinstead of OpenSSL. This may cause linking issues due to symbol clashes and/ormissing symbols when another one of your dependencies uses OpenSSL. To resolvethis, you can tellgRPC-rs to use OpenSSL too by specifying"openssl" inyourCargo.toml's features list forgprcio, which requires openssl (>=1.0.2). E.g.:

[dependencies]grpcio = {version ="0.13",features = ["openssl"] }

Featureopenssl-vendored is the same as featureopenssl except it will build openssl frombundled sources.

Seebenchmark to find out how to run a benchmark by yourself.

Seecross_compile

Make sure to format and test the code before sending a PR.

If the content in grpc-sys/grpc is updated, you may need to regenerate bindings:

$ cargo xtask bindgen