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 #[cold]
94 fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
95 f.write_str(data:match self.status {
96 TINFLStatus::FailedCannotMakeProgress => "Truncated input stream",
97 TINFLStatus::BadParam => "Invalid output buffer size",
98 TINFLStatus::Adler32Mismatch => "Adler32 checksum mismatch",
99 TINFLStatus::Failed => "Invalid input data",
100 TINFLStatus::Done => "", // Unreachable
101 TINFLStatus::NeedsMoreInput => "Truncated input stream",
102 TINFLStatus::HasMoreOutput => "Output size exceeded the specified limit",
103 })
104 }
105}
106
107/// Implement Error trait only if std feature is requested as it requires std.
108#[cfg(all(feature = "std", feature = "with-alloc"))]
109impl Error for DecompressError {}
110
111#[cfg(feature = "with-alloc")]
112fn decompress_error(status: TINFLStatus, output: Vec<u8>) -> Result<Vec<u8>, DecompressError> {
113 Err(DecompressError { status, output })
114}
115
116/// Decompress the deflate-encoded data in `input` to a vector.
117///
118/// NOTE: This function will not bound the output, so if the output is large enough it can result in an out of memory error.
119/// It is therefore suggested to not use this for anything other than test programs, use the functions with a specified limit, or
120/// ideally streaming decompression via the [flate2](https://github.com/alexcrichton/flate2-rs) library instead.
121///
122/// 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.
123#[inline]
124#[cfg(feature = "with-alloc")]
125pub fn decompress_to_vec(input: &[u8]) -> Result<Vec<u8>, DecompressError> {
126 decompress_to_vec_inner(input, flags:0, max_output_size:usize::max_value())
127}
128
129/// Decompress the deflate-encoded data (with a zlib wrapper) in `input` to a vector.
130///
131/// NOTE: This function will not bound the output, so if the output is large enough it can result in an out of memory error.
132/// It is therefore suggested to not use this for anything other than test programs, use the functions with a specified limit, or
133/// ideally streaming decompression via the [flate2](https://github.com/alexcrichton/flate2-rs) library instead.
134///
135/// 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.
136#[inline]
137#[cfg(feature = "with-alloc")]
138pub fn decompress_to_vec_zlib(input: &[u8]) -> Result<Vec<u8>, DecompressError> {
139 decompress_to_vec_inner(
140 input,
141 flags:inflate_flags::TINFL_FLAG_PARSE_ZLIB_HEADER,
142 max_output_size:usize::max_value(),
143 )
144}
145
146/// Decompress the deflate-encoded data in `input` to a vector.
147///
148/// The vector is grown to at most `max_size` bytes; if the data does not fit in that size,
149/// the error [struct][DecompressError] will contain the status [`TINFLStatus::HasMoreOutput`] and the data that was decompressed on failure.
150///
151/// 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.
152/// It is suggested to use streaming decompression via the [flate2](https://github.com/alexcrichton/flate2-rs) library instead.
153///
154/// Returns a [`Result`] containing the [`Vec`] of decompressed data on success, and a [struct][DecompressError] on failure.
155#[inline]
156#[cfg(feature = "with-alloc")]
157pub fn decompress_to_vec_with_limit(
158 input: &[u8],
159 max_size: usize,
160) -> Result<Vec<u8>, DecompressError> {
161 decompress_to_vec_inner(input, flags:0, max_output_size:max_size)
162}
163
164/// Decompress the deflate-encoded data (with a zlib wrapper) in `input` to a vector.
165/// The vector is grown to at most `max_size` bytes; if the data does not fit in that size,
166/// the error [struct][DecompressError] will contain the status [`TINFLStatus::HasMoreOutput`] and the data that was decompressed on failure.
167///
168/// 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.
169/// It is suggested to use streaming decompression via the [flate2](https://github.com/alexcrichton/flate2-rs) library instead.
170///
171/// Returns a [`Result`] containing the [`Vec`] of decompressed data on success, and a [struct][DecompressError] on failure.
172#[inline]
173#[cfg(feature = "with-alloc")]
174pub fn decompress_to_vec_zlib_with_limit(
175 input: &[u8],
176 max_size: usize,
177) -> Result<Vec<u8>, DecompressError> {
178 decompress_to_vec_inner(input, flags:inflate_flags::TINFL_FLAG_PARSE_ZLIB_HEADER, max_output_size:max_size)
179}
180
181/// Backend of various to-[`Vec`] decompressions.
182///
183/// Returns [`Vec`] of decompressed data on success and the [error struct][DecompressError] with details on failure.
184#[cfg(feature = "with-alloc")]
185fn decompress_to_vec_inner(
186 mut input: &[u8],
187 flags: u32,
188 max_output_size: usize,
189) -> Result<Vec<u8>, DecompressError> {
190 let flags = flags | inflate_flags::TINFL_FLAG_USING_NON_WRAPPING_OUTPUT_BUF;
191 let mut ret: Vec<u8> = vec![0; input.len().saturating_mul(2).min(max_output_size)];
192
193 let mut decomp = Box::<DecompressorOxide>::default();
194
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, &mut ret, out_pos, flags);
201 out_pos += out_consumed;
202
203 match status {
204 TINFLStatus::Done => {
205 ret.truncate(out_pos);
206 return Ok(ret);
207 }
208
209 TINFLStatus::HasMoreOutput => {
210 // in_consumed is not expected to be out of bounds,
211 // but the check eliminates a panicking code path
212 if in_consumed > input.len() {
213 return decompress_error(TINFLStatus::HasMoreOutput, ret);
214 }
215 input = &input[in_consumed..];
216
217 // if the buffer has already reached the size limit, return an error
218 if ret.len() >= max_output_size {
219 return decompress_error(TINFLStatus::HasMoreOutput, ret);
220 }
221 // calculate the new length, capped at `max_output_size`
222 let new_len = ret.len().saturating_mul(2).min(max_output_size);
223 ret.resize(new_len, 0);
224 }
225
226 _ => return decompress_error(status, ret),
227 }
228 }
229}
230
231/// Decompress one or more source slices from an iterator into the output slice.
232///
233/// * On success, returns the number of bytes that were written.
234/// * On failure, returns the failure status code.
235///
236/// This will fail if the output buffer is not large enough, but in that case
237/// the output buffer will still contain the partial decompression.
238///
239/// * `out` the output buffer.
240/// * `it` the iterator of input slices.
241/// * `zlib_header` if the first slice out of the iterator is expected to have a
242/// Zlib header. Otherwise the slices are assumed to be the deflate data only.
243/// * `ignore_adler32` if the adler32 checksum should be calculated or not.
244pub fn decompress_slice_iter_to_slice<'out, 'inp>(
245 out: &'out mut [u8],
246 it: impl Iterator<Item = &'inp [u8]>,
247 zlib_header: bool,
248 ignore_adler32: bool,
249) -> Result<usize, TINFLStatus> {
250 use self::core::inflate_flags::*;
251
252 let mut it = it.peekable();
253 let r = &mut DecompressorOxide::new();
254 let mut out_pos = 0;
255 while let Some(in_buf) = it.next() {
256 let has_more = it.peek().is_some();
257 let flags = {
258 let mut f = TINFL_FLAG_USING_NON_WRAPPING_OUTPUT_BUF;
259 if zlib_header {
260 f |= TINFL_FLAG_PARSE_ZLIB_HEADER;
261 }
262 if ignore_adler32 {
263 f |= TINFL_FLAG_IGNORE_ADLER32;
264 }
265 if has_more {
266 f |= TINFL_FLAG_HAS_MORE_INPUT;
267 }
268 f
269 };
270 let (status, _input_read, bytes_written) = decompress(r, in_buf, out, out_pos, flags);
271 out_pos += bytes_written;
272 match status {
273 TINFLStatus::NeedsMoreInput => continue,
274 TINFLStatus::Done => return Ok(out_pos),
275 e => return Err(e),
276 }
277 }
278 // If we ran out of source slices without getting a `Done` from the
279 // decompression we can call it a failure.
280 Err(TINFLStatus::FailedCannotMakeProgress)
281}
282
283#[cfg(all(test, feature = "with-alloc"))]
284mod test {
285 use super::{
286 decompress_slice_iter_to_slice, decompress_to_vec_zlib, decompress_to_vec_zlib_with_limit,
287 DecompressError, TINFLStatus,
288 };
289 const ENCODED: [u8; 20] = [
290 120, 156, 243, 72, 205, 201, 201, 215, 81, 168, 202, 201, 76, 82, 4, 0, 27, 101, 4, 19,
291 ];
292
293 #[test]
294 fn decompress_vec() {
295 let res = decompress_to_vec_zlib(&ENCODED[..]).unwrap();
296 assert_eq!(res.as_slice(), &b"Hello, zlib!"[..]);
297 }
298
299 #[test]
300 fn decompress_vec_with_high_limit() {
301 let res = decompress_to_vec_zlib_with_limit(&ENCODED[..], 100_000).unwrap();
302 assert_eq!(res.as_slice(), &b"Hello, zlib!"[..]);
303 }
304
305 #[test]
306 fn fail_to_decompress_with_limit() {
307 let res = decompress_to_vec_zlib_with_limit(&ENCODED[..], 8);
308 match res {
309 Err(DecompressError {
310 status: TINFLStatus::HasMoreOutput,
311 ..
312 }) => (), // expected result
313 _ => panic!("Decompression output size limit was not enforced"),
314 }
315 }
316
317 #[test]
318 fn test_decompress_slice_iter_to_slice() {
319 // one slice
320 let mut out = [0_u8; 12_usize];
321 let r =
322 decompress_slice_iter_to_slice(&mut out, Some(&ENCODED[..]).into_iter(), true, false);
323 assert_eq!(r, Ok(12));
324 assert_eq!(&out[..12], &b"Hello, zlib!"[..]);
325
326 // some chunks at a time
327 for chunk_size in 1..13 {
328 // Note: because of https://github.com/Frommi/miniz_oxide/issues/110 our
329 // out buffer needs to have +1 byte available when the chunk size cuts
330 // the adler32 data off from the last actual data.
331 let mut out = [0_u8; 12_usize + 1];
332 let r =
333 decompress_slice_iter_to_slice(&mut out, ENCODED.chunks(chunk_size), true, false);
334 assert_eq!(r, Ok(12));
335 assert_eq!(&out[..12], &b"Hello, zlib!"[..]);
336 }
337
338 // output buffer too small
339 let mut out = [0_u8; 3_usize];
340 let r = decompress_slice_iter_to_slice(&mut out, ENCODED.chunks(7), true, false);
341 assert!(r.is_err());
342 }
343}
344