use-archive

use-archive is the RustUse facade/set for primitive archive and compression vocabulary. RustUse is a collection of composable, dependency-light Rust utility crates, and this workspace provides shared concepts for projects that need to reason about archive artifacts without depending on archive extraction or compression engines.

This repository is experimental while it is below 0.3.0. APIs are intentionally small and may change as the RustUse archive vocabulary settles.

Purpose

use-archive provides primitive archive container, entry, manifest, path safety, extraction policy, and compression-codec label types. It helps tools describe archive artifacts, detect common filename encodings, validate archive-internal paths, and summarize archive manifests.

What It Is

• Archive and compression format labels.
• Archive entry and manifest metadata primitives.
• Archive-internal path safety checks.
• Safe extraction policy primitives.
• Format-specific labels for tar, ZIP, CPIO, ar, ISO, 7z, RAR, CAB, WARC, and mtree artifacts.
• Codec labels and option metadata for gzip, xz, zstd, bzip2, Brotli, and LZ4.
• A feature-gated facade crate that re-exports common child crate types.

What It Is Not

• Not an archive reader or writer.
• Not an extraction framework.
• Not a compression engine.
• Not a checksum, signature, or package-format crate.
• Not a general filesystem path utility crate.
• Not an OCI, Docker, Cargo package, or MIME integration layer.

Crates

Crate	Description
use-archive-format	Archive and compression format labels plus filename detection.
use-archive-entry	Generic archive entry metadata primitives.
use-archive-path	Archive-internal path safety checks.
use-archive-policy	Safe extraction policy presets and checks.
use-archive-manifest	Normalized archive manifest summaries.
use-tar	Tar entry type labels and typeflag mappings.
use-zip	ZIP compression method labels and method codes.
use-cpio	CPIO format, entry kind, and extension labels.
use-ar	Unix ar format, entry kind, and extension labels.
use-iso	ISO image format, volume kind, and extension labels.
use-7z	7-Zip format, compression method, and extension labels.
use-rar	RAR version, volume kind, and extension labels.
use-cab	Cabinet format, compression method, and extension labels.
use-warc	WARC/ARC format, record kind, and extension labels.
use-mtree	mtree format, entry kind, keyword, and extension labels.
use-compression	Generic compression level and intent settings.
use-gzip	Gzip labels, extensions, and option metadata.
use-xz	XZ labels, extensions, and option metadata.
use-zstd	Zstd labels, extensions, and option metadata.
use-bzip2	Bzip2 labels, extensions, and option metadata.
use-brotli	Brotli labels, extensions, and option metadata.
use-lz4	LZ4 labels, extensions, and option metadata.
use-archive	Feature-gated facade crate.

Installation

[dependencies]
use-archive = "0.1.0"

Focused crates can also be used directly:

[dependencies]
use-archive-format = "0.1.0"
use-archive-path = "0.1.0"
use-cpio = "0.1.0"
use-bzip2 = "0.1.0"

Basic Usage

use use_archive::{
    ArchiveEncoding, ArchiveEntry, ArchiveEntryKind, ArchiveFormat, ArchiveManifest,
    ArchivePolicy, CompressionFormat, is_safe_relative_archive_path,
};

let encoding = ArchiveEncoding::from_extension("release.tar.zst");
assert_eq!(encoding.archive, ArchiveFormat::Tar);
assert_eq!(encoding.compression, CompressionFormat::Zstd);

assert!(is_safe_relative_archive_path("docs/readme.md"));
assert!(!is_safe_relative_archive_path("../secrets.env"));
assert!(!is_safe_relative_archive_path("/etc/passwd"));

let policy = ArchivePolicy::strict();
assert!(!policy.allow_absolute_paths);
assert!(!policy.allow_parent_traversal);
assert!(!policy.allow_symlinks);

let manifest = ArchiveManifest::new(encoding).with_entries(vec![
    ArchiveEntry::new("docs/readme.md", ArchiveEntryKind::File).with_size(128),
]);

assert_eq!(manifest.file_count(), 1);
assert_eq!(manifest.total_size(), 128);
assert!(!manifest.has_unsafe_paths());

Relationship To Other RustUse Sets

use-archive should hold archive-artifact vocabulary only. General filesystem path utilities belong in use-fs; checksums, signatures, and verification belong in security-oriented sets; OCI and Docker layer concepts belong in OCI or Docker sets; MIME integration belongs in web-oriented sets; and package-format details can be modeled separately when needed.