rakata_formats/bif/

reader.rs

//! BIF binary reader.

use std::io::Read;

use rakata_core::ResourceId;

use super::layout::{self, BifHeader, BifTableEntry};
use super::{binary, Bif, BifBinaryError, BifContainer, BifReadOptions, BifResource};

/// Reads a BIF archive from a reader.
///
/// The stream is consumed from its current position.
///
/// # Errors
///
/// The same as [`read_bif_with_options`] under
/// [`BifReadMode::CanonicalK1`](crate::bif::BifReadMode::CanonicalK1), which
/// requires `V1  ` and loads only variable-table entries, the way the K1
/// runtime does.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(reader))
)]
pub fn read_bif<R: Read>(reader: &mut R) -> Result<Bif, BifBinaryError> {
    read_bif_with_options(reader, BifReadOptions::default())
}

/// Reads a BIF archive from a reader with explicit options.
///
/// # Errors
///
/// [`BifBinaryError::Io`] when the stream will not read to end, and whatever
/// [`read_bif_from_bytes_with_options`] reports for the bytes it collected.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(reader))
)]
pub fn read_bif_with_options<R: Read>(
    reader: &mut R,
    options: BifReadOptions,
) -> Result<Bif, BifBinaryError> {
    let mut bytes = Vec::new();
    reader.read_to_end(&mut bytes)?;
    crate::trace_debug!(bytes_len = bytes.len(), "read bif/bzf bytes from reader");
    read_bif_from_bytes_with_options(&bytes, options)
}

/// Reads a BIF archive from bytes.
///
/// # Errors
///
/// The same as [`read_bif_from_bytes_with_options`] under
/// [`BifReadMode::CanonicalK1`](crate::bif::BifReadMode::CanonicalK1).
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(bytes), fields(bytes_len = bytes.len()))
)]
pub fn read_bif_from_bytes(bytes: &[u8]) -> Result<Bif, BifBinaryError> {
    read_bif_from_bytes_with_options(bytes, BifReadOptions::default())
}

/// Reads a BIF archive from bytes with explicit options.
///
/// # Errors
///
/// [`BifBinaryError::InvalidMagic`] when the signature is neither `BIFF` nor
/// `BZF `, and [`BifBinaryError::InvalidVersion`] for a version
/// `options.input` does not accept: `CanonicalK1` takes `V1  ` alone, where
/// [`CompatibilityAurora`](crate::bif::BifReadMode::CompatibilityAurora) also
/// takes `V1.1`.
///
/// [`BifBinaryError::InvalidHeader`] when the header is truncated, either
/// table runs past the end of `bytes`, or the two entry counts sum past
/// `u32`. [`BifBinaryError::InvalidData`] when an entry's declared data slice
/// escapes the archive.
///
/// [`BifBinaryError::BzfFeatureDisabled`] for a `BZF ` archive when the crate
/// was built without the `bzf` feature. The signature is recognised either
/// way, so this says the payload cannot be decompressed rather than that the
/// file is unknown.
///
/// A BIF names no resources: the resrefs live in the `chitin.key` that points
/// at it, so nothing here can fail on a name.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(bytes), fields(bytes_len = bytes.len()))
)]
pub fn read_bif_from_bytes_with_options(
    bytes: &[u8],
    options: BifReadOptions,
) -> Result<Bif, BifBinaryError> {
    let header = BifHeader::parse(bytes, options)?;
    let variable_table_size = header.variable_table_size()?;
    binary::check_slice_in_bounds(
        bytes,
        header.variable_table_offset,
        variable_table_size,
        "variable resource table",
    )?;
    let variable_table = bytes
        .get(header.variable_table_offset..header.variable_table_offset + variable_table_size)
        .ok_or_else(|| BifBinaryError::InvalidData("variable resource table is missing".into()))?;

    let total_entry_count = if header.parse_fixed_entries {
        header
            .variable_count
            .checked_add(header.fixed_count)
            .ok_or_else(|| BifBinaryError::InvalidHeader("resource count overflow".into()))?
    } else {
        header.variable_count
    };
    let mut resource_entries = Vec::with_capacity(total_entry_count);
    for resource_index in 0..header.variable_count {
        resource_entries.push(layout::parse_variable_entry(
            variable_table,
            resource_index,
        )?);
    }

    if header.parse_fixed_entries {
        let fixed_table_size = header.fixed_table_size()?;
        binary::check_slice_in_bounds(
            bytes,
            header.fixed_table_offset,
            fixed_table_size,
            "fixed resource table",
        )?;
        let fixed_table = bytes
            .get(header.fixed_table_offset..header.fixed_table_offset + fixed_table_size)
            .ok_or_else(|| BifBinaryError::InvalidData("fixed resource table is missing".into()))?;
        for fixed_index in 0..header.fixed_count {
            resource_entries.push(layout::parse_fixed_entry(fixed_table, fixed_index)?);
        }
    }

    let mut resources = Vec::with_capacity(resource_entries.len());
    for (resource_index, entry) in resource_entries.into_iter().enumerate() {
        let BifTableEntry {
            resource_id,
            resource_type,
            data_offset,
            data_size,
            storage,
            source_data_offset,
        } = entry;
        check_data_slice_in_bounds(
            bytes,
            data_offset,
            data_size,
            &format!("resource data[{resource_index}]"),
        )?;
        let data = bytes
            .get(data_offset..data_offset + data_size)
            .ok_or_else(|| {
                BifBinaryError::InvalidData(format!(
                    "resource data slice missing for index {resource_index}"
                ))
            })?
            .to_vec();

        resources.push(BifResource {
            resource_id: ResourceId::from_raw(resource_id),
            resource_type,
            storage,
            data,
            source_data_offset: Some(source_data_offset),
        });
    }

    let bif = Bif {
        container: BifContainer::Biff,
        resources,
    };
    crate::trace_debug!(
        container = ?bif.container,
        resource_count = bif.resources.len(),
        "parsed bif/bzf from bytes"
    );
    Ok(bif)
}

fn check_data_slice_in_bounds(
    bytes: &[u8],
    offset: usize,
    size: usize,
    label: &str,
) -> Result<(), BifBinaryError> {
    binary::check_slice_in_bounds(bytes, offset, size, label)
        .map_err(|error| BifBinaryError::InvalidData(error.to_string()))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::bif::{
        write_bif_to_vec, BifReadMode, BifResourceStorage, BIF_MAGIC, BIF_VERSION_V10,
        BIF_VERSION_V11, FILE_HEADER_SIZE, FIXED_ENTRY_SIZE,
    };
    // Only the `bzf`-off build has a test that needs this, so importing it
    // unconditionally would read as unused whenever the feature is on.
    #[cfg(not(feature = "bzf"))]
    use crate::bif::VARIABLE_ENTRY_SIZE;
    use rakata_core::{ResourceId, ResourceTypeCode};

    const K1_PLAYER_BIF: &[u8] = include_bytes!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/../../fixtures/k1_player.bif"
    ));

    #[test]
    fn parses_bif_fixture() {
        let bif = read_bif_from_bytes(K1_PLAYER_BIF).expect("fixture should parse");
        assert_eq!(bif.resources.len(), 3);

        let first = &bif.resources[0];
        assert_eq!(first.resource_id, ResourceId::from_raw(0x0140_0000));
        assert_eq!(first.resource_type.raw_id(), 2002);

        let second = &bif.resources[1];
        assert_eq!(second.resource_id, ResourceId::from_raw(0x0140_0001));
        assert_eq!(second.resource_type.raw_id(), 3008);
    }

    #[test]
    fn roundtrip_synthetic_bif() {
        let mut bif = Bif::new();
        bif.push_resource(
            ResourceId::from_raw(0x0010_0000),
            ResourceTypeCode::from_raw_id(2017),
            b"abc".to_vec(),
        );
        bif.push_resource(
            ResourceId::from_raw(0x0010_0001),
            ResourceTypeCode::from_raw_id(2018),
            b"defghi".to_vec(),
        );

        let bytes = write_bif_to_vec(&bif).expect("write should succeed");
        let parsed = read_bif_from_bytes(&bytes).expect("read should succeed");

        assert_eq!(parsed, bif);
    }

    #[test]
    fn writer_is_deterministic_for_synthetic_bif() {
        let mut bif = Bif::new();
        bif.push_resource(
            ResourceId::from_raw(0x0010_0000),
            ResourceTypeCode::from_raw_id(2017),
            b"abc".to_vec(),
        );
        bif.push_resource(
            ResourceId::from_raw(0x0010_0001),
            ResourceTypeCode::from_raw_id(2018),
            b"defghi".to_vec(),
        );
        let first = write_bif_to_vec(&bif).expect("first write should succeed");
        let second = write_bif_to_vec(&bif).expect("second write should succeed");
        assert_eq!(first, second, "canonical BIF writer output drifted");
    }

    #[test]
    fn writer_aligns_payload_offsets_to_four_bytes() {
        let mut bif = Bif::new();
        bif.push_resource(
            ResourceId::from_raw(1),
            ResourceTypeCode::from_raw_id(10),
            vec![1, 2, 3],
        );
        bif.push_resource(
            ResourceId::from_raw(2),
            ResourceTypeCode::from_raw_id(10),
            vec![4, 5],
        );

        let bytes = write_bif_to_vec(&bif).expect("write should succeed");

        let first_offset = u32::from_le_bytes(bytes[24..28].try_into().expect("slice"));
        let second_offset = u32::from_le_bytes(bytes[40..44].try_into().expect("slice"));
        assert_eq!(first_offset, 52);
        assert_eq!(second_offset, 56);
    }

    #[test]
    fn roundtrip_preserves_unknown_resource_type_ids() {
        let mut bif = Bif::new();
        bif.push_resource(
            ResourceId::from_raw(7),
            ResourceTypeCode::from_raw_id(42424),
            vec![1, 2, 3, 4],
        );

        let bytes = write_bif_to_vec(&bif).expect("write should succeed");
        let parsed = read_bif_from_bytes(&bytes).expect("read should succeed");

        assert_eq!(parsed.resources.len(), 1);
        assert_eq!(parsed.resources[0].resource_type.raw_id(), 42424);
        assert_eq!(parsed.resources[0].resource_type.known_type(), None);
    }

    #[test]
    fn roundtrip_includes_fixed_resource_entries() {
        let mut bif = Bif::new();
        bif.push_resource(
            ResourceId::from_raw(0x0010_0000),
            ResourceTypeCode::from_raw_id(2017),
            b"abc".to_vec(),
        );
        bif.push_fixed_resource(
            ResourceId::from_raw(0x0010_4000),
            ResourceTypeCode::from_raw_id(2027),
            3,
            b"fixed".to_vec(),
        );

        let bytes = write_bif_to_vec(&bif).expect("write should succeed");
        assert_eq!(
            u32::from_le_bytes(bytes[8..12].try_into().expect("slice")),
            1
        );
        assert_eq!(
            u32::from_le_bytes(bytes[12..16].try_into().expect("slice")),
            1
        );

        let parsed = read_bif_from_bytes_with_options(
            &bytes,
            BifReadOptions {
                input: BifReadMode::CompatibilityAurora,
            },
        )
        .expect("read should succeed");
        assert_eq!(parsed, bif);
        assert_eq!(
            parsed.resources[1].storage,
            BifResourceStorage::Fixed { part_count: 3 }
        );
    }

    #[test]
    fn parses_fixed_resource_table_entries() {
        let mut bytes = vec![0_u8; FILE_HEADER_SIZE + FIXED_ENTRY_SIZE + 4];
        bytes[0..4].copy_from_slice(&BIF_MAGIC);
        bytes[4..8].copy_from_slice(&BIF_VERSION_V10);
        bytes[12..16].copy_from_slice(&1_u32.to_le_bytes()); // fixed_count
        bytes[16..20].copy_from_slice(
            &u32::try_from(FILE_HEADER_SIZE)
                .expect("FILE_HEADER_SIZE fits in u32")
                .to_le_bytes(),
        );

        let fixed_base = FILE_HEADER_SIZE;
        bytes[fixed_base..fixed_base + 4].copy_from_slice(&0x0010_4000_u32.to_le_bytes()); // id
        bytes[fixed_base + 4..fixed_base + 8].copy_from_slice(
            &u32::try_from(FILE_HEADER_SIZE + FIXED_ENTRY_SIZE)
                .expect("header + entry size fits in u32")
                .to_le_bytes(),
        ); // offset
        bytes[fixed_base + 8..fixed_base + 12].copy_from_slice(&2_u32.to_le_bytes()); // part_count
        bytes[fixed_base + 12..fixed_base + 16].copy_from_slice(&4_u32.to_le_bytes()); // size
        bytes[fixed_base + 16..fixed_base + 20].copy_from_slice(&2027_u32.to_le_bytes()); // type
        bytes[FILE_HEADER_SIZE + FIXED_ENTRY_SIZE..FILE_HEADER_SIZE + FIXED_ENTRY_SIZE + 4]
            .copy_from_slice(&[1, 2, 3, 4]);

        let bif = read_bif_from_bytes_with_options(
            &bytes,
            BifReadOptions {
                input: BifReadMode::CompatibilityAurora,
            },
        )
        .expect("fixed entries should parse");
        assert_eq!(bif.resources.len(), 1);
        assert_eq!(
            bif.resources[0].storage,
            BifResourceStorage::Fixed { part_count: 2 }
        );
        assert_eq!(bif.resources[0].data, vec![1, 2, 3, 4]);
        assert_eq!(
            bif.resource_by_id(rakata_core::ResourceId::from_raw(0x0010_4000_u32)),
            Some([1, 2, 3, 4].as_slice())
        );
    }

    #[test]
    fn canonical_reader_accepts_fixed_resource_table_entries() {
        let mut bytes = vec![0_u8; FILE_HEADER_SIZE + FIXED_ENTRY_SIZE];
        bytes[0..4].copy_from_slice(&BIF_MAGIC);
        bytes[4..8].copy_from_slice(&BIF_VERSION_V10);
        bytes[12..16].copy_from_slice(&1_u32.to_le_bytes()); // fixed_count
        bytes[16..20].copy_from_slice(
            &u32::try_from(FILE_HEADER_SIZE)
                .expect("FILE_HEADER_SIZE fits in u32")
                .to_le_bytes(),
        );

        let bif = read_bif_from_bytes(&bytes).expect("canonical mode should parse");
        assert_eq!(bif.resources.len(), 0);
    }

    #[test]
    fn canonical_reader_ignores_fixed_table_bounds_when_not_loading_fixed_entries() {
        let mut bytes = vec![0_u8; FILE_HEADER_SIZE];
        bytes[0..4].copy_from_slice(&BIF_MAGIC);
        bytes[4..8].copy_from_slice(&BIF_VERSION_V10);
        bytes[12..16].copy_from_slice(&1_u32.to_le_bytes()); // fixed_count
        bytes[16..20].copy_from_slice(
            &u32::try_from(FILE_HEADER_SIZE)
                .expect("FILE_HEADER_SIZE fits in u32")
                .to_le_bytes(),
        );

        let bif = read_bif_from_bytes(&bytes).expect("canonical mode should ignore fixed table");
        assert_eq!(bif.resources.len(), 0);

        let err = read_bif_from_bytes_with_options(
            &bytes,
            BifReadOptions {
                input: BifReadMode::CompatibilityAurora,
            },
        )
        .expect_err("compat mode validates fixed table bounds");
        assert!(matches!(err, BifBinaryError::InvalidHeader(_)));
    }

    #[test]
    fn compatibility_reader_accepts_v11_bif_version() {
        let mut bytes = vec![0_u8; FILE_HEADER_SIZE];
        bytes[0..4].copy_from_slice(&BIF_MAGIC);
        bytes[4..8].copy_from_slice(&BIF_VERSION_V11);
        bytes[16..20].copy_from_slice(
            &u32::try_from(FILE_HEADER_SIZE)
                .expect("FILE_HEADER_SIZE fits in u32")
                .to_le_bytes(),
        );

        let bif = read_bif_from_bytes_with_options(
            &bytes,
            BifReadOptions {
                input: BifReadMode::CompatibilityAurora,
            },
        )
        .expect("compat mode should accept v1.1");
        assert_eq!(bif.resources.len(), 0);
    }

    #[test]
    fn rejects_invalid_magic() {
        let mut bytes = vec![0_u8; FILE_HEADER_SIZE];
        bytes[0..4].copy_from_slice(b"NOPE");
        bytes[4..8].copy_from_slice(&BIF_VERSION_V10);
        let err = read_bif_from_bytes(&bytes).expect_err("must fail");
        assert!(matches!(err, BifBinaryError::InvalidMagic(_)));
    }

    #[test]
    fn rejects_invalid_version() {
        let mut bytes = vec![0_u8; FILE_HEADER_SIZE];
        bytes[0..4].copy_from_slice(&BIF_MAGIC);
        bytes[4..8].copy_from_slice(b"V9.9");
        let err = read_bif_from_bytes(&bytes).expect_err("must fail");
        assert!(matches!(err, BifBinaryError::InvalidVersion(_)));
    }

    #[test]
    fn rejects_truncated_header() {
        let bytes = vec![0_u8; FILE_HEADER_SIZE - 1];
        let err = read_bif_from_bytes(&bytes).expect_err("must fail");
        assert!(matches!(err, BifBinaryError::InvalidHeader(_)));
    }

    #[cfg(not(feature = "bzf"))]
    #[test]
    fn rejects_out_of_bounds_resource_data() {
        let mut bytes = vec![0_u8; FILE_HEADER_SIZE + VARIABLE_ENTRY_SIZE];
        bytes[0..4].copy_from_slice(&BIF_MAGIC);
        bytes[4..8].copy_from_slice(&BIF_VERSION_V10);
        bytes[8..12].copy_from_slice(&1_u32.to_le_bytes());
        bytes[16..20].copy_from_slice(
            &u32::try_from(FILE_HEADER_SIZE)
                .expect("FILE_HEADER_SIZE fits in u32")
                .to_le_bytes(),
        );

        let base = FILE_HEADER_SIZE;
        bytes[base..base + 4].copy_from_slice(&1_u32.to_le_bytes());
        bytes[base + 4..base + 8].copy_from_slice(&999_u32.to_le_bytes());
        bytes[base + 8..base + 12].copy_from_slice(&10_u32.to_le_bytes());
        bytes[base + 12..base + 16].copy_from_slice(&2017_u32.to_le_bytes());

        let err = read_bif_from_bytes(&bytes).expect_err("must fail");
        assert!(matches!(err, BifBinaryError::InvalidData(_)));
    }

    #[test]
    fn resource_lookup_by_id_accepts_raw_and_typed_values() {
        let mut bif = Bif::new();
        let resource_id = ResourceId::from_raw(0x0010_0000);
        bif.push_resource(
            resource_id,
            ResourceTypeCode::from_raw_id(2017),
            b"abc".to_vec(),
        );

        assert_eq!(bif.resource_by_id(resource_id), Some(b"abc".as_slice()));
        assert_eq!(
            bif.resource_by_id(rakata_core::ResourceId::from_raw(resource_id.raw())),
            Some(b"abc".as_slice())
        );
    }
}