zipatch_rs/chunk/

mod.rs

//! Wire-format chunk types and the [`ZiPatchReader`] iterator.
//!
//! This module is the parsing layer: it decodes the raw `ZiPatch` byte
//! stream into a stream of typed [`Chunk`] values. Each top-level
//! variant corresponds to one 4-byte ASCII wire tag (`FHDR`, `APLY`,
//! `SQPK`, …); the per-variant submodules below own the binary layout for
//! their body. Nothing in this module touches the filesystem — apply-time
//! effects live in [`crate::apply`].
//!
//! The [`ZiPatchReader`] iterator validates the 12-byte file magic on
//! construction, then yields one [`Chunk`] per [`Iterator::next`] call
//! until the internal `EOF_` terminator is consumed or a parse error
//! surfaces.

pub(crate) mod adir;
pub(crate) mod afsp;
pub(crate) mod aply;
pub(crate) mod ddir;
pub(crate) mod fhdr;
pub(crate) mod sqpk;
pub(crate) mod util;

pub use adir::AddDirectory;
pub use afsp::ApplyFreeSpace;
pub use aply::{ApplyOption, ApplyOptionKind};
pub use ddir::DeleteDirectory;
pub use fhdr::{FileHeader, FileHeaderV2, FileHeaderV3};
pub use sqpk::{SqpackFile, SqpkCommand};
// Re-export SqpkCommand sub-types so callers can match on them
pub use sqpk::{
    IndexCommand, SqpkAddData, SqpkCompressedBlock, SqpkDeleteData, SqpkExpandData, SqpkFile,
    SqpkFileOperation, SqpkHeader, SqpkHeaderTarget, SqpkIndex, SqpkPatchInfo, SqpkTargetInfo,
    TargetFileKind, TargetHeaderKind,
};

use crate::reader::ReadExt;
use crate::{Result, ZiPatchError};
use tracing::trace;

const MAGIC: [u8; 12] = [
    0x91, 0x5A, 0x49, 0x50, 0x41, 0x54, 0x43, 0x48, 0x0D, 0x0A, 0x1A, 0x0A,
];

const MAX_CHUNK_SIZE: usize = 512 * 1024 * 1024;

/// One top-level chunk parsed from a `ZiPatch` stream.
///
/// Each variant corresponds to a 4-byte ASCII wire tag. The tag dispatch table
/// mirrors the C# reference in
/// `lib/FFXIVQuickLauncher/.../Patching/ZiPatch/Chunk/ZiPatchChunk.cs`.
///
/// # Observed frequency
///
/// SE's XIVARR+ patch files almost exclusively contain `FHDR`, `APLY`, and
/// `SQPK` chunks. `ADIR`/`DELD` can theoretically appear and are implemented,
/// but are rarely emitted in practice. `APFS` has never been observed in modern
/// patches (the reference implementation treats it as a no-op). `EOF_` is
/// consumed by [`ZiPatchReader`] and is never yielded to the caller.
///
/// # Exhaustiveness
///
/// The enum is `#[non_exhaustive]`. Match arms should include a wildcard to
/// remain forward-compatible as new chunk types are added.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Chunk {
    /// `FHDR` — the first chunk in every patch file; carries version and
    /// per-version patch metadata. See [`FileHeader`] for the versioned body.
    FileHeader(FileHeader),
    /// `APLY` — sets or clears a boolean apply-time flag on the
    /// [`crate::ApplyContext`] (e.g. "ignore missing files"). See [`ApplyOption`].
    ApplyOption(ApplyOption),
    /// `APFS` — free-space book-keeping emitted by old patcher tooling; treated
    /// as a no-op at apply time. See [`ApplyFreeSpace`].
    ApplyFreeSpace(ApplyFreeSpace),
    /// `ADIR` — instructs the patcher to create a directory under the game
    /// install root. See [`AddDirectory`].
    AddDirectory(AddDirectory),
    /// `DELD` — instructs the patcher to remove a directory under the game
    /// install root. See [`DeleteDirectory`].
    DeleteDirectory(DeleteDirectory),
    /// `SQPK` — the workhorse chunk; wraps one of eight sub-commands that
    /// add, delete, expand, or replace `SqPack` data. See [`SqpkCommand`].
    Sqpk(SqpkCommand),
    /// `EOF_` — marks the clean end of the patch stream. [`ZiPatchReader`]
    /// consumes this chunk internally; it is never yielded to the caller.
    EndOfFile,
}

/// One parsed chunk plus its 4-byte ASCII tag and the byte count consumed
/// from the input stream by its frame.
///
/// Returned by [`parse_chunk`]. The `consumed` count is exactly the size of
/// the chunk's on-wire frame: `4 (body_len) + 4 (tag) + body_len + 4 (crc32)`
/// = `body_len + 12`. This is what
/// [`ZiPatchReader`](crate::ZiPatchReader) accumulates into its running
/// byte counter for progress reporting.
pub(crate) struct ParsedChunk {
    pub(crate) chunk: Chunk,
    pub(crate) tag: [u8; 4],
    pub(crate) consumed: u64,
}

/// Parse one chunk frame from `r`.
///
/// # Wire framing
///
/// Each chunk is laid out as:
///
/// ```text
/// [body_len: u32 BE] [tag: 4 bytes] [body: body_len bytes] [crc32: u32 BE]
/// ```
///
/// The CRC32 is computed over `tag ++ body` (not over `body_len`), matching
/// the C# `ChecksumBinaryReader` in the `XIVLauncher` reference. When
/// `verify_checksums` is `true` and the stored CRC does not match the computed
/// one, [`ZiPatchError::ChecksumMismatch`] is returned.
///
/// # Errors
///
/// - [`ZiPatchError::TruncatedPatch`] — the reader returns EOF while reading
///   the `body_len` field (i.e. no more chunks are present but `EOF_` was
///   never seen).
/// - [`ZiPatchError::OversizedChunk`] — `body_len` exceeds 512 MiB.
/// - [`ZiPatchError::ChecksumMismatch`] — CRC32 mismatch (only when
///   `verify_checksums` is `true`).
/// - [`ZiPatchError::UnknownChunkTag`] — tag is not recognised.
/// - [`ZiPatchError::Io`] — any other I/O failure reading from `r`.
pub(crate) fn parse_chunk<R: std::io::Read>(
    r: &mut R,
    verify_checksums: bool,
) -> Result<ParsedChunk> {
    let size = match r.read_u32_be() {
        Ok(s) => s as usize,
        Err(ZiPatchError::Io(e)) if e.kind() == std::io::ErrorKind::UnexpectedEof => {
            return Err(ZiPatchError::TruncatedPatch);
        }
        Err(e) => return Err(e),
    };
    if size > MAX_CHUNK_SIZE {
        return Err(ZiPatchError::OversizedChunk(size));
    }

    // Tag (4 B) and CRC (4 B) are always present regardless of body shape.
    let mut tag = [0u8; 4];
    r.read_exact(&mut tag)?;

    // Peek at the first 5 bytes of the body without committing to either the
    // generic single-allocation path or the SQPK `A` zero-copy-into-data path.
    // For SQPK chunks, those 5 bytes are `[inner_size: i32 BE][sub_cmd: u8]`.
    // For chunks with bodies shorter than 5 bytes (e.g. `EOF_`), we still read
    // exactly `size` bytes into the prefix array and leave the rest zero.
    let mut prefix = [0u8; 5];
    let prefix_len = size.min(5);
    if prefix_len > 0 {
        r.read_exact(&mut prefix[..prefix_len])?;
    }

    // ---- Fast path: SQPK `A` (SqpkAddData) — see `parse_sqpk_add_data_fast`. ----
    if &tag == b"SQPK" && size >= 5 + SQPK_ADDDATA_HEADER_SIZE && prefix[4] == b'A' {
        return parse_sqpk_add_data_fast(r, tag, prefix, size, verify_checksums);
    }

    // ---- Generic path: one allocation for the whole body. ----
    let mut body_vec = vec![0u8; size];
    body_vec[..prefix_len].copy_from_slice(&prefix[..prefix_len]);
    if size > prefix_len {
        r.read_exact(&mut body_vec[prefix_len..])?;
    }

    let mut crc_buf = [0u8; 4];
    r.read_exact(&mut crc_buf)?;
    let expected_crc = u32::from_be_bytes(crc_buf);

    if verify_checksums {
        let mut hasher = crc32fast::Hasher::new();
        hasher.update(&tag);
        hasher.update(&body_vec);
        let actual_crc = hasher.finalize();
        if actual_crc != expected_crc {
            return Err(ZiPatchError::ChecksumMismatch {
                tag,
                expected: expected_crc,
                actual: actual_crc,
            });
        }
    }

    trace!(tag = %String::from_utf8_lossy(&tag), "chunk");

    // 4 (body_len) + 4 (tag) + size (body) + 4 (crc32)
    let consumed = (size as u64) + 12;

    let body = &body_vec[..];

    let chunk = match &tag {
        b"EOF_" => Chunk::EndOfFile,
        b"FHDR" => Chunk::FileHeader(fhdr::parse(body)?),
        b"APLY" => Chunk::ApplyOption(aply::parse(body)?),
        b"APFS" => Chunk::ApplyFreeSpace(afsp::parse(body)?),
        b"ADIR" => Chunk::AddDirectory(adir::parse(body)?),
        b"DELD" => Chunk::DeleteDirectory(ddir::parse(body)?),
        b"SQPK" => Chunk::Sqpk(sqpk::parse_sqpk(body)?),
        _ => return Err(ZiPatchError::UnknownChunkTag(tag)),
    };

    Ok(ParsedChunk {
        chunk,
        tag,
        consumed,
    })
}

// Size of the SqpkAddData fixed header that precedes the inline data payload.
// Mirrors `add_data::SqpkAddData::DATA_SOURCE_OFFSET` (23) without taking a
// `u64` round-trip; kept private to the framing path.
const SQPK_ADDDATA_HEADER_SIZE: usize = 23;

/// Fast path for SQPK `A` (`SqpkAddData`) chunks.
///
/// `AddData` is the largest chunk type by byte volume — payloads of hundreds of
/// KB to MB are typical. The generic framing path allocates one `Vec<u8>` of
/// `size` for the whole body, then `binrw`'s derived parser allocates a second
/// `Vec<u8>` of exactly `data_bytes` and memcpys the inline payload into it.
/// That second allocation + memcpy dominates parse time for `AddData`.
///
/// This function reads the `AddData` fixed header into a stack array, parses
/// the seven fields directly, allocates the `data` payload at its exact size,
/// and `read_exact`s the source bytes straight into it — one allocation, no
/// intermediate copy of the payload.
///
/// On entry: `tag` and the 5-byte `prefix` (SQPK `inner_size` + sub-command
/// byte) have already been consumed from `r`. The remaining bytes are
/// `[fixed_header: 23 B][data: data_bytes][crc32: 4 B]`.
fn parse_sqpk_add_data_fast<R: std::io::Read>(
    r: &mut R,
    tag: [u8; 4],
    prefix: [u8; 5],
    size: usize,
    verify_checksums: bool,
) -> Result<ParsedChunk> {
    // Validate the SQPK inner_size against the outer chunk size, matching the
    // check in `sqpk::parse_sqpk` so callers see byte-identical error behaviour.
    let inner_size = i32::from_be_bytes([prefix[0], prefix[1], prefix[2], prefix[3]]) as usize;
    if inner_size != size {
        return Err(ZiPatchError::InvalidField {
            context: "SQPK inner size mismatch",
        });
    }

    let mut header = [0u8; SQPK_ADDDATA_HEADER_SIZE];
    r.read_exact(&mut header)?;

    // SqpkAddData fixed-header layout (all big-endian):
    //   [0..3]   pad
    //   [3..5]   main_id   u16
    //   [5..7]   sub_id    u16
    //   [7..11]  file_id   u32
    //   [11..15] block_offset_raw  u32 (<< 7 = bytes)
    //   [15..19] data_bytes_raw    u32 (<< 7 = bytes)
    //   [19..23] block_delete_raw  u32 (<< 7 = bytes)
    let main_id = u16::from_be_bytes([header[3], header[4]]);
    let sub_id = u16::from_be_bytes([header[5], header[6]]);
    let file_id = u32::from_be_bytes([header[7], header[8], header[9], header[10]]);
    let block_offset_raw = u32::from_be_bytes([header[11], header[12], header[13], header[14]]);
    let data_bytes_raw = u32::from_be_bytes([header[15], header[16], header[17], header[18]]);
    let block_delete_raw = u32::from_be_bytes([header[19], header[20], header[21], header[22]]);

    let block_offset = (block_offset_raw as u64) << 7;
    let data_bytes = (data_bytes_raw as u64) << 7;
    let block_delete_number = (block_delete_raw as u64) << 7;

    // The declared payload length must fit exactly within the chunk body:
    //   size = 5 (inner_size + sub_cmd) + 23 (fixed header) + data_bytes
    let expected_data = size - 5 - SQPK_ADDDATA_HEADER_SIZE;
    if data_bytes as usize != expected_data {
        return Err(ZiPatchError::InvalidField {
            context: "SqpkAddData data_bytes does not match SQPK body length",
        });
    }

    let mut data = vec![0u8; data_bytes as usize];
    r.read_exact(&mut data)?;

    let mut crc_buf = [0u8; 4];
    r.read_exact(&mut crc_buf)?;
    let expected_crc = u32::from_be_bytes(crc_buf);

    if verify_checksums {
        // CRC is over `tag ++ body`. The body is split across three disjoint
        // buffers — feed each segment to the incremental hasher.
        let mut hasher = crc32fast::Hasher::new();
        hasher.update(&tag);
        hasher.update(&prefix);
        hasher.update(&header);
        hasher.update(&data);
        let actual_crc = hasher.finalize();
        if actual_crc != expected_crc {
            return Err(ZiPatchError::ChecksumMismatch {
                tag,
                expected: expected_crc,
                actual: actual_crc,
            });
        }
    }

    trace!(tag = %String::from_utf8_lossy(&tag), "chunk");

    let chunk = Chunk::Sqpk(sqpk::SqpkCommand::AddData(Box::new(sqpk::SqpkAddData {
        target_file: sqpk::SqpackFile {
            main_id,
            sub_id,
            file_id,
        },
        block_offset,
        data_bytes,
        block_delete_number,
        data,
    })));

    // 4 (body_len) + 4 (tag) + size (body) + 4 (crc32)
    let consumed = (size as u64) + 12;

    Ok(ParsedChunk {
        chunk,
        tag,
        consumed,
    })
}

/// Iterator over the [`Chunk`]s in a `ZiPatch` stream.
///
/// `ZiPatchReader` wraps any [`std::io::Read`] source and yields one
/// [`Chunk`] per call to [`Iterator::next`]. It validates the 12-byte file
/// magic on construction, then reads chunks sequentially until the `EOF_`
/// terminator is encountered or an error occurs.
///
/// # Stream contract
///
/// - **Magic** — the first 12 bytes must be `\x91ZIPATCH\r\n\x1a\n`. Any
///   mismatch returns [`ZiPatchError::InvalidMagic`] from [`ZiPatchReader::new`].
/// - **Framing** — every chunk is a length-prefixed frame:
///   `[body_len: u32 BE] [tag: 4 B] [body: body_len B] [crc32: u32 BE]`.
/// - **CRC32** — computed over `tag ++ body`. Verification is enabled by
///   default; use [`ZiPatchReader::skip_checksum_verification`] to disable it.
/// - **Termination** — the `EOF_` chunk is consumed internally and causes
///   the iterator to return `None`. Call [`ZiPatchReader::is_complete`] after
///   iteration to distinguish a clean end from a truncated stream.
/// - **Fused** — once `None` is returned (either from `EOF_` or an error),
///   subsequent calls to `next` also return `None`. The iterator implements
///   [`std::iter::FusedIterator`].
///
/// # Errors
///
/// Each call to [`Iterator::next`] returns `Some(Err(e))` on parse failure,
/// then `None` on all future calls. Possible errors include:
/// - [`ZiPatchError::TruncatedPatch`] — stream ended before `EOF_`.
/// - [`ZiPatchError::OversizedChunk`] — a declared chunk body exceeds 512 MiB.
/// - [`ZiPatchError::ChecksumMismatch`] — CRC32 verification failed.
/// - [`ZiPatchError::UnknownChunkTag`] — unrecognised 4-byte tag.
/// - [`ZiPatchError::Io`] — underlying I/O failure.
///
/// # Example
///
/// Build a minimal in-memory patch (magic + `ADIR` + `EOF_`) and iterate it:
///
/// ```rust
/// use std::io::Cursor;
/// use zipatch_rs::{Chunk, ZiPatchReader};
///
/// // Helper: wrap tag + body into a correctly framed chunk with CRC32.
/// fn make_chunk(tag: &[u8; 4], body: &[u8]) -> Vec<u8> {
///     let mut crc_input = Vec::new();
///     crc_input.extend_from_slice(tag);
///     crc_input.extend_from_slice(body);
///     let crc = crc32fast::hash(&crc_input);
///
///     let mut out = Vec::new();
///     out.extend_from_slice(&(body.len() as u32).to_be_bytes());
///     out.extend_from_slice(tag);
///     out.extend_from_slice(body);
///     out.extend_from_slice(&crc.to_be_bytes());
///     out
/// }
///
/// // 12-byte ZiPatch magic.
/// let magic: [u8; 12] = [0x91, 0x5A, 0x49, 0x50, 0x41, 0x54, 0x43, 0x48, 0x0D, 0x0A, 0x1A, 0x0A];
///
/// // ADIR body: u32 BE name_len (7) + b"created".
/// let mut adir_body = Vec::new();
/// adir_body.extend_from_slice(&7u32.to_be_bytes());
/// adir_body.extend_from_slice(b"created");
///
/// let mut patch = Vec::new();
/// patch.extend_from_slice(&magic);
/// patch.extend_from_slice(&make_chunk(b"ADIR", &adir_body));
/// patch.extend_from_slice(&make_chunk(b"EOF_", &[]));
///
/// let chunks: Vec<_> = ZiPatchReader::new(Cursor::new(patch))
///     .unwrap()
///     .collect::<Result<_, _>>()
///     .unwrap();
///
/// assert_eq!(chunks.len(), 1);
/// assert!(matches!(chunks[0], Chunk::AddDirectory(_)));
/// ```
#[derive(Debug)]
pub struct ZiPatchReader<R> {
    inner: std::io::BufReader<R>,
    done: bool,
    verify_checksums: bool,
    eof_seen: bool,
    // Running total of bytes consumed from `inner`, including the 12-byte
    // magic header. Updated after each successful `parse_chunk` call.
    // Exposed via `bytes_read()` so the apply driver can fire monotonic
    // progress events without instrumenting the underlying `Read` source.
    bytes_read: u64,
    // 4-byte ASCII tag of the most recently yielded chunk. `None` before the
    // first successful `next()` and after iteration completes. Used by
    // `apply_to` to attach the tag to per-chunk progress events without
    // re-matching on the `Chunk` enum.
    last_tag: Option<[u8; 4]>,
    // Absolute patch-file offset of the body of the most recently yielded
    // chunk (i.e. the byte right after the 8-byte `[len: u32 BE, tag: [u8;4]]`
    // frame header). `None` until the first chunk is successfully yielded; the
    // value is only set on the success arms of `next()` so a parse failure
    // never exposes a stale offset.
    current_body_offset: Option<u64>,
}

impl<R: std::io::Read> ZiPatchReader<R> {
    /// Wrap `reader` and validate the leading 12-byte `ZiPatch` magic.
    ///
    /// Consumes exactly 12 bytes from `reader`. The magic is the byte sequence
    /// `0x91 0x5A 0x49 0x50 0x41 0x54 0x43 0x48 0x0D 0x0A 0x1A 0x0A`
    /// (i.e. `\x91ZIPATCH\r\n\x1a\n`).
    ///
    /// The reader is wrapped in a [`std::io::BufReader`] internally, so the
    /// many small typed reads the chunk parser issues (4-byte size, 4-byte
    /// tag, 5-byte SQPK prefix, …) coalesce into a small number of syscalls.
    /// Callers do not need to pre-wrap a raw [`std::fs::File`] or other
    /// unbuffered source.
    ///
    /// CRC32 verification is **enabled** by default. Call
    /// [`ZiPatchReader::skip_checksum_verification`] before iterating to
    /// disable it.
    ///
    /// # Errors
    ///
    /// - [`ZiPatchError::InvalidMagic`] — the first 12 bytes do not match the
    ///   expected magic.
    /// - [`ZiPatchError::Io`] — an I/O error occurred while reading the magic.
    pub fn new(reader: R) -> Result<Self> {
        let mut reader = std::io::BufReader::new(reader);
        let magic = reader.read_exact_vec(12)?;
        if magic.as_slice() != MAGIC {
            return Err(ZiPatchError::InvalidMagic);
        }
        Ok(Self {
            inner: reader,
            done: false,
            verify_checksums: true,
            eof_seen: false,
            // The 12-byte magic header has already been consumed.
            bytes_read: 12,
            last_tag: None,
            current_body_offset: None,
        })
    }

    /// Enable per-chunk CRC32 verification (the default).
    ///
    /// This is the default state after [`ZiPatchReader::new`]. Calling this
    /// method after construction is only necessary if
    /// [`ZiPatchReader::skip_checksum_verification`] was previously called.
    #[must_use]
    pub fn verify_checksums(mut self) -> Self {
        self.verify_checksums = true;
        self
    }

    /// Disable per-chunk CRC32 verification.
    ///
    /// Useful when the source has already been verified out-of-band (e.g. a
    /// download hash was checked before the file was opened), or when
    /// processing known-good test data where the overhead is unnecessary.
    #[must_use]
    pub fn skip_checksum_verification(mut self) -> Self {
        self.verify_checksums = false;
        self
    }

    /// Returns `true` if iteration reached the `EOF_` terminator cleanly.
    ///
    /// A `false` return after `next()` yields `None` indicates the stream was
    /// truncated — the download or file copy was incomplete. In that case the
    /// iterator stopped because of a [`ZiPatchError::TruncatedPatch`] error,
    /// not because the patch finished normally.
    pub fn is_complete(&self) -> bool {
        self.eof_seen
    }

    /// Returns the running total of bytes consumed from the patch stream.
    ///
    /// Starts at `12` after [`ZiPatchReader::new`] (the magic header has been
    /// read) and increases monotonically by the size of each chunk's wire
    /// frame after each successful [`Iterator::next`] call. Includes the
    /// `EOF_` terminator's frame.
    ///
    /// On parse error, the counter is **not** advanced past the failing
    /// chunk — it reflects the byte offset at the start of that chunk's
    /// length prefix, not the broken position somewhere inside its frame.
    /// Use this offset together with the surfaced error to point a user at
    /// where the patch became unreadable.
    ///
    /// This is the same counter that the
    /// [`apply_to`](crate::ZiPatchReader::apply_to) driver attaches to
    /// [`ChunkEvent::bytes_read`](crate::ChunkEvent::bytes_read) when firing
    /// progress events. Useful for the `bytes_applied / total_patch_size`
    /// ratio in a progress bar.
    #[must_use]
    pub fn bytes_read(&self) -> u64 {
        self.bytes_read
    }

    /// Returns the 4-byte ASCII tag of the most recently yielded chunk.
    ///
    /// `None` before the first successful [`Iterator::next`] call and after
    /// the `EOF_` terminator has been consumed (or an error has been
    /// surfaced). Used by [`apply_to`](crate::ZiPatchReader::apply_to) to
    /// populate [`ChunkEvent::kind`](crate::ChunkEvent::kind).
    #[must_use]
    pub fn last_tag(&self) -> Option<[u8; 4]> {
        self.last_tag
    }

    /// Returns the absolute patch-file offset of the body of the most recently
    /// yielded chunk.
    ///
    /// The chunk body begins immediately after the 8-byte
    /// `[body_len: u32 BE, tag: [u8; 4]]` frame header, so the value points at
    /// the first byte of the body — for `SQPK` chunks that is the start of
    /// `[inner_size: i32 BE, sub_cmd: u8, …]`; for the other chunk types it
    /// is the start of the variant-specific body.
    ///
    /// Index builders use this to compute absolute patch-file offsets for
    /// `SqpkAddData::data`, `SqpkFile` block payloads, and `SqpkHeader::header_data`
    /// without re-walking the stream.
    ///
    /// `None` before the first chunk is successfully yielded. A parse failure
    /// leaves the previously-set value untouched (the offset returned by this
    /// method always points at a chunk that was successfully parsed).
    #[must_use]
    pub fn current_chunk_body_offset(&self) -> Option<u64> {
        self.current_body_offset
    }
}

impl ZiPatchReader<std::io::BufReader<std::fs::File>> {
    /// Open the file at `path`, wrap it in a [`std::io::BufReader`], and
    /// validate the `ZiPatch` magic.
    ///
    /// This is a convenience constructor equivalent to:
    ///
    /// ```rust,no_run
    /// # use std::io::BufReader;
    /// # use std::fs::File;
    /// # use zipatch_rs::ZiPatchReader;
    /// let reader = ZiPatchReader::new(BufReader::new(File::open("patch.patch").unwrap())).unwrap();
    /// ```
    ///
    /// # Errors
    ///
    /// - [`ZiPatchError::Io`] — the file could not be opened.
    /// - [`ZiPatchError::InvalidMagic`] — the file does not start with the
    ///   `ZiPatch` magic bytes.
    pub fn from_path(path: impl AsRef<std::path::Path>) -> crate::Result<Self> {
        let file = std::fs::File::open(path)?;
        Self::new(std::io::BufReader::new(file))
    }
}

impl<R: std::io::Read> Iterator for ZiPatchReader<R> {
    type Item = Result<Chunk>;

    fn next(&mut self) -> Option<Self::Item> {
        if self.done {
            return None;
        }
        // Snapshot the body offset before parsing so a successful parse can
        // commit it without re-walking the stream. The chunk body begins after
        // the 8-byte `[body_len: u32 BE, tag: [u8; 4]]` frame header.
        let body_offset = self.bytes_read + 8;
        match parse_chunk(&mut self.inner, self.verify_checksums) {
            Ok(ParsedChunk {
                chunk: Chunk::EndOfFile,
                tag,
                consumed,
            }) => {
                self.bytes_read += consumed;
                self.last_tag = Some(tag);
                self.current_body_offset = Some(body_offset);
                self.done = true;
                self.eof_seen = true;
                None
            }
            Ok(ParsedChunk {
                chunk,
                tag,
                consumed,
            }) => {
                self.bytes_read += consumed;
                self.last_tag = Some(tag);
                self.current_body_offset = Some(body_offset);
                Some(Ok(chunk))
            }
            Err(e) => {
                self.done = true;
                Some(Err(e))
            }
        }
    }
}

impl<R: std::io::Read> std::iter::FusedIterator for ZiPatchReader<R> {}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::test_utils::make_chunk;
    use std::io::Cursor;

    // --- parse_chunk error paths ---

    #[test]
    fn truncated_at_chunk_boundary_yields_truncated_patch() {
        // Magic + no chunks: parse_chunk must see EOF on the body_len read and
        // convert it to TruncatedPatch.  This exercises the
        // `Err(ZiPatchError::Io(e)) if e.kind() == UnexpectedEof` arm at
        // chunk/mod.rs line 121.
        let mut patch = Vec::new();
        patch.extend_from_slice(&MAGIC);
        let mut reader = ZiPatchReader::new(Cursor::new(patch)).unwrap();
        match reader
            .next()
            .expect("iterator must yield an error, not None")
        {
            Err(ZiPatchError::TruncatedPatch) => {}
            other => panic!("expected TruncatedPatch, got {other:?}"),
        }
        assert!(!reader.is_complete(), "stream is not clean-ended");
    }

    #[test]
    fn non_eof_io_error_on_body_len_read_propagates_as_io() {
        // Exercises the `Err(e) => return Err(e)` arm at line 124: an I/O
        // error that is NOT UnexpectedEof must propagate verbatim.
        // We trigger this by passing a reader that errors immediately.
        struct BrokenReader;
        impl std::io::Read for BrokenReader {
            fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
                Err(std::io::Error::new(
                    std::io::ErrorKind::BrokenPipe,
                    "simulated broken pipe",
                ))
            }
        }
        let result = parse_chunk(&mut BrokenReader, false);
        match result {
            Err(ZiPatchError::Io(e)) => {
                assert_eq!(
                    e.kind(),
                    std::io::ErrorKind::BrokenPipe,
                    "non-EOF I/O error must propagate unchanged, got kind {:?}",
                    e.kind()
                );
            }
            Err(other) => panic!("expected ZiPatchError::Io(BrokenPipe), got {other:?}"),
            Ok(_) => panic!("expected an error, got Ok"),
        }
    }

    #[test]
    fn truncated_after_one_chunk_yields_truncated_patch() {
        // Magic + one well-formed ADIR + no more bytes: the second call to
        // next() must surface TruncatedPatch, not None.
        let mut adir_body = Vec::new();
        adir_body.extend_from_slice(&4u32.to_be_bytes());
        adir_body.extend_from_slice(b"test");
        let chunk = make_chunk(b"ADIR", &adir_body);

        let mut patch = Vec::new();
        patch.extend_from_slice(&MAGIC);
        patch.extend_from_slice(&chunk);

        let mut reader = ZiPatchReader::new(Cursor::new(patch)).unwrap();
        let first = reader.next().expect("first chunk must be present");
        assert!(
            first.is_ok(),
            "first ADIR chunk should parse cleanly: {first:?}"
        );
        match reader.next().expect("second call must yield an error") {
            Err(ZiPatchError::TruncatedPatch) => {}
            other => panic!("expected TruncatedPatch on truncated stream, got {other:?}"),
        }
        assert!(
            !reader.is_complete(),
            "is_complete must be false after truncation"
        );
    }

    #[test]
    fn checksum_mismatch_returns_checksum_mismatch_error() {
        // Corrupt the CRC32 field of an otherwise valid ADIR chunk and verify
        // that parse_chunk returns ChecksumMismatch (not a panic or a wrong error).
        let mut adir_body = Vec::new();
        adir_body.extend_from_slice(&4u32.to_be_bytes());
        adir_body.extend_from_slice(b"test");
        let mut chunk = make_chunk(b"ADIR", &adir_body);
        // Flip the last byte of the CRC32 field.
        let last = chunk.len() - 1;
        chunk[last] ^= 0xFF;

        let mut cur = Cursor::new(chunk);
        let result = parse_chunk(&mut cur, true);
        assert!(
            matches!(result, Err(ZiPatchError::ChecksumMismatch { .. })),
            "corrupted CRC must yield ChecksumMismatch"
        );
    }

    #[test]
    fn unknown_chunk_tag_returns_unknown_chunk_tag_error() {
        // A tag of all-Z bytes is not recognised; parse_chunk must return
        // UnknownChunkTag carrying the raw 4-byte tag.
        let chunk = make_chunk(b"ZZZZ", &[]);
        let mut cur = Cursor::new(chunk);
        match parse_chunk(&mut cur, false) {
            Err(ZiPatchError::UnknownChunkTag(tag)) => {
                assert_eq!(tag, *b"ZZZZ", "tag bytes must be preserved in error");
            }
            Err(other) => panic!("expected UnknownChunkTag, got {other:?}"),
            Ok(_) => panic!("expected UnknownChunkTag, got Ok"),
        }
    }

    #[test]
    fn oversized_chunk_body_len_returns_oversized_chunk_error() {
        // body_len == u32::MAX (> 512 MiB) must be rejected before any allocation.
        let bytes = [0xFFu8, 0xFF, 0xFF, 0xFF];
        let mut cur = Cursor::new(&bytes[..]);
        let Err(ZiPatchError::OversizedChunk(size)) = parse_chunk(&mut cur, false) else {
            panic!("expected OversizedChunk for u32::MAX body_len")
        };
        assert!(
            size > MAX_CHUNK_SIZE,
            "reported size {size} must exceed MAX_CHUNK_SIZE {MAX_CHUNK_SIZE}"
        );
    }

    // --- ZiPatchReader byte-counter and tag accessors ---

    #[test]
    fn bytes_read_starts_at_12_before_first_chunk() {
        // The magic header is 12 bytes; bytes_read must reflect that immediately
        // after construction, before any chunk is read.
        let mut patch = Vec::new();
        patch.extend_from_slice(&MAGIC);
        patch.extend_from_slice(&make_chunk(b"EOF_", &[]));
        let reader = ZiPatchReader::new(Cursor::new(patch)).unwrap();
        assert_eq!(
            reader.bytes_read(),
            12,
            "bytes_read must be 12 (magic only) before iteration starts"
        );
    }

    #[test]
    fn last_tag_is_none_before_first_chunk() {
        // Before calling next(), last_tag must be None.
        let mut patch = Vec::new();
        patch.extend_from_slice(&MAGIC);
        patch.extend_from_slice(&make_chunk(b"EOF_", &[]));
        let reader = ZiPatchReader::new(Cursor::new(patch)).unwrap();
        assert_eq!(
            reader.last_tag(),
            None,
            "last_tag must be None before any chunk is read"
        );
    }

    #[test]
    fn bytes_read_and_last_tag_track_each_chunk_frame() {
        // MAGIC + ADIR("a") + EOF_ — verify bytes_read grows by the exact frame
        // size after each chunk and that last_tag follows the stream.
        let mut adir_body = Vec::new();
        adir_body.extend_from_slice(&1u32.to_be_bytes());
        adir_body.extend_from_slice(b"a");
        // ADIR frame: 4(size) + 4(tag) + 5(body) + 4(crc) = 17 bytes
        // EOF_  frame: 4 + 4 + 0 + 4 = 12 bytes

        let mut patch = Vec::new();
        patch.extend_from_slice(&MAGIC);
        patch.extend_from_slice(&make_chunk(b"ADIR", &adir_body));
        patch.extend_from_slice(&make_chunk(b"EOF_", &[]));

        let mut reader = ZiPatchReader::new(Cursor::new(patch)).unwrap();
        assert_eq!(reader.bytes_read(), 12, "pre-read: magic only");
        assert_eq!(reader.last_tag(), None, "pre-read: no tag yet");

        let chunk = reader.next().unwrap().unwrap();
        assert!(
            matches!(chunk, Chunk::AddDirectory(_)),
            "first chunk must be ADIR"
        );
        assert_eq!(
            reader.bytes_read(),
            12 + 17,
            "after ADIR: magic + ADIR frame"
        );
        assert_eq!(
            reader.last_tag(),
            Some(*b"ADIR"),
            "last_tag must be ADIR after first next()"
        );

        assert!(reader.next().is_none(), "EOF_ must terminate iteration");
        assert_eq!(
            reader.bytes_read(),
            12 + 17 + 12,
            "after EOF_: magic + ADIR + EOF_ frames"
        );
        assert_eq!(
            reader.last_tag(),
            Some(*b"EOF_"),
            "last_tag must be EOF_ after stream ends"
        );
        assert!(reader.is_complete(), "is_complete must be true after EOF_");
    }

    #[test]
    fn bytes_read_is_monotonically_non_decreasing() {
        // Stream with two ADIR chunks + EOF_ — verify bytes_read only ever
        // increases between calls to next() and that consuming the EOF_
        // chunk (whose body is empty but whose frame is 12 bytes) still
        // advances the counter past the last non-EOF position.
        let make_adir = |name: &[u8]| -> Vec<u8> {
            let mut body = Vec::new();
            body.extend_from_slice(&(name.len() as u32).to_be_bytes());
            body.extend_from_slice(name);
            make_chunk(b"ADIR", &body)
        };

        let mut patch = Vec::new();
        patch.extend_from_slice(&MAGIC);
        patch.extend_from_slice(&make_adir(b"a"));
        patch.extend_from_slice(&make_adir(b"bb"));
        patch.extend_from_slice(&make_chunk(b"EOF_", &[]));

        let mut reader = ZiPatchReader::new(Cursor::new(patch)).unwrap();
        let mut prev = reader.bytes_read();
        while let Some(result) = reader.next() {
            result.unwrap();
            let current = reader.bytes_read();
            assert!(
                current >= prev,
                "bytes_read must be monotonically non-decreasing: {prev} -> {current}"
            );
            // For ADIR chunks with non-empty bodies, the increment must be
            // strictly positive — a body of N bytes adds N + 12 frame bytes.
            assert!(
                current > prev,
                "non-empty ADIR frame must strictly advance bytes_read: \
                 {prev} -> {current}"
            );
            prev = current;
        }
        // EOF_ has been consumed: its 12-byte empty-body frame must have
        // pushed the counter past the previous position.
        assert!(
            reader.bytes_read() > prev,
            "consuming EOF_ must advance bytes_read by its 12-byte frame: \
             {prev} -> {}",
            reader.bytes_read()
        );
    }

    // --- from_path constructor ---

    #[test]
    fn from_path_opens_minimal_patch_and_reaches_eof() {
        let mut bytes = Vec::new();
        bytes.extend_from_slice(&MAGIC);
        bytes.extend_from_slice(&make_chunk(b"EOF_", &[]));

        let tmp = tempfile::tempdir().unwrap();
        let file_path = tmp.path().join("test.patch");
        std::fs::write(&file_path, &bytes).unwrap();

        let mut reader =
            ZiPatchReader::from_path(&file_path).expect("from_path must open valid patch");
        assert!(
            reader.next().is_none(),
            "EOF_ must terminate iteration immediately"
        );
        assert!(reader.is_complete(), "is_complete must be true after EOF_");
    }

    #[test]
    fn from_path_returns_io_error_when_file_is_missing() {
        let tmp = tempfile::tempdir().unwrap();
        let file_path = tmp.path().join("nonexistent.patch");
        assert!(
            matches!(
                ZiPatchReader::from_path(&file_path),
                Err(ZiPatchError::Io(_))
            ),
            "from_path on a missing file must return ZiPatchError::Io"
        );
    }

    // --- Iterator fused-ness and is_complete ---

    #[test]
    fn iterator_is_fused_after_error() {
        // Once next() yields Some(Err(_)), all subsequent calls must yield None.
        let mut patch = Vec::new();
        patch.extend_from_slice(&MAGIC);
        patch.extend_from_slice(&make_chunk(b"ZZZZ", &[])); // unknown tag → error

        let mut reader = ZiPatchReader::new(Cursor::new(patch)).unwrap();
        let first = reader.next();
        assert!(
            matches!(first, Some(Err(ZiPatchError::UnknownChunkTag(_)))),
            "first call must yield the error: {first:?}"
        );
        // All subsequent calls must return None.
        assert!(
            reader.next().is_none(),
            "fused: must return None after error"
        );
        assert!(reader.next().is_none(), "fused: still None on third call");
    }

    #[test]
    fn is_complete_false_until_eof_seen() {
        let mut adir_body = Vec::new();
        adir_body.extend_from_slice(&1u32.to_be_bytes());
        adir_body.extend_from_slice(b"x");

        let mut patch = Vec::new();
        patch.extend_from_slice(&MAGIC);
        patch.extend_from_slice(&make_chunk(b"ADIR", &adir_body));
        patch.extend_from_slice(&make_chunk(b"EOF_", &[]));

        let mut reader = ZiPatchReader::new(Cursor::new(patch)).unwrap();
        assert!(
            !reader.is_complete(),
            "not complete before reading anything"
        );
        reader.next().unwrap().unwrap(); // consume ADIR
        assert!(
            !reader.is_complete(),
            "not complete after ADIR, before EOF_"
        );
        assert!(reader.next().is_none(), "EOF_ consumed");
        assert!(reader.is_complete(), "complete after EOF_ consumed");
    }
}