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, ApplyObserver};
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. The `Unknown` case deliberately stores the
/// raw `platform_id` and returns `Ok(())` rather than failing eagerly — a
/// patch that only touches non-SqPack chunks (e.g. `ADIR`, `DELD`, or
/// `SqpkFile` operations resolved via `generic_path`) can still apply.
/// `SqPack` `.dat`/`.index` path resolution refuses to guess and returns
/// [`crate::ZiPatchError::UnsupportedPlatform`] on the first lookup.
#[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
///
/// - [`crate::ZiPatchError::UnsupportedPlatform`] — the context's platform is
///   [`Platform::Unknown`]; path resolution refuses to guess a layout.
/// - [`crate::ZiPatchError::Io`] — file open, seek, or write failure.
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
///
/// - [`crate::ZiPatchError::UnsupportedPlatform`] — the context's platform is
///   [`Platform::Unknown`]; path resolution refuses to guess a layout.
/// - [`crate::ZiPatchError::Io`] — file open or write failure (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
///
/// - [`crate::ZiPatchError::UnsupportedPlatform`] — the context's platform is
///   [`Platform::Unknown`]; path resolution refuses to guess a layout.
/// - [`crate::ZiPatchError::Io`] — file open or write failure.
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
///
/// - [`crate::ZiPatchError::UnsupportedPlatform`] — the context's platform is
///   [`Platform::Unknown`]; path resolution refuses to guess a layout.
/// - [`crate::ZiPatchError::Io`] — file open, seek, or write failure.
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 ---

    #[test]
    fn write_empty_block_writes_correct_header_and_zeroed_body() {
        // block_number=2: zeroes 2*128=256 bytes, then writes the 5-field LE
        // header at offset 0.
        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=2 must produce exactly 256 zeroed bytes"
        );
        // Bytes beyond the 20-byte header must all be zero.
        assert!(
            buf[20..].iter().all(|&b| b == 0),
            "bytes after the header must remain zeroed"
        );
        // Header field layout (all LE u32).
        assert_eq!(
            &buf[0..4],
            &128u32.to_le_bytes(),
            "field 0: block-size marker must be 128"
        );
        assert_eq!(&buf[4..8], &0u32.to_le_bytes(), "field 1: must be 0");
        assert_eq!(&buf[8..12], &0u32.to_le_bytes(), "field 2: must be 0");
        assert_eq!(
            &buf[12..16],
            &1u32.to_le_bytes(),
            "field 3: block_number.wrapping_sub(1) must be 1"
        );
        assert_eq!(&buf[16..20], &0u32.to_le_bytes(), "field 4: must be 0");
    }

    #[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("block_number=0 must be rejected");
        assert_eq!(
            err.kind(),
            std::io::ErrorKind::InvalidInput,
            "zero block_number must produce InvalidInput error kind"
        );
    }

    #[test]
    fn write_empty_block_at_nonzero_offset_seeks_correctly() {
        // offset=128: should write 128 zero bytes at position 128, then write
        // the header at position 128.  The first 128 bytes must remain untouched
        // (i.e. whatever was there before).
        let initial = vec![0xABu8; 256];
        let mut cur = Cursor::new(initial);
        write_empty_block(&mut cur, 128, 1).unwrap();
        let buf = cur.into_inner();

        // First 128 bytes untouched.
        assert!(
            buf[..128].iter().all(|&b| b == 0xAB),
            "bytes before offset must be untouched"
        );
        // Bytes from offset 128 to 148 are the header; rest zeroed.
        assert_eq!(
            &buf[128..132],
            &128u32.to_le_bytes(),
            "header marker at offset 128"
        );
    }

    // --- keep_in_remove_all ---

    #[test]
    fn keep_in_remove_all_var_extension_always_kept() {
        assert!(
            keep_in_remove_all(Path::new("path/to/something.var")),
            ".var files must be kept"
        );
        // .var at root.
        assert!(keep_in_remove_all(Path::new("ffxiv.var")));
    }

    #[test]
    fn keep_in_remove_all_bk2_00000_through_00003_kept() {
        for name in &["00000.bk2", "00001.bk2", "00002.bk2", "00003.bk2"] {
            assert!(keep_in_remove_all(Path::new(name)), "{name} must be kept");
        }
    }

    #[test]
    fn keep_in_remove_all_bk2_00004_and_beyond_deleted() {
        for name in &["00004.bk2", "00005.bk2", "00099.bk2"] {
            assert!(
                !keep_in_remove_all(Path::new(name)),
                "{name} must NOT be kept"
            );
        }
    }

    #[test]
    fn keep_in_remove_all_sqpack_dat_and_index_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() {
        // The match is exact on the base name — a file like prefix00000.bk2
        // must NOT be kept.
        assert!(!keep_in_remove_all(Path::new("prefix00000.bk2")));
    }

    #[test]
    fn keep_in_remove_all_path_without_filename_not_kept() {
        // A path component with no file_name (e.g. "/") exercises the
        // `let Some(name) = … else { return false; }` arm (line 102).
        assert!(
            !keep_in_remove_all(Path::new("/")),
            "root path with no filename must return false, not panic"
        );
    }

    // --- SqpkCommand dispatch: Index and PatchInfo are no-ops ---

    #[test]
    fn sqpk_command_index_apply_is_noop() {
        use crate::chunk::SqpackFile;
        use crate::chunk::sqpk::{IndexCommand, SqpkIndex};

        let index_cmd = SqpkIndex {
            command: IndexCommand::Add,
            is_synonym: false,
            target_file: SqpackFile {
                main_id: 0,
                sub_id: 0,
                file_id: 0,
            },
            file_hash: 0,
            block_offset: 0,
            block_number: 0,
        };
        let cmd = SqpkCommand::Index(index_cmd);
        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path());
        // Must return Ok(()) without touching the filesystem.
        cmd.apply(&mut ctx).unwrap();
    }

    #[test]
    fn sqpk_command_patch_info_apply_is_noop() {
        use crate::chunk::sqpk::SqpkPatchInfo;

        let patch_info = SqpkPatchInfo {
            status: 0,
            version: 0,
            install_size: 0,
        };
        let cmd = SqpkCommand::PatchInfo(patch_info);
        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path());
        cmd.apply(&mut ctx).unwrap();
    }

    // --- apply_file AddFile: parent directory creation ---

    #[test]
    fn add_file_creates_parent_directories_automatically() {
        // Exercises the `fs::create_dir_all(parent)?` branch (line 403):
        // the path "deep/nested/file.dat" requires two directory levels that
        // do not yet exist in the temp dir.
        use crate::apply::Apply;
        use crate::chunk::sqpk::{SqpkCompressedBlock, SqpkFile, SqpkFileOperation};

        let file_cmd = SqpkFile {
            operation: SqpkFileOperation::AddFile,
            file_offset: 0,
            file_size: 4,
            expansion_id: 0,
            path: "deep/nested/file.dat".to_owned(),
            blocks: vec![SqpkCompressedBlock::new(false, 4, b"data".to_vec())],
            block_source_offsets: vec![0],
        };
        let cmd = SqpkCommand::File(Box::new(file_cmd));

        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path());
        cmd.apply(&mut ctx).unwrap();
        // `cmd.apply` writes through `BufWriter`; explicit flush is required
        // before reading the on-disk state because `apply_to`'s end-of-stream
        // auto-flush is not in play when callers drive `Apply::apply` directly.
        ctx.flush().unwrap();

        let target = tmp.path().join("deep").join("nested").join("file.dat");
        assert!(
            target.is_file(),
            "AddFile must create parent directories and write the file"
        );
        assert_eq!(
            std::fs::read(&target).unwrap(),
            b"data",
            "file contents must match the block payload"
        );
    }

    // --- apply_file AddFile: negative file_offset rejected ---

    #[test]
    fn add_file_negative_offset_returns_negative_file_offset_error() {
        // Exercises the `u64::try_from(cmd.file_offset).map_err(|_| NegativeFileOffset)?`
        // arm. The wire format stores file_offset as u64 but is cast to i64 after
        // parsing, so a value with the high bit set arrives here as a negative i64.
        let file_cmd = SqpkFile {
            operation: SqpkFileOperation::AddFile,
            file_offset: -1,
            file_size: 0,
            expansion_id: 0,
            path: "neg_offset.dat".to_owned(),
            blocks: vec![],
            block_source_offsets: vec![],
        };
        let cmd = SqpkCommand::File(Box::new(file_cmd));

        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path());
        let err = cmd.apply(&mut ctx).unwrap_err();
        match err {
            ZiPatchError::NegativeFileOffset(n) => assert_eq!(
                n, -1,
                "error must carry the original negative offset for diagnostics"
            ),
            other => panic!("expected NegativeFileOffset(-1), got {other:?}"),
        }
    }

    // --- apply_file DeleteFile: ignore_missing branches ---

    fn delete_file_cmd(path: &str) -> SqpkCommand {
        SqpkCommand::File(Box::new(SqpkFile {
            operation: SqpkFileOperation::DeleteFile,
            file_offset: 0,
            file_size: 0,
            expansion_id: 0,
            path: path.to_owned(),
            blocks: vec![],
            block_source_offsets: vec![],
        }))
    }

    #[test]
    fn delete_file_removes_existing_file() {
        let tmp = tempfile::tempdir().unwrap();
        let target = tmp.path().join("victim.dat");
        std::fs::write(&target, b"bye").unwrap();
        assert!(target.is_file(), "pre-condition: file must exist");

        let cmd = delete_file_cmd("victim.dat");
        let mut ctx = ApplyContext::new(tmp.path());
        cmd.apply(&mut ctx)
            .expect("delete on an existing file must succeed");

        assert!(!target.exists(), "file must be removed after DeleteFile");
    }

    #[test]
    fn delete_file_missing_with_ignore_missing_returns_ok() {
        // Exercises the `Err(NotFound) && ctx.ignore_missing` arm in apply_file's
        // DeleteFile branch — warn-and-continue rather than propagating the error.
        let tmp = tempfile::tempdir().unwrap();
        let target = tmp.path().join("ghost.dat");
        assert!(!target.exists(), "pre-condition: file must not exist");

        let cmd = delete_file_cmd("ghost.dat");
        let mut ctx = ApplyContext::new(tmp.path()).with_ignore_missing(true);
        cmd.apply(&mut ctx)
            .expect("missing file must be silently ignored when ignore_missing=true");
    }

    #[test]
    fn delete_file_missing_without_ignore_missing_returns_not_found() {
        // Companion to the above: with the flag off (default), the NotFound error
        // must propagate as ZiPatchError::Io.
        let tmp = tempfile::tempdir().unwrap();
        let cmd = delete_file_cmd("ghost.dat");
        let mut ctx = ApplyContext::new(tmp.path());

        let err = cmd.apply(&mut ctx).unwrap_err();
        match err {
            ZiPatchError::Io(e) if e.kind() == std::io::ErrorKind::NotFound => {}
            other => panic!("expected Io(NotFound), got {other:?}"),
        }
    }
}

/// 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 writer = ctx.open_cached(path.clone())?;
            if cmd.file_offset == 0 {
                // `set_len` is on the raw `File`, not on `BufWriter`. Flush
                // any pending buffered writes destined for the pre-truncate
                // offsets before reaching through to the underlying handle —
                // otherwise the in-memory buffer would be silently dropped on
                // the next seek and a write error would never surface.
                writer.flush()?;
                writer.get_mut().set_len(0)?;
            }
            let offset = u64::try_from(cmd.file_offset)
                .map_err(|_| ZiPatchError::NegativeFileOffset(cmd.file_offset))?;
            writer.seek(SeekFrom::Start(offset))?;
            // Split-borrow the observer separately from the file-handle cache so
            // we can poll cancellation between blocks while still holding the
            // cached `&mut BufWriter<File>`. The entry is guaranteed to be in
            // the cache because the `open_cached` call immediately above just
            // inserted (or refreshed) it, and no cache-mutating call sits
            // between them.
            let observer: &mut dyn ApplyObserver = &mut *ctx.observer;
            let writer = ctx
                .file_cache
                .get_mut(&path)
                .expect("open_cached above inserted this path");
            for block in &cmd.blocks {
                if observer.should_cancel() {
                    debug!(path = %path.display(), "add file: cancelled mid-blocks");
                    return Err(ZiPatchError::Cancelled);
                }
                block.decompress_into(writer)?;
            }
            Ok(())
        }
        SqpkFileOperation::RemoveAll => {
            // Flush all cached handles before bulk-deleting files — buffered
            // writes against any of the about-to-be-removed paths must reach
            // disk first, or be surfaced as an error rather than silently
            // dropped when the file is unlinked.
            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);
            // Flush and drop the cached handle before the OS delete so the
            // fd is closed first (required on Windows; harmless on Linux),
            // and any buffered writes against the to-be-deleted path either
            // land on disk or surface as an error.
            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(())
        }
    }
}