tar_minimal 1.1.0

A minimalist, Unix-focused TAR library designed for high-performance streaming with Zstd.
Documentation

🔍 Overview

It's a focused, "no-frills" alternative to robust archiving crates like tar-rs. In a world of feature-heavy libraries, this crate carves out a niche for developers who need exactly two things: packing a directory and unpacking a bundle, with the best-in-class compression provided by Zstd.

It was engineered for automated deployment systems, log rotators, and payload delivery mechanisms where build times, binary size, and execution speed are more important than supporting legacy formats or cross-platform edge cases.

âœĻ Key Features

  • Unix-Native Core
    Leverages Unix-specific traits for handling file permissions (mode) and metadata, ensuring fidelity on Linux/BSD.

  • Zstd-Centric
    Unlike other libraries that treat compression as an afterthought, tar_minimal was primarily designed around Zstd streams.

  • Safety First
    Built-in protection against Path Traversal attacks during extraction.

  • Lean Dependency Tree
    Zero bloat. We avoid heavy crates like walkdir or complex async runtimes by default.

⚠ïļ Scope & Critical Limitations

This library is highly specialized. To maintain its "minimalist" status, we explicitly chose not to implement certain features:

  • No Random Access / Listing
    You cannot list files or read a single file from the archive. It's a "stream-in" (Builder) or "stream-out" (Decoder) architecture.

  • No Windows Support
    While it might compile, file permissions and path handling are not guaranteed or tested on Windows.

  • Verified Multi-Format Streaming
    While primarily designed for Zstd, the library is fully compatible and verified with any Write/Read stream, including Gzip, Xz, Bzip2, Lz4, and Brotli via the standard USTAR format.

  • Basic Metadata Only
    We handle standard permissions (UID/GID/Mode/MTime), but we do not support extended attributes (xattrs), ACLs, or complex PAX headers.

  • No In-Place Updates
    Archives are immutable once created. You cannot append or delete files from an existing .tar.zst bundle.

📖 Usage Example

[dependencies]
tar_minimal = "1.0"
zstd = "0.13"

📁 Creating an Archive/Bunble (TAR + Zstd)

use tar_minimal::Builder;
use zstd::stream::write::Encoder;
use std::fs::File;

fn main() -> std::io::Result<()> {
    let file_writer = File::create("bundle.tar.zst")?;
    let mut enc = Encoder::new(file_writer, 5)?;
    enc.long_distance_matching(true)?;
    let mut encoder = enc.auto_finish();

    {
        let mut builder = Builder::new(&mut encoder);
        builder.append_dir_all("myapp_bundle", "/path/to/source")?;
        builder.finish()?;
    }

    Ok(())
}

ðŸ“Ī Extracting an Archive/Bunble

use tar_minimal::Decoder;
use zstd::stream::read::Decoder as ZstdDecoder;
use std::fs::File;

fn main() -> std::io::Result<()> {
    let file_reader = File::open("bundle.tar.zst")?;
    let zstd_decoder = ZstdDecoder::new(file_reader)?;

    let mut decoder = Decoder::new(zstd_decoder);
    decoder.unpack("/path/to/extract")?;

    Ok(())
}

ðŸĪ Contributing

We welcome contributions, but we are very protective of the library's scope. Please follow these guidelines carefully.

✅ What we are looking for

  • Security Audits
    Improvements to the Decoder to prevent zip-slip vulnerabilities, path traversal issues, and symlink-based attacks.

  • Stability & Robustness
    Fixes for I/O edge cases, error handling, and buffer management.

  • Zstd Performance Tuning
    Optimizations in how TAR blocks are streamed into Zstd frames for better compression ratios and throughput.

  • Documentation Enhancements
    Clearer examples, improved explanations, and more actionable error messages.

🔧 Optional & Feature-Gated Enhancements

The core functionality of tar_minimal will remain strictly minimal and dependency-light. However, non-essential capabilities may be accepted behind optional Cargo feature flags, allowing advanced users to extend behavior without impacting the default experience.

  1. Possible feature-gated additions include:

    • Platform-Specific Behavior
      Optional compatibility layers for non-Unix systems (such as Windows), implemented in isolation to avoid polluting the Unix-focused core.

    • Extended Metadata Support
      Optional handling of xattrs, ACLs, and PAX headers for users who need richer filesystem fidelity.

    • Performance Helpers & Utilities Enhancements that may introduce extra dependencies for speed, parallelism, or buffering strategies.

  2. All optional features must:

    • Be disabled by default
      The base crate must remain lean and predictable.

    • Preserve a minimal dependency tree
      No heavy crates unless absolutely necessary and clearly justified.

    • Maintain core security guarantees
      Optional functionality must not weaken extraction safety or validation logic.

ðŸŠķ Design Philosophy (Feature-Based Expansion)

To preserve the minimalist nature of tar_minimal:

  • The core remains Unix + Zstd focused
    This is the guaranteed, stable, and optimized path.

  • All expanded functionality lives behind Cargo features
    No hidden dependencies or surprise behaviors.

  • Users only pay for what they enable
    Both in compile time and dependency complexity.

This ensures the crate scales from ultra-lightweight tooling to more advanced use cases without compromising its original goals.

⚙ïļ Optional Features — Outside the Core Scope

Functionality beyond the minimal archive pipeline may be considered if:

  • It is cleanly isolated from the core logic
    Clear module boundaries and no cross-contamination.

  • It does not bloat default builds
    The zero-feature experience must remain fast and small.

  • It follows Rust feature best practices
    Predictable flags, no implicit enables, and clear documentation.

📜 MIT License

This repository has scripts that were created to be free software.
Therefore, they can be distributed and/or modified within the terms of the MIT License.

See the LICENSE file for details.

📎 Contact & Support