Skip to main content

ProtoBytes

Trait ProtoBytes 

Source
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-written Debug impl on message structs, and for clear() when the field has no declared default (a substituted type may be immutable).
  • Send + Sync — so a message owning such a field stays Send + Sync.
  • Deref<Target = [u8]> and AsRef<[u8]> — generated code reads the field’s bytes through these bounds: the size pass borrows &[u8] where bytes_encoded_len expects it, and the write pass goes through put_shared_bytes_field / AsSharedBytes, whose blanket impl reads via AsRef<[u8]>.
  • From<Vec<u8>> — used by the JSON and view→owned paths, and by Default and clear() to construct declared field defaults. Binary decode uses decode_length_delimited instead, whose default calls from_wire. Note that From<&[u8]> is deliberately not required: bytes::Bytes implements it only for &'static [u8], so requiring it would exclude Bytes itself.

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:

  • Default is the empty value — generated clear() resets to Default::default() and implicit-presence encoding skips empty values, so a non-empty Default silently drops or corrupts cleared fields.
  • Deref, AsRef, and the constructors observe the same content — encoding borrows via Deref / AsRef and the view / reflect paths read the same way; if they disagree, a value encodes differently than it reads back.
  • from_wire and any decode_length_delimited override are value-equivalent to From<Vec<u8>> — binary decode uses them while JSON / view→owned use From, so a representation must not transform the bytes in one path but not the other.

§Limitations

  • repeated elements and map<K, bytes> values must be crate-local. A custom type used as the element of a repeated field — or as a map<K, bytes> value — needs codegen-emitted ReflectElement (vtable) and base64 ProtoElemJson (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 custom bytes map value is honored just like the built-in bytes::Bytes; only the map<bytes, bytes> carve-out keeps Vec<u8> values.) A type with a JSON policy (json_policy_type) gets no ProtoElemJson impl, 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 Arbitrary impl required. Under the arbitrary feature codegen attaches a generic builder, so a custom type needs no native arbitrary::Arbitrary impl.

Provided Associated Constants§

Source

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§

Source

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§

Source

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());
Source

fn as_shared(&self) -> Option<Bytes>

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".

Implementations on Foreign Types§

Source§

impl ProtoBytes for Bytes

Source§

impl ProtoBytes for Vec<u8>

Source§

fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError>

Implementors§