Crate zesven

Crate zesven 

Source
Expand description

§zesven

A pure-Rust library for reading and writing 7z archives.

This crate provides a safe, efficient, and fully-featured implementation of the 7z archive format with support for multiple compression methods, AES-256 encryption, solid archives, and streaming decompression.

§Quick Start

§Extracting an Archive

use zesven::{Archive, ExtractOptions, Result};
use std::io::Cursor;

fn main() -> Result<()> {
    // Open from a file path
    let mut archive = Archive::open_path("archive.7z")?;

    // List entries
    for entry in archive.entries() {
        println!("{}: {} bytes", entry.path.as_str(), entry.size);
    }

    // Extract all entries to a directory
    archive.extract("./output", (), &ExtractOptions::default())?;
    Ok(())
}

§Creating an Archive

use zesven::{Writer, WriteOptions, ArchivePath, Result};

fn main() -> Result<()> {
    // Create a new archive
    let mut writer = Writer::create_path("new.7z")?;

    // Add files from disk
    writer.add_path("file.txt", ArchivePath::new("file.txt")?)?;

    // Add data from memory
    writer.add_bytes(ArchivePath::new("hello.txt")?, b"Hello, World!")?;

    // Finish and get statistics
    let result = writer.finish()?;
    println!("Wrote {} entries ({:.1}% compression)",
        result.entries_written,
        result.space_savings() * 100.0);
    Ok(())
}

§Extracting Password-Protected Archives

ⓘ
use zesven::{Archive, ExtractOptions, Password, Result};

fn main() -> Result<()> {
    let mut archive = Archive::open_path_with_password(
        "encrypted.7z",
        Password::new("secret"),
    )?;
    archive.extract("./output", (), &ExtractOptions::default())?;
    Ok(())
}

§Creating an Encrypted Archive

ⓘ
use zesven::{Writer, WriteOptions, ArchivePath, Password, Result};

fn main() -> Result<()> {
    let options = WriteOptions::new()
        .password(Password::new("secret"))
        .level(7)?;

    let mut writer = Writer::create_path("encrypted.7z")?
        .options(options);

    writer.add_bytes(ArchivePath::new("secret.txt")?, b"Secret data")?;
    writer.finish()?;
    Ok(())
}

§Feature Flags

FeatureDefaultDescription
lzmaYesLZMA compression support
lzma2YesLZMA2 compression support (includes lzma)
deflateYesDeflate/zlib compression
bzip2YesBZip2 compression
ppmdYesPPMd compression
aesYesAES-256 encryption for data and headers
parallelYesMulti-threaded compression with Rayon
lz4NoLZ4 compression support
zstdNoZstandard compression support
brotliNoBrotli compression support
fast-lzma2NoFast LZMA2 encoder with radix match-finder
regexNoRegex-based file filtering
sysinfoNoSystem info for adaptive memory limits
asyncNoAsync/await API with Tokio integration
wasmNoWebAssembly/browser support
cliNoCommand-line interface tool

§Disabling Default Features

To create a minimal build, disable default features:

[dependencies]
zesven = { version = "1.0", default-features = false, features = ["lzma2"] }

§Async API

Enable the async feature for Tokio-based async operations:

ⓘ
use zesven::{AsyncArchive, AsyncExtractOptions, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let mut archive = AsyncArchive::open_path("archive.7z").await?;
    archive.extract("./output", (), &AsyncExtractOptions::default()).await?;
    Ok(())
}

§Streaming API

For memory-efficient processing of large archives, use the streaming API:

ⓘ
use zesven::{StreamingArchive, StreamingConfig, Result};

fn main() -> Result<()> {
    let config = StreamingConfig::default()
        .max_memory_buffer(64 * 1024 * 1024); // 64 MB limit

    // With default features (aes enabled), pass empty string for unencrypted archives
    let archive = StreamingArchive::open_path_with_config("large.7z", "", config)?;

    for entry in archive.entries()? {
        let entry = entry?;
        println!("Processing: {}", entry.path().as_str());
    }
    Ok(())
}

§Error Handling

All operations return Result<T>, which is an alias for std::result::Result<T, Error>. The Error enum covers all possible failure modes:

use zesven::{Archive, Error};

fn open_archive(path: &str) -> zesven::Result<()> {
    match Archive::open_path(path) {
        Ok(archive) => {
            println!("Opened archive with {} entries", archive.len());
            Ok(())
        }
        Err(Error::Io(e)) => {
            eprintln!("I/O error: {}", e);
            Err(Error::Io(e))
        }
        Err(Error::InvalidFormat(msg)) => {
            eprintln!("Not a valid 7z file: {}", msg);
            Err(Error::InvalidFormat(msg))
        }
        Err(e @ Error::WrongPassword { .. }) => {
            eprintln!("Incorrect password");
            Err(e)
        }
        Err(e) => Err(e),
    }
}

§Safety and Resource Limits

The library includes built-in protections against malicious archives:

  • Path traversal protection: Prevents extraction outside the destination
  • Resource limits: Guards against zip bombs and excessive memory usage
  • CRC verification: Validates data integrity during extraction
use zesven::{ExtractOptions, read::PathSafety};

// Enable strict path validation (default)
let options = ExtractOptions::new()
    .path_safety(PathSafety::Strict);

§Platform Support

PlatformStatus
Linux (x86_64, aarch64)Full support
macOS (x86_64, aarch64)Full support
Windows (x86_64)Full support
WebAssemblyVia wasm feature

§Minimum Supported Rust Version (MSRV)

This crate requires Rust 1.85 or later.

Re-exports§

pub use archive_path::ArchivePath;
pub use error::Error;
pub use error::PasswordDetectionMethod;
pub use error::Result;
pub use timestamp::Timestamp;
pub use crypto::Password;aes
pub use read::Archive;
pub use read::Entry;
pub use read::ExtractOptions;
pub use read::ExtractResult;
pub use read::TestOptions;
pub use read::TestResult;
pub use write::AppendResult;
pub use write::ArchiveAppender;
pub use write::WriteFilter;
pub use write::WriteOptions;
pub use write::WriteResult;
pub use write::Writer;
pub use volume::VolumeConfig;
pub use format::streams::LimitMode;
pub use format::streams::RatioLimit;
pub use format::streams::ResourceLimits;
pub use safety::LimitedReader;
pub use safety::validate_extract_path;
pub use streaming::CompressionMethod;
pub use streaming::DecoderPool;
pub use streaming::EntryIterator;
pub use streaming::ExtractAllResult;
pub use streaming::MemoryEstimate;
pub use streaming::MemoryGuard;
pub use streaming::MemoryTracker;
pub use streaming::PoolStats;
pub use streaming::StreamingArchive;
pub use streaming::StreamingConfig;
pub use streaming::StreamingEntry;
pub use stats::ReadStats;
pub use stats::StatsConfig;
pub use stats::StatsReader;
pub use stats::WithStats;
pub use progress::AtomicProgress;
pub use progress::NoProgress;
pub use progress::ProgressReporter;
pub use progress::ProgressState;
pub use progress::StatisticsProgress;
pub use progress::ThrottledProgress;
pub use progress::progress_fn;
pub use edit::ArchiveEditor;
pub use edit::EditResult;
pub use edit::EditableArchive;
pub use edit::Operation;
pub use edit::OperationBuilder;
pub use sfx::SfxBuilder;
pub use sfx::SfxConfig;
pub use sfx::SfxFormat;
pub use sfx::SfxInfo;
pub use sfx::SfxResult;
pub use sfx::SfxStub;
pub use sfx::create_sfx;
pub use recovery::FailedEntry;
pub use recovery::RecoveredEntry;
pub use recovery::RecoveryOptions;
pub use recovery::RecoveryResult;
pub use recovery::RecoveryStatus;
pub use recovery::SignatureScanner;
pub use recovery::find_all_signatures;
pub use recovery::is_valid_archive;
pub use recovery::recover_archive;
pub use ownership::UnixOwnership;
pub use hardlink::HardLinkEntry;
pub use hardlink::HardLinkInfo;
pub use hardlink::HardLinkTracker;
pub use ntfs::ADS_SEPARATOR;
pub use ntfs::AltStream;
pub use ntfs::discover_alt_streams;
pub use ntfs::is_ads_path;
pub use ntfs::make_ads_path;
pub use ntfs::parse_ads_path;
pub use ntfs::read_alt_stream;
pub use ntfs::write_alt_stream;
pub use async_options::AsyncExtractOptions;async
pub use async_options::AsyncProgressCallback;async
pub use async_options::AsyncTestOptions;async
pub use async_options::ChannelProgressReporter;async
pub use async_options::ProgressEvent;async
pub use async_read::AsyncArchive;async
pub use async_write::AsyncWriter;async
pub use async_password::AsyncPassword;async and aes
pub use async_password::AsyncPasswordProvider;async and aes
pub use async_password::CallbackPasswordProvider;async and aes
pub use async_password::InteractivePasswordProvider;async and aes
pub use async_codec::AsyncDecoder;async
pub use async_codec::AsyncEncoder;async
pub use async_codec::build_async_decoder;async
pub use async_codec::build_async_encoder;async

Modules§

archive_path
Archive path type with validation for secure path handling.
async_codecasync
Async codec infrastructure for 7z archives.
async_optionsasync
Async-specific options for archive operations.
async_passwordasync
Async password handling for 7z encryption.
async_readasync
Async archive reading API for 7z archives.
async_writeasync
Async archive writing API for 7z archives.
checksum
Checksum computation utilities.
codec
Compression codec infrastructure for 7z archives.
cryptoaes
AES-256 encryption support for 7z archives.
edit
Archive editing and modification.
error
Error types for 7z archive operations.
format
7z archive format constants, definitions, and low-level parsing utilities.
fs
Filesystem-style API for archive access.
hardlink
Hard link tracking and detection for 7z archives.
ntfs
NTFS Alternate Data Streams support.
ownership
Unix file ownership support.
progress
Enhanced progress reporting for archive operations.
read
Archive reading API for 7z archives.
recovery
Archive recovery for damaged or corrupted 7z archives.
safety
Safety and resource limit utilities.
sfx
Self-extracting archive (SFX) creation.
stats
Read statistics tracking for archive operations.
streaming
Streaming decompression API for memory-efficient extraction.
timestamp
High-precision timestamp handling.
volume
Multi-volume archive support.
write
Archive writing API for 7z archives.

Structs§

CancellationTokenasync
A token which can be used to signal a cancellation request to one or more tasks.