rakata_formats/erf/

rewrite.rs

//! Rewrites an archive by substituting some entries and copying the rest.
//!
//! Changing one resource inside a module archive today means reading the
//! whole thing into an [`Erf`](super::Erf) and calling
//! [`write_erf`](super::write_erf), which holds every entry in memory to
//! change one of them. For a save with dozens of module archives that is the
//! entire save resident to edit two fields.
//!
//! This path never holds more than the tables and one entry at a time. It
//! copies bytes it was not asked to change, and a byte copy does not have to
//! understand what it is copying, so an entry this crate cannot parse comes
//! out the far side intact. Reading into an `Erf` cannot offer that.
//!
//! The eager path stays as it is. It is the authoring path, the way
//! `to_gff()` is at the GFF layer, and the two are kept apart on purpose.
//!
//! ## What it will not do
//!
//! **Adding and removing entries is left out deliberately.** Committing an
//! edited save never changes an archive's entry set: editing a creature
//! changes a GIT's bytes, not which resources the module holds. Both
//! operations would resize the two tables and move every payload after them,
//! and nothing needs it yet.
//!
//! **Header metadata is preserved verbatim, build date included.** There is
//! no option to stamp a fresh one. A commit that silently rewrites when the
//! archive was built has changed something nobody asked it to.
//!
//! ## Layout rules this has to respect
//!
//! Both from `docs/src/formats/archives/erf.md`.
//!
//! The header and the three tables are read *sequentially* by the engine,
//! from the fixed end of the header, sized from the entry counts alone. The
//! block offsets in the header are parsed and then never read back. So those
//! four regions have to stay contiguous and in that order whatever the offset
//! fields say, which is why they are copied as one verbatim span rather than
//! rebuilt: preserving them is easier than reproducing them, and it carries
//! the reserved zone and any blank block along for free.
//!
//! Key entry `n` and resource entry `n` must describe the same resource, and
//! nothing in the format checks that they do. Rows are located here through
//! the key entry's own `resource_id` rather than by assuming it equals the
//! entry's position, so the pairing the source had is the pairing the output
//! gets.
//!
//! Payload placement is the one free part of the layout, since each entry's
//! bytes are found through its own `data_offset`. Payloads are emitted in the
//! order the source stored them and packed with no gaps. Every archive
//! measured for this already tiles that way, so substituting nothing
//! reproduces the input byte for byte.

use std::collections::HashMap;
use std::io::{self, Read, Seek, Write};

use rakata_core::ResRef;
use thiserror::Error;

use super::index::ErfIndex;
use super::layout::ErfHeader;
use super::{KEY_ENTRY_SIZE, RESOURCE_ENTRY_SIZE};
use crate::archive::EntryDefect;

/// Byte offset of `resource_id` within a key-table entry.
const KEY_RESOURCE_ID_OFFSET: usize = 16;

/// Errors produced while rewriting an ERF-family archive.
#[derive(Debug, Error)]
pub enum ErfRewriteError {
    /// I/O read/write failure.
    #[error(transparent)]
    Io(#[from] std::io::Error),
    /// A substitution named an entry the archive does not have.
    #[error("substitution names entry {index}, but the archive holds {entry_count}")]
    NoSuchEntry {
        /// Table position the caller supplied.
        index: usize,
        /// Number of entries in the archive.
        entry_count: usize,
    },
    /// Two substitutions named the same entry.
    #[error("entry {index} was given more than one substitution")]
    DuplicateSubstitution {
        /// Table position named twice.
        index: usize,
    },
    /// An entry that was not being replaced cannot be read.
    ///
    /// Substituting the entry is the way past this: supplying its bytes means
    /// the unreadable range is never touched, which is how a damaged archive
    /// gets repaired rather than refused.
    #[error("entry {index} ({resref}) cannot be copied: {defect}")]
    UnreadableEntry {
        /// Table position of the entry.
        index: usize,
        /// Name the archive gives it.
        resref: ResRef,
        /// Why its bytes are unreachable.
        defect: EntryDefect,
    },
    /// Two entries claim overlapping byte ranges.
    #[error("entry {index} starts at {offset}, inside the range ending at {earliest}")]
    OverlappingPayload {
        /// Table position of the entry that starts too early.
        index: usize,
        /// Offset it declares.
        offset: u64,
        /// First offset that was still free.
        earliest: u64,
    },
    /// A key entry points at a resource row outside the resource table.
    #[error("key entry {index} names resource row {row}, which is not in the table")]
    KeyNamesMissingResourceRow {
        /// Table position of the key entry.
        index: usize,
        /// Row it names.
        row: usize,
    },
    /// A table lies outside the span copied verbatim from the source.
    ///
    /// The header, the localized string block and both tables are copied as
    /// one region ending at the resource table. A file that puts one of them
    /// somewhere else is one the engine's own sequential reader mis-parses,
    /// so it is refused rather than silently truncated.
    #[error("the {region} ends at {region_end}, past the copied region ending at {prefix_end}")]
    RegionOutsidePrefix {
        /// Which region is misplaced.
        region: &'static str,
        /// Where it ends.
        region_end: usize,
        /// Where the copied region ends.
        prefix_end: usize,
    },
    /// An entry's bytes ran out before its declared size.
    #[error("entry {index} declares {expected} bytes but only {copied} could be read")]
    TruncatedEntry {
        /// Table position of the entry.
        index: usize,
        /// Size the table declares.
        expected: u64,
        /// Bytes actually copied.
        copied: u64,
    },
    /// Value cannot fit the on-disk integer width.
    #[error("value overflow while writing field `{0}`")]
    ValueOverflow(&'static str),
}

/// Writes `source` to `writer`, replacing the named entries' bytes.
///
/// `substitutions` pairs a table position, as given by
/// [`ErfIndex::entries`] or [`ErfIndex::position`], with the bytes to store
/// there. Every other entry is copied verbatim, as are the header, the
/// localized string block and both tables.
///
/// # Errors
///
/// [`ErfRewriteError::NoSuchEntry`] and
/// [`ErfRewriteError::DuplicateSubstitution`] for a bad substitution set,
/// both checked before anything is written.
///
/// [`ErfRewriteError::UnreadableEntry`] when an entry that is *not* being
/// replaced cannot be read. Supplying its bytes as a substitution is the way
/// past this, which is how a damaged archive gets repaired rather than
/// refused. [`ErfRewriteError::TruncatedEntry`] when such an entry reads and
/// runs out before its declared size, and
/// [`ErfRewriteError::OverlappingPayload`] when two entries claim the same
/// bytes.
///
/// [`ErfRewriteError::RegionOutsidePrefix`] when the source's string block or
/// key table sits outside the span copied verbatim, since copying it would
/// truncate them, and [`ErfRewriteError::KeyNamesMissingResourceRow`] when a
/// key points at a row the resource table does not have.
///
/// [`ErfRewriteError::ValueOverflow`] when a recomputed offset or size will
/// not fit its on-disk width, and [`ErfRewriteError::Io`] from either side.
/// The I/O arm can leave a partial archive.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(source, substitutions, writer))
)]
pub fn rewrite_erf<'a, R, W>(
    source: &ErfIndex<R>,
    substitutions: impl IntoIterator<Item = (usize, &'a [u8])>,
    writer: &mut W,
) -> Result<(), ErfRewriteError>
where
    R: Read + Seek,
    W: Write,
{
    let entry_count = source.len();
    let mut replacements: HashMap<usize, &[u8]> = HashMap::new();
    for (index, bytes) in substitutions {
        if index >= entry_count {
            return Err(ErfRewriteError::NoSuchEntry { index, entry_count });
        }
        if replacements.insert(index, bytes).is_some() {
            return Err(ErfRewriteError::DuplicateSubstitution { index });
        }
    }

    let header = source.header();
    let mut prefix = read_prefix(source, header, entry_count)?;
    let prefix_len =
        u64::try_from(prefix.len()).map_err(|_| ErfRewriteError::ValueOverflow("data_offset"))?;

    // Payloads keep the order the source gave them, so an equal-sized
    // substitution changes nothing but the bytes themselves.
    let mut order: Vec<usize> = (0..entry_count).collect();
    order.sort_by_key(|&index| (source.entries()[index].offset, index));

    // Two cursors: one walks the source ranges to catch entries that claim
    // the same bytes, the other assigns the packed output offsets.
    let mut source_cursor = prefix_len;
    let mut out_cursor = prefix_len;
    for &index in &order {
        let entry = &source.entries()[index];
        let size = match replacements.get(&index) {
            Some(bytes) => u64::try_from(bytes.len())
                .map_err(|_| ErfRewriteError::ValueOverflow("data_size"))?,
            None => {
                if let Some(defect) = &entry.defect {
                    return Err(ErfRewriteError::UnreadableEntry {
                        index,
                        resref: entry.resref,
                        defect: defect.clone(),
                    });
                }
                if entry.offset < source_cursor {
                    return Err(ErfRewriteError::OverlappingPayload {
                        index,
                        offset: entry.offset,
                        earliest: source_cursor,
                    });
                }
                // The index only admits an entry whose range fits the
                // archive, so this addition cannot overflow.
                source_cursor = entry.offset + entry.size;
                entry.size
            }
        };
        write_resource_row(&mut prefix, header, index, out_cursor, size)?;
        out_cursor = out_cursor
            .checked_add(size)
            .ok_or(ErfRewriteError::ValueOverflow("data_offset"))?;
    }

    writer.write_all(&prefix)?;
    for &index in &order {
        match replacements.get(&index) {
            Some(bytes) => writer.write_all(bytes)?,
            None => copy_entry(source, index, writer)?,
        }
    }

    crate::trace_debug!(
        entry_count,
        substituted = replacements.len(),
        "rewrote erf-family archive"
    );
    Ok(())
}

/// Serializes a rewritten archive to bytes.
///
/// See [`rewrite_erf`] for the semantics.
///
/// # Errors
///
/// The same as [`rewrite_erf`]. The `Vec` target has no I/O to fail at, but
/// [`ErfRewriteError::Io`] still arrives from reading `source`.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(source, substitutions))
)]
pub fn rewrite_erf_to_vec<'a, R: Read + Seek>(
    source: &ErfIndex<R>,
    substitutions: impl IntoIterator<Item = (usize, &'a [u8])>,
) -> Result<Vec<u8>, ErfRewriteError> {
    let mut bytes = Vec::new();
    rewrite_erf(source, substitutions, &mut bytes)?;
    crate::trace_debug!(bytes_len = bytes.len(), "serialized rewritten archive");
    Ok(bytes)
}

/// Reads the header, string block and both tables as one verbatim span.
///
/// Refuses a source whose string block or key table falls outside that span,
/// since copying it would truncate them.
fn read_prefix<R: Read + Seek>(
    source: &ErfIndex<R>,
    header: &ErfHeader,
    entry_count: usize,
) -> Result<Vec<u8>, ErfRewriteError> {
    let keys_end = table_end(
        header.keys_offset,
        entry_count,
        KEY_ENTRY_SIZE,
        "keys_offset",
    )?;
    let prefix_end = table_end(
        header.resources_offset,
        entry_count,
        RESOURCE_ENTRY_SIZE,
        "resources_offset",
    )?;
    let strings_end = header
        .localized_strings_offset
        .checked_add(header.localized_string_size)
        .ok_or(ErfRewriteError::ValueOverflow("localized_string_size"))?;

    for (region, region_end) in [
        ("localized string block", strings_end),
        ("key table", keys_end),
    ] {
        if region_end > prefix_end {
            return Err(ErfRewriteError::RegionOutsidePrefix {
                region,
                region_end,
                prefix_end,
            });
        }
    }

    let len = u64::try_from(prefix_end)
        .map_err(|_| ErfRewriteError::ValueOverflow("resources_offset"))?;
    Ok(source
        .section()
        .section(0, len)
        .expect("the index read the resource table out of this span, so it is inside the archive")
        .read_all()?)
}

/// Returns the end offset of a table of `entry_count` fixed-size records.
fn table_end(
    offset: usize,
    entry_count: usize,
    stride: usize,
    field: &'static str,
) -> Result<usize, ErfRewriteError> {
    entry_count
        .checked_mul(stride)
        .and_then(|size| offset.checked_add(size))
        .ok_or(ErfRewriteError::ValueOverflow(field))
}

/// Points the resource row belonging to key entry `index` at `offset`/`size`.
///
/// The row is the one the key entry names rather than the one sharing its
/// position, so a source whose two tables are permuted stays paired.
fn write_resource_row(
    prefix: &mut [u8],
    header: &ErfHeader,
    index: usize,
    offset: u64,
    size: u64,
) -> Result<(), ErfRewriteError> {
    // The key table was checked to lie inside the prefix and `index` is below
    // the entry count, so neither the multiply nor the slice can fail.
    let id_at = header.keys_offset + index * KEY_ENTRY_SIZE + KEY_RESOURCE_ID_OFFSET;
    let raw: [u8; 4] = prefix[id_at..id_at + 4]
        .try_into()
        .expect("a four-byte slice converts to a four-byte array");
    let row = usize::try_from(u32::from_le_bytes(raw))
        .map_err(|_| ErfRewriteError::ValueOverflow("resource_id"))?;

    let row_at = row
        .checked_mul(RESOURCE_ENTRY_SIZE)
        .and_then(|by| header.resources_offset.checked_add(by))
        .ok_or(ErfRewriteError::ValueOverflow("resource_id"))?;
    let slot = prefix
        .get_mut(row_at..row_at + RESOURCE_ENTRY_SIZE)
        .ok_or(ErfRewriteError::KeyNamesMissingResourceRow { index, row })?;

    let offset =
        u32::try_from(offset).map_err(|_| ErfRewriteError::ValueOverflow("data_offset"))?;
    let size = u32::try_from(size).map_err(|_| ErfRewriteError::ValueOverflow("data_size"))?;
    slot[..4].copy_from_slice(&offset.to_le_bytes());
    slot[4..].copy_from_slice(&size.to_le_bytes());
    Ok(())
}

/// Streams one entry's bytes from the source into `writer`.
fn copy_entry<R: Read + Seek, W: Write>(
    source: &ErfIndex<R>,
    index: usize,
    writer: &mut W,
) -> Result<(), ErfRewriteError> {
    let expected = source.entries()[index].size;
    let mut section = source
        .entry_section(index)
        .expect("the entry is in range and carries no defect, both checked above");
    let copied = io::copy(&mut section, writer)?;
    if copied != expected {
        return Err(ErfRewriteError::TruncatedEntry {
            index,
            expected,
            copied,
        });
    }
    Ok(())
}