miniz_oxide/inflate/
mod.rs

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

miniz_oxide/inflate/
mod.rs
