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;
10pub mod stream;
11use self::core::*;
12
13const TINFL_STATUS_FAILED_CANNOT_MAKE_PROGRESS: i32 = -4;
14const TINFL_STATUS_BAD_PARAM: i32 = -3;
15const TINFL_STATUS_ADLER32_MISMATCH: i32 = -2;
16const TINFL_STATUS_FAILED: i32 = -1;
17const TINFL_STATUS_DONE: i32 = 0;
18const TINFL_STATUS_NEEDS_MORE_INPUT: i32 = 1;
19const TINFL_STATUS_HAS_MORE_OUTPUT: i32 = 2;
20
21/// Return status codes.
22#[repr(i8)]
23#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
24pub enum TINFLStatus {
25 /// More input data was expected, but the caller indicated that there was no more data, so the
26 /// input stream is likely truncated.
27 ///
28 /// This can't happen if you have provided the
29 /// [`TINFL_FLAG_HAS_MORE_INPUT`][core::inflate_flags::TINFL_FLAG_HAS_MORE_INPUT] flag to the
30 /// decompression. By setting that flag, you indicate more input exists but is not provided,
31 /// and so reaching the end of the input data without finding the end of the compressed stream
32 /// would instead return a [`NeedsMoreInput`][Self::NeedsMoreInput] status.
33 FailedCannotMakeProgress = TINFL_STATUS_FAILED_CANNOT_MAKE_PROGRESS as i8,
34
35 /// The output buffer is an invalid size; consider the `flags` parameter.
36 BadParam = TINFL_STATUS_BAD_PARAM as i8,
37
38 /// The decompression went fine, but the adler32 checksum did not match the one
39 /// provided in the header.
40 Adler32Mismatch = TINFL_STATUS_ADLER32_MISMATCH as i8,
41
42 /// Failed to decompress due to invalid data.
43 Failed = TINFL_STATUS_FAILED as i8,
44
45 /// Finished decompression without issues.
46 ///
47 /// This indicates the end of the compressed stream has been reached.
48 Done = TINFL_STATUS_DONE as i8,
49
50 /// The decompressor needs more input data to continue decompressing.
51 ///
52 /// This occurs when there's no more consumable input, but the end of the stream hasn't been
53 /// reached, and you have supplied the
54 /// [`TINFL_FLAG_HAS_MORE_INPUT`][core::inflate_flags::TINFL_FLAG_HAS_MORE_INPUT] flag to the
55 /// decompressor. Had you not supplied that flag (which would mean you were asserting that you
56 /// believed all the data was available) you would have gotten a
57 /// [`FailedCannotMakeProcess`][Self::FailedCannotMakeProgress] instead.
58 NeedsMoreInput = TINFL_STATUS_NEEDS_MORE_INPUT as i8,
59
60 /// There is still pending data that didn't fit in the output buffer.
61 HasMoreOutput = TINFL_STATUS_HAS_MORE_OUTPUT as i8,
62}
63
64impl TINFLStatus {
65 pub fn from_i32(value: i32) -> Option<TINFLStatus> {
66 use self::TINFLStatus::*;
67 match value {
68 TINFL_STATUS_FAILED_CANNOT_MAKE_PROGRESS => Some(FailedCannotMakeProgress),
69 TINFL_STATUS_BAD_PARAM => Some(BadParam),
70 TINFL_STATUS_ADLER32_MISMATCH => Some(Adler32Mismatch),
71 TINFL_STATUS_FAILED => Some(Failed),
72 TINFL_STATUS_DONE => Some(Done),
73 TINFL_STATUS_NEEDS_MORE_INPUT => Some(NeedsMoreInput),
74 TINFL_STATUS_HAS_MORE_OUTPUT => Some(HasMoreOutput),
75 _ => None,
76 }
77 }
78}
79
80/// Struct return when decompress_to_vec functions fail.
81#[cfg(feature = "with-alloc")]
82#[derive(Debug)]
83pub struct DecompressError {
84 /// Decompressor status on failure. See [TINFLStatus] for details.
85 pub status: TINFLStatus,
86 /// The currently decompressed data if any.
87 pub output: Vec<u8>,
88}
89
90#[cfg(feature = "with-alloc")]
91impl alloc::fmt::Display for DecompressError {
92 #[cold]
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)
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,
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 mut 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 out_pos = 0;
195 loop {
196 // Wrap the whole output slice so we know we have enough of the
197 // decompressed data for matches.
198 let (status, in_consumed, out_consumed) =
199 decompress(&mut decomp, input, &mut ret, out_pos, flags);
200 out_pos += out_consumed;
201
202 match status {
203 TINFLStatus::Done => {
204 ret.truncate(out_pos);
205 return Ok(ret);
206 }
207
208 TINFLStatus::HasMoreOutput => {
209 // in_consumed is not expected to be out of bounds,
210 // but the check eliminates a panicking code path
211 if in_consumed > input.len() {
212 return decompress_error(TINFLStatus::HasMoreOutput, ret);
213 }
214 input = &input[in_consumed..];
215
216 // if the buffer has already reached the size limit, return an error
217 if ret.len() >= max_output_size {
218 return decompress_error(TINFLStatus::HasMoreOutput, ret);
219 }
220 // calculate the new length, capped at `max_output_size`
221 let new_len = ret.len().saturating_mul(2).min(max_output_size);
222 ret.resize(new_len, 0);
223 }
224
225 _ => return decompress_error(status, ret),
226 }
227 }
228}
229
230/// Decompress one or more source slices from an iterator into the output slice.
231///
232/// * On success, returns the number of bytes that were written.
233/// * On failure, returns the failure status code.
234///
235/// This will fail if the output buffer is not large enough, but in that case
236/// the output buffer will still contain the partial decompression.
237///
238/// * `out` the output buffer.
239/// * `it` the iterator of input slices.
240/// * `zlib_header` if the first slice out of the iterator is expected to have a
241/// Zlib header. Otherwise the slices are assumed to be the deflate data only.
242/// * `ignore_adler32` if the adler32 checksum should be calculated or not.
243pub fn decompress_slice_iter_to_slice<'out, 'inp>(
244 out: &'out mut [u8],
245 it: impl Iterator<Item = &'inp [u8]>,
246 zlib_header: bool,
247 ignore_adler32: bool,
248) -> Result<usize, TINFLStatus> {
249 use self::core::inflate_flags::*;
250
251 let mut it = it.peekable();
252 let r = &mut DecompressorOxide::new();
253 let mut out_pos = 0;
254 while let Some(in_buf) = it.next() {
255 let has_more = it.peek().is_some();
256 let flags = {
257 let mut f = TINFL_FLAG_USING_NON_WRAPPING_OUTPUT_BUF;
258 if zlib_header {
259 f |= TINFL_FLAG_PARSE_ZLIB_HEADER;
260 }
261 if ignore_adler32 {
262 f |= TINFL_FLAG_IGNORE_ADLER32;
263 }
264 if has_more {
265 f |= TINFL_FLAG_HAS_MORE_INPUT;
266 }
267 f
268 };
269 let (status, _input_read, bytes_written) = decompress(r, in_buf, out, out_pos, flags);
270 out_pos += bytes_written;
271 match status {
272 TINFLStatus::NeedsMoreInput => continue,
273 TINFLStatus::Done => return Ok(out_pos),
274 e => return Err(e),
275 }
276 }
277 // If we ran out of source slices without getting a `Done` from the
278 // decompression we can call it a failure.
279 Err(TINFLStatus::FailedCannotMakeProgress)
280}
281
282#[cfg(all(test, feature = "with-alloc"))]
283mod test {
284 use super::{
285 decompress_slice_iter_to_slice, decompress_to_vec_zlib, decompress_to_vec_zlib_with_limit,
286 DecompressError, TINFLStatus,
287 };
288 const ENCODED: [u8; 20] = [
289 120, 156, 243, 72, 205, 201, 201, 215, 81, 168, 202, 201, 76, 82, 4, 0, 27, 101, 4, 19,
290 ];
291
292 #[test]
293 fn decompress_vec() {
294 let res = decompress_to_vec_zlib(&ENCODED[..]).unwrap();
295 assert_eq!(res.as_slice(), &b"Hello, zlib!"[..]);
296 }
297
298 #[test]
299 fn decompress_vec_with_high_limit() {
300 let res = decompress_to_vec_zlib_with_limit(&ENCODED[..], 100_000).unwrap();
301 assert_eq!(res.as_slice(), &b"Hello, zlib!"[..]);
302 }
303
304 #[test]
305 fn fail_to_decompress_with_limit() {
306 let res = decompress_to_vec_zlib_with_limit(&ENCODED[..], 8);
307 match res {
308 Err(DecompressError {
309 status: TINFLStatus::HasMoreOutput,
310 ..
311 }) => (), // expected result
312 _ => panic!("Decompression output size limit was not enforced"),
313 }
314 }
315
316 #[test]
317 fn test_decompress_slice_iter_to_slice() {
318 // one slice
319 let mut out = [0_u8; 12_usize];
320 let r =
321 decompress_slice_iter_to_slice(&mut out, Some(&ENCODED[..]).into_iter(), true, false);
322 assert_eq!(r, Ok(12));
323 assert_eq!(&out[..12], &b"Hello, zlib!"[..]);
324
325 // some chunks at a time
326 for chunk_size in 1..13 {
327 // Note: because of https://github.com/Frommi/miniz_oxide/issues/110 our
328 // out buffer needs to have +1 byte available when the chunk size cuts
329 // the adler32 data off from the last actual data.
330 let mut out = [0_u8; 12_usize + 1];
331 let r =
332 decompress_slice_iter_to_slice(&mut out, ENCODED.chunks(chunk_size), true, false);
333 assert_eq!(r, Ok(12));
334 assert_eq!(&out[..12], &b"Hello, zlib!"[..]);
335 }
336
337 // output buffer too small
338 let mut out = [0_u8; 3_usize];
339 let r = decompress_slice_iter_to_slice(&mut out, ENCODED.chunks(7), true, false);
340 assert!(r.is_err());
341 }
342}
343