Skip to main content

buffa/
error.rs

1// Modified by ReallyMe Technologies Limited.
2//! Error types for buffa encoding and decoding operations.
3
4/// An error that occurred while decoding a protobuf message.
5#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
6#[non_exhaustive]
7pub enum DecodeError {
8    /// The buffer ended before a complete value could be read.
9    #[error("unexpected end of buffer")]
10    UnexpectedEof,
11
12    /// A varint exceeded the maximum encoded length of 10 bytes.
13    #[error("varint exceeded maximum length of 10 bytes")]
14    VarintTooLong,
15
16    /// The wire type in a tag was not a recognised protobuf wire type.
17    ///
18    /// Carries the raw 3-bit value from the tag for diagnostic purposes.
19    #[error("invalid wire type: {0}")]
20    InvalidWireType(u32),
21
22    /// The field number decoded from a tag was zero, or the tag varint
23    /// overflowed a `u32` — both indicate a malformed message.
24    #[error("invalid field number")]
25    InvalidFieldNumber,
26
27    /// The message or sub-message length exceeded the size limit.
28    ///
29    /// By default, the limit is the 2 GiB protobuf maximum. Use
30    /// [`DecodeOptions::with_max_message_size`](crate::DecodeOptions::with_max_message_size)
31    /// to set a lower limit for untrusted input. Fallible re-encode paths
32    /// ([`OwnedView::from_owned`](crate::view::OwnedView::from_owned)) also
33    /// surface an over-limit *encode* through this variant, mirroring
34    /// [`EncodeError::MessageTooLarge`].
35    #[error("message length exceeds the size limit (2 GiB protobuf maximum, or a configured DecodeOptions limit)")]
36    MessageTooLarge,
37
38    /// The wire type of an incoming field did not match the type expected for
39    /// that field number.
40    ///
41    /// Carries the field number and the raw wire type values (as `u8` to keep
42    /// this type independent of the encoding module).
43    #[error("wire type mismatch on field {field_number}: expected {expected}, got {actual}")]
44    WireTypeMismatch {
45        field_number: u32,
46        expected: u8,
47        actual: u8,
48    },
49
50    /// A `string` field contained bytes that are not valid UTF-8.
51    #[error("invalid UTF-8 in string field")]
52    InvalidUtf8,
53
54    /// The message nesting depth exceeded the recursion limit.
55    #[error("recursion limit exceeded")]
56    RecursionLimitExceeded,
57
58    /// An EndGroup tag was encountered with a field number that does not match
59    /// the opening StartGroup tag, or an EndGroup was seen outside of a group.
60    #[error("invalid end-group tag: field number {0}")]
61    InvalidEndGroup(u32),
62
63    /// A MessageSet `Item` group was malformed (missing or out-of-range
64    /// `type_id`). Only occurs for messages declared with
65    /// `option message_set_wire_format = true`.
66    #[error("invalid MessageSet item: {0}")]
67    InvalidMessageSet(&'static str),
68
69    /// Decoding encountered more unknown fields than the configured limit.
70    ///
71    /// Unknown fields can be far smaller on the wire than in memory (a
72    /// 2-byte varint field occupies ~40 bytes as an
73    /// [`UnknownField`](crate::UnknownField)), so the decoder bounds how
74    /// many records it materializes rather than trusting the input size. A
75    /// zero limit additionally rejects discarded unknown occurrences. By
76    /// default the limit is
77    /// [`DEFAULT_UNKNOWN_FIELD_LIMIT`](crate::DEFAULT_UNKNOWN_FIELD_LIMIT)
78    /// (1,000,000 fields per decode); use
79    /// [`DecodeOptions::with_unknown_field_limit`](crate::DecodeOptions::with_unknown_field_limit)
80    /// to raise it for trusted inputs that legitimately carry very many
81    /// unknown fields.
82    #[error("unknown field limit exceeded")]
83    UnknownFieldLimitExceeded,
84
85    /// A decode would materialize more memory in the elements of
86    /// length-delimited containers — repeated message, string and bytes fields,
87    /// and map entries — than its budget allows.
88    ///
89    /// These elements cost far more decoded than encoded: an empty message
90    /// element is two bytes on the wire and `size_of::<T>()` in the `Vec` it
91    /// lands in, so a payload well inside
92    /// [`DecodeOptions::with_max_message_size`](crate::DecodeOptions::with_max_message_size)
93    /// can still expand by two orders of magnitude. By default the budget is
94    /// [`DEFAULT_ELEMENT_MEMORY_LIMIT`](crate::DEFAULT_ELEMENT_MEMORY_LIMIT)
95    /// (32 MiB per decode); use
96    /// [`DecodeOptions::with_element_memory_limit`](crate::DecodeOptions::with_element_memory_limit)
97    /// to raise it for trusted inputs that legitimately decode into more.
98    #[error("element memory limit exceeded")]
99    ElementMemoryLimitExceeded,
100
101    /// A custom `string`/`bytes` representation rejected the decoded payload in
102    /// its [`from_wire`](crate::ProtoString::from_wire) constructor — for
103    /// example a length or domain check beyond UTF-8 validation. Carries a
104    /// static reason for diagnostics (mirroring [`InvalidMessageSet`]).
105    ///
106    /// Only produced by user-supplied [`ProtoString`](crate::ProtoString) /
107    /// [`ProtoBytes`](crate::ProtoBytes) impls; the built-in representations
108    /// never return it.
109    ///
110    /// [`InvalidMessageSet`]: DecodeError::InvalidMessageSet
111    #[error("custom representation rejected the field value: {0}")]
112    Custom(&'static str),
113}
114
115/// An error that occurred while encoding a protobuf message.
116///
117/// Returned by the `try_encode*` family
118/// ([`Message::try_encode`](crate::Message::try_encode) and friends). The
119/// panicking entry points ([`Message::encode`](crate::Message::encode) and
120/// friends) raise the same conditions as panics instead.
121///
122/// The enum is `#[non_exhaustive]`: further variants may be added without a
123/// breaking change to the type name.
124#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
125#[non_exhaustive]
126pub enum EncodeError {
127    /// The message's encoded size exceeds the 2 GiB protobuf limit
128    /// ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)).
129    ///
130    /// Encoding such a message would produce bytes that no conforming
131    /// protobuf decoder — including buffa's own, which returns the mirror
132    /// error [`DecodeError::MessageTooLarge`] — will accept. Shrink or
133    /// split the message instead.
134    #[error("message encoded size exceeds the 2 GiB protobuf limit")]
135    MessageTooLarge,
136
137    /// The message's encoded size exceeds the caller-supplied budget passed
138    /// to a `try_encode_bounded*` entry point. The message is within the
139    /// 2 GiB protobuf limit and could be encoded with a larger budget.
140    ///
141    /// `len` is the exact encoded size (in bytes); `max_bytes` is the budget
142    /// that was exceeded.
143    #[error("message encoded size {len} exceeds the caller budget of {max_bytes} bytes")]
144    ExceedsBudget {
145        /// The exact encoded size of the message in bytes.
146        len: u32,
147        /// The caller-supplied budget that was exceeded.
148        max_bytes: u32,
149    },
150}