zipatch_rs/

lib.rs

//! Parser and applier for FFXIV `ZiPatch` (`.patch`) binary files.
//!
//! `zipatch-rs` decodes the binary patch format that Square Enix ships for
//! Final Fantasy XIV and writes the decoded changes to a local game installation.
//! The library never touches the network — it operates entirely on byte streams
//! you supply.
//!
//! # Architecture
//!
//! The crate is split into three layers that share types but are otherwise
//! independent:
//!
//! ## Layer 1 — I/O primitives (`reader`)
//!
//! `reader::ReadExt` is a crate-internal extension trait that adds typed
//! big- and little-endian reads on top of [`std::io::Read`]. It is not part
//! of the public API; the parsing layer uses it exclusively.
//!
//! ## Layer 2 — Parsing ([`chunk`])
//!
//! [`ZiPatchReader`] is an [`Iterator`] over [`Chunk`] values. Construct it
//! from any [`std::io::Read`] source (a [`std::fs::File`], a
//! [`std::io::Cursor<Vec<u8>>`], a network stream, …). It validates the
//! 12-byte file magic on construction, then yields one [`Chunk`] per
//! [`Iterator::next`] call until it sees the `EOF_` terminator or hits an
//! error.
//!
//! Nothing in the parsing layer allocates file handles, stats paths, or
//! performs I/O against the install tree. Parse-only users can consume
//! [`ZiPatchReader`] without ever importing [`apply`].
//!
//! ## Layer 3 — Applying ([`apply`])
//!
//! The [`Apply`] trait bridges parsing and application: every [`Chunk`]
//! variant implements it, and each implementation writes the patch change to
//! disk via an [`ApplyContext`]. [`ApplyContext`] holds the install root, the
//! target [`Platform`], behavioural flags, and an internal file-handle cache
//! that avoids re-opening the same `.dat` file for every chunk.
//!
//! # Quick start
//!
//! The most common usage: open a patch file, build a context, apply every
//! chunk in stream order.
//!
//! ```no_run
//! use std::fs::File;
//! use zipatch_rs::{ApplyContext, ZiPatchReader};
//!
//! let patch_file = File::open("H2017.07.11.0000.0000a.patch").unwrap();
//! let mut ctx = ApplyContext::new("/opt/ffxiv/game");
//!
//! ZiPatchReader::new(patch_file)
//!     .unwrap()
//!     .apply_to(&mut ctx)
//!     .unwrap();
//! ```
//!
//! # Inspecting a patch without applying it
//!
//! Iterate the reader directly to inspect chunks without touching the
//! filesystem:
//!
//! ```no_run
//! use zipatch_rs::{Chunk, ZiPatchReader};
//! use std::fs::File;
//!
//! let reader = ZiPatchReader::new(File::open("patch.patch").unwrap()).unwrap();
//! for chunk in reader {
//!     match chunk.unwrap() {
//!         Chunk::FileHeader(h) => println!("patch version: {:?}", h),
//!         Chunk::AddDirectory(d) => println!("mkdir {}", d.name),
//!         Chunk::Sqpk(cmd) => println!("sqpk: {cmd:?}"),
//!         _ => {}
//!     }
//! }
//! ```
//!
//! # In-memory doctest
//!
//! The following example builds a minimal well-formed patch in memory — magic
//! header, one `ADIR` chunk (which creates a directory), and an `EOF_`
//! terminator — then applies it to a temporary directory. This mirrors the
//! technique used in the crate's own unit tests.
//!
//! ```rust
//! use std::io::Cursor;
//! use zipatch_rs::{ApplyContext, Chunk, ZiPatchReader};
//!
//! // ZiPatch file magic: \x91ZIPATCH\r\n\x1a\n
//! const MAGIC: [u8; 12] = [
//!     0x91, 0x5A, 0x49, 0x50, 0x41, 0x54, 0x43, 0x48,
//!     0x0D, 0x0A, 0x1A, 0x0A,
//! ];
//!
//! /// Wrap `tag + body` into a length-prefixed, CRC32-verified chunk frame.
//! fn make_chunk(tag: &[u8; 4], body: &[u8]) -> Vec<u8> {
//!     // CRC is computed over tag ++ body (NOT including the leading body_len).
//!     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()); // body_len: u32 BE
//!     out.extend_from_slice(tag);                                // tag: 4 bytes
//!     out.extend_from_slice(body);                               // body: body_len bytes
//!     out.extend_from_slice(&crc.to_be_bytes());                 // crc32: u32 BE
//!     out
//! }
//!
//! // ADIR body: big-endian u32 name length followed by the name bytes.
//! let mut adir_body = Vec::new();
//! adir_body.extend_from_slice(&7u32.to_be_bytes()); // name_len
//! adir_body.extend_from_slice(b"created");          // name
//!
//! // Assemble the full patch stream.
//! 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_", &[]));
//!
//! // Apply to a temporary directory.
//! let tmp = tempfile::tempdir().unwrap();
//! let mut ctx = ApplyContext::new(tmp.path());
//! ZiPatchReader::new(Cursor::new(patch))
//!     .unwrap()
//!     .apply_to(&mut ctx)
//!     .unwrap();
//!
//! assert!(tmp.path().join("created").is_dir());
//! ```
//!
//! # Error handling
//!
//! Every fallible operation returns [`Result<T>`], which is an alias for
//! `std::result::Result<T, `[`ZiPatchError`]`>`. Parse errors and apply
//! errors share the same type so callers need only one error arm.
//!
//! # Progress and cancellation
//!
//! [`ApplyContext::with_observer`] installs an [`ApplyObserver`] that is
//! called after each chunk applies (with the chunk index, tag, and running
//! byte count from [`ZiPatchReader::bytes_read`]) and polled inside long-
//! running chunks for cancellation. Returning
//! [`std::ops::ControlFlow::Break`] from a per-chunk callback, or `true`
//! from [`ApplyObserver::should_cancel`], aborts the apply call with
//! [`ZiPatchError::Cancelled`]. Parsing-only consumers and existing
//! [`apply_to`](ZiPatchReader::apply_to) callers that never install an
//! observer pay nothing — the default is a no-op.
//!
//! # Tracing
//!
//! The library emits structured [`tracing`] events at `trace!`, `debug!`, and
//! `warn!` levels. No subscriber is configured here — configure output in your
//! application binary (or in `gaveloc`'s launcher binary).
//!
//! [`tracing`]: https://docs.rs/tracing

#![deny(missing_docs)]

/// Filesystem application of parsed chunks ([`Apply`], [`ApplyContext`]).
pub mod apply;
/// Wire-format chunk types and the [`ZiPatchReader`] iterator.
pub mod chunk;
/// Error type returned by parsing and applying ([`ZiPatchError`]).
pub mod error;
pub(crate) mod reader;

/// Shared chunk-framing fixtures for unit and integration tests.
///
/// Exposed under `#[cfg(test)]` to all tests in this crate, and behind the
/// `test-utils` feature flag to downstream consumers. **Not part of the
/// stable public API** — see the module rustdoc for details.
#[cfg(any(test, feature = "test-utils"))]
pub mod test_utils;

pub use apply::{Apply, ApplyContext, ApplyObserver, ChunkEvent, NoopObserver};
pub use chunk::{Chunk, ZiPatchReader};
pub use error::ZiPatchError;

/// Crate-wide `Result` alias parameterised over [`ZiPatchError`].
pub type Result<T> = std::result::Result<T, ZiPatchError>;

impl<R: std::io::Read> chunk::ZiPatchReader<R> {
    /// Iterate every chunk in the patch stream and apply each one to `ctx`.
    ///
    /// This is the primary high-level entry point for applying a patch. It
    /// drives the [`ZiPatchReader`] iterator to completion, calling
    /// [`Apply::apply`] on each yielded [`Chunk`] in stream order.
    ///
    /// Chunks **must** be applied in order — the `ZiPatch` format is a
    /// sequential log and later chunks may depend on filesystem state produced
    /// by earlier ones (e.g. a directory created by an `ADIR` chunk that a
    /// subsequent `SQPK AddFile` writes into).
    ///
    /// # Errors
    ///
    /// Stops at the first parse or apply error and returns it immediately.
    /// Any filesystem changes already applied by earlier chunks are **not**
    /// rolled back — the format does not provide transactional semantics.
    ///
    /// Possible error variants:
    /// - [`ZiPatchError::Io`] — underlying I/O failure (read or write).
    /// - [`ZiPatchError::InvalidMagic`] — caught at construction, not here.
    /// - [`ZiPatchError::UnknownChunkTag`] — an unrecognised 4-byte tag was
    ///   encountered.
    /// - [`ZiPatchError::ChecksumMismatch`] — a chunk's CRC32 did not match.
    /// - [`ZiPatchError::TruncatedPatch`] — the stream ended before `EOF_`.
    /// - [`ZiPatchError::NegativeFileOffset`] — a `SqpkFile` chunk carried a
    ///   negative offset.
    /// - [`ZiPatchError::Decompress`] — a compressed block could not be
    ///   inflated.
    /// - [`ZiPatchError::UnsupportedPlatform`] — a `SqpkTargetInfo` chunk
    ///   declared a `platform_id` outside `0`/`1`/`2`, and a subsequent SQPK
    ///   data chunk requested `SqPack` `.dat`/`.index` path resolution.
    /// - [`ZiPatchError::Cancelled`] — an installed
    ///   [`ApplyObserver`](crate::ApplyObserver) requested cancellation.
    ///
    /// # Panics
    ///
    /// Never panics under normal operation. The internal
    /// [`ZiPatchReader::last_tag`] is unwrapped after a successful
    /// [`Iterator::next`] — this is an internal invariant of the iterator
    /// (every `Some(Ok(_))` updates the tag) and would only fail on a bug
    /// in this crate.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use std::fs::File;
    /// use zipatch_rs::{ApplyContext, ZiPatchReader};
    ///
    /// let mut ctx = ApplyContext::new("/opt/ffxiv/game");
    /// ZiPatchReader::new(File::open("update.patch").unwrap())
    ///     .unwrap()
    ///     .apply_to(&mut ctx)
    ///     .unwrap();
    /// ```
    pub fn apply_to(mut self, ctx: &mut apply::ApplyContext) -> Result<()> {
        // Run the chunk loop in an IIFE so the outer function can flush the
        // file-handle cache on the way out — both on success (to make the
        // durability guarantee meaningful: returning `Ok` implies the writes
        // reached the OS) and on error (so partial progress, e.g. mid-stream
        // cancellation, is observable in the filesystem). A flush failure
        // only escapes when there was no primary error to begin with;
        // otherwise the primary error takes precedence.
        let result: Result<()> = (|| {
            use apply::Apply;
            use std::ops::ControlFlow;
            let mut index: usize = 0;
            // Hand-rolled loop (instead of `for chunk in self`) so we can read
            // `self.bytes_read()` and `self.last_tag()` after each successful
            // `next()` without giving up ownership of the iterator.
            while let Some(chunk) = self.next() {
                let chunk = chunk?;
                chunk.apply(ctx)?;
                // Snapshot the byte counter and tag *after* the apply completes —
                // `bytes_read` is monotonic relative to the patch stream, not the
                // apply progress, but for byte-driven UI progress that is exactly
                // what we want: the consumer sees how far through the patch file
                // they are once a chunk's effects have landed on disk.
                let bytes_read = self.bytes_read();
                let tag = self
                    .last_tag()
                    .expect("last_tag is set whenever next() yielded Some(Ok(_))");
                let event = apply::ChunkEvent {
                    index,
                    kind: tag,
                    bytes_read,
                };
                if let ControlFlow::Break(()) = ctx.observer.on_chunk_applied(event) {
                    return Err(ZiPatchError::Cancelled);
                }
                index += 1;
            }
            Ok(())
        })();
        match ctx.flush() {
            Err(e) if result.is_ok() => Err(ZiPatchError::Io(e)),
            _ => result,
        }
    }
}

/// Target platform for `SqPack` file path resolution.
///
/// FFXIV's `SqPack` archive files live in platform-specific subdirectories
/// under the game install root. For example, a data file for the Windows
/// client lives at `sqpack/ffxiv/000000.win32.dat0`, while the PS4 equivalent
/// is `sqpack/ffxiv/000000.ps4.dat0`. The [`Platform`] value stored in an
/// [`ApplyContext`] selects which suffix is used when resolving chunk targets
/// to filesystem paths.
///
/// # Default
///
/// An [`ApplyContext`] defaults to [`Platform::Win32`]. Override this at
/// construction time with [`ApplyContext::with_platform`].
///
/// # Runtime override via `SqpkTargetInfo`
///
/// In practice, real FFXIV patch files begin with an `SQPK T` chunk
/// ([`chunk::SqpkTargetInfo`]) that declares the target platform. When
/// [`Apply::apply`] is called on that chunk (see `src/apply/sqpk.rs`,
/// `apply_target_info`), it overwrites [`ApplyContext::platform`] with the
/// decoded [`Platform`] value. This means the default is only relevant for
/// synthetic patches or when you know the target in advance and want to assert
/// it before the stream starts.
///
/// # Forward compatibility
///
/// The enum is `#[non_exhaustive]`. The [`Platform::Unknown`] variant
/// preserves unrecognised platform IDs so that newer patch files do not fail
/// parsing when a new platform is introduced. Path resolution for `SqPack`
/// `.dat`/`.index` files refuses to guess and returns
/// [`ZiPatchError::UnsupportedPlatform`] carrying the raw `platform_id` —
/// silently substituting a default layout would risk writing platform-specific
/// data to the wrong file.
///
/// # Display
///
/// Implements [`std::fmt::Display`]: `"Win32"`, `"PS3"`, `"PS4"`, or
/// `"Unknown(N)"` where `N` is the raw platform ID.
///
/// # Example
///
/// ```rust
/// use zipatch_rs::{ApplyContext, Platform};
///
/// let ctx = ApplyContext::new("/opt/ffxiv/game")
///     .with_platform(Platform::Win32);
///
/// assert_eq!(ctx.platform(), Platform::Win32);
/// assert_eq!(format!("{}", Platform::Unknown(99)), "Unknown(99)");
/// ```
///
/// [`chunk::SqpkTargetInfo`]: crate::chunk::SqpkTargetInfo
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Platform {
    /// Windows / PC client (`win32` path suffix).
    ///
    /// This is the platform used by all current PC releases of FFXIV and is
    /// the default for [`ApplyContext`].
    Win32,
    /// `PlayStation` 3 client (`ps3` path suffix).
    ///
    /// PS3 support was discontinued after FFXIV: A Realm Reborn. Patches
    /// targeting this platform are no longer issued by Square Enix, but the
    /// variant is retained for completeness.
    Ps3,
    /// `PlayStation` 4 client (`ps4` path suffix).
    ///
    /// Active platform alongside Windows. PS4 patches share the same chunk
    /// structure as Windows patches but target different file paths.
    Ps4,
    /// Unrecognised platform ID preserved from a `SqpkTargetInfo` chunk.
    ///
    /// When `apply_target_info` in `src/apply/sqpk.rs` encounters a
    /// `platform_id` it does not recognise, it stores the raw `u16` value
    /// here and emits a `warn!` tracing event. Subsequent `SqPack` path
    /// resolution returns [`ZiPatchError::UnsupportedPlatform`] carrying
    /// the same `u16` rather than silently routing writes to a default
    /// layout — quietly substituting `win32` paths for an unknown platform
    /// would corrupt the on-disk install with platform-specific data
    /// written to the wrong files. Non-SqPack chunks (e.g. `ADIR`, `DELD`,
    /// or `SqpkFile` operations resolved via `generic_path`) continue to
    /// apply, so an unknown platform only aborts at the first `.dat` or
    /// `.index` lookup.
    Unknown(u16),
}

impl std::fmt::Display for Platform {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Platform::Win32 => f.write_str("Win32"),
            Platform::Ps3 => f.write_str("PS3"),
            Platform::Ps4 => f.write_str("PS4"),
            Platform::Unknown(id) => write!(f, "Unknown({id})"),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::test_utils::{MAGIC, make_chunk};
    use std::io::Cursor;
    use std::ops::ControlFlow;
    use std::sync::Arc;
    use std::sync::atomic::{AtomicUsize, Ordering};

    /// One uncompressed block carrying 8 bytes of payload, framed as a
    /// `SqpkCompressedBlock` would appear inside an `SqpkFile` `AddFile` body.
    ///
    /// Block layout: 16-byte header + 8 data bytes + 104 alignment-pad bytes
    /// (rounded up to the 128-byte boundary via `(8 + 143) & !127 = 128`).
    fn make_sqpk_file_block(byte: u8) -> Vec<u8> {
        let mut out = Vec::new();
        out.extend_from_slice(&16i32.to_le_bytes()); // header_size
        out.extend_from_slice(&0u32.to_le_bytes()); // pad
        out.extend_from_slice(&0x7d00i32.to_le_bytes()); // compressed_size = uncompressed sentinel
        out.extend_from_slice(&8i32.to_le_bytes()); // decompressed_size
        out.extend_from_slice(&[byte; 8]); // data
        out.extend_from_slice(&[0u8; 104]); // 128-byte alignment padding
        out
    }

    /// Build an SQPK `F`(`AddFile`) chunk that targets `path` and contains
    /// `block_count` uncompressed blocks of 8 bytes each.
    fn make_sqpk_addfile_chunk(path: &str, block_count: usize) -> Vec<u8> {
        // SQPK `F` command body layout — see `chunk/sqpk/file.rs` docs.
        let path_bytes: Vec<u8> = {
            let mut p = path.as_bytes().to_vec();
            p.push(0); // NUL terminator
            p
        };

        let mut cmd_body = Vec::new();
        cmd_body.push(b'A'); // operation = AddFile
        cmd_body.extend_from_slice(&[0u8; 2]); // alignment
        cmd_body.extend_from_slice(&0u64.to_be_bytes()); // file_offset = 0
        cmd_body.extend_from_slice(&0u64.to_be_bytes()); // file_size
        cmd_body.extend_from_slice(&(path_bytes.len() as u32).to_be_bytes());
        cmd_body.extend_from_slice(&0u16.to_be_bytes()); // expansion_id
        cmd_body.extend_from_slice(&[0u8; 2]); // padding
        cmd_body.extend_from_slice(&path_bytes);
        for i in 0..block_count {
            cmd_body.extend_from_slice(&make_sqpk_file_block(0xA0 + (i as u8)));
        }

        // SQPK chunk body: i32 BE inner_size + 'F' command byte + cmd_body
        let inner_size = 5 + cmd_body.len();
        let mut sqpk_body = Vec::new();
        sqpk_body.extend_from_slice(&(inner_size as i32).to_be_bytes());
        sqpk_body.push(b'F');
        sqpk_body.extend_from_slice(&cmd_body);

        make_chunk(b"SQPK", &sqpk_body)
    }

    // --- Platform Display ---

    #[test]
    fn platform_display_all_variants() {
        assert_eq!(format!("{}", Platform::Win32), "Win32");
        assert_eq!(format!("{}", Platform::Ps3), "PS3");
        assert_eq!(format!("{}", Platform::Ps4), "PS4");
        assert_eq!(format!("{}", Platform::Unknown(42)), "Unknown(42)");
        // Zero unknown ID is distinct from Win32.
        assert_eq!(format!("{}", Platform::Unknown(0)), "Unknown(0)");
    }

    // --- apply_to: basic end-to-end ---

    #[test]
    fn apply_to_applies_adir_chunk_to_filesystem() {
        // Verify that a well-formed ADIR + EOF_ patch creates the directory.
        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 tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path());
        ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .apply_to(&mut ctx)
            .unwrap();

        assert!(
            tmp.path().join("created").is_dir(),
            "ADIR must have created the directory"
        );
    }

    #[test]
    fn apply_to_empty_patch_succeeds_without_side_effects() {
        // MAGIC + EOF_ only: apply_to must return Ok(()) with no filesystem changes.
        let mut patch = Vec::new();
        patch.extend_from_slice(&MAGIC);
        patch.extend_from_slice(&make_chunk(b"EOF_", &[]));

        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path());
        ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .apply_to(&mut ctx)
            .unwrap();
        // No new entries should appear in the temp dir.
        let entries: Vec<_> = std::fs::read_dir(tmp.path()).unwrap().collect();
        assert!(
            entries.is_empty(),
            "empty patch must not create any files/dirs"
        );
    }

    // --- apply_to: error propagation ---

    #[test]
    fn apply_to_propagates_parse_error_as_unknown_chunk_tag() {
        // ZZZZ is not a known tag; apply_to must surface UnknownChunkTag.
        let mut patch = Vec::new();
        patch.extend_from_slice(&MAGIC);
        patch.extend_from_slice(&make_chunk(b"ZZZZ", &[]));

        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path());
        let err = ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .apply_to(&mut ctx)
            .unwrap_err();
        assert!(
            matches!(err, ZiPatchError::UnknownChunkTag(_)),
            "expected UnknownChunkTag, got {err:?}"
        );
    }

    #[test]
    fn apply_to_propagates_apply_error_from_delete_directory() {
        // DELD on a non-existent directory without ignore_missing must return Io.
        let mut deld_body = Vec::new();
        deld_body.extend_from_slice(&14u32.to_be_bytes());
        deld_body.extend_from_slice(b"does_not_exist");

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

        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path());
        let err = ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .apply_to(&mut ctx)
            .unwrap_err();
        assert!(
            matches!(err, ZiPatchError::Io(_)),
            "expected ZiPatchError::Io for missing dir without ignore_missing, got {err:?}"
        );
    }

    // --- Progress / observer / cancellation tests ---

    /// Observer that returns `should_cancel() == true` after `cancel_after` calls.
    struct CancelAfter {
        calls: usize,
        cancel_after: usize,
    }

    impl ApplyObserver for CancelAfter {
        fn should_cancel(&mut self) -> bool {
            let now = self.calls;
            self.calls += 1;
            now >= self.cancel_after
        }
    }

    #[test]
    fn observer_fires_for_each_non_eof_chunk_with_correct_fields() {
        // Two ADIR chunks — observer must receive exactly two events, in order,
        // with 0-based index, correct tag, and a monotonically increasing
        // bytes_read that matches the exact wire-frame sizes.
        let log: Arc<std::sync::Mutex<Vec<ChunkEvent>>> =
            Arc::new(std::sync::Mutex::new(Vec::new()));
        let log_clone = log.clone();

        let mut a = Vec::new();
        a.extend_from_slice(&1u32.to_be_bytes());
        a.extend_from_slice(b"a");
        let mut b = Vec::new();
        b.extend_from_slice(&1u32.to_be_bytes());
        b.extend_from_slice(b"b");

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

        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path()).with_observer(move |ev| {
            log_clone.lock().unwrap().push(ev);
            ControlFlow::Continue(())
        });
        ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .apply_to(&mut ctx)
            .unwrap();

        let events = log.lock().unwrap();
        assert_eq!(
            events.len(),
            2,
            "two non-EOF chunks must fire exactly two events"
        );
        // Index must be 0-based and monotonically increasing.
        assert_eq!(events[0].index, 0, "first event index must be 0");
        assert_eq!(events[1].index, 1, "second event index must be 1");
        // Tag must reflect the chunk wire tag.
        assert_eq!(events[0].kind, *b"ADIR");
        assert_eq!(events[1].kind, *b"ADIR");
        // ADIR body for name "a": 4 (name_len) + 1 (byte) = 5
        // Frame: 4(size) + 4(tag) + 5(body) + 4(crc) = 17
        assert_eq!(
            events[0].bytes_read,
            12 + 17,
            "bytes_read after first ADIR must be magic + one 17-byte frame"
        );
        assert_eq!(
            events[1].bytes_read,
            12 + 17 + 17,
            "bytes_read after second ADIR must be magic + two 17-byte frames"
        );
        // Strict monotonicity.
        assert!(
            events[0].bytes_read < events[1].bytes_read,
            "bytes_read must strictly increase between events"
        );
    }

    #[test]
    fn observer_break_on_first_chunk_aborts_immediately_leaving_first_applied() {
        // Observer that always breaks: only the first chunk's apply runs, then
        // apply_to returns Cancelled. Second and third chunks are never reached.
        let mut a = Vec::new();
        a.extend_from_slice(&1u32.to_be_bytes());
        a.extend_from_slice(b"a");
        let mut b_body = Vec::new();
        b_body.extend_from_slice(&1u32.to_be_bytes());
        b_body.extend_from_slice(b"b");
        let mut c = Vec::new();
        c.extend_from_slice(&1u32.to_be_bytes());
        c.extend_from_slice(b"c");

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

        let count = Arc::new(AtomicUsize::new(0));
        let count_clone = count.clone();

        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path()).with_observer(move |_| {
            count_clone.fetch_add(1, Ordering::Relaxed);
            ControlFlow::Break(())
        });
        let err = ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .apply_to(&mut ctx)
            .unwrap_err();

        assert!(
            matches!(err, ZiPatchError::Cancelled),
            "observer Break must produce ZiPatchError::Cancelled, got {err:?}"
        );
        assert_eq!(
            count.load(Ordering::Relaxed),
            1,
            "exactly one on_chunk_applied call fires before the abort takes effect"
        );
        // The first ADIR's apply completed before the event fired.
        assert!(
            tmp.path().join("a").is_dir(),
            "first ADIR must have been applied before Cancelled was returned"
        );
        // Second and third ADIRs were never reached.
        assert!(
            !tmp.path().join("b").exists(),
            "second ADIR must NOT have been applied after Cancelled"
        );
        assert!(
            !tmp.path().join("c").exists(),
            "third ADIR must NOT have been applied after Cancelled"
        );
    }

    #[test]
    fn observer_break_on_last_chunk_before_eof_leaves_all_earlier_applied() {
        // Three ADIRs: observer continues for the first two, breaks on the third.
        // After Cancelled, a/ and b/ must exist; c/ was the breaker's chunk
        // (its apply ran before the event fired) and d/ (hypothetical fourth) never runs.
        let make_adir_chunk = |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_chunk(b"a"));
        patch.extend_from_slice(&make_adir_chunk(b"b"));
        patch.extend_from_slice(&make_adir_chunk(b"c"));
        patch.extend_from_slice(&make_chunk(b"EOF_", &[]));

        let call_count = Arc::new(AtomicUsize::new(0));
        let cc = call_count.clone();
        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path()).with_observer(move |_| {
            let n = cc.fetch_add(1, Ordering::Relaxed) + 1;
            if n >= 3 {
                ControlFlow::Break(())
            } else {
                ControlFlow::Continue(())
            }
        });

        let err = ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .apply_to(&mut ctx)
            .unwrap_err();

        assert!(
            matches!(err, ZiPatchError::Cancelled),
            "expected Cancelled, got {err:?}"
        );
        // First two ADIRs fully applied.
        assert!(tmp.path().join("a").is_dir(), "a/ must exist");
        assert!(tmp.path().join("b").is_dir(), "b/ must exist");
        // Third ADIR's apply ran before the event — c/ exists.
        assert!(
            tmp.path().join("c").is_dir(),
            "c/ must exist (apply ran before event fired)"
        );
    }

    #[test]
    fn sqpk_file_cancellation_mid_block_loop_returns_aborted() {
        // Three blocks of 8 bytes each. Observer cancels after 2 should_cancel
        // polls, so at most 2 blocks are written before abort.
        let chunk = make_sqpk_addfile_chunk("created/test.dat", 3);

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

        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path()).with_observer(CancelAfter {
            calls: 0,
            cancel_after: 2,
        });

        let err = ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .apply_to(&mut ctx)
            .unwrap_err();

        assert!(
            matches!(err, ZiPatchError::Cancelled),
            "mid-block cancellation must return Cancelled, got {err:?}"
        );

        // File exists (create=true opened it) but the third block must not have
        // been written.  With `cancel_after = 2`, `should_cancel` returns true
        // on the third poll (the one that gates block 3), so exactly the first
        // two 8-byte blocks (= 16 bytes) reach disk.  Pin this exactly so an
        // off-by-one in where `should_cancel` is polled inside the block loop
        // would surface as a failing test rather than passing by inequality.
        let target = tmp.path().join("created").join("test.dat");
        assert!(
            target.is_file(),
            "target file must exist (was created before cancel)"
        );
        let len = std::fs::metadata(&target).unwrap().len();
        assert_eq!(
            len, 16,
            "partial write: exactly 2 of 3 blocks (= 16 bytes) must have \
             been written before cancellation"
        );
    }

    #[test]
    fn sqpk_file_single_block_no_mid_loop_cancel_opportunity() {
        // A single-block AddFile provides no between-block cancellation
        // opportunity. An observer that cancels only on the second call to
        // should_cancel must NOT abort — the loop executes exactly one block
        // and then the chunk completes normally. The chunk-boundary event fires
        // next, and a Continue there lets apply_to succeed.
        let chunk = make_sqpk_addfile_chunk("created/single.dat", 1);

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

        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path()).with_observer(CancelAfter {
            calls: 0,
            cancel_after: 2, // never reaches 2nd call within a single block
        });

        // should succeed: only 1 should_cancel call (call 0 < 2 = cancel_after)
        ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .apply_to(&mut ctx)
            .unwrap();

        let target = tmp.path().join("created").join("single.dat");
        assert!(
            target.is_file(),
            "single-block AddFile must complete and create the file"
        );
        assert_eq!(
            std::fs::metadata(&target).unwrap().len(),
            8,
            "single block of 8 bytes must be fully written"
        );
    }

    #[test]
    fn sqpk_file_cancel_on_very_first_block_writes_zero_blocks() {
        // Observer cancels immediately (cancel_after = 0).  The first
        // should_cancel poll inside the block loop fires before any block data
        // is written, so the file must be empty (truncated by set_len(0) but
        // no block data written).
        let chunk = make_sqpk_addfile_chunk("created/zero.dat", 3);

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

        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path()).with_observer(CancelAfter {
            calls: 0,
            cancel_after: 0, // cancel on very first check
        });

        let err = ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .apply_to(&mut ctx)
            .unwrap_err();

        assert!(
            matches!(err, ZiPatchError::Cancelled),
            "immediate cancel must return Cancelled, got {err:?}"
        );

        let target = tmp.path().join("created").join("zero.dat");
        let len = std::fs::metadata(&target).unwrap().len();
        assert_eq!(
            len, 0,
            "cancel before first block: file must be empty, got {len} bytes"
        );
    }

    #[test]
    fn closure_observer_composes_ergonomically_with_with_observer() {
        // Verify the intended ergonomic usage path: a closure recording state,
        // passed directly to with_observer via the blanket impl on FnMut.
        let events: Arc<std::sync::Mutex<Vec<(usize, [u8; 4])>>> =
            Arc::new(std::sync::Mutex::new(Vec::new()));
        let ev_clone = events.clone();

        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"d1"));
        patch.extend_from_slice(&make_adir(b"d2"));
        patch.extend_from_slice(&make_chunk(b"EOF_", &[]));

        let tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path()).with_observer(move |ev: ChunkEvent| {
            ev_clone.lock().unwrap().push((ev.index, ev.kind));
            ControlFlow::Continue(())
        });

        ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .apply_to(&mut ctx)
            .unwrap();

        let recorded = events.lock().unwrap();
        assert_eq!(recorded.len(), 2);
        assert_eq!(recorded[0], (0, *b"ADIR"));
        assert_eq!(recorded[1], (1, *b"ADIR"));
    }

    #[test]
    fn default_no_observer_apply_succeeds_as_before() {
        // Regression: without with_observer the apply must succeed exactly as
        // it did before the observer API was introduced.
        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 tmp = tempfile::tempdir().unwrap();
        let mut ctx = ApplyContext::new(tmp.path()); // no with_observer call
        ZiPatchReader::new(Cursor::new(patch))
            .unwrap()
            .apply_to(&mut ctx)
            .unwrap();
        assert!(
            tmp.path().join("created").is_dir(),
            "ADIR must be applied when no observer is set"
        );
    }
}