ZarSharp 0.1.0

ZarSharp

ZarSharp is a pure-managed, idiomatic .NET 8 implementation of the ZArchive v1 archive format (.zar and .wua). It reads and creates archives without binding to the upstream C++ library or shipping native binaries. Zstandard compression is provided by the pure-C# ZstdSharp.Port package.

Features

• Random-access, seekable reads from independently compressed 64 KiB blocks.
• Append-only archive creation that works with non-seekable and write-once streams.
• Synchronous and cancellation-aware asynchronous APIs.
• Thread-safe concurrent reads with a bounded decompressed-block LRU cache.
• Strict structural validation and explicit whole-archive SHA-256 verification.
• Platform-independent Windows-1252 paths with the format's ASCII-only case folding.
• Compatibility tests in both directions with Exzap's v0.1.2 reference tool.

Install

dotnet add package ZarSharp

Create an archive

using ZarSharp;

await using var output = File.Create("content.zar");
await using var writer = ZArchiveWriter.Create(output);

writer.CreateDirectory("empty-folder");
await using var source = File.OpenRead("picture.bin");
await writer.WriteEntryAsync("assets/picture.bin", source);
await writer.CompleteAsync();

The output only needs to be writable; it does not need to support seeking. Parent directories are created automatically. Only one stream returned by CreateEntry may be open at a time.

Read an archive

using ZarSharp;

await using var archive = await ZArchiveReader.OpenAsync("content.zar");
var entry = archive.GetEntry("ASSETS/picture.bin")
    ?? throw new FileNotFoundException();

await using var input = entry.Open();
input.Seek(64 * 1024, SeekOrigin.Begin);
var buffer = new byte[4096];
var bytesRead = await input.ReadAsync(buffer);

if (!await archive.VerifyIntegrityAsync())
    throw new InvalidDataException("The archive checksum does not match.");

Opening validates the footer, section ranges, block table, name table, and complete file tree. VerifyIntegrity is explicit because it must read the entire archive and can be expensive for multi-terabyte files.

Paths and interoperability

Writers accept relative paths using / or \ and serialize them with / semantics. Names must round-trip through Windows-1252. Absolute paths, empty components, . and .., embedded NUL characters, unrepresentable Unicode, components longer than 32,767 encoded bytes, and ASCII-case-insensitive sibling duplicates are rejected.

The reader accepts both separators and compares only ASCII letters without regard to case, matching the reference implementation. Non-ASCII letters remain case-sensitive.

ZArchive does not support editing an archive after creation. The metadata sections in format version 1 have no defined upstream semantics, so ZarSharp validates their ranges but otherwise ignores them.

Stream ownership and thread safety

File-path overloads own their file streams. Stream overloads dispose the supplied stream by default; pass leaveOpen: true to retain ownership. A reader supports concurrent reads from separate entry streams. Individual entry streams and writers are not thread-safe.

License

ZarSharp is licensed under MIT-0. See THIRD-PARTY-NOTICES.md for the managed Zstandard dependency and format-reference notices.