Expand description
Zero-copy borrowed message views.
Buffa generates two representations for each protobuf message:
-
Owned (
MyMessage): usesString,Vec<u8>,Vec<T>for fields. Suitable for building messages, long-lived storage, and mutation. -
Borrowed (
MyMessageView<'a>): uses&'a str,&'a [u8], and slice-backed repeated fields. Borrows directly from the input buffer for zero-copy deserialization on the read path.
§Motivation
In a typical RPC handler, the request is parsed from a buffer, fields are read, and the buffer is discarded. With owned types, every string and bytes field requires an allocation + copy. With view types, strings and bytes borrow directly from the input buffer — no allocation at all.
This is analogous to how Cap’n Proto’s Rust implementation works, and how Go achieves zero-copy string deserialization via its garbage collector.
§Usage pattern
// Decode a view (zero-copy, borrows from `wire_bytes`)
let request = MyRequestView::decode_view(&wire_bytes)?;
println!("name: {}", request.name); // &str, no allocation
// Build an owned response
let response = MyResponse {
id: request.id,
status: "ok".into(),
..Default::default()
};
// Convert view to owned if needed for storage
let owned: MyRequest = request.to_owned_message()?;§Reborrowing from OwnedView
OwnedView<V> wraps a decoded view with the lifetime erased
to 'static. The inner view is reached through
OwnedView::reborrow, which ties the borrow to the OwnedView itself —
field reads, assigning the view to a binding, passing it to a function
with a non-'static lifetime parameter, and returning a borrowed field
all go through the same call:
// reborrow ties the returned borrow to the OwnedView's lifetime.
fn handler<'a>(req: &'a OwnedView<PersonView<'static>>) -> &'a str {
req.reborrow().name
}The view is deliberately not exposed as &V (e.g. via Deref): V is
FooView<'static>, so its borrowed fields would appear 'static to the
compiler and could outlive the buffer they point into. reborrow narrows
that synthetic 'static down to the OwnedView’s real lifetime. Generated
code also provides a per-message FooOwnedView wrapper with field accessor
methods, so handler code rarely needs to call reborrow directly. See
OwnedView for details.
The same synthetic 'static is what V::decode_view sees, so every
OwnedView constructor requires V: ViewLifetimeParametric — the
unsafe marker asserting that no impl on V can let a borrow of that
buffer outlive the view. Codegen emits it for every generated view;
hand-written views opt in with an explicit unsafe impl.
§Generated code shape
For a message like:
message Person {
string name = 1;
int32 id = 2;
bytes avatar = 3;
repeated string tags = 4;
Address address = 5;
}Buffa generates:
// Owned type (heap-allocated strings and vecs)
pub struct Person {
pub name: String,
pub id: i32,
pub avatar: Vec<u8>,
pub tags: Vec<String>,
pub address: MessageField<Address>,
#[doc(hidden)] pub __buffa_unknown_fields: UnknownFields,
}
// Borrowed view type (zero-copy from input buffer)
pub struct PersonView<'a> {
pub name: &'a str,
pub id: i32,
pub avatar: &'a [u8],
pub tags: RepeatedView<'a, &'a str>,
pub address: MessageFieldView<AddressView<'a>>,
pub __buffa_unknown_fields: UnknownFieldsView<'a>,
}Structs§
- Lazy
Message Field View - A deferred view of a singular message field on a lazy view.
- Lazy
Repeated Iter - Iterator over a
LazyRepeatedView, decoding each element on access. - Lazy
Repeated View - A deferred view of a repeated message field on a lazy view.
- MapView
- A borrowed view of a map field.
- Message
Field View - A borrowed view of an optional message field.
- Owned
View - An owned,
'staticcontainer for a decoded message view. - Repeated
View - A borrowed view of a repeated field.
- Unknown
Fields View - A borrowed view of unknown fields.
Traits§
- Default
View Instance - Provides access to a lazily-initialized default view instance.
- HasMessage
View - Links an owned message type to its generated zero-copy view types.
- Lazy
Message View - The trait implemented by generated lazy view types (
FooLazyView<'a>). - Message
View - Trait for zero-copy borrowed message views.
- View
Encode - Serialize a
MessageViewdirectly from its borrowed fields. - View
Lifetime Parametric - Marker asserting that a view type is parametric in its buffer lifetime —
the soundness contract behind
OwnedView. - View
Reborrow - Exposes the real lifetime of an
OwnedView’s borrows.