zipatch_rs/apply/

sqpk.rs

//! [`Apply`] implementations for [`SqpkCommand`] variants.
//!
//! This module is the consumer side of the SQPK dispatcher. Each function
//! applies one SQPK sub-command to the filesystem via an [`ApplyContext`].
//!
//! # Dispatch
//!
//! [`SqpkCommand`]'s [`Apply`] impl matches on the variant and calls the
//! corresponding private function. Two variants — `Index` and `PatchInfo` —
//! carry metadata that is used by the indexed `ZiPatch` reader (not yet
//! implemented) and have no direct filesystem effect; their apply arms return
//! `Ok(())` immediately.
//!
//! # File-handle caching
//!
//! All write operations (`AddData`, `DeleteData`, `ExpandData`, `Header`, and
//! the `AddFile` arm of `File`) call an internal `open_cached` method rather
//! than opening a new handle directly. See [`crate::apply`] for the cache
//! semantics. The `RemoveAll` and `DeleteFile` arms flush or evict cached
//! handles before touching the filesystem.
//!
//! # Block-offset scaling
//!
//! Block offsets in `AddData`, `DeleteData`, and `ExpandData` are stored in
//! the wire format as a `u32` scaled by 128 (`<< 7`). The shift is applied
//! during parsing; by the time an apply function sees a chunk, `block_offset`
//! is already in bytes.

use crate::Platform;
use crate::apply::path::{dat_path, expansion_folder_id, generic_path, index_path};
use crate::apply::{Apply, ApplyContext};
use crate::chunk::sqpk::SqpkCommand;
use crate::chunk::sqpk::add_data::SqpkAddData;
use crate::chunk::sqpk::delete_data::SqpkDeleteData;
use crate::chunk::sqpk::expand_data::SqpkExpandData;
use crate::chunk::sqpk::file::{SqpkFile, SqpkFileOperation};
use crate::chunk::sqpk::header::{SqpkHeader, SqpkHeaderTarget, TargetHeaderKind};
use crate::chunk::sqpk::target_info::SqpkTargetInfo;
use crate::{Result, ZiPatchError};
use std::fs;
use std::io::{Read, Seek, SeekFrom, Write};
use std::path::Path;
use tracing::{debug, trace, warn};

/// Write `len` zero bytes to `w` using `std::io::copy`.
fn write_zeros(w: &mut impl Write, len: u64) -> std::io::Result<()> {
    std::io::copy(&mut std::io::repeat(0).take(len), w)?;
    Ok(())
}

/// Write a `SqPack` empty-block header at `offset` and zero the full block range.
///
/// The block range is `block_number * 128` bytes starting at `offset`. After
/// zeroing, a 5-field little-endian header is written at `offset`:
///
/// | Offset | Size | Value |
/// |--------|------|-------|
/// | 0 | 4 | `128` — block-size marker |
/// | 4 | 4 | `0` |
/// | 8 | 4 | `0` |
/// | 12 | 4 | `block_number - 1` — "next free" count |
/// | 16 | 4 | `0` |
///
/// `block_number` must be non-zero; the function returns
/// [`std::io::ErrorKind::InvalidInput`] otherwise, because a zero-block range
/// has no meaningful on-disk representation and would silently skip the seek.
fn write_empty_block(
    f: &mut (impl Write + Seek),
    offset: u64,
    block_number: u32,
) -> std::io::Result<()> {
    if block_number == 0 {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidInput,
            "block_number must be non-zero",
        ));
    }
    f.seek(SeekFrom::Start(offset))?;
    write_zeros(f, (block_number as u64) << 7)?;
    f.seek(SeekFrom::Start(offset))?;
    f.write_all(&128u32.to_le_bytes())?;
    f.write_all(&0u32.to_le_bytes())?;
    f.write_all(&0u32.to_le_bytes())?;
    f.write_all(&block_number.wrapping_sub(1).to_le_bytes())?;
    f.write_all(&0u32.to_le_bytes())?;
    Ok(())
}

/// Decide whether a path should be preserved by `RemoveAll`.
///
/// `RemoveAll` deletes all files in an expansion folder's `sqpack/` and
/// `movie/` subdirectories, but preserves:
///
/// - Any file whose name ends in `.var` (version markers used by the patcher).
/// - The four introductory movie files `00000.bk2` through `00003.bk2`.
///   Files named `00004.bk2` and beyond are deleted.
///
/// The `.bk2` match is exact on the base name — a file like
/// `prefix00000.bk2` is **not** kept.
fn keep_in_remove_all(path: &Path) -> bool {
    let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
        return false;
    };
    #[allow(clippy::case_sensitive_file_extension_comparisons)]
    let is_var = name.ends_with(".var");
    is_var || matches!(name, "00000.bk2" | "00001.bk2" | "00002.bk2" | "00003.bk2")
}

/// Dispatch an [`SqpkCommand`] to its specific apply function.
///
/// - [`SqpkCommand::TargetInfo`] — updates [`ApplyContext::platform`] in place.
/// - [`SqpkCommand::Index`] and [`SqpkCommand::PatchInfo`] — metadata only;
///   returns `Ok(())` without touching the filesystem.
/// - All other variants — delegate to the write/delete functions below.
impl Apply for SqpkCommand {
    fn apply(&self, ctx: &mut ApplyContext) -> Result<()> {
        match self {
            SqpkCommand::TargetInfo(c) => apply_target_info(c, ctx),
            SqpkCommand::Index(_) | SqpkCommand::PatchInfo(_) => Ok(()),
            SqpkCommand::AddData(c) => apply_add_data(c, ctx),
            SqpkCommand::DeleteData(c) => apply_delete_data(c, ctx),
            SqpkCommand::ExpandData(c) => apply_expand_data(c, ctx),
            SqpkCommand::Header(c) => apply_header(c, ctx),
            SqpkCommand::File(c) => apply_file(c, ctx),
        }
    }
}

/// Apply a [`SqpkTargetInfo`] chunk.
///
/// Overwrites [`ApplyContext::platform`] with the platform declared by the
/// chunk. All subsequent path resolution — for `AddData`, `DeleteData`, etc.
/// — uses the updated platform. Real FFXIV patches start with a `TargetInfo`
/// chunk, so this is typically the first mutation applied to the context.
///
/// Platform ID mapping:
///
/// | `platform_id` | [`Platform`] |
/// |---------------|-------------|
/// | `0` | [`Platform::Win32`] |
/// | `1` | [`Platform::Ps3`] |
/// | `2` | [`Platform::Ps4`] |
/// | anything else | [`Platform::Unknown`] + `warn!` |
///
/// No filesystem I/O is performed.
#[allow(clippy::unnecessary_wraps)] // sibling dispatch arms all return Result<()>
fn apply_target_info(cmd: &SqpkTargetInfo, ctx: &mut ApplyContext) -> Result<()> {
    ctx.platform = match cmd.platform_id {
        0 => Platform::Win32,
        1 => Platform::Ps3,
        2 => Platform::Ps4,
        id => {
            warn!(
                platform_id = id,
                "unknown platform_id in TargetInfo; stored as Unknown"
            );
            Platform::Unknown(id)
        }
    };
    debug!(platform = ?ctx.platform, "target info");
    Ok(())
}

/// Apply a [`SqpkAddData`] chunk.
///
/// Seeks to `block_offset` in the resolved `.dat` file and writes the chunk's
/// inline `data` payload, then appends `block_delete_number` zero bytes
/// immediately after it. The file is opened via the handle cache, so
/// repeated writes to the same file re-use a single open handle.
///
/// The target path is resolved from `(main_id, sub_id, file_id, platform)`.
///
/// # Errors
///
/// Returns [`crate::ZiPatchError::Io`] if the file cannot be opened, the seek
/// fails, or either write fails.
fn apply_add_data(cmd: &SqpkAddData, ctx: &mut ApplyContext) -> Result<()> {
    let tf = &cmd.target_file;
    let path = dat_path(ctx, tf.main_id, tf.sub_id, tf.file_id);
    trace!(path = %path.display(), offset = cmd.block_offset, delete_zeros = cmd.block_delete_number, "add data");
    let file = ctx.open_cached(path)?;
    file.seek(SeekFrom::Start(cmd.block_offset))?;
    file.write_all(&cmd.data)?;
    write_zeros(file, cmd.block_delete_number)?;
    Ok(())
}

/// Apply a [`SqpkDeleteData`] chunk.
///
/// Writes an empty-block header at `block_offset` covering `block_count`
/// 128-byte blocks. The operation logically "frees" the range in the `SqPack`
/// data file so the game's archive reader treats those blocks as available
/// space.
///
/// The target path is resolved from `(main_id, sub_id, file_id, platform)`.
///
/// # Errors
///
/// Returns [`crate::ZiPatchError::Io`] if the file cannot be opened, or if
/// the write fails (e.g. `block_count` is zero, or a seek or write error).
fn apply_delete_data(cmd: &SqpkDeleteData, ctx: &mut ApplyContext) -> Result<()> {
    let tf = &cmd.target_file;
    let path = dat_path(ctx, tf.main_id, tf.sub_id, tf.file_id);
    trace!(path = %path.display(), offset = cmd.block_offset, block_count = cmd.block_count, "delete data");
    let file = ctx.open_cached(path)?;
    write_empty_block(file, cmd.block_offset, cmd.block_count)?;
    Ok(())
}

/// Apply a [`SqpkExpandData`] chunk.
///
/// Behaves identically to `apply_delete_data`: writes an empty-block header
/// at `block_offset` for `block_count` blocks. The semantic difference is
/// in the patch's intent — `ExpandData` extends the file into previously
/// unallocated space, while `DeleteData` clears existing content — but the
/// on-disk operation (writing empty-block markers) is the same.
///
/// # Errors
///
/// Returns [`crate::ZiPatchError::Io`] if the file cannot be opened or if
/// the write fails.
fn apply_expand_data(cmd: &SqpkExpandData, ctx: &mut ApplyContext) -> Result<()> {
    let tf = &cmd.target_file;
    let path = dat_path(ctx, tf.main_id, tf.sub_id, tf.file_id);
    trace!(path = %path.display(), offset = cmd.block_offset, block_count = cmd.block_count, "expand data");
    let file = ctx.open_cached(path)?;
    write_empty_block(file, cmd.block_offset, cmd.block_count)?;
    Ok(())
}

/// Apply a [`SqpkHeader`] chunk.
///
/// Writes exactly 1024 bytes of header data into a `.dat` or `.index` `SqPack`
/// file at one of two fixed offsets determined by `header_kind`:
///
/// | [`TargetHeaderKind`] | File offset |
/// |--------------------|------------|
/// | `Version` | `0` (version header slot) |
/// | `Index` or `Data` | `1024` (secondary header slot) |
///
/// The target file is determined by `SqpkHeaderTarget`:
///
/// - `Dat(f)` → `.dat` path resolved from `(f.main_id, f.sub_id, f.file_id)`
/// - `Index(f)` → `.index` path resolved from `(f.main_id, f.sub_id, f.file_id)`
///
/// The file handle is obtained from the cache.
///
/// # Errors
///
/// Returns [`crate::ZiPatchError::Io`] if the file cannot be opened, the
/// seek fails, or the write fails.
fn apply_header(cmd: &SqpkHeader, ctx: &mut ApplyContext) -> Result<()> {
    let path = match &cmd.target {
        SqpkHeaderTarget::Dat(f) => dat_path(ctx, f.main_id, f.sub_id, f.file_id),
        SqpkHeaderTarget::Index(f) => index_path(ctx, f.main_id, f.sub_id, f.file_id),
    };
    let offset: u64 = match cmd.header_kind {
        TargetHeaderKind::Version => 0,
        _ => 1024,
    };
    trace!(path = %path.display(), offset, kind = ?cmd.header_kind, "apply header");
    let file = ctx.open_cached(path)?;
    file.seek(SeekFrom::Start(offset))?;
    file.write_all(&cmd.header_data)?;
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::io::Cursor;
    use std::path::Path;

    // --- write_empty_block header structure ---
    // Tests the private helper directly; cannot be tested through public API.

    #[test]
    fn write_empty_block_header_structure() {
        let mut cur = Cursor::new(Vec::<u8>::new());
        write_empty_block(&mut cur, 0, 2).unwrap();
        let buf = cur.into_inner();

        assert_eq!(buf.len(), 256); // block_number << 7 = 256 bytes zeroed
        assert!(buf[20..].iter().all(|&b| b == 0));

        assert_eq!(&buf[0..4], &128u32.to_le_bytes()); // block size marker
        assert_eq!(&buf[4..8], &0u32.to_le_bytes());
        assert_eq!(&buf[8..12], &0u32.to_le_bytes());
        assert_eq!(&buf[12..16], &1u32.to_le_bytes()); // block_number.wrapping_sub(1) = 1
        assert_eq!(&buf[16..20], &0u32.to_le_bytes());
    }

    #[test]
    fn write_empty_block_rejects_zero_block_number() {
        let mut cur = Cursor::new(Vec::<u8>::new());
        let err = write_empty_block(&mut cur, 0, 0).expect_err("must reject block_number=0");
        assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput);
    }

    // --- keep_in_remove_all filter ---
    // Tests the private helper directly.

    #[test]
    fn keep_in_remove_all_var_kept() {
        assert!(keep_in_remove_all(Path::new("path/to/something.var")));
    }

    #[test]
    fn keep_in_remove_all_bk2_kept() {
        assert!(keep_in_remove_all(Path::new("00000.bk2")));
        assert!(keep_in_remove_all(Path::new("00001.bk2")));
        assert!(keep_in_remove_all(Path::new("00002.bk2")));
        assert!(keep_in_remove_all(Path::new("00003.bk2")));
    }

    #[test]
    fn keep_in_remove_all_bk2_04_deleted() {
        assert!(!keep_in_remove_all(Path::new("00004.bk2")));
    }

    #[test]
    fn keep_in_remove_all_dat_deleted() {
        assert!(!keep_in_remove_all(Path::new("040100.win32.dat0")));
        assert!(!keep_in_remove_all(Path::new("040100.win32.index")));
    }

    #[test]
    fn keep_in_remove_all_prefixed_bk2_not_kept() {
        assert!(!keep_in_remove_all(Path::new("prefix00000.bk2")));
    }
}

/// Apply a [`SqpkFile`] chunk.
///
/// Dispatches on [`SqpkFileOperation`]:
///
/// ## `AddFile`
///
/// Writes compressed-or-raw block payloads into the target file at
/// `file_offset`. The target path is resolved by joining the game install root
/// with `cmd.path` (a relative path). Parent directories are created with
/// `create_dir_all` if they do not exist.
///
/// If `file_offset == 0`, the file is truncated to zero before writing (the
/// operation replaces the file entirely). If `file_offset > 0`, only the
/// covered byte range is overwritten.
///
/// Each block in `cmd.blocks` is decompressed (or passed through verbatim if
/// uncompressed) into the file handle in sequence. The file handle is kept
/// open in the cache for subsequent chunks targeting the same path.
///
/// ## Errors (`AddFile`)
///
/// - [`crate::ZiPatchError::Io`] — file open, `set_len`, seek, or write
///   failure.
/// - [`crate::ZiPatchError::NegativeFileOffset`] — `cmd.file_offset` is
///   negative and cannot be converted to a `u64` seek position.
/// - [`crate::ZiPatchError::Decompress`] — a DEFLATE block could not be
///   decompressed.
///
/// ## `RemoveAll`
///
/// Deletes all files in `sqpack/<expansion>` and `movie/<expansion>` that are
/// not in the keep-list (`.var` files and `00000`–`00003.bk2`). Before
/// iterating the directories, **all** cached file handles are flushed to avoid
/// open-handle conflicts on Windows.
///
/// Directories that do not exist are silently skipped.
///
/// ## Errors (`RemoveAll`)
///
/// - [`crate::ZiPatchError::Io`] — directory read or file deletion failure.
///
/// ## `DeleteFile`
///
/// Removes a single file at the path resolved from `cmd.path`. The cached
/// handle for that path is evicted before the deletion (required on Windows;
/// harmless on Linux).
///
/// If the file does not exist and [`ApplyContext::ignore_missing`] is `true`,
/// the error is demoted to a `warn!` log and `Ok(())` is returned.
///
/// ## Errors (`DeleteFile`)
///
/// - [`crate::ZiPatchError::Io`] — deletion failed for a reason other than
///   `NotFound`, or `NotFound` with `ignore_missing = false`.
///
/// ## `MakeDirTree`
///
/// Creates the directory tree at the path resolved from `cmd.path`,
/// equivalent to `fs::create_dir_all`. Idempotent.
///
/// ## Errors (`MakeDirTree`)
///
/// - [`crate::ZiPatchError::Io`] — directory creation failed.
fn apply_file(cmd: &SqpkFile, ctx: &mut ApplyContext) -> Result<()> {
    match cmd.operation {
        SqpkFileOperation::AddFile => {
            let path = generic_path(ctx, &cmd.path);
            trace!(path = %path.display(), file_offset = cmd.file_offset, blocks = cmd.blocks.len(), "add file");
            if let Some(parent) = path.parent() {
                fs::create_dir_all(parent)?;
            }
            let file = ctx.open_cached(path)?;
            if cmd.file_offset == 0 {
                file.set_len(0)?;
            }
            let offset = u64::try_from(cmd.file_offset)
                .map_err(|_| ZiPatchError::NegativeFileOffset(cmd.file_offset))?;
            file.seek(SeekFrom::Start(offset))?;
            for block in &cmd.blocks {
                block.decompress_into(file)?;
            }
            Ok(())
        }
        SqpkFileOperation::RemoveAll => {
            // Flush all cached handles before bulk-deleting files.
            ctx.clear_file_cache();
            let folder = expansion_folder_id(cmd.expansion_id);
            debug!(folder = %folder, "remove all");
            for top in &["sqpack", "movie"] {
                let dir = ctx.game_path.join(top).join(&folder);
                if !dir.exists() {
                    continue;
                }
                for entry in fs::read_dir(&dir)? {
                    let path = entry?.path();
                    if path.is_file() && !keep_in_remove_all(&path) {
                        fs::remove_file(&path)?;
                    }
                }
            }
            Ok(())
        }
        SqpkFileOperation::DeleteFile => {
            let path = generic_path(ctx, &cmd.path);
            // Drop the cached handle before the OS delete so the fd is closed first
            // (required on Windows; harmless on Linux).
            ctx.evict_cached(&path);
            match fs::remove_file(&path) {
                Ok(()) => {
                    trace!(path = %path.display(), "delete file");
                    Ok(())
                }
                Err(e) if e.kind() == std::io::ErrorKind::NotFound && ctx.ignore_missing => {
                    warn!(path = %path.display(), "delete file: not found, ignored");
                    Ok(())
                }
                Err(e) => Err(e.into()),
            }
        }
        SqpkFileOperation::MakeDirTree => {
            let path = generic_path(ctx, &cmd.path);
            debug!(path = %path.display(), "make dir tree");
            fs::create_dir_all(path)?;
            Ok(())
        }
    }
}