zipatch_rs/chunk/sqpk/

file.rs

use crate::reader::ReadExt;
use crate::{Result, ZiPatchError};
use flate2::read::DeflateDecoder;
use flate2::{Decompress, FlushDecompress, Status};
use std::borrow::Cow;
use std::io::{Cursor, Read, Write};

/// Operation byte of a SQPK `F` command; selects what the command does to
/// the game install tree.
///
/// Encoded as a single ASCII byte in the wire format:
/// `b'A'` → `AddFile`, `b'R'` → `RemoveAll`, `b'D'` → `DeleteFile`,
/// `b'M'` → `MakeDirTree`. Any other byte is rejected with
/// [`ZiPatchError::UnknownFileOperation`].
///
/// See `SqpkFile.cs` in the `XIVLauncher` reference implementation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SqpkFileOperation {
    /// `A` — write the inline compressed-block payload into a file under the
    /// game install root, creating it (or overwriting it) as needed.
    ///
    /// Parent directories are created automatically. If `file_offset` is zero,
    /// the target file is truncated to zero before writing (full replacement);
    /// if `file_offset` is non-zero, only the covered range is overwritten.
    AddFile,
    /// `R` — delete all files in the expansion folder (`sqpack/<expansion>/`
    /// and `movie/<expansion>/`) that are not on the keep-list.
    ///
    /// Kept unconditionally: `.var` files and `00000.bk2`–`00003.bk2`.
    /// Files `00004.bk2` and beyond are deleted. `expansion_id` selects
    /// the target expansion folder.
    RemoveAll,
    /// `D` — delete a single file at the path given by `SqpkFile::path`.
    DeleteFile,
    /// `M` — create the directory tree at `SqpkFile::path` (equivalent to
    /// `std::fs::create_dir_all`). Idempotent.
    MakeDirTree,
}

/// One block of a [`SqpkFile`] `AddFile` payload, which may be DEFLATE-compressed
/// or stored raw.
///
/// `SqpkFile` payloads are split into a sequence of these blocks. Each block
/// begins with a 16-byte little-endian header that describes the compressed
/// and decompressed sizes, followed by the data bytes padded to a 128-byte
/// boundary.
///
/// ## Compression sentinel
///
/// The `compressed_size` field in the wire header uses the value `0x7d00`
/// (decimal **32000**) as a sentinel meaning "this block is not compressed".
/// Any other value means the data bytes are a raw DEFLATE stream
/// (no zlib wrapper, no gzip header — just RFC 1951 raw deflate).
///
/// ## Wire format of one block (all little-endian)
///
/// ```text
/// ┌─────────────────────────────────────────────────────────────────────┐
/// │ header_size     : i32 LE   always 16 in practice                   │  bytes 0–3
/// │ <pad>           : u32 LE   always zero                              │  bytes 4–7
/// │ compressed_size : i32 LE   byte count of DEFLATE data               │  bytes 8–11
/// │                             OR 0x7d00 (32000) if uncompressed       │
/// │ decompressed_size : i32 LE  byte count of decompressed output       │  bytes 12–15
/// │ data            : [u8]     compressed or raw bytes                  │  bytes 16–…
/// │ <alignment>     : [u8]     zero-padding to 128-byte boundary        │
/// └─────────────────────────────────────────────────────────────────────┘
/// ```
///
/// ## 128-byte alignment formula
///
/// The total byte count to read for a block's data + alignment is:
///
/// ```text
/// block_len = (data_len + 143) & !127
/// ```
///
/// where `data_len` is `compressed_size` if compressed, or `decompressed_size`
/// if uncompressed. The constant 143 is `128 - 1 + 16` (subtract the 16-byte
/// header that is not included in `data_len`, then round up to the next
/// 128-byte boundary). The number of data bytes actually read is
/// `block_len - header_size`; the alignment padding is consumed but discarded.
///
/// ## `pub(crate)` visibility
///
/// `SqpkCompressedBlock` is `pub` so that it appears in rustdoc and can be
/// named in `SqpkFile::blocks`, but it can only be constructed via
/// [`new`](SqpkCompressedBlock::new) (for tests) or by parsing a [`SqpkFile`].
///
/// See `SqpkFile.cs` / `ZiPatchConfig.cs` in the `XIVLauncher` reference implementation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SqpkCompressedBlock {
    // true  → data holds raw DEFLATE bytes (compressed_size != 0x7d00)
    // false → data holds the exact decompressed bytes (compressed_size == 0x7d00)
    is_compressed: bool,
    // Expected output size in bytes; used to pre-allocate the decompression buffer.
    decompressed_size: usize,
    // Compressed blocks: the raw DEFLATE stream, trimmed to compressed_size bytes
    //   (alignment padding is consumed by read() but not stored here).
    // Uncompressed blocks: the exact payload bytes, already stripped of padding.
    data: Vec<u8>,
}

impl SqpkCompressedBlock {
    /// Construct a block directly from its component parts.
    ///
    /// This constructor exists primarily for unit tests. Production code
    /// creates blocks by parsing a [`SqpkFile`] from a patch byte stream.
    ///
    /// - `is_compressed`: `true` if `data` is a raw DEFLATE stream.
    /// - `decompressed_size`: the expected number of bytes after decompression;
    ///   used to pre-allocate the output buffer in
    ///   [`decompress`](SqpkCompressedBlock::decompress).
    /// - `data`: raw compressed bytes or exact uncompressed bytes, depending
    ///   on `is_compressed`.
    #[must_use]
    pub fn new(is_compressed: bool, decompressed_size: usize, data: Vec<u8>) -> Self {
        Self {
            is_compressed,
            decompressed_size,
            data,
        }
    }

    // Parse one block from the reader, consuming header + data + alignment padding.
    //
    // Reads the 16-byte little-endian block header, determines whether the block
    // is compressed (compressed_size != 0x7d00), computes the 128-byte-aligned
    // total length via (data_len + 143) & !127, then reads exactly that many
    // bytes minus the header size — leaving the reader positioned at the start
    // of the next block.
    fn read<R: Read>(r: &mut R) -> Result<Self> {
        // 16-byte block header, all fields little-endian:
        //   i32 header_size  (always 16)
        //   u32 pad          (always 0)
        //   i32 compressed_size   (0x7d00 = uncompressed sentinel)
        //   i32 decompressed_size
        let header_size_raw = r.read_i32_le()?;
        r.skip(4)?; // pad — always zero, no semantic content
        let compressed_size = r.read_i32_le()?;
        let decompressed_size_raw = r.read_i32_le()?;

        if header_size_raw < 0 {
            return Err(ZiPatchError::InvalidField {
                context: "negative header_size in block",
            });
        }
        if decompressed_size_raw < 0 {
            return Err(ZiPatchError::InvalidField {
                context: "negative decompressed_size in block",
            });
        }
        // 0x7d00 (32000) is the sentinel for "store raw, not compressed".
        // Any other value is the byte count of the DEFLATE stream.
        let is_compressed = compressed_size != 0x7d00;
        if is_compressed && compressed_size < 0 {
            return Err(ZiPatchError::InvalidField {
                context: "negative compressed_size in block",
            });
        }

        let header_size = header_size_raw as usize;
        let decompressed_size = decompressed_size_raw as usize;
        // data_len is the logical size used for alignment: for compressed blocks
        // it is the compressed byte count; for uncompressed it is the raw byte count.
        let data_len = if is_compressed {
            compressed_size
        } else {
            decompressed_size_raw
        };
        // Round data_len up to the next 128-byte boundary, accounting for the
        // 16-byte header that precedes the data in the stream.
        // Formula: (data_len + 128 - 1 + (header_size=16)) & !127
        //        = (data_len + 143) & !127
        let block_len = ((data_len as u32 + 143) & !127u32) as usize;
        let data = if is_compressed {
            // Read block_len - header_size bytes: the DEFLATE payload plus any
            // alignment padding. For compressed blocks we store everything
            // (padding included) because DeflateDecoder stops at the end of the
            // DEFLATE stream before reading into the padding.
            r.read_exact_vec(block_len - header_size)?
        } else {
            // Uncompressed: read exactly decompressed_size bytes of payload,
            // then skip any alignment padding so the reader is positioned at the
            // start of the next block.
            let d = r.read_exact_vec(decompressed_size)?;
            r.skip((block_len - header_size - decompressed_size) as u64)?;
            d
        };
        Ok(SqpkCompressedBlock {
            is_compressed,
            decompressed_size,
            data,
        })
    }

    /// Stream the block's decompressed bytes into `w`.
    ///
    /// For uncompressed blocks, `w.write_all(&self.data)` is called directly.
    /// For compressed blocks, the data is piped through [`DeflateDecoder`] (raw
    /// DEFLATE, RFC 1951 — no zlib or gzip wrapper) before being written.
    ///
    /// This is the primary write path used by the apply layer: each block in a
    /// [`SqpkFile`] `AddFile` operation is streamed into the target file handle
    /// in sequence.
    ///
    /// # Errors
    ///
    /// - [`ZiPatchError::Decompress`] — the DEFLATE stream is malformed or
    ///   truncated.
    /// - [`ZiPatchError::Io`] — `w.write_all` failed.
    pub fn decompress_into(&self, w: &mut impl Write) -> Result<()> {
        if self.is_compressed {
            std::io::copy(&mut DeflateDecoder::new(self.data.as_slice()), w)
                .map_err(ZiPatchError::Decompress)?;
        } else {
            w.write_all(&self.data)?;
        }
        Ok(())
    }

    /// Stream the block's decompressed bytes into `w`, reusing a caller-owned
    /// [`Decompress`] state across blocks.
    ///
    /// Equivalent to [`decompress_into`](SqpkCompressedBlock::decompress_into)
    /// in behaviour and error semantics, but avoids the per-call ~100 KiB
    /// zlib-state allocation that [`DeflateDecoder::new`] would otherwise
    /// pay. The apply layer threads a single `Decompress` through every
    /// block in a multi-block `SqpkFile::AddFile` chunk; uncompressed blocks
    /// short-circuit to `write_all` and leave the decompressor untouched.
    ///
    /// `decompressor` is reset via [`Decompress::reset(false)`](Decompress::reset)
    /// at the start of every compressed block, so callers may pass an
    /// already-used state without manually resetting it.
    ///
    /// # Errors
    ///
    /// - [`ZiPatchError::Decompress`] — the DEFLATE stream is malformed or
    ///   the manual feed loop made no forward progress (corrupt or truncated
    ///   payload).
    /// - [`ZiPatchError::Io`] — `w.write_all` failed.
    pub fn decompress_into_with(
        &self,
        decompressor: &mut Decompress,
        w: &mut impl Write,
    ) -> Result<()> {
        if !self.is_compressed {
            w.write_all(&self.data)?;
            return Ok(());
        }

        // Raw DEFLATE — match the legacy `DeflateDecoder::new(_)` zlib_header=false.
        decompressor.reset(false);
        // 8 KiB output buffer matches `std::io::copy`'s default and is plenty
        // for the per-iteration output the underlying miniz_oxide / zlib-ng
        // backends emit. Stays on the stack — no allocation per block.
        let mut out = [0u8; 8 * 1024];
        let mut input: &[u8] = &self.data;
        loop {
            let before_in = decompressor.total_in();
            let before_out = decompressor.total_out();
            let status = decompressor
                .decompress(input, &mut out, FlushDecompress::Finish)
                .map_err(|e| {
                    ZiPatchError::Decompress(std::io::Error::new(
                        std::io::ErrorKind::InvalidData,
                        e,
                    ))
                })?;
            let consumed = (decompressor.total_in() - before_in) as usize;
            let produced = (decompressor.total_out() - before_out) as usize;
            if produced > 0 {
                w.write_all(&out[..produced])?;
            }
            input = &input[consumed..];
            match status {
                Status::StreamEnd => return Ok(()),
                Status::Ok | Status::BufError => {
                    // Forward progress is required. SqPack DEFLATE blocks are
                    // self-contained — the trailing alignment padding the parser
                    // intentionally leaves in `self.data` is past the
                    // end-of-stream marker, so the decoder must signal
                    // StreamEnd before exhausting the input. A no-progress loop
                    // means the payload is corrupt or truncated.
                    if consumed == 0 && produced == 0 {
                        return Err(ZiPatchError::Decompress(std::io::Error::new(
                            std::io::ErrorKind::InvalidData,
                            "DEFLATE stream made no forward progress",
                        )));
                    }
                }
            }
        }
    }

    /// Return the block's decompressed bytes as a [`Cow`].
    ///
    /// Uncompressed blocks return `Cow::Borrowed(&self.data)` — a zero-copy
    /// borrow into the block's existing buffer. Compressed blocks decompress
    /// into a newly allocated `Vec` and return `Cow::Owned`.
    ///
    /// Use [`decompress_into`](SqpkCompressedBlock::decompress_into) instead
    /// when writing to a file handle, to avoid the intermediate allocation.
    ///
    /// # Errors
    ///
    /// - [`ZiPatchError::Decompress`] — the DEFLATE stream is malformed or
    ///   truncated (compressed blocks only).
    pub fn decompress(&self) -> crate::Result<Cow<'_, [u8]>> {
        if self.is_compressed {
            let mut out = Vec::with_capacity(self.decompressed_size);
            self.decompress_into(&mut out)?;
            Ok(Cow::Owned(out))
        } else {
            Ok(Cow::Borrowed(&self.data))
        }
    }
}

/// SQPK `F` command body: a file-level operation on the game install tree.
///
/// Unlike the block-oriented commands (`A`, `D`, `E`) that target `SqPack`
/// archive internals, `F` operates on whole files in the install directory.
/// The operation to perform is selected by [`operation`](SqpkFile::operation).
///
/// ## Wire format
///
/// ```text
/// ┌──────────────────────────────────────────────────────────────────────────┐
/// │ operation    : u8      b'A', b'R', b'D', or b'M'                        │  byte 0
/// │ <padding>    : [u8; 2] (always zero)                                     │  bytes 1–2
/// │ file_offset  : u64 BE  destination byte offset within the target file    │  bytes 3–10
/// │ file_size    : u64 BE  declared size of the target file after operation  │  bytes 11–18
/// │ path_len     : u32 BE  byte length of the path field (including NUL)     │  bytes 19–22
/// │ expansion_id : u16 BE  expansion folder selector for `RemoveAll`         │  bytes 23–24
/// │ <padding>    : [u8; 2] (always zero)                                     │  bytes 25–26
/// │ path         : [u8; path_len]  NUL-terminated UTF-8 path                │  bytes 27–…
/// │ [blocks]     : SqpkCompressedBlock…  (only for `AddFile`)                │
/// └──────────────────────────────────────────────────────────────────────────┘
/// ```
///
/// `file_offset` and `file_size` are stored as big-endian `u64` in the wire
/// format but cast to `i64` after parsing (negative values in `file_offset`
/// cause [`ZiPatchError::NegativeFileOffset`] at apply time).
///
/// The NUL terminator in `path` is stripped during parsing; [`path`](SqpkFile::path)
/// always contains a clean UTF-8 string.
///
/// For `AddFile` operations the remaining bytes in the command body after the
/// path form a sequence of [`SqpkCompressedBlock`]s (see that type's
/// documentation for the block wire format). For all other operations the block
/// list is empty.
///
/// ## Reference
///
/// See `SqpkFile.cs` in the `XIVLauncher` reference implementation.
///
/// # Errors
///
/// Parsing returns a [`crate::ZiPatchError`] if:
/// - The operation byte is not `b'A'`, `b'R'`, `b'D'`, or `b'M'`
///   → [`ZiPatchError::UnknownFileOperation`].
/// - The path bytes are not valid UTF-8 → [`ZiPatchError::Utf8Error`].
/// - A block header contains a negative `header_size` or `decompressed_size`,
///   or a negative non-sentinel `compressed_size`
///   → [`ZiPatchError::InvalidField`].
/// - The body is too short → [`ZiPatchError::Io`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SqpkFile {
    /// The file operation to perform.
    pub operation: SqpkFileOperation,
    /// Destination byte offset within the target file.
    ///
    /// For `AddFile`: if zero, the target file is truncated to zero before
    /// writing (complete replacement); if positive, writing begins at this
    /// byte offset in the existing file. Negative values (cast from the raw
    /// `u64`) are rejected at apply time with [`ZiPatchError::NegativeFileOffset`].
    ///
    /// Unused by `RemoveAll`, `DeleteFile`, and `MakeDirTree`.
    pub file_offset: i64,
    /// Declared total size of the target file after the operation, in bytes.
    ///
    /// Informational; the apply layer does not use this to pre-allocate or
    /// truncate the file (truncation is controlled by `file_offset == 0`).
    pub file_size: i64,
    /// Expansion folder selector used by `RemoveAll`.
    ///
    /// `0` → `ffxiv` (base game), `n > 0` → `ex<n>`. Corresponds to the
    /// high byte of `sub_id` in block-oriented commands.
    pub expansion_id: u16,
    /// Relative path to the target file or directory under the game install root.
    ///
    /// NUL terminator is stripped during parsing. For `AddFile` / `DeleteFile`
    /// this is joined with the install root via `generic_path`. For `MakeDirTree`
    /// it is the directory tree to create.
    pub path: String,
    /// Byte offset of each block's data payload — measured from the start of
    /// the SQPK command body slice — after skipping the block's 16-byte header.
    ///
    /// `block_source_offsets[i]` corresponds to `blocks[i]`. Adding the chunk's
    /// absolute position in the patch file to this offset gives the patch-file
    /// byte offset where the block's data begins, enabling `IndexedZiPatch`
    /// random-access reads that do not need to decompress the full stream.
    ///
    /// Empty for all operations other than `AddFile`.
    pub block_source_offsets: Vec<u64>,
    /// Inline compressed-or-raw block payloads that make up the file content.
    ///
    /// Only populated for `AddFile`; empty for `RemoveAll`, `DeleteFile`, and
    /// `MakeDirTree`. Each block is decompressed in sequence into the target
    /// file by the apply layer. See [`SqpkCompressedBlock`] for the block wire
    /// format and DEFLATE discrimination logic.
    pub blocks: Vec<SqpkCompressedBlock>,
}

// Parse a SQPK 'F' command body into a SqpkFile.
//
// Reads the fixed-size header fields (operation, offsets, sizes, path),
// then — for AddFile only — iterates over the remaining bytes in `body`,
// parsing SqpkCompressedBlock entries until the cursor reaches the end.
// The block source offsets are recorded as the cursor position + 16 (to
// skip the block's own 16-byte header) before each SqpkCompressedBlock::read
// call.
pub(crate) fn parse(body: &[u8]) -> Result<SqpkFile> {
    let mut c = Cursor::new(body);

    let operation = match c.read_u8()? {
        b'A' => SqpkFileOperation::AddFile,
        b'R' => SqpkFileOperation::RemoveAll,
        b'D' => SqpkFileOperation::DeleteFile,
        b'M' => SqpkFileOperation::MakeDirTree,
        b => {
            return Err(ZiPatchError::UnknownFileOperation(b));
        }
    };
    c.skip(2)?; // alignment

    let file_offset = c.read_u64_be()? as i64;
    let file_size = c.read_u64_be()? as i64;
    let path_len = c.read_u32_be()?;
    let expansion_id = c.read_u16_be()?;
    c.skip(2)?; // padding

    let path_bytes = c.read_exact_vec(path_len as usize)?;
    let path = String::from_utf8(path_bytes)
        .map(|s| s.trim_end_matches('\0').to_owned())
        .map_err(ZiPatchError::Utf8Error)?;

    let (blocks, block_source_offsets) = if matches!(operation, SqpkFileOperation::AddFile) {
        let mut blocks = Vec::new();
        let mut offsets = Vec::new();
        while (c.position() as usize) < body.len() {
            // Record offset of the data payload (after the fixed 16-byte block header).
            offsets.push(c.position() + 16);
            blocks.push(SqpkCompressedBlock::read(&mut c)?);
        }
        (blocks, offsets)
    } else {
        (Vec::new(), Vec::new())
    };

    Ok(SqpkFile {
        operation,
        file_offset,
        file_size,
        expansion_id,
        path,
        block_source_offsets,
        blocks,
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    fn make_header(
        op: u8,
        file_offset: i64,
        file_size: i64,
        path: &[u8],
        expansion_id: u16,
    ) -> Vec<u8> {
        let mut body = Vec::new();
        body.push(op);
        body.extend_from_slice(&[0u8; 2]); // alignment
        body.extend_from_slice(&(file_offset as u64).to_be_bytes());
        body.extend_from_slice(&(file_size as u64).to_be_bytes());
        body.extend_from_slice(&(path.len() as u32).to_be_bytes());
        body.extend_from_slice(&expansion_id.to_be_bytes());
        body.extend_from_slice(&[0u8; 2]); // padding
        body.extend_from_slice(path);
        body
    }

    #[test]
    fn parses_add_file_no_blocks() {
        let body = make_header(b'A', 0, 512, b"test\0", 1);
        let cmd = parse(&body).unwrap();
        assert!(matches!(cmd.operation, SqpkFileOperation::AddFile));
        assert_eq!(cmd.file_offset, 0);
        assert_eq!(cmd.file_size, 512);
        assert_eq!(cmd.expansion_id, 1);
        assert_eq!(cmd.path, "test");
        assert!(cmd.blocks.is_empty());
        assert!(cmd.block_source_offsets.is_empty());
    }

    #[test]
    fn parses_add_file_uncompressed_block() {
        // block_len = ((8 + 143) & !127) = 128; read 8 data bytes + skip 104 padding
        let mut body = make_header(b'A', 0, 0, b"\0", 0);
        // header bytes: 1+2+8+8+4+2+2+1 = 28 — block starts at offset 28
        body.extend_from_slice(&16i32.to_le_bytes()); // header_size
        body.extend_from_slice(&0u32.to_le_bytes()); // pad
        body.extend_from_slice(&0x7d00i32.to_le_bytes()); // compressed_size = uncompressed sentinel
        body.extend_from_slice(&8i32.to_le_bytes()); // decompressed_size
        body.extend_from_slice(&[0xABu8; 8]); // data
        body.extend_from_slice(&[0u8; 104]); // alignment padding

        let cmd = parse(&body).unwrap();
        assert_eq!(cmd.blocks.len(), 1);
        let block = &cmd.blocks[0];
        assert!(!block.is_compressed);
        assert_eq!(block.decompressed_size, 8);
        assert_eq!(block.data.len(), 8);
        assert!(block.data.iter().all(|&b| b == 0xAB));
        assert_eq!(block.decompress().unwrap(), vec![0xABu8; 8]);
        assert_eq!(cmd.block_source_offsets, vec![44u64]); // 28 (header) + 16 (block header)
    }

    #[test]
    fn parses_remove_all_operation() {
        let body = make_header(b'R', 0, 0, b"\0", 0);
        let cmd = parse(&body).unwrap();
        assert!(matches!(cmd.operation, SqpkFileOperation::RemoveAll));
        assert!(cmd.blocks.is_empty());
        assert!(cmd.block_source_offsets.is_empty());
    }

    #[test]
    fn parses_delete_file_operation() {
        let body = make_header(b'D', 0, 0, b"sqpack/foo.dat\0", 0);
        let cmd = parse(&body).unwrap();
        assert!(matches!(cmd.operation, SqpkFileOperation::DeleteFile));
        assert_eq!(cmd.path, "sqpack/foo.dat");
    }

    #[test]
    fn parses_make_dir_tree_operation() {
        let body = make_header(b'M', 0, 0, b"sqpack/ex1\0", 0);
        let cmd = parse(&body).unwrap();
        assert!(matches!(cmd.operation, SqpkFileOperation::MakeDirTree));
        assert_eq!(cmd.path, "sqpack/ex1");
    }

    #[test]
    fn rejects_unknown_operation() {
        let body = make_header(b'Z', 0, 0, b"\0", 0);
        assert!(parse(&body).is_err());
    }

    fn block_with_sizes(header_size: i32, compressed_size: i32, decompressed_size: i32) -> Vec<u8> {
        let mut body = make_header(b'A', 0, 0, b"\0", 0);
        body.extend_from_slice(&header_size.to_le_bytes());
        body.extend_from_slice(&0u32.to_le_bytes()); // pad
        body.extend_from_slice(&compressed_size.to_le_bytes());
        body.extend_from_slice(&decompressed_size.to_le_bytes());
        body
    }

    #[test]
    fn rejects_negative_header_size() {
        let body = block_with_sizes(-1, 0x7d00, 0);
        let Err(ZiPatchError::InvalidField { context }) = parse(&body) else {
            panic!("expected InvalidField for negative header_size");
        };
        assert!(
            context.contains("header_size"),
            "unexpected context: {context}"
        );
    }

    #[test]
    fn rejects_negative_decompressed_size() {
        let body = block_with_sizes(16, 0x7d00, -1);
        let Err(ZiPatchError::InvalidField { context }) = parse(&body) else {
            panic!("expected InvalidField for negative decompressed_size");
        };
        assert!(
            context.contains("decompressed_size"),
            "unexpected context: {context}"
        );
    }

    #[test]
    fn rejects_negative_compressed_size() {
        // is_compressed = (compressed_size != 0x7d00) — pass -1 (not 0x7d00).
        let body = block_with_sizes(16, -1, 8);
        let Err(ZiPatchError::InvalidField { context }) = parse(&body) else {
            panic!("expected InvalidField for negative compressed_size");
        };
        assert!(
            context.contains("compressed_size"),
            "unexpected context: {context}"
        );
    }

    #[test]
    fn rejects_invalid_utf8_in_path() {
        // 0xFF is not valid UTF-8 — Utf8Error path on `String::from_utf8`.
        let body = make_header(b'D', 0, 0, &[0xFFu8], 0);
        assert!(matches!(parse(&body), Err(ZiPatchError::Utf8Error(_))));
    }

    #[test]
    fn decompress_into_uncompressed_writes_data_verbatim() {
        // Uncompressed branch: w.write_all(&self.data).
        let block = SqpkCompressedBlock::new(false, 5, b"hello".to_vec());
        let mut out = Vec::new();
        block.decompress_into(&mut out).unwrap();
        assert_eq!(out, b"hello");
    }

    #[test]
    fn decompress_into_with_reuses_decompressor_across_blocks() {
        // Verifies the contract of `decompress_into_with`: the same
        // `Decompress` instance can be threaded through multiple consecutive
        // compressed blocks, with `reset` between calls, and produce identical
        // output to `decompress_into`. This is the apply-layer hot path.
        use flate2::Compression;
        use flate2::write::DeflateEncoder;
        use std::io::Write;

        let payload_a: &[u8] = b"alpha alpha alpha beta beta gamma";
        let payload_b: &[u8] = b"the quick brown fox jumps over the lazy dog";

        let compress = |raw: &[u8]| -> SqpkCompressedBlock {
            let mut enc = DeflateEncoder::new(Vec::new(), Compression::default());
            enc.write_all(raw).unwrap();
            SqpkCompressedBlock::new(true, raw.len(), enc.finish().unwrap())
        };
        let a = compress(payload_a);
        let b = compress(payload_b);

        let mut state = Decompress::new(false);
        let mut out_a = Vec::new();
        a.decompress_into_with(&mut state, &mut out_a).unwrap();
        assert_eq!(out_a, payload_a, "first block must round-trip");

        let mut out_b = Vec::new();
        b.decompress_into_with(&mut state, &mut out_b).unwrap();
        assert_eq!(out_b, payload_b, "reused state must reset and round-trip");
    }

    #[test]
    fn decompress_into_with_uncompressed_skips_decompressor() {
        // The uncompressed branch must never touch the supplied state — it
        // delegates to `write_all`. Verify the state's `total_in`/`total_out`
        // are unchanged after the call.
        let block = SqpkCompressedBlock::new(false, 5, b"hello".to_vec());
        let mut state = Decompress::new(false);
        let before_in = state.total_in();
        let before_out = state.total_out();
        let mut out = Vec::new();
        block.decompress_into_with(&mut state, &mut out).unwrap();
        assert_eq!(out, b"hello");
        assert_eq!(state.total_in(), before_in);
        assert_eq!(state.total_out(), before_out);
    }

    #[test]
    fn decompress_into_with_propagates_corrupt_stream_error() {
        // Garbage DEFLATE payload must surface as ZiPatchError::Decompress
        // rather than panic or loop forever.
        let block = SqpkCompressedBlock::new(true, 16, vec![0xFFu8; 16]);
        let mut state = Decompress::new(false);
        let mut out = Vec::new();
        assert!(matches!(
            block.decompress_into_with(&mut state, &mut out),
            Err(ZiPatchError::Decompress(_))
        ));
    }

    #[test]
    fn decompress_returns_borrowed_for_uncompressed() {
        // Cow::Borrowed branch — no allocation, points at the block's data.
        let block = SqpkCompressedBlock::new(false, 4, b"data".to_vec());
        let cow = block.decompress().unwrap();
        assert!(matches!(cow, Cow::Borrowed(_)));
        assert_eq!(&*cow, b"data");
    }

    #[test]
    fn decompress_into_compressed_propagates_decompress_error() {
        // Garbage DEFLATE payload — the `.map_err(ZiPatchError::Decompress)?` arm.
        let block = SqpkCompressedBlock::new(true, 16, vec![0xFFu8; 16]);
        let mut out = Vec::new();
        assert!(matches!(
            block.decompress_into(&mut out),
            Err(ZiPatchError::Decompress(_))
        ));
        // And via the `decompress()` wrapper — the `?` error arm at line 106.
        assert!(matches!(
            block.decompress(),
            Err(ZiPatchError::Decompress(_))
        ));
    }

    #[test]
    fn parses_compressed_block() {
        use flate2::Compression;
        use flate2::write::DeflateEncoder;
        use std::io::Write;

        let raw: &[u8] = b"hello compressed world";
        let mut enc = DeflateEncoder::new(Vec::new(), Compression::default());
        enc.write_all(raw).unwrap();
        let compressed = enc.finish().unwrap();

        let header_size: i32 = 16;
        let compressed_size = compressed.len() as i32;
        let decompressed_size = raw.len() as i32;
        let block_len = ((compressed_size as u32 + 143) & !127) as usize;
        let trailing_pad = block_len - header_size as usize - compressed.len();

        // header bytes: 1+2+8+8+4+2+2+1 = 28 — block starts at offset 28
        let mut body = make_header(b'A', 0, 0, b"\0", 0);
        body.extend_from_slice(&header_size.to_le_bytes());
        body.extend_from_slice(&0u32.to_le_bytes()); // pad
        body.extend_from_slice(&compressed_size.to_le_bytes());
        body.extend_from_slice(&decompressed_size.to_le_bytes());
        body.extend_from_slice(&compressed);
        body.extend_from_slice(&vec![0u8; trailing_pad]);

        let cmd = parse(&body).unwrap();
        assert_eq!(cmd.blocks.len(), 1);
        let block = &cmd.blocks[0];
        assert!(block.is_compressed);
        assert_eq!(block.decompressed_size, raw.len());
        assert_eq!(block.decompress().unwrap(), raw);
        assert_eq!(cmd.block_source_offsets, vec![44u64]); // 28 (header) + 16 (block header)
    }
}