Skip to main content

Crate zarchive_rs

Crate zarchive_rs 

Source
Expand description

§zarchive-rs

Crates.io Downloads Tests

Safe, idiomatic Rust bindings for Exzap/ZArchive, a random-access archive format using independent 64 KiB zstd-compressed blocks.

zarchive-rs provides:

  • random-access reading from any Read + Seek source;
  • directory traversal with lossless byte names;
  • seekable Read implementations for archived files;
  • streaming archive creation to any Write destination;
  • explicit whole-archive SHA-256 verification;
  • deterministic directory packing and capability-confined extraction.

The package name and Rust import are both intentionally distinct from the older, GPL-licensed zarchive crate:

[dependencies]
zarchive-rs = "0.1"
use std::io::Read;
use zarchive_rs::{Archive, Result};

fn main() -> Result<()> {
    let mut archive = Archive::open("assets.zar")?;
    let mut file = archive
        .open_file("textures/logo.bin")?
        .expect("entry exists");
    let mut data = Vec::new();
    file.read_to_end(&mut data)?;
    Ok(())
}

§Reading and integrity

Archive<R> owns any R: Read + Seek. Opening validates the ZArchive structure without scanning payload data. Whole-archive SHA-256 verification is deliberately explicit because it is O(archive size):

use std::fs::File;
use zarchive_rs::{OpenOptions, Result};

fn verified() -> Result<()> {
    let file = File::open("assets.zar")?;
    let mut archive = OpenOptions::new()
        .verify_integrity(true)
        .open(file)?;
    assert!(archive.entry("textures")?.is_some());
    archive.verify_integrity()?; // Verification can also be requested later.
    Ok(())
}

Archive-internal paths accept both strings and byte slices. DirEntry retains the exact bytes and exposes name_str, path_str, and lossy display helpers. ZArchive only folds ASCII letters for case-insensitive lookup; UTF-8 is otherwise treated as ordinary bytes.

§Streaming creation

use std::io::{Cursor, Write};
use zarchive_rs::{ArchiveWriter, Result};

fn create_in_memory() -> Result<Vec<u8>> {
    let mut archive = ArchiveWriter::new(Cursor::new(Vec::new()))?;
    archive.create_dir_all("docs/guides")?;
    archive
        .start_file("docs/guides/start.txt")?
        .write_all(b"hello from ZArchive\n")?;
    Ok(archive.finish()?.into_inner())
}

finish is mandatory: dropping an ArchiveWriter leaves an intentionally incomplete stream. Writer paths are normalized to / and reject absolute paths, empty components, ./.., NUL bytes, components longer than 32767 bytes, missing parents, and ASCII-case-insensitive duplicates.

§Filesystem conveniences

use zarchive_rs::{ExtractOptions, Result, extract, pack_dir};

fn filesystem() -> Result<()> {
    pack_dir("assets", "assets.zar")?;
    extract("assets.zar", "unpacked")?;

    // Overwriting regular files must be requested explicitly.
    let _options = ExtractOptions::new().overwrite(true);
    Ok(())
}

pack_dir traverses in deterministic byte order, rejects symlinks and non-UTF-8 disk names, writes to a sibling temporary file, and atomically persists without overwriting. Extraction rejects absolute, traversal, and non-UTF-8 entry names. Filesystem access is relative to a cap-std directory capability, so archive paths and symlinks cannot escape the destination. Existing files are refused unless ExtractOptions::overwrite(true) is set; links and directories are never replaced.

ZArchive has no symlink, permission, timestamp, or incremental-update metadata.

§Native build and compatibility

The crate vendors the required ZArchive sources at commit 965b66c8d67b6b7e30fd63b3b75aa91a99ff303b and builds them together with the bundled zstd-sys library. Consumers need a C++20 compiler but do not need a system ZArchive or zstd installation.

Supported CI platforms are Windows, Linux, and macOS. The minimum supported Rust version is 1.85 and the crate uses Rust 2024.

Local upstream fixes and provenance are recorded in vendor/zarchive/UPSTREAM.md.

§License

The Rust code and upstream ZArchive are MIT-0. The vendored sha_256.c and sha_256.h files are public domain. See LICENSE and vendor/zarchive/LICENSE.

Structs§

Archive
A validated, open ZArchive backed by a seekable Rust reader.
ArchiveFile
A seekable reader for one file stored in an archive.
ArchiveWriter
A streaming ZArchive creator backed by any Rust writer.
DirEntry
An owned directory entry. Names are retained exactly as archive bytes.
EntryMetadata
Metadata attached to an archive entry.
EntryWriter
A scoped writer for the currently active archive file.
ExtractOptions
Controls convenience extraction behavior.
OpenOptions
Options controlling archive opening.
ReadDir
Iterator over one archive directory.

Enums§

EntryKind
The kind of an archive entry.
Error
Errors returned by zarchive-rs.

Functions§

extract
Extracts an archive file without replacing existing files.
extract_with_options
Extracts an archive file with explicit extraction options.
pack_dir
Packs a directory into a new archive using deterministic traversal order.

Type Aliases§

Result