dream_archivetool 0.1.0

Inspect, extract, create, and update Bethesda BSA and BA2 archives
Documentation
// SPDX-License-Identifier: GPL-3.0-or-later

use std::collections::BTreeMap;
use std::collections::btree_map::Entry;
use std::io::Write;
use std::path::Path;

use serde::{Deserialize, Serialize};

use crate::paths::{archive_path_bytes_to_display, archive_path_bytes_to_hex};
use crate::{ArchiveError, Result};

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
/// Options controlling archive comparison.
pub struct DiffOptions {
    /// Compute a fast non-cryptographic FNV-1a payload fingerprint instead of comparing only
    /// listed metadata.
    pub fingerprint_payloads: bool,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// Archive comparison report.
#[non_exhaustive]
pub struct DiffReport {
    /// Old archive label/path formatted for display.
    pub old: String,
    /// New archive label/path formatted for display.
    pub new: String,
    /// How entries were compared. `metadata-only` does not prove payload equality.
    pub comparison: DiffComparison,
    /// Whether payload fingerprints were computed.
    pub fingerprint_payloads: bool,
    /// Entries present only in the new archive.
    pub added: Vec<DiffEntry>,
    /// Entries present only in the old archive.
    pub removed: Vec<DiffEntry>,
    /// Entries present in both archives but with different metadata or payload fingerprint.
    pub changed: Vec<DiffChange>,
    /// Number of entries considered unchanged.
    pub unchanged: usize,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
/// Diff comparison mode used for this report.
#[non_exhaustive]
pub enum DiffComparison {
    /// Compare listed metadata only. Entries with incomplete metadata can be reported unchanged even
    /// when payload bytes differ.
    MetadataOnly,
    /// Compare listed metadata and streamed non-cryptographic payload fingerprints.
    PayloadFingerprint,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// Entry present on one side of an archive diff.
#[non_exhaustive]
pub struct DiffEntry {
    /// Archive path formatted for display.
    pub path: String,
    /// Hex-encoded normalized archive-path lookup key, not raw identity.
    pub path_bytes_hex: String,
    /// Decompressed size when known.
    pub size: Option<u64>,
    /// Compressed size when known and applicable.
    pub compressed_size: Option<u64>,
    /// Non-cryptographic payload fingerprint when requested.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub payload_fingerprint: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// Entry present in both archives but with differing metadata or payload fingerprint.
#[non_exhaustive]
pub struct DiffChange {
    /// Archive path formatted for display.
    pub path: String,
    /// Hex-encoded normalized archive-path lookup key, not raw identity.
    pub path_bytes_hex: String,
    /// Old archive state for the changed entry.
    pub old: DiffEntryState,
    /// New archive state for the changed entry.
    pub new: DiffEntryState,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// Side-specific state for a changed entry.
#[non_exhaustive]
pub struct DiffEntryState {
    /// Decompressed size when known.
    pub size: Option<u64>,
    /// Compressed size when known and applicable.
    pub compressed_size: Option<u64>,
    /// Non-cryptographic payload fingerprint when requested.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub payload_fingerprint: Option<String>,
}

#[derive(Debug, Clone)]
struct DiffEntryData {
    raw_path: Vec<u8>,
    size: Option<u64>,
    compressed_size: Option<u64>,
    payload_fingerprint: Option<String>,
}

/// Compare two archives by normalized path bytes and metadata, optionally fingerprinting payloads.
///
/// # Errors
///
/// Returns an error if either archive cannot be opened or requested payload fingerprints cannot be read.
pub fn diff_archives(old: &Path, new: &Path, options: &DiffOptions) -> Result<DiffReport> {
    let old_archive = crate::loaded::LoadedArchive::open(old)?;
    let new_archive = crate::loaded::LoadedArchive::open(new)?;
    diff_loaded_archives(
        &old.display().to_string(),
        old_archive.as_ref(),
        &new.display().to_string(),
        new_archive.as_ref(),
        *options,
    )
}

pub(crate) fn diff_loaded_archives(
    old_label: &str,
    old_archive: crate::loaded::LoadedArchiveRef<'_>,
    new_label: &str,
    new_archive: crate::loaded::LoadedArchiveRef<'_>,
    options: DiffOptions,
) -> Result<DiffReport> {
    reject_unnameable_entries(old_archive, old_label)?;
    reject_unnameable_entries(new_archive, new_label)?;
    let old_entries = diff_entries(old_archive, options.fingerprint_payloads)?;
    let new_entries = diff_entries(new_archive, options.fingerprint_payloads)?;
    let mut added = Vec::new();
    let mut removed = Vec::new();
    let mut changed = Vec::new();
    let mut unchanged = 0;

    for (path, old_entry) in &old_entries {
        if let Some(new_entry) = new_entries.get(path) {
            if same_entry_state(old_entry, new_entry) {
                unchanged += 1;
            } else {
                changed.push(DiffChange {
                    path: archive_path_bytes_to_display(path),
                    path_bytes_hex: archive_path_bytes_to_hex(path),
                    old: entry_state(old_entry),
                    new: entry_state(new_entry),
                });
            }
        } else {
            removed.push(diff_entry(path, old_entry));
        }
    }
    for (path, new_entry) in &new_entries {
        if !old_entries.contains_key(path) {
            added.push(diff_entry(path, new_entry));
        }
    }

    Ok(DiffReport {
        old: old_label.to_string(),
        new: new_label.to_string(),
        comparison: if options.fingerprint_payloads {
            DiffComparison::PayloadFingerprint
        } else {
            DiffComparison::MetadataOnly
        },
        fingerprint_payloads: options.fingerprint_payloads,
        added,
        removed,
        changed,
        unchanged,
    })
}

fn reject_unnameable_entries(
    archive: crate::loaded::LoadedArchiveRef<'_>,
    label: &str,
) -> Result<()> {
    if archive.has_unnameable_entries() {
        return Err(ArchiveError::Archive(format!(
            "archive '{label}' contains entries without recoverable paths; refusing to diff it lossy"
        )));
    }
    Ok(())
}

fn diff_entries(
    archive: crate::loaded::LoadedArchiveRef<'_>,
    fingerprint_payloads: bool,
) -> Result<BTreeMap<Vec<u8>, DiffEntryData>> {
    let mut entries = BTreeMap::new();
    for entry in archive.list_loaded_entries()? {
        let crate::loaded::LoadedEntry {
            raw_path,
            path,
            size,
            compressed_size,
        } = entry;
        let payload_fingerprint = if fingerprint_payloads {
            Some(payload_fingerprint(archive, &path)?)
        } else {
            None
        };
        let data = DiffEntryData {
            raw_path,
            size,
            compressed_size,
            payload_fingerprint,
        };
        match entries.entry(path) {
            Entry::Vacant(slot) => {
                slot.insert(data);
            }
            Entry::Occupied(slot) => {
                return Err(ArchiveError::Archive(format!(
                    "archive contains duplicate normalized path: {} (first raw path hex: {}, duplicate raw path hex: {})",
                    archive_path_bytes_to_display(slot.key()),
                    archive_path_bytes_to_hex(&slot.get().raw_path),
                    archive_path_bytes_to_hex(&data.raw_path)
                )));
            }
        }
    }
    Ok(entries)
}

fn payload_fingerprint(
    archive: crate::loaded::LoadedArchiveRef<'_>,
    path: &[u8],
) -> Result<String> {
    let mut hasher = Fnv1a64Writer::default();
    archive.extract_normalized_entry_path_to_writer(path, &mut hasher)?;
    Ok(format!("{:016x}", hasher.finish()))
}

#[derive(Debug)]
struct Fnv1a64Writer {
    hash: u64,
}

impl Default for Fnv1a64Writer {
    fn default() -> Self {
        Self {
            hash: FNV1A64_OFFSET,
        }
    }
}

impl Fnv1a64Writer {
    fn finish(self) -> u64 {
        self.hash
    }
}

impl Write for Fnv1a64Writer {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        self.hash = fnv1a64_update(self.hash, buf);
        Ok(buf.len())
    }

    fn flush(&mut self) -> std::io::Result<()> {
        Ok(())
    }
}

fn same_entry_state(left: &DiffEntryData, right: &DiffEntryData) -> bool {
    left.size == right.size
        && left.compressed_size == right.compressed_size
        && left.payload_fingerprint == right.payload_fingerprint
}

fn diff_entry(path: &[u8], entry: &DiffEntryData) -> DiffEntry {
    DiffEntry {
        path: archive_path_bytes_to_display(path),
        path_bytes_hex: archive_path_bytes_to_hex(path),
        size: entry.size,
        compressed_size: entry.compressed_size,
        payload_fingerprint: entry.payload_fingerprint.clone(),
    }
}

fn entry_state(entry: &DiffEntryData) -> DiffEntryState {
    DiffEntryState {
        size: entry.size,
        compressed_size: entry.compressed_size,
        payload_fingerprint: entry.payload_fingerprint.clone(),
    }
}

#[cfg(test)]
fn fnv1a64(bytes: &[u8]) -> u64 {
    fnv1a64_update(FNV1A64_OFFSET, bytes)
}

const FNV1A64_OFFSET: u64 = 0xcbf2_9ce4_8422_2325;

fn fnv1a64_update(mut hash: u64, bytes: &[u8]) -> u64 {
    for byte in bytes {
        hash ^= u64::from(*byte);
        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
    }
    hash
}

#[cfg(test)]
mod tests {
    use std::io::Write as _;

    use super::*;

    #[test]
    fn streaming_fnv_matches_whole_buffer_hash() {
        let mut writer = Fnv1a64Writer::default();
        writer.write_all(b"abc").unwrap();
        writer.write_all(b"def").unwrap();
        assert_eq!(writer.finish(), fnv1a64(b"abcdef"));
    }
}