pbrs

pbrs is a pure-Rust Protocol Buffers runtime and code generator for Rust developers who want the Google protobuf v4 application API without a C or C++ runtime. This workspace also contains pbrs-grpc for native gRPC over HTTP/2 and protobuf-tonic for tonic 0.14+ users.

Current status: published versions are available for evaluation, with recorded conformance through Protocol Buffers Edition 2023; production qualification and stronger performance claims still require the evidence in the roadmap.

Why use pbrs?

• Pure Rust build: pbrs compiles with rustc. It does not wrap Google's upb C library through foreign function interface (FFI).
• Google protobuf v4-shaped API: generated types use the application-level traits and shapes such as Parse, Serialize, Clear, proto!, ProtoStr, RepeatedView, and DynamicMessage.
• Recorded conformance: Google's conformance_test_runner v35.1 passes 5,631 binary + JSON cases and 909 text cases with no unexpected results.
• Broad protobuf surface: proto2, proto3, Edition 2023 behavior, well-known types (WKT), dynamic reflection, JSON formatting, and text formatting are in scope.
• Performance-oriented storage: small-string optimization, zero-allocation empty collections, lazy materialization after wire validation, and specialized packed-scalar handling are built into the runtime.

pbrs is an application API alternative, not a drop-in replacement for official generated internals or prost::Message. See the upb comparison and implementation status for the tested boundaries.

Quick start: install, generate, use

This quick start generates Rust from proto/person.proto during your Cargo build. Direct .proto generation requires protoc on your PATH; see code generation options if you want checked-in descriptors instead.

1. Add pbrs as both a runtime and build dependency:

   [dependencies]
   pbrs = "0.2"
   
   [build-dependencies]
   pbrs = "0.2"
   

2. Add a proto file at proto/person.proto:

   syntax = "proto3";
   package tutorial;
   
   message Person {
     string name = 1;
     int32 id = 2;
     string email = 3;
     repeated string phones = 4;
   }
   

3. Generate Rust in build.rs:

   fn main() -> Result<(), Box<dyn std::error::Error>> {
       pbrs::codegen::compile_protos(&["proto/person.proto"], &["proto"])?;
       Ok(())
   }
   

4. Include and use the generated type:

   use pbrs::prelude::*;
   
   include!(concat!(env!("OUT_DIR"), "/person.rs"));
   
   fn main() -> Result<(), Box<dyn std::error::Error>> {
       let mut person = Person::new();
       person.set_name("Ada Lovelace");
       person.set_id(42);
       person.set_email("ada@example.com");
       person.phones_mut().push("555-0100");
   
       let bytes: Vec<u8> = person.serialize()?;
       let decoded = Person::parse(&bytes)?;
   
       assert_eq!(decoded.name(), "Ada Lovelace");
       assert_eq!(decoded.id(), 42);
   
       println!("Parsed: {} (ID: {})", decoded.name(), decoded.id());
       Ok(())
   }
   

For protos that define services, compile_protos emits native pbrs-grpc stubs by default. tonic users must opt in with Config::emit_tonic_stubs(true).

Which crate do I need?

Workspace Crates

Code generation options

Generating directly from .proto files needs protoc. Generating from a previously compiled descriptor set does not run protoc during the application build.

There is no enforced universal protoc version; see the support matrix.

Direct .proto generation with build.rs

Use this when your build environment has protoc available:

fn main() -> Result<(), Box<dyn std::error::Error>> {
    pbrs::codegen::compile_protos(&["proto/person.proto"], &["proto"])?;
    Ok(())
}

Then include the generated file in src/lib.rs or src/main.rs:

include!(concat!(env!("OUT_DIR"), "/person.rs"));

Checked descriptor set generation

Use this when you want application builds to avoid running protoc. First create and check in a descriptor set with imports included:

protoc -I proto --include_imports --descriptor_set_out=proto/person.fds proto/person.proto

Then compile from that descriptor set:

fn main() -> Result<(), Box<dyn std::error::Error>> {
    pbrs::codegen::Config::new()
        .out_dir(std::env::var("OUT_DIR")?)
        .compile_descriptor_set("proto/person.fds", &["person.proto"], &["proto"])?;
    Ok(())
}

Descriptor targets use include-relative names such as person.proto. The descriptor and available source imports are tracked for rebuilds. See the codegen guide for native stubs, tonic stubs, and messages-only generation.

Against this checkout, a consumer using a checked descriptor set can cold-build messages, native stubs, and tonic stubs without protoc on its build PATH. The older 0.1.0-alpha.1 adapter archives still require it.

protoc-gen-pbrs plugin

Install or build the plugin binary:

cargo install --path . --bin protoc-gen-pbrs

Run protoc with the --pbrs_out flag:

protoc --pbrs_out=./gen --proto_path=./proto ./proto/hello.proto

Or use the helper script:

./scripts/gen.sh -I proto -o gen proto/your.proto

gRPC choices

For a complete service with generated stubs, health checking, and server reflection, see examples/greeter.

Support matrix

Recorded against this repository on stable rustc 1.98. Declared rust-version is the continuous integration (CI) minimum supported Rust version (MSRV) job, not this host's toolchain. Releases follow the release guide: tag/dispatch only; main pushes do not publish.

The maintained crates and tools use Rust language Edition 2024, available from rustc 1.85. Frozen reference/comparator and discarded-experiment manifests keep their original edition for reproducibility. This is independent of Protocol Buffers Edition 2024.

Untested / unsupported (not a support commitment):

• tonic 0.12 and 0.13 are unsupported.
• Protocol Buffers Edition 2024 descriptor fixtures are tested, but generated consumers and conformance beyond Edition 2023 are not qualified.
• Windows CI is untested.

Performance and stack selection

Use the benchmark report for versioned, workload-specific comparisons with prost, the Google Rust/upb wrapper, buffa, tonic, and grpc-go. Those results include wins, losses, and caveats; they do not establish universal feature parity or superiority. The roadmap scorecard defines the evidence needed for stronger claims.

For large payloads and copy behavior, also see Large payloads / zero-copy.

Conformance and testing

pbrs is tested against Google's official protobuf test suite:

The separate rust/test/shared coverage has documented exclusions.

Run the conformance suite locally:

./scripts/fetch-protobuf.sh
./scripts/conformance.sh

Documentation

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.