buffa

Buffa is a pure Rust Protocol Buffers implementation designed with a first-class support for Protobuf Editions. The project is split into several crates to separate the runtime from the code generation tools:

• buffa: The core runtime library. All generated code depends on this. It provides the Message and MessageView traits, wire format codecs, and support for no_std environments.
• buffa-types: Provides pre-generated Rust types for Google's Well-Known Types (e.g., Timestamp, Any, Struct). It is a lightweight dependency that does not require protoc or buffa-codegen at build time.
• buffa-descriptor: Contains Rust types for Protobuf descriptors and compiler plugin messages. It is used by the code generation logic.
• buffa-codegen: The shared logic that transforms Protobuf descriptors into Rust source code.
• protoc-gen-buffa: A protoc plugin binary used as the primary entry point for code generation.
• buffa-build: A convenience crate for integrating code generation into your Rust build.rs script.

The benchmarks/history directory tracks Buffa's performance across releases to identify regressions or improvements. Unlike general benchmarks that compare Buffa to other libraries, this tracks Buffa against its own past versions.

Key Metrics

• Throughput (MiB/s): The primary headline metric. It is used because it remains comparable across releases even if the benchmark dataset size changes.
• Median nanoseconds per iteration: Stored alongside throughput for detailed timing.
• Median across cores: To ensure robustness against noise, each benchmark number is the median across several runs on distinct physical cores.

Measurement Methodology

To isolate code changes from environmental noise, the following are held constant across the entire series:

• The Machine: Runs are performed on a quiesced host (CPU turbo disabled, performance frequency governor, and benchmarks pinned to physical cores).
• The Build Profile: Every binary is built with lto=true and codegen-units=1 to ensure a reproducible, optimized layout.
• The Compiler: A specific toolchain is pinned via RUSTUP_TOOLCHAIN (e.g., 1.96.0) so that performance shifts reflect code changes rather than compiler updates.

The ReflectMessage trait defines how to interact with message data via reflection. When calling get(field: &FieldDescriptor), the behavior follows these rules:

• Singular Scalars: If the field is absent, get() returns the type's default value. Presence is checked via has().
• Repeated/Map Fields: If absent, get() returns an empty list or map.
• Enums: Returns the number only, matching DynamicMessage behavior.
• Messages: Returns a ValueRef::Message containing either a borrowed view (MessageFieldView<V>) or a static default instance if unset.

ValueRef is the container for reflected values. It uses trait objects for collections to avoid materializing full data structures:

• ValueRef::List(&'a dyn ReflectList)
• ValueRef::Map(&'a dyn ReflectMap)
• ValueRef::String(&'a str)
• ValueRef::Bytes(&'a [u8])
• ValueRef::I32(i32) (and other scalars)
• ValueRef::EnumNumber(i32)

pub enum ValueRef<'a> {
    String(&'a str),
    Bytes(&'a [u8]),
    I32(i32),
    EnumNumber(i32),
    Message(ReflectCow<'a>),
    List(&'a dyn ReflectList),
    Map(&'a dyn ReflectMap),
}

Buffa generates Rust structs that map to Protobuf messages. Key characteristics include:

• Sub-messages: Represented as buffa::MessageField<T> rather than Option<Box<T>> to allow inline storage and ergonomic access.
• Open Enums: Represented as EnumValue<E> to preserve unknown integer values (Proto3 behavior).
• Unknown Fields: A hidden field __buffa_unknown_fields of type buffa::UnknownFields is included to preserve data from newer schema versions.
• Module Nesting: Nested messages are placed in modules named after the parent (e.g., outer::Inner) rather than being flattened (e.g., OuterInner).
• No Serialization State: Structs do not contain internal mutability or size caches; sizes are managed externally via a SizeCache.

// Example Protobuf:
// message Person {
//   string name = 1;
//   int32 id = 2;
//   repeated string tags = 3;
//   Address address = 4;
//   optional string nickname = 5;
// }

// Generated Rust:
pub struct Person {
    pub name: String,
    pub id: i32,
    pub tags: Vec<String>,
    pub address: buffa::MessageField<Address>,
    pub nickname: Option<String>,
    #[doc(hidden)]
    pub __buffa_unknown_fields: buffa::UnknownFields,
}

If you generate the same .proto file in two different crates using different representation types (e.g., one uses SmolStr and another uses Bytes), Rust treats them as unrelated types (a::Foo and b::Foo). They cannot be used interchangeably.

Recommended Solutions:

1. Use extern_path (Best Practice): Instead of generating the same proto twice, use extern_path to point to a single, shared definition. This ensures one definition and zero conversions.
2. Manual From Implementation: If you must have two different representations, the most efficient way to convert between them is to hand-write a static field-by-field impl From<a::Foo> for b::Foo. This avoids the overhead of a wire round-trip (encoding/decoding) and dynamic dispatch.

Note on Conversions: Because different representations own separate buffers, any conversion path will require allocating the destination's string and bytes fields.

Buffa uses EnumValue<E> for open enums (proto3 default) and bare E for closed enums (proto2).

• Reading: Match on buffa::EnumValue::Known(variant) or buffa::EnumValue::Unknown(value). You can also use direct comparison (e.g., msg.status == Status::ACTIVE).
• Setting: Use .into() on the enum variant.
• Raw Access: Use .to_i32() to get the underlying integer.

 // Setting an enum field
-msg.status = Status::Active as i32;
+msg.status = Status::ACTIVE.into();

 // Reading
-match Status::try_from(msg.status) {
-    Ok(Status::Active) => { /* ... */ }
-    Ok(s) => { /* other known variant */ }
-    Err(_) => { /* unknown value */ }
-}
+match msg.status {
+    buffa::EnumValue::Known(Status::ACTIVE) => { /* ... */ }
+    buffa::EnumValue::Known(s) => { /* other known variant */ }
+    buffa::EnumValue::Unknown(v) => { /* unknown value */ }
+}
+// or use direct comparison:
+if msg.status == Status::ACTIVE { /* ... */ }

 // Getting the raw integer
-let raw: i32 = msg.status;
+let raw: i32 = msg.status.to_i32();