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