zipatch_rs/chunk/sqpk/

mod.rs

//! SQPK chunk sub-commands and their dispatcher.
//!
//! A `ZiPatch` file is made up of top-level chunks; the `SQPK` chunk type is the
//! workhorse — it covers the vast majority of the data in any patch file.
//! Inside each `SQPK` chunk sits a one-byte sub-command tag that selects the
//! specific archive operation to perform.
//!
//! # Sub-command overview
//!
//! | Tag | Type | Purpose |
//! |-----|------|---------|
//! | `A` | [`SqpkAddData`] | Write a data payload into a `.dat` file at a block offset |
//! | `D` | [`SqpkDeleteData`] | Overwrite a block range with empty-block markers |
//! | `E` | [`SqpkExpandData`] | Grow a `.dat` file by adding empty-block markers |
//! | `H` | [`SqpkHeader`] | Write a 1024-byte `SqPack` header |
//! | `T` | [`SqpkTargetInfo`] | Declare the target platform and region |
//! | `F` | [`SqpkFile`] | File-level operation (add, delete, directory creation) |
//! | `I` | [`SqpkIndex`] | Index entry metadata (not applied directly to disk) |
//! | `X` | [`SqpkPatchInfo`] | Patch install metadata (not applied directly to disk) |
//!
//! Unknown sub-command bytes are surfaced as [`ZiPatchError::UnknownSqpkCommand`].
//!
//! # Wire format
//!
//! The SQPK chunk body begins with a 4-byte big-endian `i32` (`inner_size`) that
//! must equal the total body length, followed immediately by the 1-byte sub-command
//! tag. The remaining bytes starting at offset 5 form the sub-command body and are
//! forwarded to the per-command parser.
//!
//! ```text
//! ┌────────────────────────────────────────────────────┐
//! │ inner_size   : i32 BE  (== body.len())             │  bytes 0–3
//! │ sub-command  : u8      ('A','D','E','H','T','F',…)  │  byte  4
//! │ sub-cmd body : [u8]    (varies by sub-command)      │  bytes 5–…
//! └────────────────────────────────────────────────────┘
//! ```
//!
//! # Block-offset units
//!
//! Unless otherwise noted, offsets in SQPK sub-commands are stored as raw `u32`
//! values that must be multiplied by 128 (`<< 7`) to obtain byte offsets. The
//! shift is applied automatically during parsing by the `#[br(map = ...)]`
//! attributes on each struct field; by the time a parsed struct reaches calling
//! code, all `block_offset` fields are already in bytes.
//!
//! # Reference
//!
//! The canonical binary format reference is `XIVLauncher`'s C# implementation at
//! `lib/FFXIVQuickLauncher/src/XIVLauncher.Common/Patching/ZiPatch/Chunk/SqpkCommand/`.

pub(crate) mod add_data;
pub(crate) mod delete_data;
pub(crate) mod expand_data;
pub(crate) mod file;
pub(crate) mod header;
pub(crate) mod index;
pub(crate) mod target_info;

pub use add_data::SqpkAddData;
pub use delete_data::SqpkDeleteData;
pub use expand_data::SqpkExpandData;
pub use file::{SqpkCompressedBlock, SqpkFile, SqpkFileOperation};
pub use header::{SqpkHeader, SqpkHeaderTarget, TargetFileKind, TargetHeaderKind};
pub use index::{IndexCommand, SqpkIndex, SqpkPatchInfo};
pub use target_info::SqpkTargetInfo;

use crate::reader::ReadExt;
use crate::{Result, ZiPatchError};
use binrw::BinRead;
use std::io::Cursor;

/// Identifier of a `SqPack` file targeted by a SQPK command.
///
/// `SqPack` files live under
/// `<game_root>/sqpack/<expansion>/<main_id:02x><sub_id:04x>.<platform>.<kind>`.
/// The three fields together uniquely address one file on disk; see the
/// `apply::path` module for how they are combined into filesystem paths.
#[derive(BinRead, Debug, Clone, PartialEq, Eq, Hash)]
#[br(big)]
pub struct SqpackFile {
    /// Category/repository identifier — the first two hex digits of the filename
    /// stem (e.g. `04` in `040100.win32.dat0`).
    ///
    /// Encoded as a big-endian `u16` (2 bytes) in the wire format.
    pub main_id: u16,
    /// Sub-category identifier — the next four hex digits of the filename stem
    /// (e.g. `0100` in `040100.win32.dat0`).
    ///
    /// Encoded as a big-endian `u16` (2 bytes). The **high byte** (`sub_id >> 8`)
    /// selects the expansion folder: `0` → `ffxiv`, `1` → `ex1`, `2` → `ex2`, etc.
    pub sub_id: u16,
    /// File index within the category, used to derive the numeric suffix:
    ///
    /// - For `.dat` files: appended directly as the decimal `N` in `.datN`.
    /// - For `.index` files: `0` produces no suffix (`.index`); `1` or higher
    ///   appends the value directly (`.index1`, `.index2`, …).
    ///
    /// Encoded as a big-endian `u32` (4 bytes).
    pub file_id: u32,
}

/// Sub-command of a `SQPK` chunk; the variant is selected by the command byte.
///
/// Each variant wraps the parsed body of its corresponding sub-command.
/// `AddData` and `File` are heap-allocated to keep the enum from inflating the
/// stack when used in iterators — `SqpkAddData` can carry a large inline data
/// `Vec`, and `SqpkFile` carries both a path and a `Vec` of compressed blocks.
///
/// Two variants — `Index` and `PatchInfo` — carry metadata consumed by the
/// indexed `ZiPatch` reader (not yet implemented) and have no direct filesystem
/// effect; their [`crate::apply::Apply`] arms return `Ok(())` immediately.
///
/// Unknown sub-command bytes are never silently ignored: they surface as
/// [`ZiPatchError::UnknownSqpkCommand`] during parsing.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SqpkCommand {
    /// SQPK `A` — write a data payload into a `.dat` file at a block offset,
    /// then zero a trailing range of blocks. See [`SqpkAddData`].
    AddData(Box<SqpkAddData>),
    /// SQPK `D` — overwrite a contiguous block range with empty-block markers,
    /// logically freeing those blocks in the `SqPack` archive. See [`SqpkDeleteData`].
    DeleteData(SqpkDeleteData),
    /// SQPK `E` — extend a `.dat` file into previously unallocated space by
    /// writing empty-block markers. See [`SqpkExpandData`].
    ExpandData(SqpkExpandData),
    /// SQPK `H` — write a 1024-byte `SqPack` header into a `.dat` or `.index`
    /// file at offset 0 (version header) or 1024 (secondary header). See [`SqpkHeader`].
    Header(SqpkHeader),
    /// SQPK `T` — declares the target platform and region for all subsequent
    /// path-resolution operations in this patch. See [`SqpkTargetInfo`].
    TargetInfo(SqpkTargetInfo),
    /// SQPK `F` — file-level operation: add a file from inline block payloads,
    /// delete a file, remove all files in an expansion folder, or create a
    /// directory tree. See [`SqpkFile`] and [`SqpkFileOperation`].
    File(Box<SqpkFile>),
    /// SQPK `I` — add or remove a single `SqPack` index entry. Carries the
    /// index hash and block location for use by the indexed `ZiPatch` reader;
    /// has no direct apply effect. See [`SqpkIndex`].
    Index(SqpkIndex),
    /// SQPK `X` — patch install info: status, version, and declared post-patch
    /// install size. Metadata only; not applied to the filesystem. See [`SqpkPatchInfo`].
    PatchInfo(SqpkPatchInfo),
}

/// Parse a SQPK chunk body into a [`SqpkCommand`] variant.
///
/// `body` must be the raw bytes of the entire SQPK chunk body (everything after
/// the outer chunk header that the [`crate::chunk`] layer strips). The first
/// 4 bytes are a big-endian `i32` (`inner_size`) that is validated against
/// `body.len()`; byte 4 is the sub-command tag; bytes 5 onward are forwarded to
/// the per-command parser.
///
/// # Errors
///
/// - [`ZiPatchError::InvalidField`] — the `inner_size` field does not equal
///   `body.len()`.
/// - [`ZiPatchError::UnknownSqpkCommand`] — the sub-command byte is not one of
///   the recognised tags (`A`, `D`, `E`, `H`, `T`, `F`, `I`, `X`).
/// - Any [`ZiPatchError`] returned by the per-command parser (e.g.
///   [`ZiPatchError::BinrwError`] for a truncated sub-command body, or
///   [`ZiPatchError::UnknownFileOperation`] for an unrecognised `F` operation byte).
pub fn parse_sqpk(body: &[u8]) -> Result<SqpkCommand> {
    let mut c = Cursor::new(body);
    let inner_size = c.read_i32_be()? as usize;
    if inner_size != body.len() {
        return Err(ZiPatchError::InvalidField {
            context: "SQPK inner size mismatch",
        });
    }
    let command = c.read_u8()?;
    let cmd_body = &body[5..];

    match command {
        b'T' => Ok(SqpkCommand::TargetInfo(target_info::parse(cmd_body)?)),
        b'I' => Ok(SqpkCommand::Index(index::parse_index(cmd_body)?)),
        b'X' => Ok(SqpkCommand::PatchInfo(index::parse_patch_info(cmd_body)?)),
        b'A' => Ok(SqpkCommand::AddData(Box::new(add_data::parse(cmd_body)?))),
        b'D' => Ok(SqpkCommand::DeleteData(delete_data::parse(cmd_body)?)),
        b'E' => Ok(SqpkCommand::ExpandData(expand_data::parse(cmd_body)?)),
        b'H' => Ok(SqpkCommand::Header(header::parse(cmd_body)?)),
        b'F' => Ok(SqpkCommand::File(Box::new(file::parse(cmd_body)?))),
        _ => Err(ZiPatchError::UnknownSqpkCommand(command)),
    }
}

#[cfg(test)]
mod tests {
    use super::{SqpkCommand, parse_sqpk};

    fn make_sqpk_body(command: u8, cmd_body: &[u8]) -> Vec<u8> {
        let total = 5 + cmd_body.len();
        let mut out = Vec::with_capacity(total);
        out.extend_from_slice(&(total as i32).to_be_bytes());
        out.push(command);
        out.extend_from_slice(cmd_body);
        out
    }

    #[test]
    fn parses_target_info() {
        let mut cmd_body = Vec::new();
        cmd_body.extend_from_slice(&[0u8; 3]); // reserved
        cmd_body.extend_from_slice(&0u16.to_be_bytes()); // platform Win32
        cmd_body.extend_from_slice(&(-1i16).to_be_bytes()); // region Global
        cmd_body.extend_from_slice(&0i16.to_be_bytes()); // not debug
        cmd_body.extend_from_slice(&0u16.to_be_bytes()); // version
        cmd_body.extend_from_slice(&1234u64.to_le_bytes()); // deleted_data_size
        cmd_body.extend_from_slice(&5678u64.to_le_bytes()); // seek_count

        let body = make_sqpk_body(b'T', &cmd_body);
        match parse_sqpk(&body).unwrap() {
            SqpkCommand::TargetInfo(t) => {
                assert_eq!(t.platform_id, 0);
                assert_eq!(t.region, -1);
                assert!(!t.is_debug);
                assert_eq!(t.deleted_data_size, 1234);
                assert_eq!(t.seek_count, 5678);
            }
            other => panic!("expected SqpkCommand::TargetInfo, got {other:?}"),
        }
    }

    #[test]
    fn rejects_inner_size_mismatch() {
        let mut body = Vec::new();
        body.extend_from_slice(&999i32.to_be_bytes()); // wrong inner_size
        body.push(b'T');
        assert!(parse_sqpk(&body).is_err());
    }

    #[test]
    fn rejects_unknown_command() {
        let body = make_sqpk_body(b'Z', &[]);
        assert!(parse_sqpk(&body).is_err());
    }

    fn index_cmd_body() -> Vec<u8> {
        let mut v = Vec::new();
        v.push(b'A'); // IndexCommand::Add
        v.push(0u8); // is_synonym = false
        v.push(0u8); // alignment
        v.extend_from_slice(&0u16.to_be_bytes()); // main_id
        v.extend_from_slice(&0u16.to_be_bytes()); // sub_id
        v.extend_from_slice(&0u32.to_be_bytes()); // file_id
        v.extend_from_slice(&0u64.to_be_bytes()); // file_hash
        v.extend_from_slice(&0u32.to_be_bytes()); // block_offset
        v.extend_from_slice(&0u32.to_be_bytes()); // block_number
        v
    }

    #[test]
    fn parses_index_command() {
        let body = make_sqpk_body(b'I', &index_cmd_body());
        assert!(matches!(parse_sqpk(&body).unwrap(), SqpkCommand::Index(_)));
    }

    #[test]
    fn parses_patch_info_command() {
        let mut cmd_body = Vec::new();
        cmd_body.push(0u8); // status
        cmd_body.push(0u8); // version
        cmd_body.push(0u8); // alignment
        cmd_body.extend_from_slice(&0u64.to_be_bytes()); // install_size
        let body = make_sqpk_body(b'X', &cmd_body);
        assert!(matches!(
            parse_sqpk(&body).unwrap(),
            SqpkCommand::PatchInfo(_)
        ));
    }

    #[test]
    fn index_command_truncated_body_returns_error() {
        // Empty `I` body — index::parse_index must error, exercising the `?` arm.
        let body = make_sqpk_body(b'I', &[]);
        assert!(parse_sqpk(&body).is_err());
    }

    #[test]
    fn patch_info_command_truncated_body_returns_error() {
        // Empty `X` body — index::parse_patch_info must error, exercising the `?` arm.
        let body = make_sqpk_body(b'X', &[]);
        assert!(parse_sqpk(&body).is_err());
    }

    #[test]
    fn parses_add_data_command() {
        let mut cmd_body = Vec::new();
        cmd_body.extend_from_slice(&[0u8; 3]); // pad
        cmd_body.extend_from_slice(&0u16.to_be_bytes()); // main_id
        cmd_body.extend_from_slice(&0u16.to_be_bytes()); // sub_id
        cmd_body.extend_from_slice(&0u32.to_be_bytes()); // file_id
        cmd_body.extend_from_slice(&0u32.to_be_bytes()); // block_offset_raw
        cmd_body.extend_from_slice(&0u32.to_be_bytes()); // data_bytes_raw = 0 → no data
        cmd_body.extend_from_slice(&0u32.to_be_bytes()); // block_delete_number_raw
        let body = make_sqpk_body(b'A', &cmd_body);
        assert!(matches!(
            parse_sqpk(&body).unwrap(),
            SqpkCommand::AddData(_)
        ));
    }

    #[test]
    fn parses_delete_data_command() {
        let mut cmd_body = Vec::new();
        cmd_body.extend_from_slice(&[0u8; 3]); // pad
        cmd_body.extend_from_slice(&0u16.to_be_bytes()); // main_id
        cmd_body.extend_from_slice(&0u16.to_be_bytes()); // sub_id
        cmd_body.extend_from_slice(&0u32.to_be_bytes()); // file_id
        cmd_body.extend_from_slice(&0u32.to_be_bytes()); // block_offset_raw
        cmd_body.extend_from_slice(&1u32.to_be_bytes()); // block_count
        cmd_body.extend_from_slice(&[0u8; 4]); // reserved
        let body = make_sqpk_body(b'D', &cmd_body);
        assert!(matches!(
            parse_sqpk(&body).unwrap(),
            SqpkCommand::DeleteData(_)
        ));
    }

    #[test]
    fn parses_expand_data_command() {
        let mut cmd_body = Vec::new();
        cmd_body.extend_from_slice(&[0u8; 3]); // pad
        cmd_body.extend_from_slice(&0u16.to_be_bytes()); // main_id
        cmd_body.extend_from_slice(&0u16.to_be_bytes()); // sub_id
        cmd_body.extend_from_slice(&0u32.to_be_bytes()); // file_id
        cmd_body.extend_from_slice(&0u32.to_be_bytes()); // block_offset_raw
        cmd_body.extend_from_slice(&1u32.to_be_bytes()); // block_count
        cmd_body.extend_from_slice(&[0u8; 4]); // reserved
        let body = make_sqpk_body(b'E', &cmd_body);
        assert!(matches!(
            parse_sqpk(&body).unwrap(),
            SqpkCommand::ExpandData(_)
        ));
    }

    #[test]
    fn parses_header_command() {
        let mut cmd_body = Vec::new();
        cmd_body.push(b'D'); // file_kind = Dat
        cmd_body.push(b'V'); // header_kind = Version
        cmd_body.push(0u8); // alignment
        cmd_body.extend_from_slice(&0u16.to_be_bytes()); // main_id
        cmd_body.extend_from_slice(&0u16.to_be_bytes()); // sub_id
        cmd_body.extend_from_slice(&0u32.to_be_bytes()); // file_id
        cmd_body.extend_from_slice(&[0u8; 1024]); // header_data
        let body = make_sqpk_body(b'H', &cmd_body);
        assert!(matches!(parse_sqpk(&body).unwrap(), SqpkCommand::Header(_)));
    }

    #[test]
    fn parses_file_command() {
        let mut cmd_body = Vec::new();
        cmd_body.push(b'A'); // operation = AddFile
        cmd_body.extend_from_slice(&[0u8; 2]); // alignment
        cmd_body.extend_from_slice(&0u64.to_be_bytes()); // file_offset
        cmd_body.extend_from_slice(&0u64.to_be_bytes()); // file_size
        cmd_body.extend_from_slice(&1u32.to_be_bytes()); // path_len = 1
        cmd_body.extend_from_slice(&0u16.to_be_bytes()); // expansion_id
        cmd_body.extend_from_slice(&[0u8; 2]); // padding
        cmd_body.push(b'\0'); // path = ""
        let body = make_sqpk_body(b'F', &cmd_body);
        assert!(matches!(parse_sqpk(&body).unwrap(), SqpkCommand::File(_)));
    }
}