compress-lib 0.3.0

DEFLATE, zlib, and gzip for Rust services: streaming and sans-IO with bounded memory, hard limits against decompression bombs, WebSocket permessage-deflate (RFC 7692) support, no unsafe code, and zero third-party dependencies.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! # compress_lib
//!
//! DEFLATE (RFC 1951), zlib (RFC 1950), and gzip (RFC 1952) for Rust
//! services, with the per-message rules of WebSocket permessage-deflate
//! (RFC 7692).
//!
//! The engine is sans-IO: the caller pushes input and pulls output through
//! buffers it owns. Memory is fixed when an engine is built and never grows
//! with input, and every decoder enforces an absolute output cap while it
//! decodes, so a decompression bomb costs at most the cap. There is no
//! `unsafe` code and no third-party runtime dependency.
//!
//! ## Tier 1
//!
//! Add it with Cargo's rename, `compress = { package = "compress-lib", version
//! = "0.3" }`, and code reads `compress::`. One call decompresses a complete
//! raw DEFLATE stream, capped at 64 MiB of output by default:
//!
//! ```
//! use compress_lib as compress;
//!
//! let data = compress::deflate::decompress(&[0xCB, 0x48, 0xCD, 0xC9, 0xC9, 0x07, 0x00])?;
//! assert_eq!(data, b"hello");
//!
//! let small = compress::Limits::new().with_max_output(1 << 20);
//! let data = compress::deflate::decompress_with(&[0x03, 0x00], small)?;
//! assert!(data.is_empty());
//! # Ok::<(), compress_lib::Error>(())
//! ```
//!
//! ## Streaming
//!
//! [`deflate::Inflater`] takes input and output buffers you own and says
//! where it stopped ([`Status`]); memory is fixed when it is built (about
//! 11 KiB of tables plus a window of `2^window_bits` bytes), and every limit
//! is checked before output is written.
//!
//! ```
//! use compress_lib::deflate::{Inflater, Status};
//!
//! let mut inflater = Inflater::new().with_window_bits(12)?;
//! let mut out = [0u8; 4096];
//! let p = inflater.finish(&[0xCB, 0x48, 0xCD, 0xC9, 0xC9, 0x07, 0x00], &mut out)?;
//! assert_eq!(p.status, Status::Done);
//! assert_eq!(&out[..p.produced], b"hello");
//! # Ok::<(), compress_lib::Error>(())
//! ```
//!
//! Every failure is an [`Error`] with a matchable [`ErrorKind`] and a stable
//! code for logs and metrics. [`checksum`] has CRC-32 and Adler-32.
//!
//! ## Status
//!
//! `0.3.0`, the raw DEFLATE inflater. The deflater and the RFC 7692 helpers
//! arrive in `0.4`, zlib and gzip in `0.5`; the complete planned API, each
//! item with its version, is `docs/API.md` in the
//! [repository](https://github.com/jamesgober/compress-lib).

#![doc(html_root_url = "https://docs.rs/compress-lib")]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(not(feature = "std"), no_std)]
#![forbid(unsafe_code)]
#![deny(missing_docs)]
#![cfg_attr(
    not(test),
    deny(
        clippy::unwrap_used,
        clippy::expect_used,
        clippy::panic,
        clippy::todo,
        clippy::unimplemented,
        clippy::unreachable,
        clippy::dbg_macro
    )
)]

extern crate alloc;

/// Crate version string, populated by Cargo at build time.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

pub mod checksum;
pub mod deflate;

mod error;
mod inflate;
mod level;
mod limits;
mod stream;

pub use error::{Error, ErrorKind};
pub use level::Level;
pub use limits::Limits;
pub use stream::{Progress, Status};

#[cfg(test)]
mod tests {
    use super::VERSION;

    #[test]
    fn test_version_matches_manifest() {
        assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
        let core = VERSION.split(['-', '+']).next().unwrap_or_default();
        assert_eq!(core.split('.').count(), 3);
        assert!(core.split('.').all(|part| part.parse::<u64>().is_ok()));
    }
}