Crate buffa 

A pure-Rust Protocol Buffers runtime with first-class editions support, zero-copy views, and no_std compatibility.

This is the runtime crate. For code generation, see buffa-build (for build.rs integration) or protoc-gen-buffa (for use as a protoc plugin).

Quick start

Generated message types implement Message. Encode and decode:

use buffa::Message;

// Encode to a Vec<u8> or bytes::Bytes
let bytes: Vec<u8> = person.encode_to_vec();
let bytes: buffa::bytes::Bytes = person.encode_to_bytes();  // re-export of `bytes` crate

// Decode from a byte slice
let decoded = Person::decode_from_slice(&bytes)?;

// Merge into an existing message (proto3 last-wins / proto2 merge semantics)
existing.merge_from_slice(&bytes)?;

For untrusted input, use DecodeOptions to tighten limits:

use buffa::DecodeOptions;

let msg: Person = DecodeOptions::new()
    .with_recursion_limit(50)
    .with_max_message_size(1024 * 1024)     // 1 MiB
    .with_unknown_field_limit(10_000)        // unknown fields per decode
    .decode_from_slice(&bytes)?;

The trait-level convenience methods (decode_from_slice, merge_from_slice) use a fixed recursion limit of RECURSION_LIMIT (100), a fixed DEFAULT_UNKNOWN_FIELD_LIMIT (1,000,000) bounding how many unknown fields the decoder will materialize, and no explicit size cap — a &[u8] is already bounded by whatever allocated it. Use DecodeOptions to tune these, e.g. to reject oversized inputs at the decode entry point rather than at the allocator.

Zero-copy views

Every owned message type Foo has a corresponding FooView<'a> that borrows string and bytes fields directly from the input buffer — no allocation on the read path. See the view module.

let req = PersonView::decode_view(&wire_bytes)?;
println!("name: {}", req.name);  // &'a str, zero-copy

Feature flags

Flag	Default	Enables
std	✓	std::io::Read decoders, std::collections::HashMap for map fields, thread-local JSON parse options (the json module)
json		Proto3 JSON via serde (the json_helpers and any_registry modules)
text		Textproto (human-readable) encoding and decoding
arbitrary		arbitrary::Arbitrary impls for fuzzing

Generated string / bytes fields can use a custom owned type (any type satisfying ProtoString / ProtoBytes) selected at code-generation time through buffa_build’s string_type / bytes_type knobs. The chosen crate is an ordinary dependency of the consuming crate — buffa does not re-export it (see ProtoString).

With default-features = false the crate is #![no_std] (requires alloc). Proto3 JSON serialization still works without std via serde + serde_json with their own alloc features.

Key types

Type	Purpose
Message	Core trait for encode / decode / merge
MessageName	Compile-time FULL_NAME const ("pkg.Msg") for generic dispatch
DecodeOptions	Configurable recursion and size limits
MessageField<T>	Optional sub-message with transparent Deref to default
EnumValue<E>	Open enum wrapper (Known(E) / Unknown(i32))
UnknownFields	Unknown-field preservation for round-trip fidelity
Extension<C>	Typed extension descriptor (codegen-emitted pub const)
ExtensionSet	Get/set extensions via unknown-field storage
view::MessageView	Zero-copy borrowed view trait
view::OwnedView<V>	Self-contained 'static view backed by Bytes
view::ViewReborrow	Expose real borrow lifetime from OwnedView via reborrow

no_std

cargo add buffa --no-default-features

Generated code uses ::buffa::alloc::string::String etc. rather than relying on the prelude, so it compiles unchanged on bare-metal targets. Map fields use std::collections::HashMap (hashbrown::HashMap under no_std) with the foldhash hasher on both paths — see Map for the rationale and the opt-out.

Re-exports

pub use enumeration::EnumValue;

pub use enumeration::Enumeration;

pub use error::DecodeError;

pub use error::EncodeError;

pub use extension::Extension;

pub use extension::ExtensionCodec;

pub use extension::ExtensionSet;

pub use message::DecodeContext;

pub use message::DecodeOptions;

pub use message::Message;

pub use message::MessageName;

pub use message::DEFAULT_UNKNOWN_FIELD_LIMIT;

pub use message::RECURSION_LIMIT;

pub use message_field::DefaultInstance;

pub use message_field::MessageField;

pub use message_field::ProtoBox;

pub use oneof::Oneof;

pub use types::ProtoBytes;

pub use types::ProtoList;

pub use types::ProtoString;

pub use types::WirePayload;

pub use unknown_fields::UnknownField;

pub use unknown_fields::UnknownFieldData;

pub use unknown_fields::UnknownFields;

pub use text::TextFormat;text

pub use view::DefaultViewInstance;

pub use view::HasMessageView;

pub use view::LazyMessageFieldView;

pub use view::LazyMessageView;

pub use view::LazyRepeatedView;

pub use view::MapView;

pub use view::MessageFieldView;

pub use view::MessageView;

pub use view::OwnedView;

pub use view::RepeatedView;

pub use view::UnknownFieldsView;

pub use view::ViewEncode;

pub use view::ViewReborrow;

pub use foldhash;

Modules

any_registryjson

Type registry for google.protobuf.Any proto3 JSON serialization.

editions

Edition feature types and resolution.

encoding

Wire format encoding and decoding primitives.

enumeration

Enum support: the Enumeration trait and EnumValue<E> open-enum wrapper.

error

Error types for buffa encoding and decoding operations.

extension

Typed access to protobuf extensions stored in unknown fields.

extension_registryjson

Runtime registry for proto3 JSON serialization of extensions.

jsonjson

JSON parse options for protobuf JSON deserialization.

json_helpersjson

Proto3 JSON encoding helpers for use with serde.

message

The core Message trait and DecodeOptions builder.

message_field

Optional message field wrapper that provides ergonomic access.

message_set

MessageSet wire format helpers (legacy Google-internal encoding).

oneof

texttext

Textproto (text format) encoding and decoding.

type_registryjson or text

Unified type registry for Any expansion and extension brackets — JSON + text.

types

Protobuf scalar type encoding strategies.

unknown_fields

Unknown field preservation for round-trip fidelity.

view

Zero-copy borrowed message views.

Macros

impl_default_instance

Implement DefaultInstance for a message type via a lazily-initialized OnceBox singleton.

impl_default_view_instance

Implement DefaultViewInstance for a generated view type via a lazily-initialized OnceBox<FooView<'static>> singleton.

impl_view_reborrow

Implement ViewReborrow for a generated view type.

include_proto

Include the generated stitcher for a proto package from OUT_DIR.

include_proto_relative

Like include_proto! but takes a relative directory instead of reading OUT_DIR — for crates that check generated code into the source tree (e.g. buffa-types, buffa-descriptor).

Structs

SizeCache

Transient pre-order cache of nested-message sizes for the two-pass serialization model (compute_size populates, write_to consumes).

SizeCachePool

A caller-owned free-list of spill buffers that amortizes the SizeCache spill allocation across many encodes.

Traits

MapStorage

The owned collection backing a proto map<K, V> field.

Type Aliases

Map

The default owned HashMap type generated map<K, V> fields use.