protoc-gen-tonic

A protoc plugin that generates Tonic gRPC server and client code using the Prost! code generation engine.

When used in projects that use only Rust code, the preferred mechanism for generating gRPC services with Tonic is to use tonic-build from within a build.rs file. However, when working in polyglot environments, it can be advantageous to utilize common tooling in the Protocol Buffers ecosystem. One common tool used for this purpose is buf, which simplifies the code generation process and includes several useful features, including linting, package management, and breaking change detection.

Usage

Ensure that protoc-gen-tonic has been installed within a directory on your $PATH. Then invoke protoc from the command line as follows:

protoc --tonic_out=proto/gen -I proto proto/greeter/v1/greeter.proto

Options

This tool supports all the same options from tonic-build except for those that are expected to have been completely handled in an earlier protoc-gen-prost step. For information on the effects of these settings, see the related documentation from tonic-build:

• default_package_filename=<value>: default_package_filename
• extern_path=<proto_path>=<rust_path>: extern_path
• compile_well_known_types(=<boolean>): compile_well_known_types
• disable_package_emission(=<boolean>): disable_package_emission
• server_attribute=<proto_path>=<attribute>: server_attribute
• server_mod_attribute=<proto_path>=<attribute>: server_mod_attribute
• client_attribute=<proto_path>=<attribute>: client_attribute
• client_mod_attribute=<proto_path>=<attribute>: client_mod_attribute

In addition, the following options can also be specified:

• no_server(=<boolean>): Disables generation of the server modules
• no_client(=<boolean>): Disables generation of the client modules
• no_transport(=<boolean>): Disables generation of connect method using tonic::transport::Channel
• no_include(=<boolean>): Skips adding an include into the file generated by protoc-gen-prost. This behavior may be desired if this plugin is run in a separate protoc invocation and you encounter a Tried to insert into file that doesn't exist error.

A note on parameter values:

• <attribute>: All ,s appearing in the value must be \ escaped (i.e. \,) This is due to the fact that internally, protoc joins all passed parameters with a , before sending it as a single string to the underlying plugin.
• <proto_path>: Protobuf paths beginning with . will be matched from the global root (prefix matches). All other paths will be matched as suffix matches.
• (=<boolean>): Boolean values may be specified after a parameter, but if not, the value is assumed to be true by virtue of having listed the parameter.

Usage with protoc and protoc-gen-prost

To make it easier to work with the base definitions generated by prost, this plugin assumes that it is being run in a chained mode in the same protoc invocation as protoc-gen-prost. This can be done by specifying multiple plugins in the same protoc invocation like so:

protoc -I proto proto/greeter/v1/greeter.proto \
    --prost_out=proto/gen \
    --tonic_out=proto/gen

When running as separate invocations, protoc won't be aware of the base definitions that were generated by protoc-gen-prost. In this case, using the no_include directive is necessary, and you will need to separately include the generated .tonic.rs file.

protoc -I proto proto/greeter/v1/greeter.proto \
    --prost_out=proto/gen

protoc -I proto proto/greeter/v1/greeter.proto \
    --tonic_out=proto/gen \
    --tonic_opt=no_include

Usage with buf

When used with buf, options can be specified in the buf.gen.yaml file. protoc-gen-tonic should appear as a plugin step after any protoc-gen-prost steps.

version: v2
plugins:
  - local: protoc-gen-prost
    out: gen
  - local: protoc-gen-tonic
    out: gen

If you have specified compile_well_known_types or extern_path on any earlier step, those should also be specified for this step.

The protoc-gen-tonic plugin is also published on the Buf Schema Registry as a plugin which you can execute remotely, without needing to explicitly install this tool. See the plugin listing to identify the latest published version for use. The plugin is referenced as follows:

version: v2
plugins:
  - remote: buf.build/community/neoeinstein-tonic:v0.4.1
    out: gen

Pulling all of these together, you can compile a ready-made crate for a gRPC service with types that can be JSON serialized using the following example. Then you can depend on this crate from the binary that will host the server or use the client.

version: v2
plugins:
  - local: protoc-gen-prost
    out: gen/src
    opt:
      - compile_well_known_types
      - extern_path=.google.protobuf=::pbjson_types
  - local: protoc-gen-prost-serde
    out: gen/src
  - local: protoc-gen-tonic
    out: gen/src
    opt:
      - compile_well_known_types
      - extern_path=.google.protobuf=::pbjson_types
  - local: protoc-gen-prost-crate
    out: gen
    opt:
      - gen_crate=Cargo.toml.tpl