tar-framing

Low-level strict tar stream framing for either POSIX pax/ustar or GNU archives.

This crate is a component of tar-codec. Most users should not use this crate's APIs directly.

Reading

This crate provides two views over an asynchronous I/O source:

• stream::TarStream emits physical 512-byte header and data frames for lossless inspection and debugging. Parsed PAX records are available on the final physical PAX payload frame.
• logical::TarReader emits ordinary members with extension metadata attached, exposes a compact logical header borrowing reusable ordinary path/link storage, resolves byte-oriented member path/link metadata according to PAX/GNU precedence, and streams member payload blocks through a borrowing cursor.

For PAX members, one PaxState provides standards-consistent effective values while preserving each positioned global or local extension newly encountered for that member. Trailing global extensions without a following member are consumed and ignored. Use TarStream when standalone physical extension headers must be inspected losslessly.

Each stream is "locked" to one archive family: POSIX pax/ustar or GNU. Streams that combine pax and GNU members are rejected.

Writing

tar-framing also provides write helpers for constructing pax-conforming member blocks without performing I/O.

Benchmarking

Run the internal framing benchmarks with:

cargo bench -p tar-framing --bench framing

encode_pax_framing measures reusable pure-pax framing without payload reads. decode_payload compares lossless block iteration, validated chunk reads, and payload skipping over in-memory archives.