bendb-instacart/rust-protobuf

Rust implementation of Google protocol buffers

rust-protobuf

Protobuf implementation in Rust.

• Written in pure rust
• Generate rust code
• Has runtime library for generated code (Coded{Input|Output}Stream impl)
• Supports both Protobuf versions 2 and 3

List of crates

rust-protobuf — repository provides multiple crates:

• protobuf — protobuf runtime
• protobuf-codegen — protobuf codegen engine and protoc-gen-rust plugin for protoc command
• protoc — programmatically work with protoc command
• protoc-rust — codegen which can be invoked programmatically using protoc binary (e. g. from build.rs)
• protobuf-codegen-pure — pure rust codegen
• protoc-bin-vendored — protoc binary packaged as crate, can be used with protoc or protoc-rust crates

About versions and branches

• 2.*.* is the latest stable version. 2.*.* versions follow semver conventions
• versions below 2 are no longer supported

See CHANGELOG.md for a list of changes and compatility issues between versions.

How to generate rust code

There are several ways to generate rust code from .proto files:

• Invoke protoc programmatically with protoc-rust crate (protoc-rust crate). Reliable, but depends on protoc binary.
• Use pure rust protobuf parser and code generator (protobuf-codegen-pure crate). Convenient, but may generate incorrect code or fail in complex definitions.
• Use protoc-gen-rust plugin for Google's protoc command. This is useful to generate code manually or when using external build system.

Generated code

Have a look at generated files, used internally in rust-protobuf:

• descriptor.rs for descriptor.proto (that is part of Google protobuf)

Rustdoc

docs.rs hosts rustdoc for protobuf.

Getting help

Feel free to open an issue if you need help with rust-protobuf.

Copy-on-write

Rust-protobuf can be used with bytes crate.

To enable Bytes you need to:

1. Enable with-bytes feature in rust-protobuf:

[dependencies]
protobuf = { version = "2", features = ["with-bytes"] }

2. Enable bytes option

with Customize when codegen is invoked programmatically:

With stable rust-protobuf:

protoc_rust::run(protoc_rust::Args {
    ...
    customize: Customize {
        carllerche_bytes_for_bytes: Some(true),
        carllerche_bytes_for_string: Some(true),
        ..Default::default()
    },
 });

With rust-protobuf from master:

protoc_rust::Args::new()
    ...
    .customize(Customize {
        carllerche_bytes_for_bytes: Some(true),
        carllerche_bytes_for_string: Some(true),
        ..Default::default()
    })
    .run()?;

or in .proto file:

import "rustproto.proto";

option (rustproto.carllerche_bytes_for_bytes_all) = true;
option (rustproto.carllerche_bytes_for_string_all) = true;

With these options enabled, fields of type bytes or string are generated as Bytes or Chars respectively. When CodedInputStream is constructed from Bytes object, fields of these types get subslices of original Bytes object, instead of being allocated on heap.

serde_derive support

(Only in master, not released yet)

Rust-protobuf can be used with serde.

To enable serde you need to:

1. Enable serde option

with Customize when codegen is invoked programmatically:

with stable rust-protobuf:

protoc_rust::run(protoc_rust::Args {
    ...
    customize: Customize {
        serde_derive: Some(true),
        ..Default::default()
    },
});

with rust-protobuf from master:

protoc_rust::Args::new()
    ...
    .customize(Customize {
        serde_derive: Some(true),
        ..Default::default()
    })
    .run()?;

or in .proto file:

import "rustproto.proto";

option (rustproto.serde_derive_all) = true;

You may now Serialize and Deserialize messages:

let my_message = MyMessage::new();
serde_json::to_string(&my_message).unwrap();

Related projects

• quick-protobuf — alternative protobuf implementation in Rust
• prost — another protobuf implementation in Rust
• serde-protobuf
• grpc-rust — implementation of gRPC based on this library
• grpc-rs — another gRPC implementation for Rust