Crate archive_core

Expand description

archive_core — a pure-Rust, forbid(unsafe), read-only archive layer reader for forensics.

An archive is treated as a transparent optional archive layer: foo.E01.gz resolves identically to foo.E01. peel_bytes removes one archive layer when present, so a consumer can recurse until it reaches the real evidence.

Format determination follows the settled model: the content magic is the authority for the compression codec actually applied (you cannot gzip-decode bzip2 bytes), while the file name is a secondary hint used for aliases (.tgz→gzip+tar) and the magic-absent formats. See sniff.

Codec coverage grows incrementally; gzip is wired first (the canonical E01.gz archive layer). Large-member streaming / temp-spill (for multi-GB inner evidence) is the next hardening step — today the peel is in-memory with a hard output cap.

Structs§

Archive: A decoded, listable archive over an in-memory byte slice.
ArchiveEntry: One member of an archive.
ConcatSource: One logical, seekable image reassembled by concatenating the ordered per-segment handles of a raw split set (.001/.002/.003). A logical offset maps to (segment, local offset); a single read never crosses a segment boundary (the caller’s read_exact loops across it), and seek is bounded — a position past the end clamps to the total length.
Limits: Bomb guards for resolve. Every field is a hard cap that fails loud when tripped; the inflated-size cap is tracked cumulatively across all layers, not per layer.
Segment: One member of an AccessPlan::SegmentSet, carrying its own access strategy.
SegmentSources: The ordered per-segment byte sources of a segmented image, each materialized via its own crate::Access (phase-2/3 executor) and ordered by segment number. For SegmentKind::SplitRaw these concatenate (ConcatSource); for SegmentKind::Ewf / SegmentKind::SplitVmdk they feed a container reader’s multi-segment backing (the SegmentBacking seam above).
SubRange: A zero-copy, seekable window [offset, offset + len) over a shared byte buffer. Reading never decompresses and never copies the member into a second buffer — the bytes come straight from the original archive image. The backing is an Arc so several windows (e.g. every segment of a split set) share one copy of the archive rather than cloning it per window.
TempBacked: A seekable handle over a temp file holding a once-decoded stream. The temp file lives under std::env::temp_dir and is deleted when this value drops.

Enums§

Access: The access strategy for one member or segment, chosen from the archive’s member table without decompressing (ADR 0008, rule 4 — most-seekable first).
AccessPlan: The classified, most-direct route from packed bytes to the evidence.
ArchiveError
Codec: The bare compression codec of an AccessPlan::Wrapper.
Format: A recognized packing format.
Node: A leaf of a fully-resolved packing tree.
Peel: The outcome of peeling a disk-image archive layer.
PeelOutcome: The result of attempting to peel one bare-compression layer.
PeelSource: The outcome of the seekable peel executor — the streaming twin of crate::Peel.
PeeledSource: The peeled inner evidence as a seekable handle: a zero-copy in-place window, a zran checkpoint-indexed member, or a temp-backed decode. All implement Read + Seek.
Reassembled: The outcome of reassembling a segmented image (or the finding that the input is not a segment set).
SegmentKind: How a segmented set’s members reassemble into one logical image.

Traits§

ReadSeek: A seekable byte source: the common capability every peeled handle exposes so a consumer can take a Box<dyn ReadSeek> without knowing the backing store.

Functions§

detect: Classify the most-direct access route to the evidence inside data, content-authoritatively and name-free (ADR 0008, five rules): every decision is made from bytes plus the archive’s own internal member table; no payload is ever inflated to classify.
peel_archive: Peel a bare gz/bz2 wrapper, OR extract the single member of a one-member archive, to inner bytes. Multi-member archives (a collection, not a wrapped image) return Peel::NotPacked, as does anything unrecognized.
peel_archive_seekable: Peel a bare gz/bz2 wrapper, OR extract the single member of a one-member archive, to a seekable handle — streaming to a temp file when a decode is needed, or a zero-copy window when the member is stored verbatim. Multi-member archives (a collection) and split sets return PeelSource::NotPacked, as does anything unrecognized.
peel_bytes: Peel one outer BARE gzip/bzip2 compression layer from data. Archives (.tgz/.tbz2/.zip/.7z) are NOT peeled here — they are member lists; use [crate::archive::open]. name is an optional file-name hint.
reassemble: Reassemble a segmented image: a SegmentKind::SplitRaw set becomes a stitched ConcatSource; an SegmentKind::Ewf / SegmentKind::SplitVmdk set yields its ordered SegmentSources for a container reader’s backing; anything else is Reassembled::NotSegmented.
resolve: Fully resolve data down through every archive layer to a flat list of leaf files (and the directory entries seen along the way).
segment_sources: Produce the ordered per-segment PeeledSource handles for a segmented image, or Ok(None) when data is not a segment set. Each segment is materialized via its own crate::Access (in-place window / zran index / temp spill), in segment-number order — the primitive both reassemble and a container reader’s SegmentBacking build on.
sniff: Determine the packing format. Container identity (zip / 7z) is decided by magic; the tar-compression combos (.tgz/.tbz2/.tbz/.tb2) are distinguished from bare gzip/bzip2 by the file name (the outer magic alone can’t tell a gzipped tar from a gzipped single file).

Type Aliases§

Result