zipatch-rs 1.6.0

//! Wire-format chunk types and the [`ZiPatchReader`] streaming parser.
//!
//! 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`] parser validates the 12-byte file magic on
//! construction, then yields one [`ChunkRecord`](crate::chunk::ChunkRecord) per
//! [`ZiPatchReader::next_chunk`] 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(crate) use adir::AddDirectory;
pub(crate) use afsp::ApplyFreeSpace;
pub(crate) use aply::ApplyOption;
pub(crate) use ddir::DeleteDirectory;
pub(crate) use fhdr::FileHeader;
pub use sqpk::{SqpackFileId, SqpkCommand, SqpkCompressedBlock};
pub(crate) use sqpk::{
    SqpkFile, SqpkFileOperation, SqpkHeader, SqpkHeaderTarget, TargetHeaderKind,
};

use crate::newtypes::ChunkTag;
use crate::reader::ReadExt;
use crate::{ParseError, ParseResult as Result};
use tracing::trace;

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

/// Default upper bound (512 MiB) on a single chunk's declared body length.
///
/// Used by [`ZiPatchReader::new`] to guard against pathological streams that
/// would otherwise drive the parser into a huge allocation. Override per
/// reader via [`ZiPatchReader::with_max_chunk_size`].
pub const DEFAULT_MAX_CHUNK_SIZE: u32 = 512 * 1024 * 1024;

/// One top-level chunk parsed from a `ZiPatch` stream.
///
/// Each variant corresponds to a 4-byte ASCII wire tag.
///
/// # 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 and is treated as a no-op. `EOF_` is consumed by [`ZiPatchReader`]
/// and is never yielded to the caller.
#[derive(Debug)]
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::ApplyConfig`] (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: ChunkTag,
    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`). When
/// `verify_checksums` is `true` and the stored CRC does not match the computed
/// one, [`ParseError::ChecksumMismatch`] is returned.
///
/// # Errors
///
/// - [`ParseError::TruncatedPatch`] — the reader returns EOF while reading
///   the `body_len` field (i.e. no more chunks are present but `EOF_` was
///   never seen).
/// - [`ParseError::OversizedChunk`] — `body_len` exceeds `max_chunk_size`.
/// - [`ParseError::ChecksumMismatch`] — CRC32 mismatch (only when
///   `verify_checksums` is `true`).
/// - [`ParseError::UnknownChunkTag`] — tag is not recognised.
/// - [`ParseError::Io`] — any other I/O failure reading from `r`.
pub(crate) fn parse_chunk<R: std::io::Read>(
    r: &mut R,
    verify_checksums: bool,
    max_chunk_size: u32,
) -> Result<ParsedChunk> {
    let size = match r.read_u32_be() {
        Ok(s) => s as usize,
        Err(ParseError::Io { source: e }) if e.kind() == std::io::ErrorKind::UnexpectedEof => {
            return Err(ParseError::TruncatedPatch);
        }
        Err(e) => return Err(e),
    };
    if size > max_chunk_size as usize {
        return Err(ParseError::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(ParseError::ChecksumMismatch {
                tag: ChunkTag::new(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(ParseError::UnknownChunkTag(ChunkTag::new(tag))),
    };

    Ok(ParsedChunk {
        chunk,
        tag: ChunkTag::new(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(ParseError::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(ParseError::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(ParseError::ChecksumMismatch {
                tag: ChunkTag::new(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::SqpackFileId {
            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: ChunkTag::new(tag),
        consumed,
    })
}

/// One chunk yielded by [`ZiPatchReader::next_chunk`] together with the
/// stream-position metadata the parser observed while reading it.
///
/// Bundling the chunk with its byte-position metadata in one record lets
/// downstream consumers (the apply driver, the [`crate::index::PlanBuilder`],
/// the `zipatch dump` CLI) avoid a second round of accessor calls against
/// the reader to learn where the chunk sat in the stream. Each field
/// describes one fact the parser knew at the moment the chunk was yielded;
/// see the per-field docs.
///
/// `#[non_exhaustive]`: stream-position metadata may grow (e.g. compressed
/// payload size, header-only byte count) as new index-builder needs surface.
#[non_exhaustive]
#[derive(Debug)]
pub struct ChunkRecord {
    /// The parsed chunk itself.
    pub chunk: Chunk,
    /// The 4-byte ASCII wire tag of the chunk (`FHDR`, `SQPK`, `EOF_`, …).
    ///
    /// Exposed alongside [`Self::chunk`] so consumers can attach the tag
    /// to a progress event without re-matching on the [`Chunk`] enum.
    pub tag: ChunkTag,
    /// Absolute patch-file offset of the chunk's body — the byte right
    /// after the 8-byte `[body_len: u32 BE, tag: [u8; 4]]` frame header.
    ///
    /// 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.
    pub body_offset: u64,
    /// Running total of bytes consumed from the patch stream, including
    /// the 12-byte magic header, the chunk this record describes, and
    /// every preceding chunk frame.
    ///
    /// Equivalent to the [`crate::ChunkEvent::bytes_read`] field at the
    /// same emission point; used for the `bytes_applied / total_patch_size`
    /// progress-bar ratio.
    pub bytes_read: u64,
}

/// Streaming parser over the [`Chunk`]s in a `ZiPatch` stream.
///
/// `ZiPatchReader` wraps any [`std::io::Read`] source and yields one
/// [`ChunkRecord`] per call to [`Self::next_chunk`]. 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 [`ParseError::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; pass `false` to [`ZiPatchReader::with_checksum_verification`]
///   to disable it.
/// - **Termination** — the `EOF_` chunk is consumed internally and causes
///   [`Self::next_chunk`] to return `Ok(None)`. Call
///   [`ZiPatchReader::is_complete`] after iteration to distinguish a clean
///   end from a truncated stream.
/// - **Fused** — once `Ok(None)` (clean EOF) or an `Err(_)` is returned,
///   subsequent calls to `next_chunk` also return `Ok(None)`.
///
/// # Errors
///
/// Each call to [`Self::next_chunk`] returns `Err(e)` on parse failure,
/// then `Ok(None)` on all future calls. Possible errors include:
/// - [`ParseError::TruncatedPatch`] — stream ended before `EOF_`.
/// - [`ParseError::OversizedChunk`] — a declared chunk body exceeds the
///   configured max chunk size (default [`DEFAULT_MAX_CHUNK_SIZE`], 512 MiB).
/// - [`ParseError::ChecksumMismatch`] — CRC32 verification failed.
/// - [`ParseError::UnknownChunkTag`] — unrecognised 4-byte tag.
/// - [`ParseError::Io`] — underlying I/O failure.
///
/// # Async usage
///
/// `ZiPatchReader` is a synchronous parser over a [`std::io::Read`]
/// source — see the crate-level "Async usage" section for the rationale.
/// Async consumers wrap iteration (and any apply call that drives it)
/// in `tokio::task::spawn_blocking`. To stream a patch that is itself
/// arriving over an async transport (e.g. `reqwest::Response::bytes_stream`),
/// either buffer it through a `tempfile::NamedTempFile` and feed the
/// reopened [`std::fs::File`] to [`ZiPatchReader::new`], or bridge with a
/// blocking-reader adapter that pulls from a
/// [`tokio::sync::mpsc`-equivalent](std::sync::mpsc) channel populated
/// by the async download task.
///
/// # Example
///
/// Build a minimal in-memory patch (magic + `ADIR` + `EOF_`) and walk 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 mut reader = ZiPatchReader::new(Cursor::new(patch)).unwrap();
/// let mut chunks = Vec::new();
/// while let Some(rec) = reader.next_chunk().unwrap() {
///     chunks.push(rec.chunk);
/// }
///
/// 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.
    pub(crate) bytes_read: u64,
    // Caller-supplied identifier for the patch source. Stamped onto every
    // `SequentialCheckpoint` the apply driver emits so a later
    // `resume_apply_patch` call can refuse a checkpoint that was persisted for
    // a different patch. `None` when the caller has not set one via
    // `with_patch_name`.
    patch_name: Option<String>,
    // Maximum declared body length the parser will accept; chunks declaring a
    // larger `body_len` are rejected with `ParseError::OversizedChunk` before
    // any allocation. Defaults to `DEFAULT_MAX_CHUNK_SIZE`.
    max_chunk_size: u32,
}

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::with_checksum_verification`] with `false` before
    /// iterating to disable it.
    ///
    /// # Errors
    ///
    /// - [`ParseError::InvalidMagic`] — the first 12 bytes do not match the
    ///   expected magic.
    /// - [`ParseError::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(ParseError::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,
            patch_name: None,
            max_chunk_size: DEFAULT_MAX_CHUNK_SIZE,
        })
    }

    /// Set the upper bound on a single chunk's declared body length, in
    /// bytes.
    ///
    /// The parser rejects any chunk whose `body_len` exceeds `bytes` with
    /// [`ParseError::OversizedChunk`] before allocating space for its body.
    /// Defaults to [`DEFAULT_MAX_CHUNK_SIZE`] (512 MiB). Raise it for
    /// patches with unusually large chunks; lower it when applying untrusted
    /// streams to bound the parser's worst-case allocation.
    ///
    /// # Panics
    ///
    /// Panics if `bytes` is zero — a zero ceiling rejects every chunk and
    /// is a programming error.
    #[must_use]
    pub fn with_max_chunk_size(mut self, bytes: u32) -> Self {
        assert!(bytes > 0, "with_max_chunk_size(0) is invalid");
        self.max_chunk_size = bytes;
        self
    }

    /// Returns the configured maximum chunk-body length, in bytes.
    #[must_use]
    pub fn max_chunk_size(&self) -> u32 {
        self.max_chunk_size
    }

    /// Attach a human-readable identifier to this patch stream.
    ///
    /// The identifier is stamped onto every
    /// [`SequentialCheckpoint`](crate::apply::SequentialCheckpoint) the apply
    /// driver emits so a future
    /// [`resume_apply_patch`](crate::ApplyConfig::resume_apply_patch) call can
    /// detect a checkpoint that was persisted for a different patch and
    /// refuse to resume from it.
    ///
    /// Typical value is the patch filename (e.g. `"H2017.07.11.0000.0000a.patch"`).
    /// No interpretation is performed — the string is compared verbatim.
    #[must_use]
    pub fn with_patch_name(mut self, name: impl Into<String>) -> Self {
        self.patch_name = Some(name.into());
        self
    }

    /// Returns the caller-supplied patch identifier, if any.
    ///
    /// Set by [`Self::with_patch_name`]; `None` otherwise.
    #[must_use]
    pub fn patch_name(&self) -> Option<&str> {
        self.patch_name.as_deref()
    }

    /// Mutable access to the wrapped [`std::io::BufReader`].
    ///
    /// Used by [`crate::ApplyConfig::resume_apply_patch`] to seek the
    /// underlying source for the patch-size measurement at entry. Not
    /// part of the stable API — seeking the inner reader while a chunk
    /// parse is in flight would desync `bytes_read` and break later
    /// iteration.
    pub(crate) fn inner_mut(&mut self) -> &mut std::io::BufReader<R> {
        &mut self.inner
    }

    /// Toggle per-chunk CRC32 verification.
    ///
    /// Verification is **enabled** by default after [`ZiPatchReader::new`].
    /// Pass `false` to skip CRC checks — 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 with_checksum_verification(mut self, on: bool) -> Self {
        self.verify_checksums = on;
        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 [`ParseError::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 [`Self::next_chunk`] 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.
    ///
    /// Per-chunk consumers should read the equivalent counter off the
    /// [`ChunkRecord::bytes_read`] field. This getter is for end-of-stream
    /// reporting — after [`Self::next_chunk`] returned `Ok(None)`, no
    /// [`ChunkRecord`] is produced for the consumed `EOF_` frame, so the
    /// final stream position is only available through this method.
    #[must_use]
    pub fn bytes_read(&self) -> u64 {
        self.bytes_read
    }

    /// Read the next chunk frame from the underlying stream.
    ///
    /// Returns `Ok(Some(record))` for each successfully parsed chunk in
    /// stream order, `Ok(None)` after the `EOF_` terminator has been
    /// consumed (the terminator itself is never surfaced as a record), and
    /// `Err(_)` on a parse failure. After `Ok(None)` or any `Err(_)`,
    /// subsequent calls return `Ok(None)` — the reader is fused.
    ///
    /// # Errors
    ///
    /// See [`Self`]'s "Errors" section.
    pub fn next_chunk(&mut self) -> Result<Option<ChunkRecord>> {
        if self.done {
            return Ok(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, self.max_chunk_size) {
            Ok(ParsedChunk {
                chunk: Chunk::EndOfFile,
                consumed,
                ..
            }) => {
                self.bytes_read += consumed;
                self.done = true;
                self.eof_seen = true;
                Ok(None)
            }
            Ok(ParsedChunk {
                chunk,
                tag,
                consumed,
            }) => {
                self.bytes_read += consumed;
                Ok(Some(ChunkRecord {
                    chunk,
                    tag,
                    body_offset,
                    bytes_read: self.bytes_read,
                }))
            }
            Err(e) => {
                self.done = true;
                Err(e)
            }
        }
    }
}

/// Open the file at `path` and validate the `ZiPatch` magic, returning a
/// ready-to-iterate [`ZiPatchReader`].
///
/// The concrete inner reader type is intentionally hidden behind `impl
/// Read` so the choice of source and any buffering strategy remain
/// implementation details. Callers that need to name the type should
/// construct a reader of their choice and pass it to
/// [`ZiPatchReader::new`].
///
/// # Errors
///
/// - [`ParseError::Io`] — the file could not be opened.
/// - [`ParseError::InvalidMagic`] — the file does not start with the
///   `ZiPatch` magic bytes.
pub fn open_patch(
    path: impl AsRef<std::path::Path>,
) -> crate::ParseResult<ZiPatchReader<impl std::io::Read + 'static>> {
    let file = std::fs::File::open(path)?;
    ZiPatchReader::new(file)
}

#[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.
        let mut patch = Vec::new();
        patch.extend_from_slice(&MAGIC);
        let mut reader = ZiPatchReader::new(Cursor::new(patch)).unwrap();
        match reader.next_chunk() {
            Err(ParseError::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, DEFAULT_MAX_CHUNK_SIZE);
        match result {
            Err(ParseError::Io { source: 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 ParseError::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_chunk();
        assert!(
            matches!(first, Ok(Some(_))),
            "first ADIR chunk should parse cleanly: {first:?}"
        );
        match reader.next_chunk() {
            Err(ParseError::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, DEFAULT_MAX_CHUNK_SIZE);
        assert!(
            matches!(result, Err(ParseError::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, DEFAULT_MAX_CHUNK_SIZE) {
            Err(ParseError::UnknownChunkTag(tag)) => {
                assert_eq!(
                    tag,
                    ChunkTag::new(*b"ZZZZ"),
                    "tag bytes must be preserved in error"
                );
            }
            Err(other) => panic!("expected UnknownChunkTag, got {other:?}"),
            Ok(_) => panic!("expected UnknownChunkTag, got Ok"),
        }
    }

    #[test]
    fn default_max_chunk_size_matches_constant() {
        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.max_chunk_size(), DEFAULT_MAX_CHUNK_SIZE);
    }

    #[test]
    fn with_max_chunk_size_overrides_default() {
        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()
            .with_max_chunk_size(4096);
        assert_eq!(reader.max_chunk_size(), 4096);
    }

    #[test]
    #[should_panic(expected = "with_max_chunk_size(0) is invalid")]
    fn with_max_chunk_size_zero_panics() {
        let mut patch = Vec::new();
        patch.extend_from_slice(&MAGIC);
        patch.extend_from_slice(&make_chunk(b"EOF_", &[]));
        let _ = ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .with_max_chunk_size(0);
    }

    #[test]
    fn custom_max_chunk_size_rejects_chunks_above_threshold() {
        // ADIR body of 9 bytes (4 len + 5 ascii) → frame body_len = 9. With
        // max_chunk_size = 4, the parser must reject it as Oversized.
        let mut adir_body = Vec::new();
        adir_body.extend_from_slice(&5u32.to_be_bytes());
        adir_body.extend_from_slice(b"hello");
        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()
            .with_max_chunk_size(4);
        match reader.next_chunk() {
            Err(ParseError::OversizedChunk(size)) => assert_eq!(size, 9),
            other => panic!("expected OversizedChunk(9), got {other:?}"),
        }
    }

    #[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(ParseError::OversizedChunk(size)) =
            parse_chunk(&mut cur, false, DEFAULT_MAX_CHUNK_SIZE)
        else {
            panic!("expected OversizedChunk for u32::MAX body_len")
        };
        assert!(
            size > DEFAULT_MAX_CHUNK_SIZE as usize,
            "reported size {size} must exceed DEFAULT_MAX_CHUNK_SIZE {DEFAULT_MAX_CHUNK_SIZE}"
        );
    }

    // --- ZiPatchReader byte-counter and per-record metadata ---

    #[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 record_carries_tag_body_offset_and_bytes_read() {
        // MAGIC + ADIR("a") + EOF_ — verify the per-record metadata matches
        // the expected frame sizes and offsets.
        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");

        let rec = reader.next_chunk().unwrap().expect("first ADIR record");
        assert!(
            matches!(rec.chunk, Chunk::AddDirectory(_)),
            "first chunk must be ADIR"
        );
        assert_eq!(rec.tag, ChunkTag::ADIR);
        // ADIR body sits after magic(12) + body_len(4) + tag(4) = 20.
        assert_eq!(rec.body_offset, 20);
        assert_eq!(rec.bytes_read, 12 + 17, "magic + ADIR frame");

        assert!(
            reader.next_chunk().unwrap().is_none(),
            "EOF_ must terminate iteration"
        );
        assert_eq!(
            reader.bytes_read(),
            12 + 17 + 12,
            "after EOF_: magic + ADIR + EOF_ frames"
        );
        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_chunk() 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(rec) = reader.next_chunk().unwrap() {
            let current = rec.bytes_read;
            assert_eq!(
                current,
                reader.bytes_read(),
                "record's bytes_read must equal reader's running counter"
            );
            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()
        );
    }

    // --- open_patch constructor ---

    #[test]
    fn open_patch_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 = open_patch(&file_path).expect("open_patch must open valid patch");
        assert!(
            reader.next_chunk().unwrap().is_none(),
            "EOF_ must terminate iteration immediately"
        );
        assert!(reader.is_complete(), "is_complete must be true after EOF_");
    }

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

    // --- Fused-ness and is_complete ---

    #[test]
    fn reader_is_fused_after_error() {
        // Once next_chunk yields Err(_), all subsequent calls must yield Ok(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_chunk();
        assert!(
            matches!(first, Err(ParseError::UnknownChunkTag(_))),
            "first call must yield the error: {first:?}"
        );
        // All subsequent calls must return Ok(None).
        assert!(
            matches!(reader.next_chunk(), Ok(None)),
            "fused: must return Ok(None) after error"
        );
        assert!(
            matches!(reader.next_chunk(), Ok(None)),
            "fused: still Ok(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_chunk().unwrap().unwrap(); // consume ADIR
        assert!(
            !reader.is_complete(),
            "not complete after ADIR, before EOF_"
        );
        assert!(reader.next_chunk().unwrap().is_none(), "EOF_ consumed");
        assert!(reader.is_complete(), "complete after EOF_ consumed");
    }
}