Expand description
§zarchive-rs
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 + Seeksource; - directory traversal with lossless byte names;
- seekable
Readimplementations for archived files; - streaming archive creation to any
Writedestination; - 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.
- Archive
File - A seekable reader for one file stored in an archive.
- Archive
Writer - A streaming ZArchive creator backed by any Rust writer.
- DirEntry
- An owned directory entry. Names are retained exactly as archive bytes.
- Entry
Metadata - Metadata attached to an archive entry.
- Entry
Writer - A scoped writer for the currently active archive file.
- Extract
Options - Controls convenience extraction behavior.
- Open
Options - Options controlling archive opening.
- ReadDir
- Iterator over one archive directory.
Enums§
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.