Skip to main content

Module view

Module view 

Source
Expand description

Zero-copy borrowed message views.

Buffa generates two representations for each protobuf message:

  • Owned (MyMessage): uses String, 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§

LazyMessageFieldView
A deferred view of a singular message field on a lazy view.
LazyRepeatedIter
Iterator over a LazyRepeatedView, decoding each element on access.
LazyRepeatedView
A deferred view of a repeated message field on a lazy view.
MapView
A borrowed view of a map field.
MessageFieldView
A borrowed view of an optional message field.
OwnedView
An owned, 'static container for a decoded message view.
RepeatedView
A borrowed view of a repeated field.
UnknownFieldsView
A borrowed view of unknown fields.

Traits§

DefaultViewInstance
Provides access to a lazily-initialized default view instance.
HasMessageView
Links an owned message type to its generated zero-copy view types.
LazyMessageView
The trait implemented by generated lazy view types (FooLazyView<'a>).
MessageView
Trait for zero-copy borrowed message views.
ViewEncode
Serialize a MessageView directly from its borrowed fields.
ViewLifetimeParametric
Marker asserting that a view type is parametric in its buffer lifetime — the soundness contract behind OwnedView.
ViewReborrow
Exposes the real lifetime of an OwnedView’s borrows.