exarch_core/inspection/

manifest.rs

//! Archive manifest types for listing.

use std::path::Path;
use std::path::PathBuf;
use std::time::SystemTime;

use crate::ArchiveError;
use crate::Result;
use crate::ZipEntryIndex;
use crate::closed_enum::closed_enum;
use crate::formats::detect::ArchiveType;
use crate::security::fs_view::LinkKind;
use crate::security::fs_view::check_link_target_length;

/// Complete manifest of archive contents.
///
/// Generated by `list_archive()`, contains metadata about all entries
/// without extracting them to disk. Fields are private so that the entry
/// count and total size always agree with the stored entries.
///
/// # Examples
///
/// ```no_run
/// use exarch_core::SecurityConfig;
/// use exarch_core::list_archive;
///
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let config = SecurityConfig::default();
/// let manifest = list_archive("archive.tar.gz", &config)?;
///
/// for entry in manifest.entries() {
///     println!("{}: {} bytes", entry.path.display(), entry.size);
/// }
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct ArchiveManifest {
    entries: Vec<ArchiveEntry>,
    oversized: Vec<OversizedEntry>,
    total_size: u64,
    format: ArchiveType,
}

/// The position of an entry in an [`ArchiveManifest`], only obtainable from
/// the manifest that holds it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct EntryPosition(usize);

/// An entry whose path exceeds the host's name limits.
///
/// Only the position and the path length are kept, so an archive of many
/// entries with huge names cannot inflate the manifest. The entry is not in
/// [`ArchiveManifest::entries`].
///
/// # Examples
///
/// ```
/// use exarch_core::OversizedEntry;
///
/// let entry = OversizedEntry::new(3, 70_000);
/// assert_eq!(entry.index, 3);
/// assert_eq!(entry.bytes, 70_000);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct OversizedEntry {
    /// Zero-based position among the listed entries, kept and dropped
    pub index: usize,

    /// Length of the stored path in bytes
    pub bytes: usize,
}

impl OversizedEntry {
    /// Creates a record of the entry at `index` with a path of `bytes` bytes.
    #[must_use]
    pub const fn new(index: usize, bytes: usize) -> Self {
        Self { index, bytes }
    }
}

impl ArchiveManifest {
    /// Creates a new empty manifest.
    #[must_use]
    pub fn new(format: ArchiveType) -> Self {
        Self {
            entries: Vec::new(),
            oversized: Vec::new(),
            total_size: 0,
            format,
        }
    }

    /// Records an entry dropped for its over-long path; its position counts
    /// the kept and the dropped entries listed before it.
    pub(crate) fn add_oversized(&mut self, bytes: usize) {
        let index = self.entries.len() + self.oversized.len();
        self.oversized.push(OversizedEntry::new(index, bytes));
    }

    /// Returns the entries dropped because their path exceeds the host's
    /// limits; only the verification pre-flight produces any.
    #[must_use]
    pub fn oversized_entries(&self) -> &[OversizedEntry] {
        &self.oversized
    }

    /// Returns the position in [`entries`](Self::entries) of the ZIP entry
    /// with the given index, or `None` when that entry was dropped for its
    /// over-long path.
    ///
    /// ZIP entries are listed in index order, and the dropped ones record
    /// their listing position, so the kept entry's position is its index less
    /// the dropped entries before it.
    pub(crate) fn position_of_zip_entry(&self, index: ZipEntryIndex) -> Option<usize> {
        let index = index.get();
        let dropped_before = self.oversized.partition_point(|o| o.index < index);
        if self
            .oversized
            .get(dropped_before)
            .is_some_and(|o| o.index == index)
        {
            return None;
        }
        let position = index - dropped_before;
        (position < self.entries.len()).then_some(position)
    }

    /// Adds an entry to the manifest.
    ///
    /// # Errors
    ///
    /// Returns [`ArchiveError::InvalidArchive`] if the total uncompressed size
    /// would overflow `u64`.
    ///
    /// # Examples
    ///
    /// ```
    /// use std::path::PathBuf;
    ///
    /// use exarch_core::ArchiveEntry;
    /// use exarch_core::ArchiveManifest;
    /// use exarch_core::ManifestEntryKind;
    /// use exarch_core::formats::detect::ArchiveType;
    ///
    /// let mut manifest = ArchiveManifest::new(ArchiveType::Tar);
    /// let entry = ArchiveEntry::new(PathBuf::from("a.txt"), ManifestEntryKind::File, 10);
    /// manifest.add_entry(entry)?;
    /// assert_eq!(manifest.total_entries(), 1);
    /// assert_eq!(manifest.total_size(), 10);
    /// # Ok::<(), exarch_core::ArchiveError>(())
    /// ```
    pub fn add_entry(&mut self, entry: ArchiveEntry) -> Result<()> {
        self.total_size = self.total_size.checked_add(entry.size).ok_or_else(|| {
            ArchiveError::InvalidArchive("archive total size overflows u64".to_string())
        })?;
        self.entries.push(entry);
        Ok(())
    }

    /// The position the next added entry takes.
    pub(crate) fn next_position(&self) -> EntryPosition {
        EntryPosition(self.entries.len())
    }

    /// Sets the target of the symlink entry at `position`, which listing reads
    /// after the entry was added. Any other entry is left alone.
    pub(crate) fn set_link_target(&mut self, position: EntryPosition, target: LinkTarget) {
        if let Some(ArchiveEntry {
            kind: ManifestEntryKind::Symlink { target: slot },
            ..
        }) = self.entries.get_mut(position.0)
        {
            *slot = target;
        }
    }

    /// Returns all entries in the archive (files, dirs, symlinks, hardlinks).
    #[must_use]
    pub fn entries(&self) -> &[ArchiveEntry] {
        &self.entries
    }

    /// Consumes the manifest and returns its entries.
    #[must_use]
    pub fn into_entries(self) -> Vec<ArchiveEntry> {
        self.entries
    }

    /// Returns the total number of entries.
    #[must_use]
    pub fn total_entries(&self) -> usize {
        self.entries.len()
    }

    /// Returns the total uncompressed size in bytes.
    #[must_use]
    pub const fn total_size(&self) -> u64 {
        self.total_size
    }

    /// Returns the archive format.
    #[must_use]
    pub const fn format(&self) -> ArchiveType {
        self.format
    }
}

/// Single entry in archive manifest.
///
/// Contains metadata about a file, directory, symlink, or hardlink
/// without extracting it to disk. Construct with [`ArchiveEntry::new`] and
/// assign the optional fields.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct ArchiveEntry {
    /// Entry path (relative, as stored in archive)
    pub path: PathBuf,

    /// Entry kind; link kinds carry their target
    pub kind: ManifestEntryKind,

    /// Uncompressed size in bytes (0 for directories)
    pub size: u64,

    /// How this entry's data is compressed, as far as the format exposes it
    pub compression: EntryCompression,

    /// File permissions (Unix mode)
    pub mode: Option<u32>,

    /// Modification time
    pub modified: Option<SystemTime>,
}

impl ArchiveEntry {
    /// Creates an entry with all optional metadata unset.
    #[must_use]
    pub const fn new(path: PathBuf, kind: ManifestEntryKind, size: u64) -> Self {
        Self {
            path,
            kind,
            size,
            compression: EntryCompression::Unknown,
            mode: None,
            modified: None,
        }
    }

    /// Returns the compressed size in bytes when the format reports one.
    ///
    /// For the first file of a solid block this is the size of the whole
    /// block; other solid members report `None`.
    #[must_use]
    pub const fn compressed_size(&self) -> Option<u64> {
        self.compression.compressed_size()
    }

    /// Returns the compression ratio of an entry that owns its compressed
    /// data, or `None` when none can be attributed to it (TAR, solid members,
    /// empty entries).
    #[must_use]
    pub fn compression_ratio(&self) -> Option<f64> {
        self.compression
            .entry_compressed_size()
            .filter(|&c| c > 0)
            .map(|c| self.size as f64 / c as f64)
    }
}

/// Compressed and uncompressed totals of one solid block.
///
/// # Examples
///
/// ```
/// use exarch_core::SolidBlock;
///
/// let block = SolidBlock::new(100, 13_800);
/// assert_eq!(block.compressed, 100);
/// assert_eq!(block.uncompressed, 13_800);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct SolidBlock {
    /// Sum of the block's pack stream sizes in bytes
    pub compressed: u64,

    /// Sum of the uncompressed sizes of every file in the block
    pub uncompressed: u64,
}

impl SolidBlock {
    /// Creates a block from its compressed and uncompressed totals.
    #[must_use]
    pub const fn new(compressed: u64, uncompressed: u64) -> Self {
        Self {
            compressed,
            uncompressed,
        }
    }
}

/// How an archive entry's data is compressed.
///
/// Solid 7z members share one compressed stream, so only the block as a whole
/// has a meaningful ratio; encoding that here keeps a per-file ratio from
/// being computed for them.
///
/// # Examples
///
/// ```
/// use exarch_core::EntryCompression;
///
/// assert_eq!(EntryCompression::Entry(40).compressed_size(), Some(40));
/// assert_eq!(EntryCompression::Unknown.compressed_size(), None);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum EntryCompression {
    /// The format does not expose a compressed size (TAR) or the entry has no
    /// data stream (empty 7z files)
    Unknown,

    /// The entry owns this many compressed bytes (ZIP, 7z single-file block)
    Entry(u64),

    /// First file of a solid block; carries the totals of the whole block
    SolidBlockStart(SolidBlock),

    /// Later file of a solid block; its data is accounted to the block start
    SolidBlockMember,
}

impl EntryCompression {
    /// Compressed size to report for the entry: the entry's own size, or the
    /// whole block's size for a solid block start.
    #[must_use]
    pub const fn compressed_size(&self) -> Option<u64> {
        match self {
            Self::Entry(compressed) => Some(*compressed),
            Self::SolidBlockStart(block) => Some(block.compressed),
            Self::Unknown | Self::SolidBlockMember => None,
        }
    }

    /// Compressed size owned by the entry alone, for per-file ratio checks.
    #[must_use]
    pub const fn entry_compressed_size(&self) -> Option<u64> {
        match self {
            Self::Entry(compressed) => Some(*compressed),
            Self::Unknown | Self::SolidBlockStart(_) | Self::SolidBlockMember => None,
        }
    }
}

/// Link target of a manifest entry, as far as the listing could keep it.
///
/// An over-long target is not retained: only its byte length is kept, so an
/// archive of many links with huge targets cannot inflate the manifest.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// use exarch_core::LinkKind;
/// use exarch_core::LinkTarget;
///
/// assert_eq!(
///     LinkTarget::Recorded("a.txt".into()).path(),
///     Some(Path::new("a.txt"))
/// );
/// assert_eq!(LinkTarget::Oversized { bytes: 9000 }.path(), None);
/// // 40000 exceeds the path limit of every supported host
/// assert_eq!(
///     LinkTarget::classify("x".repeat(40_000).into(), LinkKind::Symlink),
///     LinkTarget::Oversized { bytes: 40_000 }
/// );
/// assert_eq!(LinkTarget::Missing.path(), None);
/// assert_eq!(LinkTarget::Unread.path(), None);
/// assert_eq!(LinkTarget::Unreadable.path(), None);
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum LinkTarget {
    /// Target as stored in the archive, within the host's name limits
    Recorded(PathBuf),

    /// The archive stores no target
    Missing,

    /// The archive stores a target that was not read: a 7z target kept in
    /// compressed entry data, left alone by a listing that skips stored
    /// targets (the default), by a verification without an integrity check, or
    /// by an integrity pass whose budget or admission limits did not reach it
    Unread,

    /// The archive stores a target that could not be read: a 7z reparse point
    /// (in every listing), or a 7z target whose read was attempted and failed
    /// because its block is refused for decoding or its data is corrupt
    Unreadable,

    /// The target exceeds the host's name limits; only its length is kept
    Oversized {
        /// Length of the stored target in bytes
        bytes: usize,
    },
}

impl LinkTarget {
    /// Keeps `path` when it fits the host's limits for `kind`, otherwise
    /// drops it and keeps only its length.
    ///
    /// # Examples
    ///
    /// ```
    /// use std::assert_matches;
    ///
    /// use exarch_core::LinkKind;
    /// use exarch_core::LinkTarget;
    ///
    /// let long_component: std::path::PathBuf = "x".repeat(300).into();
    /// assert_matches!(
    ///     LinkTarget::classify(long_component.clone(), LinkKind::Symlink),
    ///     LinkTarget::Recorded(_)
    /// );
    /// assert_eq!(
    ///     LinkTarget::classify(long_component, LinkKind::Hardlink),
    ///     LinkTarget::Oversized { bytes: 300 }
    /// );
    /// ```
    #[must_use]
    pub fn classify(path: PathBuf, kind: LinkKind) -> Self {
        if check_link_target_length(&path, kind).is_ok() {
            Self::Recorded(path)
        } else {
            Self::Oversized {
                bytes: path.as_os_str().len(),
            }
        }
    }

    /// Returns the recorded target, or `None` when it is missing or oversized.
    #[must_use]
    pub fn path(&self) -> Option<&Path> {
        match self {
            Self::Recorded(path) => Some(path),
            Self::Missing | Self::Unread | Self::Unreadable | Self::Oversized { .. } => None,
        }
    }
}

/// Kind of a manifest entry; link kinds carry their target.
///
/// The target lives in the variant, so a regular file cannot carry one.
/// [`LinkTarget::Missing`] and [`LinkTarget::Oversized`] occur only in entries
/// produced by the pre-flight listing that
/// [`verify_archive`](crate::verify_archive) uses, where such a target must
/// become a report issue instead of a listing error. 7z link targets are
/// [`LinkTarget::Unread`] by default, in verification without an integrity
/// check, and for links an integrity pass did not reach (budget or admission
/// limits). [`LinkTarget::Unreadable`] marks a 7z reparse point in every
/// listing, and a target whose read was attempted and failed.
///
/// # Examples
///
/// ```
/// use std::path::Path;
///
/// use exarch_core::LinkTarget;
/// use exarch_core::ManifestEntryKind;
/// use exarch_core::ManifestEntryType;
///
/// let kind = ManifestEntryKind::Symlink {
///     target: LinkTarget::Recorded("a.txt".into()),
/// };
/// assert_eq!(kind.entry_type(), ManifestEntryType::Symlink);
/// assert_eq!(kind.link_target(), Some(Path::new("a.txt")));
/// assert_eq!(ManifestEntryKind::File.link_target(), None);
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum ManifestEntryKind {
    /// Regular file
    File,

    /// Directory
    Directory,

    /// Symbolic link
    Symlink {
        /// Link target as stored in the archive
        target: LinkTarget,
    },

    /// Hard link
    Hardlink {
        /// Link target as stored in the archive
        target: LinkTarget,
    },
}

impl ManifestEntryKind {
    /// Returns the wire tag of this kind.
    #[must_use]
    pub const fn entry_type(&self) -> ManifestEntryType {
        match self {
            Self::File => ManifestEntryType::File,
            Self::Directory => ManifestEntryType::Directory,
            Self::Symlink { .. } => ManifestEntryType::Symlink,
            Self::Hardlink { .. } => ManifestEntryType::Hardlink,
        }
    }

    /// Returns `true` for a symlink or a hardlink.
    #[must_use]
    pub const fn is_link(&self) -> bool {
        matches!(self, Self::Symlink { .. } | Self::Hardlink { .. })
    }

    /// Returns the target of a symlink, if one was recorded.
    #[must_use]
    pub fn symlink_target(&self) -> Option<&Path> {
        match self {
            Self::Symlink { target } => target.path(),
            Self::File | Self::Directory | Self::Hardlink { .. } => None,
        }
    }

    /// Returns the target of a hardlink, if one was recorded.
    #[must_use]
    pub fn hardlink_target(&self) -> Option<&Path> {
        match self {
            Self::Hardlink { target } => target.path(),
            Self::File | Self::Directory | Self::Symlink { .. } => None,
        }
    }

    /// Returns the link target of a symlink or hardlink, if one was recorded.
    #[must_use]
    pub fn link_target(&self) -> Option<&Path> {
        self.symlink_target().or_else(|| self.hardlink_target())
    }
}

closed_enum! {
    /// Entry type in manifest (does NOT require validation).
    ///
    /// Unlike `EntryType`, this enum is used for read-only listing
    /// and does not enforce security constraints.
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub enum ManifestEntryType {
        /// Regular file
        File => "File",

        /// Directory
        Directory => "Directory",

        /// Symbolic link
        Symlink => "Symlink",

        /// Hard link
        Hardlink => "Hardlink",
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used)]
mod tests {
    use std::assert_matches;

    use super::*;

    #[test]
    fn test_manifest_new() {
        let manifest = ArchiveManifest::new(ArchiveType::TarGz);
        assert_eq!(manifest.total_entries(), 0);
        assert_eq!(manifest.total_size(), 0);
        assert!(manifest.entries().is_empty());
        assert_eq!(manifest.format(), ArchiveType::TarGz);
    }

    #[test]
    fn test_manifest_add_entry() {
        let mut manifest = ArchiveManifest::new(ArchiveType::TarGz);

        let entry = ArchiveEntry {
            path: PathBuf::from("file.txt"),
            kind: ManifestEntryKind::File,
            size: 1024,
            compression: EntryCompression::Entry(512),
            mode: Some(0o644),
            modified: None,
        };

        manifest.add_entry(entry).unwrap();

        assert_eq!(manifest.total_entries(), 1);
        assert_eq!(manifest.total_size(), 1024);
        assert_eq!(manifest.entries().len(), 1);
    }

    #[test]
    fn test_manifest_add_entry_size_overflow() {
        let mut manifest = ArchiveManifest::new(ArchiveType::Tar);
        let big = ArchiveEntry::new(PathBuf::from("a"), ManifestEntryKind::File, u64::MAX);
        manifest.add_entry(big).unwrap();

        let more = ArchiveEntry::new(PathBuf::from("b"), ManifestEntryKind::File, 1);
        assert_matches!(
            manifest.add_entry(more),
            Err(ArchiveError::InvalidArchive(_))
        );
        assert_eq!(manifest.total_entries(), 1);
        assert_eq!(manifest.total_size(), u64::MAX);
    }

    #[test]
    fn test_compression_ratio() {
        let entry = ArchiveEntry {
            path: PathBuf::from("file.txt"),
            kind: ManifestEntryKind::File,
            size: 1000,
            compression: EntryCompression::Entry(100),
            mode: None,
            modified: None,
        };

        assert_eq!(entry.compression_ratio(), Some(10.0));
    }

    #[test]
    fn test_compression_ratio_no_compressed() {
        let entry = ArchiveEntry {
            path: PathBuf::from("file.txt"),
            kind: ManifestEntryKind::File,
            size: 1000,
            compression: EntryCompression::Unknown,
            mode: None,
            modified: None,
        };

        assert_eq!(entry.compression_ratio(), None);
    }

    #[test]
    fn test_solid_entries_have_no_per_file_ratio() {
        let mut entry = ArchiveEntry::new(PathBuf::from("a"), ManifestEntryKind::File, 1000);
        entry.compression = EntryCompression::SolidBlockStart(SolidBlock::new(10, 2000));
        assert_eq!(entry.compression_ratio(), None);
        assert_eq!(entry.compressed_size(), Some(10));

        entry.compression = EntryCompression::SolidBlockMember;
        assert_eq!(entry.compression_ratio(), None);
        assert_eq!(entry.compressed_size(), None);
    }

    #[test]
    fn test_manifest_entry_type_display() {
        assert_eq!(ManifestEntryType::File.to_string(), "File");
        assert_eq!(ManifestEntryType::Directory.to_string(), "Directory");
        assert_eq!(ManifestEntryType::Symlink.to_string(), "Symlink");
        assert_eq!(ManifestEntryType::Hardlink.to_string(), "Hardlink");
    }

    #[test]
    fn test_position_of_zip_entry_skips_dropped_entries() {
        let mut manifest = ArchiveManifest::new(ArchiveType::Zip);
        manifest.add_oversized(300);
        for name in ["a", "b"] {
            let entry = ArchiveEntry::new(PathBuf::from(name), ManifestEntryKind::File, 0);
            manifest.add_entry(entry).unwrap();
        }
        manifest.add_oversized(300);

        let position = |index| manifest.position_of_zip_entry(ZipEntryIndex::new(index));
        assert_eq!(position(0), None);
        assert_eq!(position(1), Some(0));
        assert_eq!(position(2), Some(1));
        assert_eq!(position(3), None);
        assert_eq!(position(9), None);
    }
}