1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
use core::fmt;
/// All errors reported by encoder, decoder, and dictionary paths.
///
/// Most variants represent malformed input or violated configuration limits;
/// the message attached to [`Error::Corruption`] and [`Error::InvalidParameter`]
/// gives a short human-readable cause.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum Error {
/// Catch-all for internal invariants that should not be reachable on valid input.
Generic,
/// Caller-supplied configuration was rejected; the message names the offending parameter.
InvalidParameter(&'static str),
/// A destination buffer was too small to hold the requested output.
DstSizeTooSmall,
/// The size of a source buffer disagrees with what the format encodes.
SrcSizeWrong,
/// Input ended before the next required byte.
UnexpectedEof,
/// A frame header started with an unrecognized magic number; carries the bytes seen.
BadMagic(u32),
/// Input bytes violated the Zstandard format; the message names the violation.
Corruption(&'static str),
/// An entropy table declared a `tableLog` larger than the format permits.
TableLogTooLarge,
/// An entropy table declared a maximum symbol value larger than the format permits.
MaxSymbolValueTooLarge,
/// An entropy table declared a maximum symbol value smaller than the format permits.
MaxSymbolValueTooSmall,
/// A scratch workspace was too small for the operation requested.
WorkSpaceTooSmall,
/// A frame's window size exceeded the limit configured on `DecoderOptions::max_window_size`.
WindowSizeTooLarge {
/// Window size declared by the frame header.
window_size: u64,
/// Limit currently configured on the decoder.
max_window_size: u64,
},
/// A frame requires a dictionary but none was supplied; carries the requested id when present.
DictionaryRequired(Option<u32>),
/// The supplied dictionary id does not match the frame's declared id.
DictionaryMismatch {
/// Dictionary id declared by the frame.
expected: u32,
/// Dictionary id of the dictionary the caller provided.
actual: u32,
},
/// Decoded output would exceed the limit configured on `DecoderOptions::max_output_size`.
OutputSizeTooLarge {
/// Total output size that would result from accepting the next chunk.
output_size: u64,
/// Limit currently configured on the decoder.
max_output_size: usize,
},
/// A frame's declared content size cannot be represented as a `usize` on this platform.
ContentSizeTooLarge(u64),
/// A running output-size counter overflowed `u64` or `usize`.
OutputSizeOverflow,
/// Decoded output size disagreed with the frame header's declared content size.
ContentSizeMismatch {
/// Content size declared by the frame header.
expected: u64,
/// Content size actually produced by decoding.
actual: u64,
},
/// The input was not exactly one Zstandard frame, and
/// [`DecoderOptions::single_frame`](crate::DecoderOptions::single_frame)
/// required that it be.
///
/// Raised for a second frame, a skippable frame, or bytes after the first
/// frame's end. A payload carried inside another protocol has a length its
/// framing already agreed on, so extra bytes there are not a second
/// message: they are evidence that the length was wrong.
TrailingInput {
/// Byte offset at which the unexpected input begins. Zero when the
/// input opens with a skippable frame, which this mode rejects rather
/// than passing over.
offset: usize,
},
/// The frame trailer's content checksum did not match the recomputed XXH64 truncated to 32 bits.
ChecksumMismatch {
/// Checksum bytes read from the frame trailer.
expected: u32,
/// Checksum recomputed over the decoded output.
actual: u32,
},
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Error::Generic => f.write_str("generic error"),
Error::InvalidParameter(parameter) => write!(f, "invalid parameter: {parameter}"),
Error::DstSizeTooSmall => f.write_str("destination buffer too small"),
Error::SrcSizeWrong => f.write_str("source size is invalid"),
Error::UnexpectedEof => f.write_str("unexpected end of input"),
Error::BadMagic(magic) => write!(f, "invalid frame magic number 0x{magic:08x}"),
Error::Corruption(message) => write!(f, "corruption detected: {message}"),
Error::TableLogTooLarge => f.write_str("table log too large"),
Error::MaxSymbolValueTooLarge => f.write_str("maximum symbol value too large"),
Error::MaxSymbolValueTooSmall => f.write_str("maximum symbol value too small"),
Error::WorkSpaceTooSmall => f.write_str("workspace too small"),
Error::WindowSizeTooLarge {
window_size,
max_window_size,
} => write!(
f,
"frame window size {window_size} exceeds configured limit {max_window_size}"
),
Error::DictionaryRequired(Some(dictionary_id)) => {
write!(f, "frame requires dictionary id {dictionary_id}")
}
Error::DictionaryRequired(None) => f.write_str("frame requires a dictionary"),
Error::DictionaryMismatch { expected, actual } => write!(
f,
"dictionary mismatch: frame requires id {expected}, got {actual}"
),
Error::OutputSizeTooLarge {
output_size,
max_output_size,
} => write!(
f,
"decoded output size {output_size} exceeds configured limit {max_output_size}"
),
Error::ContentSizeTooLarge(content_size) => {
write!(f, "frame content size {content_size} exceeds this platform")
}
Error::OutputSizeOverflow => {
f.write_str("decoded output size overflowed this platform")
}
Error::ContentSizeMismatch { expected, actual } => {
write!(
f,
"frame content size mismatch: expected {expected}, got {actual}"
)
}
Error::TrailingInput { offset } => write!(
f,
"input is not a single Zstandard frame: unexpected input at byte {offset}"
),
Error::ChecksumMismatch { expected, actual } => write!(
f,
"content checksum mismatch: expected 0x{expected:08x}, got 0x{actual:08x}"
),
}
}
}
impl std::error::Error for Error {}
/// Convenience alias for `core::result::Result<T, Error>` used throughout the crate.
pub type Result<T> = core::result::Result<T, Error>;