zipatch_rs/chunk/sqpk/

file.rs

use crate::reader::{PREALLOC_CAP, ReadExt};
use crate::{ParseError, ParseResult as Result};
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
/// [`ParseError::UnknownFileOperation`].
#[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`].
#[derive(Debug)]
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(ParseError::InvalidField {
                context: "negative header_size in block",
            });
        }
        if decompressed_size_raw < 0 {
            return Err(ParseError::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(ParseError::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;
        // Underflow guard: a malformed header where `header_size` exceeds the
        // aligned `block_len` would wrap to a huge size in release builds.
        let data_region = block_len
            .checked_sub(header_size)
            .ok_or(ParseError::InvalidField {
                context: "block_len smaller than header_size",
            })?;
        let data = if is_compressed {
            // Read 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 padding.
            r.read_exact_vec(data_region)?
        } 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 padding =
                data_region
                    .checked_sub(decompressed_size)
                    .ok_or(ParseError::InvalidField {
                        context: "block data region smaller than decompressed_size",
                    })?;
            let d = r.read_exact_vec(decompressed_size)?;
            r.skip(padding 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
    ///
    /// - [`ParseError::Decompress`] — the DEFLATE stream is malformed or
    ///   truncated.
    /// - [`ParseError::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(|e| ParseError::Decompress { source: e })?;
        } 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
    ///
    /// - [`ParseError::Decompress`] — the DEFLATE stream is malformed or
    ///   the manual feed loop made no forward progress (corrupt or truncated
    ///   payload).
    /// - [`ParseError::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::None)
                .map_err(|e| ParseError::Decompress {
                    source: 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(ParseError::Decompress {
                            source: std::io::Error::new(
                                std::io::ErrorKind::InvalidData,
                                "DEFLATE stream made no forward progress",
                            ),
                        });
                    }
                }
            }
        }
    }

    /// Returns `true` if the block stores a raw DEFLATE stream.
    ///
    /// `false` means the block carries already-decompressed bytes (the
    /// `compressed_size == 0x7d00` sentinel).
    #[must_use]
    pub fn is_compressed(&self) -> bool {
        self.is_compressed
    }

    /// Returns the block's expected decompressed length in bytes.
    #[must_use]
    pub fn decompressed_size(&self) -> usize {
        self.decompressed_size
    }

    /// Returns the byte length of the block's stored `data` slab.
    ///
    /// For compressed blocks this is the length of the DEFLATE payload as the
    /// parser stored it (which may include trailing 128-byte alignment padding
    /// that the decoder ignores past the end-of-stream marker). For
    /// uncompressed blocks it equals [`decompressed_size`](Self::decompressed_size).
    #[must_use]
    pub fn data_len(&self) -> usize {
        self.data.len()
    }

    /// 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
    ///
    /// - [`ParseError::Decompress`] — the DEFLATE stream is malformed or
    ///   truncated (compressed blocks only).
    pub fn decompress(&self) -> crate::ParseResult<Cow<'_, [u8]>> {
        if self.is_compressed {
            // Cap pre-alloc: `decompressed_size` originates from the parsed
            // block header. See [`crate::reader::PREALLOC_CAP`] for rationale.
            let mut out = Vec::with_capacity(self.decompressed_size.min(PREALLOC_CAP));
            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. `file_offset` is range-checked against `i64::MAX` at parse time —
/// values with the high bit set (which would round-trip as a negative `i64`
/// in the legacy wire interpretation) are rejected with
/// [`ParseError::NegativeFileOffset`] before the chunk is constructed.
///
/// 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
///
/// # Errors
///
/// Parsing returns a [`crate::ParseError`] if:
/// - The operation byte is not `b'A'`, `b'R'`, `b'D'`, or `b'M'`
///   → [`ParseError::UnknownFileOperation`].
/// - The path bytes are not valid UTF-8 → [`ParseError::Utf8Error`].
/// - A block header contains a negative `header_size` or `decompressed_size`,
///   or a negative non-sentinel `compressed_size`
///   → [`ParseError::InvalidField`].
/// - The body is too short → [`ParseError::Io`].
#[derive(Debug)]
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. Values with the high bit set in the
    /// wire `u64` are rejected at parse time with
    /// [`ParseError::NegativeFileOffset`], so every value reaching here fits
    /// in an `i64`.
    ///
    /// Unused by `RemoveAll`, `DeleteFile`, and `MakeDirTree`.
    pub file_offset: u64,
    /// 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: u64,
    /// 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(ParseError::UnknownFileOperation(b));
        }
    };
    c.skip(2)?; // alignment

    let file_offset_raw = c.read_u64_be()?;
    // The wire field is u64 BE, but the legacy interpretation treated it as
    // a signed i64 — values with the high bit set surface as ParseError so
    // the public `file_offset: u64` only ever carries non-negative offsets
    // (i.e. fits in i64 as well). The error variant keeps the raw value
    // re-encoded as the i64 the legacy reader would have produced.
    if file_offset_raw > i64::MAX as u64 {
        return Err(ParseError::NegativeFileOffset(file_offset_raw as i64));
    }
    let file_offset = file_offset_raw;
    let file_size = c.read_u64_be()?;
    let path_len = c.read_u32_be()? as usize;
    let expansion_id = c.read_u16_be()?;
    c.skip(2)?; // padding

    // Cap path_len against remaining body bytes — without this an attacker
    // can declare a 4 GiB path and OOM the patcher (issue #30).
    let remaining = body.len().saturating_sub(c.position() as usize);
    if path_len > remaining {
        return Err(ParseError::InvalidField {
            context: "SqpkFile path_len exceeds remaining body bytes",
        });
    }
    let path_bytes = c.read_exact_vec(path_len)?;
    let path = String::from_utf8(path_bytes)
        .map(|s| s.trim_end_matches('\0').to_owned())
        .map_err(ParseError::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: u64,
        file_size: u64,
        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.to_be_bytes());
        body.extend_from_slice(&file_size.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 rejects_negative_file_offset_at_parse() {
        // A `u64` wire value with the high bit set must surface as
        // `ParseError::NegativeFileOffset(i64)` — the error preserves the raw
        // value as the legacy signed reading for diagnostics.
        let body = make_header(b'A', u64::MAX, 0, b"\0", 0);
        match parse(&body) {
            Err(ParseError::NegativeFileOffset(v)) => assert_eq!(v, -1),
            other => panic!("expected NegativeFileOffset(-1), got {other:?}"),
        }
    }

    #[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(ParseError::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(ParseError::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(ParseError::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(ParseError::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 ParseError::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(ParseError::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(|e| ParseError::Decompress { source: e })?` arm.
        let block = SqpkCompressedBlock::new(true, 16, vec![0xFFu8; 16]);
        let mut out = Vec::new();
        assert!(matches!(
            block.decompress_into(&mut out),
            Err(ParseError::Decompress { .. })
        ));
        // And via the `decompress()` wrapper — the `?` error arm at line 106.
        assert!(matches!(
            block.decompress(),
            Err(ParseError::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)
    }

    #[test]
    fn parse_rejects_oversized_path_len_issue_30() {
        // Regression for issue #30: a u32 `path_len` from untrusted patch
        // bytes was fed straight into `Vec::with_capacity`, allowing a
        // malicious patch to trigger a ~4 GiB allocation and OOM-abort the
        // process. The parser must now reject such a header with
        // `InvalidField` before any allocation occurs.
        //
        // Original 32-byte fuzz input (from the `parser_sqpk` harness; byte 0
        // is the harness's sub-command selector, dropped here):
        //   2c 41 e5 11 00 36 36 36 36 00 00 00 00 00 00 ff
        //   ff ff ff ff ff ff 00 00 21 00 ac 00 00 00 00 00
        let body: &[u8] = &[
            0x41, 0xe5, 0x11, // op=AddFile, alignment
            0x00, 0x36, 0x36, 0x36, 0x36, 0x00, 0x00, 0x00, // file_offset
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, // file_size
            0xff, 0xff, 0xff, 0xff, // path_len = u32::MAX
            0xff, 0xff, // expansion_id
            0x00, 0x00, // padding
            0x21, 0x00, 0xac, 0x00, // remaining body bytes
        ];
        assert_eq!(body.len(), 31, "test input is the post-selector body");
        let err = parse(body).expect_err("oversized path_len must error");
        assert!(
            matches!(
                err,
                ParseError::InvalidField { context }
                    if context.contains("path_len")
            ),
            "expected InvalidField on oversized path_len, got: {err:?}"
        );
    }
}