rakata_formats/bif/

writer.rs

//! BIF binary writer.

use std::io::{Cursor, Write};

#[cfg(feature = "bzf")]
use lzma_rust2::{LzmaOptions, LzmaWriter};

#[cfg(feature = "bzf")]
use super::LZMA_ALONE_HEADER_SIZE;
use super::{
    binary::write_u32, Bif, BifBinaryError, BifContainer, BifResourceStorage, BIF_MAGIC,
    BIF_VERSION_V10, FILE_HEADER_SIZE, FIXED_ENTRY_SIZE, VARIABLE_ENTRY_SIZE,
};

/// Writes a BIF archive to a writer.
///
/// # Errors
///
/// [`BifBinaryError::BzfFeatureDisabled`] when `bif.container` is
/// [`BifContainer::Bzf`](crate::bif::BifContainer::Bzf) and the crate was
/// built without the `bzf` feature, raised before anything is written.
///
/// [`BifBinaryError::ValueOverflow`] when either entry count, a table offset
/// or size, or the running data offset will not fit its `u32`, naming the
/// field. [`BifBinaryError::Io`] when the writer fails, which can leave a
/// partial archive.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(writer, bif))
)]
pub fn write_bif<W: Write>(writer: &mut W, bif: &Bif) -> Result<(), BifBinaryError> {
    let result = match bif.container {
        BifContainer::Biff => write_bif_impl(writer, bif, false),
        BifContainer::Bzf => {
            #[cfg(not(feature = "bzf"))]
            {
                Err(BifBinaryError::BzfFeatureDisabled)
            }
            #[cfg(feature = "bzf")]
            {
                write_bif_impl(writer, bif, true)
            }
        }
    };
    if result.is_ok() {
        crate::trace_debug!(
            container = ?bif.container,
            resource_count = bif.resources.len(),
            "wrote bif/bzf to writer"
        );
    }
    result
}

/// Serializes a BIF archive to bytes.
///
/// # Errors
///
/// Every non-I/O failure [`write_bif`] describes. The `Vec` target has no I/O
/// to fail at.
#[cfg_attr(feature = "tracing", tracing::instrument(level = "debug", skip(bif), fields(container = ?bif.container)))]
pub fn write_bif_to_vec(bif: &Bif) -> Result<Vec<u8>, BifBinaryError> {
    let mut cursor = Cursor::new(Vec::new());
    write_bif(&mut cursor, bif)?;
    let bytes = cursor.into_inner();
    crate::trace_debug!(
        container = ?bif.container,
        bytes_len = bytes.len(),
        "serialized bif/bzf to vec"
    );
    Ok(bytes)
}

#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(writer, bif), fields(as_bzf, resource_count = bif.resources.len()))
)]
fn write_bif_impl<W: Write>(writer: &mut W, bif: &Bif, as_bzf: bool) -> Result<(), BifBinaryError> {
    // Without the compression feature this can only ever be false: the
    // dispatcher rejects compressed archives before reaching here.
    #[cfg(not(feature = "bzf"))]
    let _ = as_bzf;
    let variable_resources: Vec<_> = bif
        .resources
        .iter()
        .filter(|resource| matches!(resource.storage, BifResourceStorage::Variable))
        .collect();
    let fixed_resources: Vec<_> = bif
        .resources
        .iter()
        .filter(|resource| matches!(resource.storage, BifResourceStorage::Fixed { .. }))
        .collect();

    let variable_count = u32::try_from(variable_resources.len())
        .map_err(|_| BifBinaryError::ValueOverflow("variable_count"))?;
    let fixed_count = u32::try_from(fixed_resources.len())
        .map_err(|_| BifBinaryError::ValueOverflow("fixed_count"))?;
    let variable_table_offset = u32::try_from(FILE_HEADER_SIZE)
        .map_err(|_| BifBinaryError::ValueOverflow("variable_table_offset"))?;

    let variable_table_size = variable_resources
        .len()
        .checked_mul(VARIABLE_ENTRY_SIZE)
        .ok_or(BifBinaryError::ValueOverflow("variable_table_size"))?;
    let fixed_table_size = fixed_resources
        .len()
        .checked_mul(FIXED_ENTRY_SIZE)
        .ok_or(BifBinaryError::ValueOverflow("fixed_table_size"))?;

    #[cfg(feature = "bzf")]
    let variable_payloads = if as_bzf {
        variable_resources
            .iter()
            .map(|resource| encode_bzf_payload(&resource.data))
            .collect::<Result<Vec<_>, _>>()?
    } else {
        Vec::new()
    };
    #[cfg(feature = "bzf")]
    let fixed_payloads = if as_bzf {
        fixed_resources
            .iter()
            .map(|resource| encode_bzf_payload(&resource.data))
            .collect::<Result<Vec<_>, _>>()?
    } else {
        Vec::new()
    };

    let mut variable_offsets = Vec::with_capacity(variable_resources.len());
    let mut fixed_offsets = Vec::with_capacity(fixed_resources.len());
    let mut next_data_offset = FILE_HEADER_SIZE
        .checked_add(variable_table_size)
        .and_then(|offset| offset.checked_add(fixed_table_size))
        .ok_or(BifBinaryError::ValueOverflow("data_offset"))?;

    #[cfg(feature = "bzf")]
    for (index, resource) in variable_resources.iter().enumerate() {
        let target = if let Some(source) = resource.source_data_offset {
            usize::try_from(source).expect("source offset fits in usize")
        } else {
            align_to_four(next_data_offset)
                .ok_or(BifBinaryError::ValueOverflow("data_offset_alignment"))?
        };
        variable_offsets.push(target);
        let payload_len = if as_bzf {
            variable_payloads[index].len()
        } else {
            resource.data.len()
        };
        next_data_offset = target
            .checked_add(payload_len)
            .ok_or(BifBinaryError::ValueOverflow("data_offset"))?;
    }
    #[cfg(not(feature = "bzf"))]
    for resource in &variable_resources {
        let target = if let Some(source) = resource.source_data_offset {
            usize::try_from(source).expect("source offset fits in usize")
        } else {
            align_to_four(next_data_offset)
                .ok_or(BifBinaryError::ValueOverflow("data_offset_alignment"))?
        };
        variable_offsets.push(target);
        next_data_offset = target
            .checked_add(resource.data.len())
            .ok_or(BifBinaryError::ValueOverflow("data_offset"))?;
    }

    #[cfg(feature = "bzf")]
    for (index, resource) in fixed_resources.iter().enumerate() {
        let target = if let Some(source) = resource.source_data_offset {
            usize::try_from(source).expect("source offset fits in usize")
        } else {
            align_to_four(next_data_offset)
                .ok_or(BifBinaryError::ValueOverflow("data_offset_alignment"))?
        };
        fixed_offsets.push(target);
        let payload_len = if as_bzf {
            fixed_payloads[index].len()
        } else {
            resource.data.len()
        };
        next_data_offset = target
            .checked_add(payload_len)
            .ok_or(BifBinaryError::ValueOverflow("data_offset"))?;
    }
    #[cfg(not(feature = "bzf"))]
    for resource in &fixed_resources {
        let target = if let Some(source) = resource.source_data_offset {
            usize::try_from(source).expect("source offset fits in usize")
        } else {
            align_to_four(next_data_offset)
                .ok_or(BifBinaryError::ValueOverflow("data_offset_alignment"))?
        };
        fixed_offsets.push(target);
        next_data_offset = target
            .checked_add(resource.data.len())
            .ok_or(BifBinaryError::ValueOverflow("data_offset"))?;
    }

    // Both kinds carry the same signature: compression is signalled by the
    // filename, never by the container.
    writer.write_all(&BIF_MAGIC)?;
    writer.write_all(&BIF_VERSION_V10)?;
    write_u32(writer, variable_count)?;
    write_u32(writer, fixed_count)?;
    write_u32(writer, variable_table_offset)?;

    for (resource, data_offset) in variable_resources.iter().zip(variable_offsets.iter()) {
        write_u32(writer, resource.resource_id.raw())?;
        write_u32(
            writer,
            u32::try_from(*data_offset)
                .map_err(|_| BifBinaryError::ValueOverflow("data_offset"))?,
        )?;
        write_u32(
            writer,
            u32::try_from(resource.data.len())
                .map_err(|_| BifBinaryError::ValueOverflow("data_size"))?,
        )?;
        write_u32(writer, u32::from(resource.resource_type.raw_id()))?;
    }

    for (resource, data_offset) in fixed_resources.iter().zip(fixed_offsets.iter()) {
        let part_count = match resource.storage {
            BifResourceStorage::Fixed { part_count } => part_count,
            BifResourceStorage::Variable => {
                unreachable!("fixed resource vector must only contain fixed entries")
            }
        };
        write_u32(writer, resource.resource_id.raw())?;
        write_u32(
            writer,
            u32::try_from(*data_offset)
                .map_err(|_| BifBinaryError::ValueOverflow("fixed_data_offset"))?,
        )?;
        write_u32(writer, part_count)?;
        write_u32(
            writer,
            u32::try_from(resource.data.len())
                .map_err(|_| BifBinaryError::ValueOverflow("fixed_data_size"))?,
        )?;
        write_u32(writer, u32::from(resource.resource_type.raw_id()))?;
    }

    let mut written_offset = FILE_HEADER_SIZE
        .checked_add(variable_table_size)
        .and_then(|offset| offset.checked_add(fixed_table_size))
        .ok_or(BifBinaryError::ValueOverflow("written_offset"))?;
    #[cfg(feature = "bzf")]
    for (index, (resource, target_offset)) in variable_resources
        .iter()
        .zip(variable_offsets.iter())
        .enumerate()
    {
        if written_offset < *target_offset {
            let pad_len = target_offset
                .checked_sub(written_offset)
                .ok_or(BifBinaryError::ValueOverflow("padding"))?;
            writer.write_all(&vec![0_u8; pad_len])?;
            written_offset = *target_offset;
        }

        let payload = if as_bzf {
            variable_payloads[index].as_slice()
        } else {
            resource.data.as_slice()
        };

        writer.write_all(payload)?;
        written_offset = written_offset
            .checked_add(payload.len())
            .ok_or(BifBinaryError::ValueOverflow("written_offset"))?;
    }
    #[cfg(not(feature = "bzf"))]
    for (resource, target_offset) in variable_resources.iter().zip(variable_offsets.iter()) {
        if written_offset < *target_offset {
            let pad_len = target_offset
                .checked_sub(written_offset)
                .ok_or(BifBinaryError::ValueOverflow("padding"))?;
            writer.write_all(&vec![0_u8; pad_len])?;
            written_offset = *target_offset;
        }

        let payload = resource.data.as_slice();

        writer.write_all(payload)?;
        written_offset = written_offset
            .checked_add(payload.len())
            .ok_or(BifBinaryError::ValueOverflow("written_offset"))?;
    }

    #[cfg(feature = "bzf")]
    for (index, (resource, target_offset)) in
        fixed_resources.iter().zip(fixed_offsets.iter()).enumerate()
    {
        if written_offset < *target_offset {
            let pad_len = target_offset
                .checked_sub(written_offset)
                .ok_or(BifBinaryError::ValueOverflow("padding"))?;
            writer.write_all(&vec![0_u8; pad_len])?;
            written_offset = *target_offset;
        }

        let payload = if as_bzf {
            fixed_payloads[index].as_slice()
        } else {
            resource.data.as_slice()
        };

        writer.write_all(payload)?;
        written_offset = written_offset
            .checked_add(payload.len())
            .ok_or(BifBinaryError::ValueOverflow("written_offset"))?;
    }
    #[cfg(not(feature = "bzf"))]
    for (resource, target_offset) in fixed_resources.iter().zip(fixed_offsets.iter()) {
        if written_offset < *target_offset {
            let pad_len = target_offset
                .checked_sub(written_offset)
                .ok_or(BifBinaryError::ValueOverflow("padding"))?;
            writer.write_all(&vec![0_u8; pad_len])?;
            written_offset = *target_offset;
        }

        let payload = resource.data.as_slice();

        writer.write_all(payload)?;
        written_offset = written_offset
            .checked_add(payload.len())
            .ok_or(BifBinaryError::ValueOverflow("written_offset"))?;
    }

    Ok(())
}

fn align_to_four(value: usize) -> Option<usize> {
    let padding = (4 - (value % 4)) % 4;
    value.checked_add(padding)
}

#[cfg(feature = "bzf")]
/// Encodes one payload as a bare LZMA-alone stream.
///
/// The five-byte header (properties byte, then dictionary size) is written
/// explicitly because the reader takes the coder parameters from it. The
/// uncompressed length is deliberately absent: it lives in the entry table,
/// which is what makes these streams shorter than a standalone `.lzma` file.
///
/// Byte-parity with the shipping encoder is not a goal — only the framing is
/// contractual, since a decoder reads the parameters rather than assuming
/// them.
fn encode_bzf_payload(payload: &[u8]) -> Result<Vec<u8>, BifBinaryError> {
    let options = LzmaOptions::with_preset(6);
    let literal_context = LzmaOptions::LC_DEFAULT;
    let literal_position = LzmaOptions::LP_DEFAULT;
    let position = LzmaOptions::PB_DEFAULT;
    let dictionary_size = options.dict_size;

    // Standard LZMA packing of the three coder parameters into one byte.
    let properties = (position * 5 + literal_position) * 9 + literal_context;
    let properties =
        u8::try_from(properties).map_err(|_| BifBinaryError::ValueOverflow("lzma_properties"))?;

    let mut out = Vec::with_capacity(payload.len() / 2 + LZMA_ALONE_HEADER_SIZE);
    out.push(properties);
    out.extend_from_slice(&dictionary_size.to_le_bytes());

    let mut writer =
        LzmaWriter::new_no_header(Cursor::new(Vec::new()), &options, true).map_err(|error| {
            BifBinaryError::InvalidData(format!(
                "failed to initialize the payload encoder: {error}"
            ))
        })?;
    writer.write_all(payload).map_err(|error| {
        BifBinaryError::InvalidData(format!("failed to encode a payload: {error}"))
    })?;
    let cursor = writer.finish().map_err(|error| {
        BifBinaryError::InvalidData(format!("failed to finalize a payload: {error}"))
    })?;
    out.extend_from_slice(&cursor.into_inner());
    Ok(out)
}