1//! This module contains functionality for decompression.
2
3#[cfg(feature = "with-alloc")]
4use crate::alloc::{boxed::Box, vec, vec::Vec};
5use ::core::usize;
6#[cfg(all(feature = "std", feature = "with-alloc"))]
7use std::error::Error;
8
9pub mod core;
10mod output_buffer;
11pub mod stream;
12use self::core::*;
13
14const TINFL_STATUS_FAILED_CANNOT_MAKE_PROGRESS: i32 = -4;
15const TINFL_STATUS_BAD_PARAM: i32 = -3;
16const TINFL_STATUS_ADLER32_MISMATCH: i32 = -2;
17const TINFL_STATUS_FAILED: i32 = -1;
18const TINFL_STATUS_DONE: i32 = 0;
19const TINFL_STATUS_NEEDS_MORE_INPUT: i32 = 1;
20const TINFL_STATUS_HAS_MORE_OUTPUT: i32 = 2;
21
22/// Return status codes.
23#[repr(i8)]
24#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
25pub enum TINFLStatus {
26 /// More input data was expected, but the caller indicated that there was no more data, so the
27 /// input stream is likely truncated.
28 ///
29 /// This can't happen if you have provided the
30 /// [`TINFL_FLAG_HAS_MORE_INPUT`][core::inflate_flags::TINFL_FLAG_HAS_MORE_INPUT] flag to the
31 /// decompression. By setting that flag, you indicate more input exists but is not provided,
32 /// and so reaching the end of the input data without finding the end of the compressed stream
33 /// would instead return a [`NeedsMoreInput`][Self::NeedsMoreInput] status.
34 FailedCannotMakeProgress = TINFL_STATUS_FAILED_CANNOT_MAKE_PROGRESS as i8,
35
36 /// The output buffer is an invalid size; consider the `flags` parameter.
37 BadParam = TINFL_STATUS_BAD_PARAM as i8,
38
39 /// The decompression went fine, but the adler32 checksum did not match the one
40 /// provided in the header.
41 Adler32Mismatch = TINFL_STATUS_ADLER32_MISMATCH as i8,
42
43 /// Failed to decompress due to invalid data.
44 Failed = TINFL_STATUS_FAILED as i8,
45
46 /// Finished decompression without issues.
47 ///
48 /// This indicates the end of the compressed stream has been reached.
49 Done = TINFL_STATUS_DONE as i8,
50
51 /// The decompressor needs more input data to continue decompressing.
52 ///
53 /// This occurs when there's no more consumable input, but the end of the stream hasn't been
54 /// reached, and you have supplied the
55 /// [`TINFL_FLAG_HAS_MORE_INPUT`][core::inflate_flags::TINFL_FLAG_HAS_MORE_INPUT] flag to the
56 /// decompressor. Had you not supplied that flag (which would mean you were asserting that you
57 /// believed all the data was available) you would have gotten a
58 /// [`FailedCannotMakeProcess`][Self::FailedCannotMakeProgress] instead.
59 NeedsMoreInput = TINFL_STATUS_NEEDS_MORE_INPUT as i8,
60
61 /// There is still pending data that didn't fit in the output buffer.
62 HasMoreOutput = TINFL_STATUS_HAS_MORE_OUTPUT as i8,
63}
64
65impl TINFLStatus {
66 pub fn from_i32(value: i32) -> Option<TINFLStatus> {
67 use self::TINFLStatus::*;
68 match value {
69 TINFL_STATUS_FAILED_CANNOT_MAKE_PROGRESS => Some(FailedCannotMakeProgress),
70 TINFL_STATUS_BAD_PARAM => Some(BadParam),
71 TINFL_STATUS_ADLER32_MISMATCH => Some(Adler32Mismatch),
72 TINFL_STATUS_FAILED => Some(Failed),
73 TINFL_STATUS_DONE => Some(Done),
74 TINFL_STATUS_NEEDS_MORE_INPUT => Some(NeedsMoreInput),
75 TINFL_STATUS_HAS_MORE_OUTPUT => Some(HasMoreOutput),
76 _ => None,
77 }
78 }
79}
80
81/// Struct return when decompress_to_vec functions fail.
82#[cfg(feature = "with-alloc")]
83#[derive(Debug)]
84pub struct DecompressError {
85 /// Decompressor status on failure. See [TINFLStatus] for details.
86 pub status: TINFLStatus,
87 /// The currently decompressed data if any.
88 pub output: Vec<u8>,
89}
90
91#[cfg(feature = "with-alloc")]
92impl alloc::fmt::Display for DecompressError {
93 fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
94 f.write_str(data:match self.status {
95 TINFLStatus::FailedCannotMakeProgress => "Truncated input stream",
96 TINFLStatus::BadParam => "Invalid output buffer size",
97 TINFLStatus::Adler32Mismatch => "Adler32 checksum mismatch",
98 TINFLStatus::Failed => "Invalid input data",
99 TINFLStatus::Done => unreachable!(),
100 TINFLStatus::NeedsMoreInput => "Truncated input stream",
101 TINFLStatus::HasMoreOutput => "Output size exceeded the specified limit",
102 })
103 }
104}
105
106/// Implement Error trait only if std feature is requested as it requires std.
107#[cfg(all(feature = "std", feature = "with-alloc"))]
108impl Error for DecompressError {}
109
110#[cfg(feature = "with-alloc")]
111fn decompress_error(status: TINFLStatus, output: Vec<u8>) -> Result<Vec<u8>, DecompressError> {
112 Err(DecompressError { status, output })
113}
114
115/// Decompress the deflate-encoded data in `input` to a vector.
116///
117/// NOTE: This function will not bound the output, so if the output is large enough it can result in an out of memory error.
118/// It is therefore suggested to not use this for anything other than test programs, use the functions with a specified limit, or
119/// ideally streaming decompression via the [flate2](https://github.com/alexcrichton/flate2-rs) library instead.
120///
121/// Returns a [`Result`] containing the [`Vec`] of decompressed data on success, and a [struct][DecompressError] containing the status and so far decompressed data if any on failure.
122#[inline]
123#[cfg(feature = "with-alloc")]
124pub fn decompress_to_vec(input: &[u8]) -> Result<Vec<u8>, DecompressError> {
125 decompress_to_vec_inner(input, flags:0, max_output_size:usize::max_value())
126}
127
128/// Decompress the deflate-encoded data (with a zlib wrapper) in `input` to a vector.
129///
130/// NOTE: This function will not bound the output, so if the output is large enough it can result in an out of memory error.
131/// It is therefore suggested to not use this for anything other than test programs, use the functions with a specified limit, or
132/// ideally streaming decompression via the [flate2](https://github.com/alexcrichton/flate2-rs) library instead.
133///
134/// Returns a [`Result`] containing the [`Vec`] of decompressed data on success, and a [struct][DecompressError] containing the status and so far decompressed data if any on failure.
135#[inline]
136#[cfg(feature = "with-alloc")]
137pub fn decompress_to_vec_zlib(input: &[u8]) -> Result<Vec<u8>, DecompressError> {
138 decompress_to_vec_inner(
139 input,
140 flags:inflate_flags::TINFL_FLAG_PARSE_ZLIB_HEADER,
141 max_output_size:usize::max_value(),
142 )
143}
144
145/// Decompress the deflate-encoded data in `input` to a vector.
146///
147/// The vector is grown to at most `max_size` bytes; if the data does not fit in that size,
148/// the error [struct][DecompressError] will contain the status [`TINFLStatus::HasMoreOutput`] and the data that was decompressed on failure.
149///
150/// As this function tries to decompress everything in one go, it's not ideal for general use outside of tests or where the output size is expected to be small.
151/// It is suggested to use streaming decompression via the [flate2](https://github.com/alexcrichton/flate2-rs) library instead.
152///
153/// Returns a [`Result`] containing the [`Vec`] of decompressed data on success, and a [struct][DecompressError] on failure.
154#[inline]
155#[cfg(feature = "with-alloc")]
156pub fn decompress_to_vec_with_limit(
157 input: &[u8],
158 max_size: usize,
159) -> Result<Vec<u8>, DecompressError> {
160 decompress_to_vec_inner(input, flags:0, max_output_size:max_size)
161}
162
163/// Decompress the deflate-encoded data (with a zlib wrapper) in `input` to a vector.
164/// The vector is grown to at most `max_size` bytes; if the data does not fit in that size,
165/// the error [struct][DecompressError] will contain the status [`TINFLStatus::HasMoreOutput`] and the data that was decompressed on failure.
166///
167/// As this function tries to decompress everything in one go, it's not ideal for general use outside of tests or where the output size is expected to be small.
168/// It is suggested to use streaming decompression via the [flate2](https://github.com/alexcrichton/flate2-rs) library instead.
169///
170/// Returns a [`Result`] containing the [`Vec`] of decompressed data on success, and a [struct][DecompressError] on failure.
171#[inline]
172#[cfg(feature = "with-alloc")]
173pub fn decompress_to_vec_zlib_with_limit(
174 input: &[u8],
175 max_size: usize,
176) -> Result<Vec<u8>, DecompressError> {
177 decompress_to_vec_inner(input, flags:inflate_flags::TINFL_FLAG_PARSE_ZLIB_HEADER, max_output_size:max_size)
178}
179
180/// Backend of various to-[`Vec`] decompressions.
181///
182/// Returns [`Vec`] of decompressed data on success and the [error struct][DecompressError] with details on failure.
183#[cfg(feature = "with-alloc")]
184fn decompress_to_vec_inner(
185 input: &[u8],
186 flags: u32,
187 max_output_size: usize,
188) -> Result<Vec<u8>, DecompressError> {
189 let flags = flags | inflate_flags::TINFL_FLAG_USING_NON_WRAPPING_OUTPUT_BUF;
190 let mut ret: Vec<u8> = vec![0; input.len().saturating_mul(2).min(max_output_size)];
191
192 let mut decomp = Box::<DecompressorOxide>::default();
193
194 let mut in_pos = 0;
195 let mut out_pos = 0;
196 loop {
197 // Wrap the whole output slice so we know we have enough of the
198 // decompressed data for matches.
199 let (status, in_consumed, out_consumed) =
200 decompress(&mut decomp, &input[in_pos..], &mut ret, out_pos, flags);
201 in_pos += in_consumed;
202 out_pos += out_consumed;
203
204 match status {
205 TINFLStatus::Done => {
206 ret.truncate(out_pos);
207 return Ok(ret);
208 }
209
210 TINFLStatus::HasMoreOutput => {
211 // if the buffer has already reached the size limit, return an error
212 if ret.len() >= max_output_size {
213 return decompress_error(TINFLStatus::HasMoreOutput, ret);
214 }
215 // calculate the new length, capped at `max_output_size`
216 let new_len = ret.len().saturating_mul(2).min(max_output_size);
217 ret.resize(new_len, 0);
218 }
219
220 _ => return decompress_error(status, ret),
221 }
222 }
223}
224
225/// Decompress one or more source slices from an iterator into the output slice.
226///
227/// * On success, returns the number of bytes that were written.
228/// * On failure, returns the failure status code.
229///
230/// This will fail if the output buffer is not large enough, but in that case
231/// the output buffer will still contain the partial decompression.
232///
233/// * `out` the output buffer.
234/// * `it` the iterator of input slices.
235/// * `zlib_header` if the first slice out of the iterator is expected to have a
236/// Zlib header. Otherwise the slices are assumed to be the deflate data only.
237/// * `ignore_adler32` if the adler32 checksum should be calculated or not.
238pub fn decompress_slice_iter_to_slice<'out, 'inp>(
239 out: &'out mut [u8],
240 it: impl Iterator<Item = &'inp [u8]>,
241 zlib_header: bool,
242 ignore_adler32: bool,
243) -> Result<usize, TINFLStatus> {
244 use self::core::inflate_flags::*;
245
246 let mut it = it.peekable();
247 let r = &mut DecompressorOxide::new();
248 let mut out_pos = 0;
249 while let Some(in_buf) = it.next() {
250 let has_more = it.peek().is_some();
251 let flags = {
252 let mut f = TINFL_FLAG_USING_NON_WRAPPING_OUTPUT_BUF;
253 if zlib_header {
254 f |= TINFL_FLAG_PARSE_ZLIB_HEADER;
255 }
256 if ignore_adler32 {
257 f |= TINFL_FLAG_IGNORE_ADLER32;
258 }
259 if has_more {
260 f |= TINFL_FLAG_HAS_MORE_INPUT;
261 }
262 f
263 };
264 let (status, _input_read, bytes_written) = decompress(r, in_buf, out, out_pos, flags);
265 out_pos += bytes_written;
266 match status {
267 TINFLStatus::NeedsMoreInput => continue,
268 TINFLStatus::Done => return Ok(out_pos),
269 e => return Err(e),
270 }
271 }
272 // If we ran out of source slices without getting a `Done` from the
273 // decompression we can call it a failure.
274 Err(TINFLStatus::FailedCannotMakeProgress)
275}
276
277#[cfg(test)]
278mod test {
279 use super::{
280 decompress_slice_iter_to_slice, decompress_to_vec_zlib, decompress_to_vec_zlib_with_limit,
281 DecompressError, TINFLStatus,
282 };
283 const ENCODED: [u8; 20] = [
284 120, 156, 243, 72, 205, 201, 201, 215, 81, 168, 202, 201, 76, 82, 4, 0, 27, 101, 4, 19,
285 ];
286
287 #[test]
288 fn decompress_vec() {
289 let res = decompress_to_vec_zlib(&ENCODED[..]).unwrap();
290 assert_eq!(res.as_slice(), &b"Hello, zlib!"[..]);
291 }
292
293 #[test]
294 fn decompress_vec_with_high_limit() {
295 let res = decompress_to_vec_zlib_with_limit(&ENCODED[..], 100_000).unwrap();
296 assert_eq!(res.as_slice(), &b"Hello, zlib!"[..]);
297 }
298
299 #[test]
300 fn fail_to_decompress_with_limit() {
301 let res = decompress_to_vec_zlib_with_limit(&ENCODED[..], 8);
302 match res {
303 Err(DecompressError {
304 status: TINFLStatus::HasMoreOutput,
305 ..
306 }) => (), // expected result
307 _ => panic!("Decompression output size limit was not enforced"),
308 }
309 }
310
311 #[test]
312 fn test_decompress_slice_iter_to_slice() {
313 // one slice
314 let mut out = [0_u8; 12_usize];
315 let r =
316 decompress_slice_iter_to_slice(&mut out, Some(&ENCODED[..]).into_iter(), true, false);
317 assert_eq!(r, Ok(12));
318 assert_eq!(&out[..12], &b"Hello, zlib!"[..]);
319
320 // some chunks at a time
321 for chunk_size in 1..13 {
322 // Note: because of https://github.com/Frommi/miniz_oxide/issues/110 our
323 // out buffer needs to have +1 byte available when the chunk size cuts
324 // the adler32 data off from the last actual data.
325 let mut out = [0_u8; 12_usize + 1];
326 let r =
327 decompress_slice_iter_to_slice(&mut out, ENCODED.chunks(chunk_size), true, false);
328 assert_eq!(r, Ok(12));
329 assert_eq!(&out[..12], &b"Hello, zlib!"[..]);
330 }
331
332 // output buffer too small
333 let mut out = [0_u8; 3_usize];
334 let r = decompress_slice_iter_to_slice(&mut out, ENCODED.chunks(7), true, false);
335 assert!(r.is_err());
336 }
337}
338