pbrs

A high-performance, pure-Rust Protocol Buffers kernel with the Google protobuf v4 application API.

pbrs provides full support for Protocol Buffers (proto2, proto3, and Editions 2023) with zero C/C++ dependencies, zero unsafe in application code, and 100% official Google conformance.

Why pbrs?

• Pure Rust: No C or C++ compiler required. Unlike crates.io protobuf 4.x (which wraps Google's upb C library via FFI), pbrs compiles entirely with rustc.
• Google Protobuf v4 API: Matches the official Google Rust application API traits and shapes (Parse, Serialize, Clear, proto!, ProtoStr, RepeatedView, DynamicMessage).
• 100% Conformance: Passes Google's official conformance_test_runner v35.1 (5,631 binary + JSON tests, 909 text tests, 0 unexpected failures, 0 skips).
• Prost Alternative: Unlike Prost, which uses custom derive traits and layout conventions, pbrs gives you the standard protobuf v4 API, exact proto3 presence semantics, WKT support, dynamic reflection, and field-wise JSON/Text formatting.
• Fast & Memory Efficient: Single-pass parsing with small-string optimization (SSO), zero-allocation empty collections, lazy sub-message parsing, and vectorized packed-scalar decoding.

Workspace Crates

Installation

Add pbrs to your Cargo.toml:

[dependencies]
pbrs = "0.1"

(Until published to crates.io, you can point to the git repository:)

[dependencies]
pbrs = { git = "https://github.com/mingley/pure-protobuf" }

Code Generation

protoc must be installed and available on your PATH.

Option A: Using build.rs (Recommended)

Add pbrs as a build dependency in your Cargo.toml:

[build-dependencies]
pbrs = "0.1"

In your build.rs:

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

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

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

Option B: Using 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 using the helper script:

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

Quickstart Example

Given a proto file (proto/person.proto):

syntax = "proto3";
package tutorial;

message Person {
  string name = 1;
  int32 id = 2;
  string email = 3;
  repeated string phones = 4;
}

Using the generated struct:

use pbrs::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Create and populate a message
    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");

    // 2. Serialize to wire format
    let bytes: Vec<u8> = person.serialize()?;

    // 3. Parse back from bytes
    let decoded = Person::parse(&bytes)?;
    assert_eq!(decoded.name(), "Ada Lovelace");
    assert_eq!(decoded.id(), 42);

    // 4. Inspect or clear
    println!("Parsed: {} (ID: {})", decoded.name(), decoded.id());
    
    Ok(())
}

gRPC Integration

You can use pbrs messages with either gRPC stack:

1. pbrs-grpc (Pure-Rust Kernel): If you want a lightweight, pure-Rust gRPC stack without tonic, C dependencies, or unsafe in the transport layer. See the gRPC Guide and pbrs-grpc/README.md.
2. protobuf-tonic (Tonic Adapter): If you have an existing tonic 0.14+ service and want to drop in pbrs messages instead of prost. See protobuf-tonic/README.md.

For a complete end-to-end example with service stubs, gRPC health checking (grpc.health.v1), and server reflection (grpc.reflection.v1), check out examples/greeter.

Comparison with Alternatives

Conformance & Testing

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

• Official conformance_test_runner v35.1:
  • Required tests (×2): 5,631 binary + JSON, 0 unexpected failures.
  • Text format tests: 909 text tests, 0 unexpected failures.
  • Recommended tests (--enforce_recommended): Passed with 0 unexpected failures.
  • Skip list: None. Unlike upb, which maintains a skip list for proto2 UTF-8, pbrs passes all tests without exclusions.

Run the conformance suite locally:

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

Documentation

• Architecture Overview — Module organization and crate boundaries.
• Design & Internals — Memory layout, parsing strategy, and optimization techniques.
• Relative to upb — Detailed comparison with Google's C-based upb kernel.
• Benchmarks & Performance — Unary, streaming, and throughput measurements.
• Implementation Status — Supported features, conformance breakdown, and roadmap.
• Native gRPC Kernel Guide — In-depth guide to building microservices with pbrs-grpc.
• Tonic Adapter Guide — Using pbrs with tonic 0.14+.
• Release Policy & Publishing — Automated crates.io publication workflows and tag conventions.

License

Licensed under either of:

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

at your option.