dream_archive 0.2.2

Pure-Rust Bethesda BA2 and BSA archive reader, extractor, and writer
Documentation
use super::{
    Archive, ArchiveFlags, ArchiveInfo, ArchiveTypes, ArchiveVersion, Entry, Error, FileRecord,
    HashFields, Result,
};
use crate::BString;
use crate::{read::Cursor, storage::Storage};

const MAGIC: u32 = u32::from_le_bytes(*b"BSA\0");
const HEADER_SIZE: u32 = 0x24;

pub(super) fn parse(storage: Storage) -> Result<Archive> {
    let bytes = storage.as_bytes();
    let info = read_header(bytes)?;
    let entries = read_entries(bytes, info)?;
    Ok(Archive::from_parts(storage, info, entries))
}

fn read_header(bytes: &[u8]) -> Result<ArchiveInfo> {
    let mut cursor = Cursor::new(bytes);
    let magic = cursor.u32()?;
    if magic != MAGIC {
        return Err(Error::InvalidMagic(magic));
    }

    let version = match cursor.u32()? {
        103 => ArchiveVersion::v103,
        104 => ArchiveVersion::v104,
        105 => ArchiveVersion::v105,
        raw => return Err(Error::InvalidVersion(raw)),
    };

    let folder_record_offset = cursor.u32()?;
    if folder_record_offset != HEADER_SIZE {
        return Err(Error::InvalidHeaderSize(folder_record_offset));
    }

    let archive_flags = ArchiveFlags::from_bits_retain(cursor.u32()?);
    if archive_flags.contains(ArchiveFlags::XBOX_ARCHIVE) {
        return Err(Error::NotImplemented("TES4 Xbox archive layout"));
    }
    // Oblivion's v103 archives set the XMem bit on PC too; it only means XMem from v104.
    if version != ArchiveVersion::v103
        && archive_flags.contains(ArchiveFlags::COMPRESSED)
        && archive_flags.contains(ArchiveFlags::XBOX_COMPRESSED)
    {
        return Err(Error::NotImplemented("TES4 XMem compression"));
    }
    let folder_count = cursor.u32()?;
    let file_count = cursor.u32()?;
    let folder_names_len = cursor.u32()?;
    let file_names_len = cursor.u32()?;
    let archive_types = ArchiveTypes::from_bits_retain(cursor.u16()?);
    let _padding = cursor.u16()?;

    Ok(ArchiveInfo {
        version,
        folder_record_offset,
        archive_flags,
        folder_count,
        file_count,
        folder_names_len,
        file_names_len,
        archive_types,
    })
}

#[derive(Clone, Copy)]
struct FolderRecord {
    hash: HashFields,
    file_count: u32,
    file_records_offset: u64,
}

#[derive(Clone, Copy)]
struct ParsedFileRecord {
    hash: HashFields,
    record: FileRecord,
}

fn read_entries(bytes: &[u8], info: ArchiveInfo) -> Result<Vec<Entry>> {
    let mut cursor = Cursor::new(bytes);
    cursor.seek(info.folder_record_offset.try_into()?)?;
    let folder_count = info.folder_count.try_into()?;
    let mut folders = Vec::new();
    folders.try_reserve_exact(folder_count)?;
    let mut parsed_file_count = 0u32;
    for _ in 0..info.folder_count {
        let folder = read_folder_record(&mut cursor, info.version)?;
        parsed_file_count = parsed_file_count
            .checked_add(folder.file_count)
            .ok_or(Error::OutOfBounds)?;
        folders.push(folder);
    }
    if parsed_file_count != info.file_count {
        return Err(Error::OutOfBounds);
    }

    let mut entries = Vec::new();
    entries.try_reserve_exact(info.file_count.try_into()?)?;
    for folder in folders {
        let file_records_offset: usize = folder.file_records_offset.try_into()?;
        // Real PC archives are not consistent enough to seek to this field here:
        // some tools point at the file records, while fixtures generated by
        // known-compatible tools use the folder block start. Treat it as a
        // lower-bound sanity check and read the contiguous folder block layout.
        if file_records_offset < cursor.position() || file_records_offset > bytes.len() {
            return Err(Error::OutOfBounds);
        }
        let folder_name = if info.archive_flags.contains(ArchiveFlags::DIRECTORY_STRINGS) {
            Some(normalize_folder_name(read_bzstring(&mut cursor)?))
        } else {
            None
        };
        let mut records = Vec::new();
        records.try_reserve_exact(folder.file_count.try_into()?)?;
        for _ in 0..folder.file_count {
            records.push(read_file_record(&mut cursor)?);
        }
        entries.extend(
            records
                .into_iter()
                .map(|record| (folder_name.clone(), folder.hash, record)),
        );
    }

    let file_names_offset = cursor.position();
    let file_names_len: usize = info.file_names_len.try_into()?;
    let file_names_end = file_names_offset
        .checked_add(file_names_len)
        .ok_or(Error::OutOfBounds)?;
    let mut names = Cursor::new(
        bytes
            .get(file_names_offset..file_names_end)
            .ok_or(Error::OutOfBounds)?,
    );
    let entries = entries
        .into_iter()
        .map(|(folder, folder_hash, record)| {
            let embedded_name = read_embedded_name(bytes, info, record.record)?;
            let folder = folder.or_else(|| embedded_name.as_ref().map(|name| name.0.clone()));
            let name = if info.archive_flags.contains(ArchiveFlags::FILE_STRINGS) {
                Some(read_zstring(&mut names)?)
            } else {
                None
            }
            .or_else(|| embedded_name.map(|name| name.1));
            Ok(Entry::new(
                folder,
                name,
                folder_hash,
                record.hash,
                record.record,
            ))
        })
        .collect::<Result<Vec<_>>>()?;
    // Fallout 3's voice archives pad the name block with NULs after the last name.
    let padding = bytes
        .get(file_names_offset + names.position()..file_names_end)
        .ok_or(Error::OutOfBounds)?;
    if padding.iter().any(|byte| *byte != 0) {
        return Err(Error::OutOfBounds);
    }
    for entry in &entries {
        validate_file_extent(entry.file(), file_names_end, bytes.len())?;
    }
    Ok(entries)
}

fn read_folder_record(cursor: &mut Cursor<'_>, version: ArchiveVersion) -> Result<FolderRecord> {
    let hash = read_hash(cursor)?;
    let file_count = cursor.u32()?;
    let file_records_offset = match version {
        ArchiveVersion::v103 | ArchiveVersion::v104 => u64::from(cursor.u32()?),
        ArchiveVersion::v105 => {
            let _unknown = cursor.u32()?;
            cursor.u64()?
        }
    };
    Ok(FolderRecord {
        hash,
        file_count,
        file_records_offset,
    })
}

fn read_file_record(cursor: &mut Cursor<'_>) -> Result<ParsedFileRecord> {
    let hash = read_hash(cursor)?;
    let size = cursor.u32()?;
    let offset = cursor.u32()?;
    Ok(ParsedFileRecord {
        hash,
        record: FileRecord {
            stored_size: size & !(1 << 30 | 1 << 31),
            data_offset: offset & !(1 << 31),
            compression_toggled: size & (1 << 30) != 0,
            checked: size & (1 << 31) != 0,
        },
    })
}

fn read_hash(cursor: &mut Cursor<'_>) -> Result<HashFields> {
    Ok(HashFields {
        last: cursor.u8()?,
        last2: cursor.u8()?,
        length: cursor.u8()?,
        first: cursor.u8()?,
        crc: cursor.u32()?,
    })
}

fn read_embedded_name(
    bytes: &[u8],
    info: ArchiveInfo,
    record: FileRecord,
) -> Result<Option<(BString, BString)>> {
    if !matches!(info.version, ArchiveVersion::v104 | ArchiveVersion::v105)
        || !info
            .archive_flags
            .contains(ArchiveFlags::EMBEDDED_FILE_NAMES)
    {
        return Ok(None);
    }

    let start: usize = record.data_offset.try_into()?;
    let stored_size: usize = record.stored_size.try_into()?;
    let stored = bytes
        .get(start..start.checked_add(stored_size).ok_or(Error::OutOfBounds)?)
        .ok_or(Error::OutOfBounds)?;
    let embedded_name_len = usize::from(stored.first().copied().ok_or(Error::OutOfBounds)?);
    let end = 1usize
        .checked_add(embedded_name_len)
        .ok_or(Error::OutOfBounds)?;
    let embedded_name = stored.get(1..end).ok_or(Error::OutOfBounds)?;
    let Some(name_start) = embedded_name
        .iter()
        .rposition(|byte| matches!(*byte, b'/' | b'\\'))
    else {
        return Ok(Some((
            BString::new(Vec::new()),
            BString::from(embedded_name),
        )));
    };
    Ok(Some((
        BString::from(&embedded_name[..name_start]),
        BString::from(&embedded_name[name_start + 1..]),
    )))
}

fn validate_file_extent(
    record: FileRecord,
    payload_start: usize,
    archive_size: usize,
) -> Result<()> {
    let start: usize = record.data_offset.try_into()?;
    let len: usize = record.stored_size.try_into()?;
    if start < payload_start || start.checked_add(len).ok_or(Error::OutOfBounds)? > archive_size {
        return Err(Error::OutOfBounds);
    }
    Ok(())
}

fn read_bzstring(cursor: &mut Cursor<'_>) -> Result<BString> {
    let len = cursor.u8()? as usize;
    let bytes = cursor.bytes(len)?;
    if !bytes.ends_with(&[0]) {
        return Err(crate::read::Error::UnexpectedEof.into());
    }
    Ok(BString::from(strip_nul(bytes)))
}

fn read_zstring(cursor: &mut Cursor<'_>) -> Result<BString> {
    let mut out = Vec::new();
    loop {
        let byte = cursor.u8()?;
        if byte == 0 {
            return Ok(BString::from(out));
        }
        out.push(byte);
    }
}

fn strip_nul(bytes: &[u8]) -> Vec<u8> {
    bytes.strip_suffix(&[0]).unwrap_or(bytes).to_vec()
}

fn normalize_folder_name(name: BString) -> BString {
    if name.as_slice() == b"." {
        BString::new(Vec::new())
    } else {
        name
    }
}