pub trait ProtoBytes:
Clone
+ PartialEq
+ Default
+ Debug
+ Send
+ Sync
+ Deref<Target = [u8]>
+ AsRef<[u8]>
+ From<Vec<u8>> {
const PREFERS_OWNED_PAYLOAD: bool = false;
// Required method
fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError>;
// Provided methods
fn decode_length_delimited(
payload: &mut FieldPayload<impl Buf>,
) -> Result<Self, DecodeError> { ... }
fn as_shared(&self) -> Option<Bytes> { ... }
}Expand description
The bound generated code places on the Rust type used for a proto bytes
field.
buffa implements it for the default Vec<u8> and for
bytes::Bytes (which decodes zero-copy from a
Bytes-backed buffer). Select another representation with buffa_build’s
bytes_type / bytes_type_custom. There is intentionally no blanket
impl, and a foreign type cannot implement this trait (orphan rule) — wrap
it in a local newtype that implements the trait; see
examples/custom-types in the buffa repository for the canonical template.
This is the bytes-side twin of ProtoString; the bounds are exactly what
generated code requires of a bytes field:
from_wire(the required method, below) — the binary decode constructor.Clone + PartialEq + Default + Debug— for the#[derive(...)]and the hand-writtenDebugimpl on message structs, and forclear()when the field has no declared default (a substituted type may be immutable).Send + Sync— so a message owning such a field staysSend + Sync.Deref<Target = [u8]>andAsRef<[u8]>— generated code reads the field’s bytes through these bounds: the size pass borrows&[u8]wherebytes_encoded_lenexpects it, and the write pass goes throughput_shared_bytes_field/AsSharedBytes, whose blanket impl reads viaAsRef<[u8]>.From<Vec<u8>>— used by the JSON and view→owned paths, and byDefaultandclear()to construct declared field defaults. Binary decode usesdecode_length_delimitedinstead, whose default callsfrom_wire. Note thatFrom<&[u8]>is deliberately not required:bytes::Bytesimplements it only for&'static [u8], so requiring it would excludeBytesitself.
For the default Vec<u8> representation every conversion is the identity, so
the generic path costs nothing relative to the specialized one.
§Contract
The bounds are structural and cannot capture these invariants; an implementation must uphold them:
Defaultis the empty value — generatedclear()resets toDefault::default()and implicit-presence encoding skips empty values, so a non-emptyDefaultsilently drops or corrupts cleared fields.Deref,AsRef, and the constructors observe the same content — encoding borrows viaDeref/AsRefand the view / reflect paths read the same way; if they disagree, a value encodes differently than it reads back.from_wireand anydecode_length_delimitedoverride are value-equivalent toFrom<Vec<u8>>— binary decode uses them while JSON / view→owned useFrom, so a representation must not transform the bytes in one path but not the other.
§Limitations
repeatedelements andmap<K, bytes>values must be crate-local. A custom type used as the element of arepeatedfield — or as amap<K, bytes>value — needs codegen-emittedReflectElement(vtable) and base64ProtoElemJson(JSON) impls, which the orphan rule permits only when the type is local to the generating crate. A foreign custom type in that position fails to compile — wrap it in a crate-local newtype. Singular, optional, and oneof uses work with a foreign type directly. (A custombytesmap value is honored just like the built-inbytes::Bytes; only themap<bytes, bytes>carve-out keepsVec<u8>values.) A type with a JSON policy (json_policy_type) gets noProtoElemJsonimpl, because its elements and values go through buffa’s policy helpers, so only vtable reflection (ReflectElement) or reflection with message cleanup (InspectElement) requires it to be crate-local, unless generated integrations are disabled (custom_type_impls=false).- No
Arbitraryimpl required. Under thearbitraryfeature codegen attaches a generic builder, so a custom type needs no nativearbitrary::Arbitraryimpl.
Provided Associated Constants§
Sourceconst PREFERS_OWNED_PAYLOAD: bool = false
const PREFERS_OWNED_PAYLOAD: bool = false
Whether the default
decode_length_delimited implementation hands
from_wire an owned WirePayload for every field,
including a field that is
contiguous in the input.
Set it to true for a type that keeps the Bytes from
WirePayload::into_bytes, such as a wrapper around Bytes. The
decoder then takes each payload with Buf::copy_to_bytes: a Bytes
input shares its allocation with the payload, while a &[u8] input,
and a field that spans two chunks of a Chain, are copied.
Leave it false for a type that copies the bytes from
WirePayload::as_slice, such as one that stores short values inline.
With true, such a type copies twice from an input that cannot share:
once into a temporary Bytes and once into the value.
This const controls only the default decode implementation. from_wire
still has to accept a borrowed payload, which any caller can build with
WirePayload::borrowed.
§Memory retention
A value that shares the input keeps the whole input buffer allocated
until every Bytes that shares it, including each clone of the value,
is dropped. To detach a value from a large input, replace it with a
copy, for example B::from(value.to_vec()). Users of the type meet this
cost, so repeat it in the type’s own documentation.
§Example
A wrapper around Bytes that shares the input on decode, and that a
segmented sink splices by reference count on encode:
use buffa::bytes::Bytes;
use buffa::types::{decode_bytes_to, encode_bytes, ProtoBytes, WirePayload};
use buffa::DecodeError;
#[derive(Clone, Debug, Default, PartialEq)]
struct Shared(Bytes);
impl core::ops::Deref for Shared {
type Target = [u8];
fn deref(&self) -> &[u8] {
&self.0
}
}
impl AsRef<[u8]> for Shared {
fn as_ref(&self) -> &[u8] {
&self.0
}
}
impl From<Vec<u8>> for Shared {
fn from(bytes: Vec<u8>) -> Self {
Self(Bytes::from(bytes))
}
}
impl ProtoBytes for Shared {
const PREFERS_OWNED_PAYLOAD: bool = true;
fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError> {
Ok(Self(payload.into_bytes()))
}
fn as_shared(&self) -> Option<Bytes> {
Some(self.0.clone())
}
}
let mut wire = Vec::new();
encode_bytes(b"payload", &mut wire);
let mut input = Bytes::from(wire);
let payload_start = input.as_ptr() as usize + 1; // after the length prefix
let value: Shared = decode_bytes_to(&mut input)?;
assert_eq!(&value[..], b"payload");
// The value points into the input: decoding copied no bytes.
assert_eq!(value.0.as_ptr() as usize, payload_start);Required Methods§
Sourcefn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError>
fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError>
Construct the representation from a decoded bytes field’s wire payload.
The decode constructor: it chooses between borrowing the payload
(WirePayload::as_slice) and taking ownership
(WirePayload::into_bytes). A contiguous field arrives borrowed
unless the type sets
PREFERS_OWNED_PAYLOAD.
Binary decode calls from_wire through the default
decode_length_delimited. A type that
overrides that method still provides from_wire for direct callers.
The ordinary JSON, text format, view→owned conversion, declared field
defaults and arbitrary paths use From<Vec<u8>>. Selected JSON policies
use their policy deserializer, and guarded arbitrary construction calls
from_wire directly with borrowed input.
§Errors
The built-in representations are infallible. A representation that
enforces additional invariants (e.g. a fixed length) can reject the
value with DecodeError::Custom (carrying a static reason), or return
any other DecodeError variant.
Provided Methods§
Sourcefn decode_length_delimited(
payload: &mut FieldPayload<impl Buf>,
) -> Result<Self, DecodeError>
fn decode_length_delimited( payload: &mut FieldPayload<impl Buf>, ) -> Result<Self, DecodeError>
Decode one field payload, given exactly the bytes of that field.
Generated code (decode_bytes_to_ctx) and decode_bytes_to call
this after reading the field’s length prefix and checking it, so
payload holds exactly that field and payload.remaining() is its
validated length. Under generated code the length is checked against
the end of the message that holds the field, so the payload never
reaches the following field or message. The
default passes a WirePayload to Self::from_wire, honoring
Self::PREFERS_OWNED_PAYLOAD.
Override it when the representation must also control temporary
allocations, for example to copy a fragmented field straight into
storage that is wiped on drop rather than through an intermediate
Bytes.
An override must accept and reject exactly the payloads that
from_wire does, and produce an equal value. Bytes it leaves
unread are skipped. The opaque FieldPayload exposes only bounded
Buf operations; its limit and underlying buffer cannot be accessed.
§Errors
Returns the representation’s error for a rejected payload. On error the input position within the payload is unspecified, but its window remains bounded to the same field. Propagating the error aborts the enclosing decode.
§Example
A representation that copies the field into one allocation of the field’s exact size, also when the field spans input chunks:
use buffa::bytes::Buf;
use buffa::FieldPayload;
use buffa::types::{decode_bytes_to, encode_bytes, ProtoBytes, WirePayload};
use buffa::DecodeError;
#[derive(Clone, Debug, Default, PartialEq)]
struct Exact(Vec<u8>);
impl core::ops::Deref for Exact {
type Target = [u8];
fn deref(&self) -> &[u8] {
&self.0
}
}
impl AsRef<[u8]> for Exact {
fn as_ref(&self) -> &[u8] {
&self.0
}
}
impl From<Vec<u8>> for Exact {
fn from(bytes: Vec<u8>) -> Self {
Self(bytes)
}
}
impl ProtoBytes for Exact {
fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError> {
Ok(Self(payload.as_slice().to_vec()))
}
fn decode_length_delimited(payload: &mut FieldPayload<impl Buf>) -> Result<Self, DecodeError> {
// The length is already checked against the input (and, under
// generated code, the enclosing message), so this reservation
// never exceeds the bytes actually present.
let mut out = Vec::with_capacity(payload.remaining());
while payload.has_remaining() {
let chunk = payload.chunk();
out.extend_from_slice(chunk);
let read = chunk.len();
payload.advance(read);
}
Ok(Self(out))
}
}
let mut wire = Vec::new();
encode_bytes(b"payload", &mut wire);
let (head, tail) = wire.split_at(3);
let mut input = head.chain(tail);
let value: Exact = decode_bytes_to(&mut input)?;
assert_eq!(&value[..], b"payload");
assert_eq!(value.0.capacity(), b"payload".len());The representation’s bytes as a reference-counted Bytes handle,
when one exists.
This is the encode-side hook for segmented sinks: a representation
that stores its bytes as (or can cheaply produce) a Bytes returns
Some, letting put_shared_bytes_field splice the field into a
Rope by reference count.
The default returns None, which means “copy me” — always correct.
§Correctness
The returned handle must view exactly the bytes of
self.as_ref(). A violation (stale handle, different slicing, a
reused scratch buffer) produces a corrupt encoding — and only when
the sink is segmented: contiguous sinks never call the handle, so
the bug is invisible in ordinary tests. Implementations overriding
this method should test their encode path against a
Rope explicitly (a debug_assert in
put_shared_bytes_field catches length mismatches, not aliasing).
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".