tar-codec

tar-codec is a small, fast, constrained tar encoder and decoder for Rust.

[!IMPORTANT]

This repository is in a very early state of development and is not considered ready for production use. You will encounter bugs, sharp edges, etc.

Goals:

• Fast, asynchronous, minimally ambiguous, strict pax-style tar encoding
• Fast, asynchronous tar decoding for distinct POSIX pax/ustar or GNU archive streams

Anti-goals:

• Encoding support for anything other than pax
• Decoding support for legacy (pre-ustar, "UNIX v7") archives
• Decoding archives that mix POSIX pax/ustar and GNU framing in one stream

Usage

Encoding/archive serialization:

use tar_codec::{ArchiveBuilder as _, EntryMetadata, TarEncoder};

let mut encoder = TarEncoder::new(&mut writer).builder();
encoder
    .add_entry("README.md", b"hello\n", EntryMetadata::default())
    .await?;
encoder.finish().await?;

See ArchiveBuilder::builder_with_policy for policy knobs that can be changed during building.

Note that tar-codec does not perform compression for you. If you want a compressed tar stream (like a .tar.gz) consider supplying an adapted writer, such as from the async-compression crate.

Decoding/extracting:

use tar_codec::{Archive as _, TarArchive, extract::ExtractPolicy};

TarArchive::new(reader)
    .extract_in("destination", ExtractPolicy::default())
    .await?;

Unlike encoding, decoding/extraction has two policy layers:

• Use TarArchive::new_with_policy to control various aspects of GNU or pax handling.
• Use extract::ExtractPolicy to control various aspects of how archives become real paths on the host filesystem.

Performance

tar-codec aims to be as fast as (or substantially faster than) other tar libraries for Rust, including tar and astral-tokio-tar.

See BENCHMARKS for current benchmarks.