xz2-rs

xz2 is a Rust crate offering safe bindings to liblzma, the C library behind the .xz format and the older LZMA format. It wraps liblzma’s raw stream interface in idiomatic Rust Read, Write, and BufRead adapters (XzEncoder/XzDecoder), so compressing or decompressing data is a matter of wrapping an existing I/O stream rather than managing buffers by hand.

Beneath the ergonomic streaming types, the crate also exposes a lower-level stream module that mirrors liblzma’s own lzma_stream API directly, including custom filter chains (Filters), tunable LzmaOptions, and a MtStreamBuilder for multi-threaded encoding. This dual-layer design lets most users stick to the simple stream wrappers while giving advanced callers full control over the underlying codec when they need it.

What You Get

• Read/Write/BufRead compression and decompression stream types (XzEncoder, XzDecoder) that wrap any existing I/O source
• A raw Stream API mirroring liblzma’s own lzma_stream interface for byte-buffer-level control
• Multi-threaded encoding via MtStreamBuilder for compressing large inputs faster on multi-core machines
• Custom filter chains and tunable LzmaOptions for fine-grained control over compression behavior
• An optional static feature to statically link liblzma so it isn’t required at runtime
• Optional (legacy futures 0.1-based) Tokio async I/O support behind a tokio feature flag

Common Use Cases

• Reading and writing .xz-compressed files or archives from a Rust application
• Decompressing xz-compressed payloads received over the network or from disk
• Embedding LZMA/XZ compression in a build tool or package format that needs a small, well-compressed output
• Building higher-level archive or backup tooling on top of a dependable liblzma binding

Under The Hood

Architecture The crate is organized in clear layers: src/stream.rs wraps the raw lzma_stream struct from the lzma-sys FFI crate and exposes Stream, LzmaOptions, Filters, and MtStreamBuilder as safe, owned types around unsafe liblzma calls; src/bufread.rs builds BufRead-based encoder/decoder adapters on top of Stream; and src/read.rs and src/write.rs each re-wrap the bufread types behind a BufReader/BufWriter to expose plain Read/Write adapters. This means the actual codec logic lives in exactly one place (stream.rs), and the three I/O-trait flavors (read, write, bufread) are thin, mostly mechanical wrappers around it — if the core Stream behavior changes, all three surfaces inherit the fix automatically.

Tech Stack The crate targets Rust 2018 edition and depends on a companion lzma-sys crate in the same repository (a links = "lzma" FFI crate using cc and pkg-config in its build.rs, with liblzma’s own C sources vendored under lzma-sys/xz-5.2 for the static feature). Optional integration with the legacy 0.1 futures/tokio-io crates is gated behind a tokio feature, reflecting the crate’s age relative to modern async Rust. CI in .github/workflows/main.yml runs cargo test across stable/beta/nightly on Linux, macOS, and Windows (including static-linked and MSVC/GNU variants), plus cargo fmt --check and doc publishing.

Code Quality Tests live under tests/ and exercise round-trip compression against liblzma’s own bundled test-file corpus (lzma-sys/xz-5.2/tests/files), verifying both well-formed and intentionally corrupt .xz files behave correctly through both the read and write adapters; there’s also a Send/Sync assertion test and a dedicated Tokio integration test. Public APIs use #![deny(missing_docs)] to force doc comments on every exported item, and errors from liblzma are surfaced through typed Error/Result types rather than panics. Rustfmt is enforced in CI, though there’s no lint step (e.g. clippy) visible in the workflow.

What Makes It Unique Most Rust crates in this space pick one abstraction level; xz2 deliberately keeps both — a small, idiomatic streaming API for common cases and an unrestricted raw Stream/Filters/MtStreamBuilder layer for callers who need liblzma’s full filter-chain and multi-threading capabilities. Bundling liblzma’s own conformance test files as the crate’s own test fixtures is a practical touch that ties correctness directly to the reference implementation rather than hand-written cases alone.