Skip to main content

Message

Trait Message 

Source
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_size populates the SizeCache in the same traversal order that write_to consumes it).
  • You must implement wire-format decoding in merge_field.
  • You must implement the DefaultInstance supertrait, which provides the lazily-initialized static default that MessageField dereferences 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:

  1. compute_size() — walks the message tree and records the encoded size of every length-delimited sub-message in a SizeCache.
  2. 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 generated with_* setters when generate_with_setters is 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§

Source

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.

Source

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.

Source

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

fn clear(&mut self)

Clear all fields to their default values.

Provided Methods§

Source

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.

Source

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.

Source

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.

Source

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.

Source

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
Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

fn decode(buf: &mut impl Buf) -> Result<Self, DecodeError>
where Self: Sized,

Decode a message from a buffer.

Source

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.

Source

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.

Source

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.

Source

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

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.

Source

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.

Source

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

Implementors§