pub trait Message:
DefaultInstance
+ Clone
+ PartialEq
+ Send
+ Sync {
Show 26 methods
// Required methods
fn compute_size(&self, cache: &mut SizeCache) -> u32;
fn write_to(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink);
fn merge_field(
&mut self,
tag: Tag,
buf: &mut impl Buf,
ctx: DecodeContext<'_>,
) -> Result<(), DecodeError>;
fn clear(&mut self);
// Provided methods
fn encode(&self, buf: &mut impl EncodeSink) { ... }
fn try_encode(&self, buf: &mut impl EncodeSink) -> Result<(), EncodeError> { ... }
fn encode_with_cache(
&self,
cache: &mut SizeCache,
buf: &mut impl EncodeSink,
) { ... }
fn try_encode_with_cache(
&self,
cache: &mut SizeCache,
buf: &mut impl EncodeSink,
) -> Result<(), EncodeError> { ... }
fn try_encode_bounded(
&self,
max_bytes: u32,
buf: &mut impl EncodeSink,
) -> Result<u32, EncodeError> { ... }
fn try_encode_bounded_with_cache(
&self,
max_bytes: u32,
cache: &mut SizeCache,
buf: &mut impl EncodeSink,
) -> Result<u32, EncodeError> { ... }
fn encoded_len(&self) -> u32 { ... }
fn try_encoded_len(&self) -> Result<u32, EncodeError> { ... }
fn encode_length_delimited(&self, buf: &mut impl EncodeSink) { ... }
fn try_encode_length_delimited(
&self,
buf: &mut impl EncodeSink,
) -> Result<(), EncodeError> { ... }
fn encode_to_vec(&self) -> Vec<u8> ⓘ { ... }
fn try_encode_to_vec(&self) -> Result<Vec<u8>, EncodeError> { ... }
fn encode_to_bytes(&self) -> Bytes { ... }
fn try_encode_to_bytes(&self) -> Result<Bytes, EncodeError> { ... }
fn decode(buf: &mut impl Buf) -> Result<Self, DecodeError>
where Self: Sized { ... }
fn decode_from_slice(data: &[u8]) -> Result<Self, DecodeError>
where Self: Sized { ... }
fn decode_length_delimited(buf: &mut impl Buf) -> Result<Self, DecodeError>
where Self: Sized { ... }
fn merge_to_limit(
&mut self,
buf: &mut impl Buf,
ctx: DecodeContext<'_>,
limit: usize,
) -> Result<(), DecodeError> { ... }
fn merge_group(
&mut self,
buf: &mut impl Buf,
ctx: DecodeContext<'_>,
field_number: u32,
) -> Result<(), DecodeError> { ... }
fn merge(
&mut self,
buf: &mut impl Buf,
ctx: DecodeContext<'_>,
) -> Result<(), DecodeError> { ... }
fn merge_from_slice(&mut self, data: &[u8]) -> Result<(), DecodeError> { ... }
fn merge_length_delimited(
&mut self,
buf: &mut impl Buf,
ctx: DecodeContext<'_>,
) -> Result<(), DecodeError> { ... }
}Expand description
The core trait implemented by all protobuf message types.
This trait is implemented by generated code — you write a .proto file,
codegen emits the Rust struct and its Message impl. You should almost
never implement this trait by hand.
§Manual implementation is discouraged
The only reason to implement Message yourself is when you need a
custom in-memory representation that codegen cannot produce — for
example, wrapping a std::ops::Range<i64> as a leaf message so the
rest of your code uses the natural Rust type. If you just want a message
type, write a .proto file instead.
Manual implementation is intentionally high-friction:
- You must correctly implement the two-pass serialization contract
(
compute_sizepopulates theSizeCachein the same traversal order thatwrite_toconsumes it). - You must implement wire-format decoding in
merge_field. - You must implement the
DefaultInstancesupertrait, which provides the lazily-initialized static default thatMessageFielddereferences to when unset.
If you still need to do this, see the custom types section of the user guide for a complete worked example.
§Serialization model
Serialization is a two-pass process to avoid the exponential-time problem that affects prost with deeply nested messages:
compute_size()— walks the message tree and records the encoded size of every length-delimited sub-message in aSizeCache.write_to()— walks the tree again, writing bytes and consuming cached sizes for length-prefixed sub-messages.
The provided encode method performs both passes with a
fresh SizeCache — most callers use that and never touch the cache
directly. compute_size / write_to take the cache explicitly so that
manual Message implementations can thread it through nested-message
recursion.
§Thread safety
Message requires Send + Sync. Generated structs contain no interior
mutability — serialization state lives in the external SizeCache, not
in the message — so messages can be placed in an Arc and shared across
threads freely. merge requires &mut self, so mutation is exclusive.
§Struct evolution policy
Generated message structs (and their MessageView /
LazyMessageView counterparts) may gain fields
across releases — both when the source .proto schema evolves and when
buffa adds internal bookkeeping such as __buffa_unknown_fields or the
required-field presence bitmaps. Exhaustive struct literals and
exhaustive destructuring patterns are not covered by buffa’s semver
guarantees: code that names every field will fail to compile when a field
is added, and that breakage is not considered a breaking change.
The forward-compatible ways to construct a generated struct are:
- decode it from bytes;
- struct-update syntax over the default:
Foo { x, y, ..Default::default() }; - start from
Foo::default()and assign fields (or call generatedwith_*setters whengenerate_with_settersis enabled).
The structs are deliberately not #[non_exhaustive], so struct-update
syntax remains available from downstream crates; this policy is a documented
contract rather than a compiler-enforced one.
Required Methods§
Sourcefn compute_size(&self, cache: &mut SizeCache) -> u32
fn compute_size(&self, cache: &mut SizeCache) -> u32
Compute the encoded byte size of this message, recording nested
sub-message sizes in cache for write_to to consume.
Most callers should use encode instead, which runs
both passes with a fresh cache. Manual Message implementations call
this recursively on nested message fields, wrapping each call in
SizeCache::reserve / SizeCache::set for length-delimited
fields — see the user guide’s custom-types section for the pattern.
§Size limit
The protobuf specification limits messages to 2 GiB
(MAX_MESSAGE_BYTES). Generated implementations accumulate in
u64 and saturate the return value via saturate_size, so an
over-limit message yields a return greater than MAX_MESSAGE_BYTES
rather than a wrapped value; the provided encode methods check this
and refuse to produce over-limit output. Manual implementations must
follow the same pattern — if their arithmetic can wrap, over-limit
messages may encode corrupt bytes that bypass the check.
Sourcefn write_to(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink)
fn write_to(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink)
Write this message’s encoded bytes to a buffer, consuming
nested-message sizes from cache (populated by a prior
compute_size call on the same cache).
Most callers should use encode instead. This is a
low-level primitive: the 2 GiB size check (MAX_MESSAGE_BYTES)
lives in the provided encode entry points, so callers driving
compute_size / write_to directly must validate the size
themselves (via checked_encode_size).
An implementation must write exactly the number of bytes
compute_size returned. The provided encode methods write a
BufMut into space sized by compute_size and panic if write_to
writes more; in debug builds they also panic if it writes fewer.
Sourcefn merge_field(
&mut self,
tag: Tag,
buf: &mut impl Buf,
ctx: DecodeContext<'_>,
) -> Result<(), DecodeError>
fn merge_field( &mut self, tag: Tag, buf: &mut impl Buf, ctx: DecodeContext<'_>, ) -> Result<(), DecodeError>
Processes a single already-decoded tag and its associated field data
from buf.
This is the per-field dispatch method generated for each message type.
Both merge_to_limit and
merge_group call this in their respective loops.
ctx carries the remaining nesting depth and the shared allocation
budget.
§Errors
Returns a DecodeError if:
- the buffer is truncated or malformed,
- a wire-type mismatch is detected for a known field,
- the recursion limit is exceeded, or
- the allocation budget is exhausted.
Provided Methods§
Sourcefn encode(&self, buf: &mut impl EncodeSink)
fn encode(&self, buf: &mut impl EncodeSink)
Compute size, then write. This is the primary encoding API.
The sink can be any BufMut (contiguous output) or
a Rope, which captures large bytes::Bytes fields
as reference-counted segments for zero-copy handoff to networking
code — see encode_sink.
§Panics
Panics if the encoded size exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES) — see try_encode for
the error-returning variant.
Also panics, when buf is a BufMut, if a manual
implementation’s write_to produces more bytes than its
compute_size declared, and in debug builds if it produces a
different number.
Sourcefn try_encode(&self, buf: &mut impl EncodeSink) -> Result<(), EncodeError>
fn try_encode(&self, buf: &mut impl EncodeSink) -> Result<(), EncodeError>
Encode, returning an error instead of panicking if the encoded size
exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).
On Err, nothing is written to buf.
§Errors
Returns EncodeError::MessageTooLarge if the encoded size exceeds
MAX_MESSAGE_BYTES.
Sourcefn encode_with_cache(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink)
fn encode_with_cache(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink)
Encode using a caller-supplied SizeCache, for
reuse across many encodes in a hot loop. Clears the cache first.
§Panics
Panics if the encoded size exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES) — see
try_encode_with_cache for the
error-returning variant.
Also panics, when buf is a BufMut, if a manual
implementation’s write_to produces more bytes than its
compute_size declared, and in debug builds if it produces a
different number.
Sourcefn try_encode_with_cache(
&self,
cache: &mut SizeCache,
buf: &mut impl EncodeSink,
) -> Result<(), EncodeError>
fn try_encode_with_cache( &self, cache: &mut SizeCache, buf: &mut impl EncodeSink, ) -> Result<(), EncodeError>
Encode with a caller-supplied SizeCache,
returning an error instead of panicking if the encoded size exceeds
the 2 GiB protobuf limit (MAX_MESSAGE_BYTES). Clears the cache
first.
On Err, nothing is written to buf.
§Errors
Returns EncodeError::MessageTooLarge if the encoded size exceeds
MAX_MESSAGE_BYTES.
Sourcefn try_encode_bounded(
&self,
max_bytes: u32,
buf: &mut impl EncodeSink,
) -> Result<u32, EncodeError>
fn try_encode_bounded( &self, max_bytes: u32, buf: &mut impl EncodeSink, ) -> Result<u32, EncodeError>
Encode this message into buf only if its encoded size fits within
max_bytes, using a single size pass that is then reused for the write.
This avoids the double tree-walk that try_encoded_len + encode
would require: one compute_size pass populates the SizeCache;
the budget check happens before write_to runs, so on Err nothing
is written to buf.
Returns the encoded body length on success (excludes any length prefix
you add for framing) — useful for metrics or frame sizing. Note that
this return type is u32, unlike try_encode’s (). max_bytes is
also u32 to match the encode-size domain; callers with a usize
budget can cast with u32::try_from(budget).unwrap_or(u32::MAX).
§Errors
EncodeError::MessageTooLargeif the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).MessageTooLargetakes precedence if both limits are exceeded.EncodeError::ExceedsBudgetif the encoded size is within the protobuf limit but exceedsmax_bytes.
Sourcefn try_encode_bounded_with_cache(
&self,
max_bytes: u32,
cache: &mut SizeCache,
buf: &mut impl EncodeSink,
) -> Result<u32, EncodeError>
fn try_encode_bounded_with_cache( &self, max_bytes: u32, cache: &mut SizeCache, buf: &mut impl EncodeSink, ) -> Result<u32, EncodeError>
Like try_encode_bounded but reuses an
existing SizeCache, clearing it first.
Prefer SizeCachePool::try_encode_bounded
for hot-loop use — the pool amortizes the cache’s spill allocation.
§Errors
Same as try_encode_bounded.
Sourcefn encoded_len(&self) -> u32
fn encoded_len(&self) -> u32
Compute the encoded byte size of this message.
Walks the message tree, discarding the intermediate SizeCache.
If you also intend to encode, prefer encode or
encode_to_vec — they do a single size pass
and reuse the cache for the write.
§Panics
Panics if the encoded size exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES) — see try_encoded_len
for the error-returning variant.
Sourcefn try_encoded_len(&self) -> Result<u32, EncodeError>
fn try_encoded_len(&self) -> Result<u32, EncodeError>
Compute the encoded byte size, returning an error instead of
panicking if it exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES).
§Errors
Returns EncodeError::MessageTooLarge if the encoded size exceeds
MAX_MESSAGE_BYTES.
Sourcefn encode_length_delimited(&self, buf: &mut impl EncodeSink)
fn encode_length_delimited(&self, buf: &mut impl EncodeSink)
Encode this message as a length-delimited byte sequence.
§Panics
Panics if the encoded size exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES); the check runs before the length prefix is
written, so nothing reaches buf on failure. See
try_encode_length_delimited
for the error-returning variant.
Also panics, when buf is a BufMut, if a manual
implementation’s write_to produces more bytes than its
compute_size declared, and in debug builds if it produces a
different number.
Sourcefn try_encode_length_delimited(
&self,
buf: &mut impl EncodeSink,
) -> Result<(), EncodeError>
fn try_encode_length_delimited( &self, buf: &mut impl EncodeSink, ) -> Result<(), EncodeError>
Encode as a length-delimited byte sequence, returning an error
instead of panicking if the encoded size exceeds the 2 GiB protobuf
limit (MAX_MESSAGE_BYTES).
On Err, nothing is written to buf.
§Errors
Returns EncodeError::MessageTooLarge if the encoded size exceeds
MAX_MESSAGE_BYTES.
Sourcefn encode_to_vec(&self) -> Vec<u8> ⓘ
fn encode_to_vec(&self) -> Vec<u8> ⓘ
Encode this message to a new Vec<u8>.
§Panics
Panics if the encoded size exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES) — see
try_encode_to_vec for the
error-returning variant. Also panics if a manual
implementation’s write_to produces more bytes than its
compute_size declared, and in debug builds if it produces a
different number.
Sourcefn try_encode_to_vec(&self) -> Result<Vec<u8>, EncodeError>
fn try_encode_to_vec(&self) -> Result<Vec<u8>, EncodeError>
Encode to a new Vec<u8>, returning an error instead of panicking
if the encoded size exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES).
§Errors
Returns EncodeError::MessageTooLarge if the encoded size exceeds
MAX_MESSAGE_BYTES.
§Panics
Panics if a manual implementation’s write_to produces more
bytes than its compute_size declared, and in debug builds if it
produces a different number.
Sourcefn encode_to_bytes(&self) -> Bytes
fn encode_to_bytes(&self) -> Bytes
Encode this message to a new bytes::Bytes.
Useful when handing off to networking code (hyper, tonic, axum)
that expects Bytes frame or body payloads. Works in no_std.
This is Bytes::from(self.encode_to_vec()) — zero-copy and
allocation-free for the exactly-sized vector encode_to_vec returns —
and saves readers from having to know that From<Vec<u8>> for Bytes
is zero-copy. Because it is defined in terms of
encode_to_vec, an implementation that
overrides that method must not call this one from it.
§Panics
Panics if the encoded size exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES) — see
try_encode_to_bytes for the
error-returning variant. Also panics if a manual
implementation’s write_to produces more bytes than its
compute_size declared, and in debug builds if it produces a
different number.
Sourcefn try_encode_to_bytes(&self) -> Result<Bytes, EncodeError>
fn try_encode_to_bytes(&self) -> Result<Bytes, EncodeError>
Encode to a new bytes::Bytes, returning an error instead of
panicking if the encoded size exceeds the 2 GiB protobuf limit
(MAX_MESSAGE_BYTES).
§Errors
Returns EncodeError::MessageTooLarge if the encoded size exceeds
MAX_MESSAGE_BYTES.
§Panics
Panics if a manual implementation’s write_to produces more
bytes than its compute_size declared, and in debug builds if it
produces a different number.
Sourcefn decode(buf: &mut impl Buf) -> Result<Self, DecodeError>where
Self: Sized,
fn decode(buf: &mut impl Buf) -> Result<Self, DecodeError>where
Self: Sized,
Decode a message from a buffer.
Sourcefn decode_from_slice(data: &[u8]) -> Result<Self, DecodeError>where
Self: Sized,
fn decode_from_slice(data: &[u8]) -> Result<Self, DecodeError>where
Self: Sized,
Decode a message from a byte slice.
Convenience wrapper around decode that avoids the
&mut bytes.as_slice() incantation.
Sourcefn decode_length_delimited(buf: &mut impl Buf) -> Result<Self, DecodeError>where
Self: Sized,
fn decode_length_delimited(buf: &mut impl Buf) -> Result<Self, DecodeError>where
Self: Sized,
Decode a length-delimited message from a buffer.
This is a top-level entry point. It reads a varint length prefix,
then decodes using arithmetic bounds checking, calling
merge_to_limit with a fresh
RECURSION_LIMIT budget. Any sub-messages inside are decoded via
merge_length_delimited, which tracks
and decrements the budget.
Do not call this method from within a
merge_to_limit implementation to decode a
nested sub-message field; use
merge_length_delimited instead so
that the caller’s depth budget is propagated correctly.
Sourcefn merge_to_limit(
&mut self,
buf: &mut impl Buf,
ctx: DecodeContext<'_>,
limit: usize,
) -> Result<(), DecodeError>
fn merge_to_limit( &mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>, limit: usize, ) -> Result<(), DecodeError>
Merge fields from a buffer until buf.remaining() reaches limit.
This is the core decode loop. merge delegates to this
with limit = 0 (read until exhausted).
merge_length_delimited computes
limit from the declared sub-message length and calls this directly.
The caller must ensure limit <= buf.remaining(). The default
implementations of merge and
merge_length_delimited uphold this
invariant.
ctx carries the remaining nesting depth and the shared allocation
budget. Each call to
merge_length_delimited consumes one
depth level before recursing; when the depth reaches zero the call
returns DecodeError::RecursionLimitExceeded.
Sourcefn merge_group(
&mut self,
buf: &mut impl Buf,
ctx: DecodeContext<'_>,
field_number: u32,
) -> Result<(), DecodeError>
fn merge_group( &mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>, field_number: u32, ) -> Result<(), DecodeError>
Merges a group-encoded message from buf, reading fields until an
EndGroup tag with the given field_number is encountered.
Proto2 groups use StartGroup/EndGroup wire types instead of length-delimited encoding. The opening StartGroup tag has already been consumed by the caller; this method reads the group body and the closing EndGroup tag.
§Errors
Returns a DecodeError if:
- the buffer is truncated before the EndGroup tag,
- an EndGroup tag is encountered with a mismatched field number,
- a wire-type mismatch is detected for a known field, or
- the recursion limit is exceeded.
Sourcefn merge(
&mut self,
buf: &mut impl Buf,
ctx: DecodeContext<'_>,
) -> Result<(), DecodeError>
fn merge( &mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>, ) -> Result<(), DecodeError>
Merge fields from a buffer into this message.
Fields that are already set will be overwritten for singular fields, or appended for repeated fields, following standard protobuf merge semantics.
ctx carries the remaining nesting depth and the shared allocation
budget. Each call to
merge_length_delimited consumes one
depth level before recursing; when the depth reaches zero the call
returns DecodeError::RecursionLimitExceeded. Construct a fresh
DecodeContext at the outermost call site, or use the convenience
methods (decode,
merge_from_slice) which do this
automatically.
Sourcefn merge_from_slice(&mut self, data: &[u8]) -> Result<(), DecodeError>
fn merge_from_slice(&mut self, data: &[u8]) -> Result<(), DecodeError>
Merge fields from a byte slice into this message.
Convenience wrapper around merge that avoids the
&mut bytes.as_slice() incantation.
Sourcefn merge_length_delimited(
&mut self,
buf: &mut impl Buf,
ctx: DecodeContext<'_>,
) -> Result<(), DecodeError>
fn merge_length_delimited( &mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>, ) -> Result<(), DecodeError>
Merge fields from a length-delimited sub-message payload into this message.
Reads a varint length prefix, then calls merge_to_limit
with an arithmetic bound derived from the declared sub-message length.
The buffer type B passes through unchanged at every recursion level,
avoiding the E0275 trait-solver recursion limit that occurs with
Take<&mut Take<&mut T>> type growth.
Used by generated code when decoding singular MessageField<T> fields
— the sub-message is merged into the existing value rather than
replaced, per protobuf merge semantics.
ctx carries the remaining nesting depth and the shared allocation
budget passed down from the enclosing
merge_to_limit call. This method consumes
one depth level before calling the inner merge_to_limit; when the
depth reaches zero it returns
DecodeError::RecursionLimitExceeded.
Enforces the same 2 GiB safety limit as decode_length_delimited.
§Errors
Returns an error if the buffer is too short, if the declared length
exceeds 2 GiB, if the recursion limit is reached, or if the inner
merge_to_limit call fails.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".