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.
//!
//! # Quick start
//!
//! The most common usage — apply a single patch file to an install root
//! with all defaults — is a single call:
//!
//! ```no_run
//! zipatch_rs::apply_patch_file(
//!     "H2017.07.11.0000.0000a.patch",
//!     "/opt/ffxiv/game",
//! ).unwrap();
//! ```
//!
//! For consumers that need progress observers, custom checkpoint sinks, a
//! non-default platform, or multi-patch session reuse, use the two-step
//! form directly:
//!
//! ```no_run
//! use zipatch_rs::{ApplyConfig, open_patch};
//!
//! let reader = open_patch("H2017.07.11.0000.0000a.patch").unwrap();
//! let ctx = ApplyConfig::new("/opt/ffxiv/game");
//! ctx.apply_patch(reader).unwrap();
//! ```
//!
//! # Choosing an apply pipeline
//!
//! `zipatch-rs` ships two apply pipelines. They are not alternatives in the
//! sense of "one is better" — they answer different questions.
//!
//! - **Sequential** ([`ApplyConfig::apply_patch`]) walks a single patch in
//!   chunk order and writes each chunk to disk as it is parsed. One pass,
//!   one patch, bounded memory, minimum latency from "start" to "first byte
//!   on disk". This is the default; reach for it unless you specifically need
//!   what the indexed pipeline offers.
//! - **Indexed** ([`PlanBuilder`] → [`Plan`] →
//!   [`IndexApplier::execute`](crate::IndexApplier::execute)) folds one or
//!   many patches into a deduplicated, target-major [`Plan`] in memory, then
//!   replays it against the install. The plan is pure data: it can be
//!   inspected, persisted (with the `serde` feature), CRC-populated via
//!   [`Plan::with_crc32`](crate::index::Plan::with_crc32), verified against
//!   the current install via [`PlanVerifier`](crate::index::PlanVerifier),
//!   and used to drive a repair via
//!   [`IndexApplier::execute_with_manifest`](crate::index::IndexApplier::execute_with_manifest)
//!   with a [`RepairManifest`](crate::index::RepairManifest).
//!
//! Pick by what the consumer needs:
//!
//! | Need                                                                | Pipeline   |
//! |---------------------------------------------------------------------|------------|
//! | Apply one patch to an install, in order, now                        | Sequential |
//! | Apply a chain of N patches and dedupe writes superseded mid-chain   | Indexed    |
//! | Pre-validate the chain against the install before touching a byte   | Indexed    |
//! | Pre-compute expected CRC32s and verify the install against them     | Indexed    |
//! | Produce a [`RepairManifest`](crate::index::RepairManifest) of drifted regions | Indexed    |
//! | Persist a structured description of pending work for later replay   | Indexed    |
//! | Minimum latency to first write; bounded streaming memory            | Sequential |
//! | Patch source is forward-only (no seeks)                             | Sequential |
//!
//! Costs to weigh: the indexed pipeline does two passes over the patch
//! source (plan-build, then apply) and holds the plan in memory; the source
//! must support random access, which is why the indexed entry points take a
//! [`PatchSource`](crate::index::PatchSource) (typically
//! [`FilePatchSource`](crate::index::FilePatchSource)) rather than a plain
//! [`Read`](std::io::Read). The sequential pipeline does a single forward
//! pass and never holds more than one chunk in flight.
//!
//! Starting sequential and growing to indexed later is a supported path —
//! the [`ApplyConfig`] knobs (`with_observer`, `with_cancel_token`,
//! `with_checkpoint_sink`, `with_platform`, `with_vfs`) all carry across to
//! [`IndexApplier`] with the same names and semantics.
//!
//! ```no_run
//! // Sequential: one patch, one pass.
//! zipatch_rs::apply_patch_file("patch.patch", "/opt/ffxiv/game").unwrap();
//! ```
//!
//! ```no_run
//! // Indexed: build a plan over a chain, then apply it.
//! use zipatch_rs::{IndexApplier, PlanBuilder, open_patch};
//! use zipatch_rs::index::FilePatchSource;
//!
//! let mut builder = PlanBuilder::new();
//! builder.add_patch("p1.patch", open_patch("p1.patch").unwrap()).unwrap();
//! builder.add_patch("p2.patch", open_patch("p2.patch").unwrap()).unwrap();
//! let plan = builder.finish();
//!
//! let source = FilePatchSource::open_chain(["p1.patch", "p2.patch"]).unwrap();
//! IndexApplier::new(source, "/opt/ffxiv/game").execute(&plan).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 mut reader = ZiPatchReader::new(File::open("patch.patch").unwrap()).unwrap();
//! while let Some(rec) = reader.next_chunk().unwrap() {
//!     match rec.chunk {
//!         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::{ApplyConfig, 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 = ApplyConfig::new(tmp.path());
//! let reader = ZiPatchReader::new(Cursor::new(patch)).unwrap();
//! ctx.apply_patch(reader).unwrap();
//!
//! assert!(tmp.path().join("created").is_dir());
//! ```
//!
//! # Error handling
//!
//! Each layer returns its own domain-specific error type ([`ParseError`],
//! [`ApplyError`], [`IndexError`], [`VerifyError`]); the corresponding
//! [`ParseResult`], [`ApplyResult`], [`IndexResult`], and [`VerifyResult`]
//! aliases at the crate root cover the common signatures.
//!
//! Callers that want a single `?`-friendly type at the edges of their code
//! can use the umbrella [`Error`] enum (and the matching [`Result`] alias) —
//! every domain error `From`-converts into it, so a one-line `?` collapses
//! the four domains into one match arm.
//!
//! ```no_run
//! use zipatch_rs::{apply_patch_file, Error, Result};
//!
//! fn install(patch: &str, root: &str) -> Result<()> {
//!     apply_patch_file(patch, root)?; // ApplyError -> Error via From
//!     Ok(())
//! }
//! # let _ = install;
//! ```
//!
//! # Progress and cancellation
//!
//! [`ApplyConfig::with_observer`] installs an [`ApplyObserver`] that is
//! called after each chunk applies (with the chunk index, tag, and running
//! byte count from [`chunk::ChunkRecord::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
//! [`ApplyError::Cancelled`]. Parsing-only consumers and existing
//! [`apply_patch`](ApplyConfig::apply_patch) callers that never install an
//! observer pay nothing — the default is a no-op.
//!
//! For cancellation alone, prefer [`CancelToken`]: a cheap cloneable
//! [`AtomicBool`](std::sync::atomic::AtomicBool) wrapper installed via
//! [`ApplyConfig::with_cancel_token`] (or
//! [`IndexApplier::with_cancel_token`](crate::IndexApplier::with_cancel_token)).
//! Hold a clone on whichever thread initiates cancellation, call
//! [`CancelToken::cancel`] on a user gesture, and the apply driver picks
//! up the flip at the next chunk boundary or inner-loop poll point. The
//! token composes with an installed observer — both are polled, either can
//! abort.
//!
//! # Tracing
//!
//! The library emits structured [`tracing`] events and spans across the
//! parse, plan-build, apply, and verify entry points. Levels follow a
//! "one event per logical operation at `info!`, per-target/per-fs-op at
//! `debug!`, per-region/byte-level work at `trace!`" cadence. The top-level
//! spans listed below are emitted at the `info` level so a subscriber
//! configured at the default level can scope output via span filtering,
//! while per-target sub-spans emit at `debug`. Recoverable anomalies — stale
//! manifest entries, unknown platform IDs, missing-but-ignored files — fire
//! `warn!`; errors are returned via the domain error types rather than
//! logged. No subscriber is configured here — that is the consumer's
//! responsibility.
//!
//! [`tracing`]: https://docs.rs/tracing
//!
//! ## Stability contract
//!
//! `tracing` names are a public API for any consumer wiring up
//! `tracing-subscriber` filters, OpenTelemetry exporters, log scrapers, or
//! dashboards that key off span/event/field names. This crate treats them
//! as such, with the following tiers:
//!
//! - **Stable (SemVer-tracked)** — the span names and field names listed in
//!   the catalog below at the **info** and **debug** levels, plus the
//!   per-operation completion-event messages explicitly called out.
//!   Renaming or removing one of these is a minor-version bump while the
//!   crate is on `0.x`/`1.x`; a major-version bump after `2.0`. New spans,
//!   new events, and new fields on existing spans are additive and ship in
//!   patch releases.
//! - **Best-effort (not contracted)** — `trace!` events and any field they
//!   carry, all event messages not explicitly listed, and the precise
//!   wording of `warn!` messages. These exist for operator forensics and
//!   may change in any release; depend on them only inside a development
//!   environment.
//!
//! The canonical strings live in a crate-internal `tracing_schema` module
//! so a rename lands in a single file. Field names are kept as
//! literals at the emission sites (their `tracing` macro syntax for
//! const-named fields would clutter the call site without a corresponding
//! rename-cost benefit), but they appear in the stable catalog below and
//! follow the same contract.
//!
//! ## Span catalog
//!
//! All spans are tagged with the entry point they bracket and the fields
//! they carry on creation. Sub-spans inherit the parent's field set via
//! the standard `tracing` span hierarchy.
//!
//! ### Info-level (top-level operations)
//!
//! | Span | Entry point | Fields |
//! |---|---|---|
//! | `apply_patch` | [`ApplyConfig::apply_patch`] | *(none on creation)* |
//! | `resume_apply_patch` | [`ApplyConfig::resume_apply_patch`] | *(none on creation)* |
//! | `apply_plan` | [`IndexApplier::execute_with_manifest`](crate::index::IndexApplier::execute_with_manifest) | `mode`, `targets`, `regions` |
//! | `resume_execute` | [`IndexApplier::execute`](crate::index::IndexApplier::execute) / [`IndexApplier::resume_execute`](crate::index::IndexApplier::resume_execute) | `plan_crc32`, `targets`, `regions`, `fs_ops` |
//! | `build_plan_patch` | [`PlanBuilder::add_patch`](crate::index::PlanBuilder::add_patch) | `patch` |
//! | `with_crc32` | [`Plan::with_crc32`](crate::index::Plan::with_crc32) | `targets` |
//! | `verify_plan` | [`PlanVerifier::execute`](crate::index::PlanVerifier::execute) | `targets` |
//! | `verify_hashes` | [`HashVerifier::execute`](crate::verify::HashVerifier::execute) | `files` |
//!
//! ### Debug-level (per-target / per-file sub-spans)
//!
//! | Span | Parent | Fields |
//! |---|---|---|
//! | `apply_target` | `apply_plan` / `resume_execute` | `target_idx`, `path`, `regions` |
//! | `verify_target` | `verify_plan` | `target` |
//! | `verify_file` | `verify_hashes` | `path` |
//!
//! ## Event catalog (info-level, per-operation completion)
//!
//! These messages are emitted exactly once per call to their owning entry
//! point on the success path, and are part of the stable contract:
//!
//! | Span | Message | Fields |
//! |---|---|---|
//! | `apply_patch` | `apply_patch: patch applied` | `chunks`, `bytes_read`, `resumed_from_chunk`, `elapsed_ms` |
//! | `resume_apply_patch` | `resume_apply_patch: patch applied` | `chunks`, `bytes_read`, `resumed_from_chunk`, `skipped_bytes` (resumed only), `elapsed_ms` |
//! | `resume_apply_patch` | `resume_apply_patch: resuming patch` | `patch_name`, `skipped_chunks`, `skipped_bytes`, `has_in_flight` |
//! | `resume_execute` | `apply_plan: indexed apply complete` | `bytes_written`, `targets`, `resumed_from`, `elapsed_ms` |
//! | `resume_execute` | `resume_execute: resuming indexed apply` | `plan_crc32`, `skipped_targets`, `skipped_regions`, `fs_ops_skipped` |
//! | `apply_plan` | `apply_plan: manifest replay complete` | `bytes_written`, `targets`, `regions`, `elapsed_ms` |
//! | `build_plan_patch` | `plan: patch consumed` | `chunks`, `targets`, `fs_ops` |
//! | *(none — fires from `PlanBuilder::finish`)* | `plan: built` | `patches`, `targets`, `regions`, `fs_ops` |
//! | `with_crc32` | `with_crc32: populated CRC32 for regions` | `populated`, `skipped` |
//! | `verify_plan` | `verify_plan: scan complete` | `targets`, `missing_targets`, `size_mismatched`, `damaged_targets`, `damaged_regions`, `elapsed_ms` |
//! | `verify_hashes` | `verify_hashes: run complete` | `files`, `failures`, `bytes_hashed`, `elapsed_ms` |
//!
//! ## Stable field-name vocabulary
//!
//! Field names attached to the spans and events above are stable. Across
//! the library they're used consistently:
//!
//! - `patch`, `patch_name`, `patches`, `chunks`, `bytes_read`, `elapsed_ms`
//! - `resumed_from_chunk`, `resumed_from`, `skipped_chunks`, `skipped_bytes`,
//!   `skipped_targets`, `skipped_regions`, `has_in_flight`, `fs_ops_skipped`
//! - `targets`, `regions`, `fs_ops`, `target_idx`, `region_idx`,
//!   `target`, `path`, `mode`
//! - `plan_crc32`, `populated`, `skipped`, `bytes_written`
//! - `files`, `failures`, `bytes_hashed`, `missing_targets`,
//!   `size_mismatched`, `damaged_targets`, `damaged_regions`
//!
//! Field names emitted only at `debug!` / `trace!` levels (e.g.
//! `next_chunk_index`, `bytes_into_target`, `block_idx`, `chunk_bytes`,
//! `delete_zeros`, `decoded_skip`, per-fs-op `folder`/`kind`) are
//! best-effort and may change without a version bump.
//!
//! # API conventions
//!
//! All constructors follow consistent naming:
//!
//! - **`new(…)`** — canonical constructor; fails only on structurally invalid input
//!   ([`ZiPatchReader::new`] validates the file magic).
//! - **`open(path)`** — opens a filesystem resource and returns a `Result`
//!   ([`index::FilePatchSource::open`], [`index::FilePatchSource::open_chain`]).
//! - **`with_X(self, value) -> Self`** — builder-style setter; chains on
//!   [`ApplyConfig`] and [`IndexApplier`].
//! - **`into_X(self)`** — type transition consuming `self`
//!   ([`ApplyConfig::into_session`]).
//! - **`execute(self, …) -> Result<T>`** — runs a pipeline to completion
//!   ([`IndexApplier::execute`](crate::IndexApplier::execute),
//!   [`index::PlanVerifier::execute`],
//!   [`verify::HashVerifier::execute`]).
//! - **`finish(self) -> T`** — builder finaliser with no I/O
//!   ([`index::PlanBuilder::finish`]).
//!
//! The crate root re-exports the happy-path symbols. Secondary types live in
//! their owning modules:
//!
//! - [`chunk`] — [`chunk::ChunkRecord`], [`chunk::SqpkCommand`],
//!   [`chunk::SqpackFileId`], [`chunk::SqpkCompressedBlock`]
//! - [`apply`] — [`apply::CheckpointSink`], [`apply::Checkpoint`],
//!   [`apply::CheckpointPolicy`], [`apply::SequentialCheckpoint`],
//!   [`apply::IndexedCheckpoint`], [`apply::NoopCheckpointSink`],
//!   [`apply::NoopObserver`], [`apply::Vfs`], [`apply::StdFs`],
//!   [`apply::InMemoryFs`]
//! - [`index`] — [`index::PlanVerifier`], [`index::PatchSource`],
//!   [`index::FilePatchSource`], [`index::RepairManifest`]
//! - [`newtypes`] — [`newtypes::PatchIndex`], [`newtypes::ChunkTag`],
//!   [`newtypes::SchemaVersion`]
//!
//! # Async usage
//!
//! `zipatch-rs` is a **synchronous** crate. Every public trait
//! ([`index::PatchSource`], [`apply::CheckpointSink`],
//! [`ApplyObserver`], [`apply::Vfs`]) and every driver entry point
//! ([`ApplyConfig::apply_patch`], [`IndexApplier::execute`](crate::index::IndexApplier::execute),
//! [`ZiPatchReader::next_chunk`]) is blocking. The crate has no
//! runtime dependency.
//!
//! This is a deliberate design choice. The apply-side hot path is
//! dominated by DEFLATE decompression (CPU-bound) and filesystem
//! syscalls (blocking by their nature on every mainstream OS); neither
//! benefits from an `async` signature. Staying sync also keeps the crate
//! trivially embeddable in a CLI binary, a Tauri command, or an
//! async-runtime worker without forcing a runtime choice or pulling
//! `tokio` into the dependency graph.
//!
//! ## Driving the crate from an async runtime
//!
//! Async consumers (e.g. a tokio-based launcher) park the whole apply
//! call on a blocking-pool thread:
//!
//! ```ignore
//! // pseudo-code; the crate has no tokio dependency
//! let install_path = install_path.clone();
//! let patch_path   = patch_path.clone();
//! let cancel       = zipatch_rs::CancelToken::new();
//! let cancel_bg    = cancel.clone();
//!
//! // ... wire `cancel.cancel()` to a tokio::select! arm or UI handler ...
//!
//! let result = tokio::task::spawn_blocking(move || {
//!     let reader = zipatch_rs::open_patch(&patch_path)?;
//!     let ctx = zipatch_rs::ApplyConfig::new(install_path)
//!         .with_cancel_token(cancel_bg);
//!     ctx.apply_patch(reader)
//! }).await??;
//! ```
//!
//! Per-chunk progress reaches the async UI through an
//! [`mpsc`](std::sync::mpsc) (or tokio-mpsc-equivalent) channel whose
//! `Sender` lives inside an [`ApplyObserver`] impl and whose `Receiver`
//! is polled from an async task. Consumers that need both progress and
//! cancellation pair an observer (for progress) with a [`CancelToken`]
//! (for cancellation) — they compose without a wrapper observer.
//!
//! ## Async-backed sources
//!
//! Implementors whose backing storage is itself async (e.g. an
//! in-progress download, an async KV store for checkpoints, a remote
//! object-store [`apply::Vfs`]) satisfy the sync traits by bridging through a
//! channel against a separate async task: the sync method blocks on a
//! response from the async side. Because the trait methods run from
//! inside the `spawn_blocking` thread, blocking on the channel does
//! not stall the runtime's reactor.

#![deny(missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg))]

#[cfg(not(any(feature = "rust-backend", feature = "zlib-rs", feature = "zlib-ng")))]
compile_error!(
    "zipatch-rs requires a flate2 backend. Enable exactly one of the features \
     `rust-backend` (default, pure-Rust via miniz_oxide), `zlib-rs` (pure-Rust \
     via zlib-rs), or `zlib-ng` (C via zlib-ng). If you set \
     `default-features = false`, re-enable a backend explicitly, e.g. \
     `features = [\"rust-backend\"]`."
);

/// Filesystem application of parsed chunks ([`ApplyConfig`]).
pub mod apply;
/// Wire-format chunk types and the [`ZiPatchReader`] iterator.
pub mod chunk;
/// Domain-split error types ([`ParseError`], [`ApplyError`], [`IndexError`], [`VerifyError`]).
pub mod error;
/// Indexed-apply plan model and single-patch builder
/// ([`Plan`], [`PlanBuilder`]).
pub mod index;
/// Strongly-typed wrappers around primitive identifiers in the public API
/// ([`newtypes::PatchIndex`], [`newtypes::ChunkTag`], [`newtypes::SchemaVersion`]).
pub mod newtypes;
pub(crate) mod tracing_schema;
/// Post-apply integrity verification against caller-supplied file hashes.
pub mod verify;

/// Test fixtures quarantined behind the `test-utils` Cargo feature.
///
/// `#[doc(hidden)]` so this module — and everything it re-exports — stays
/// out of the user-facing rustdoc landing page. See the module rustdoc for
/// the no-stability stance.
#[cfg(any(test, feature = "test-utils"))]
#[doc(hidden)]
pub mod test_utils;

// =============================================================================
// Public API — curated crate-root surface
//
// Only the happy-path symbols are re-exported here. Everything else stays
// addressable via its module path (`zipatch_rs::chunk::ChunkRecord`,
// `zipatch_rs::apply::CheckpointSink`, `zipatch_rs::newtypes::PatchIndex`,
// `zipatch_rs::index::PlanVerifier`, …) but does not crowd the landing page.
// =============================================================================

// --- One-shot drivers — the 90% case ---
pub use chunk::open_patch;
// `apply_patch_file` is defined below.

// --- Parsing primary types ---
pub use chunk::{Chunk, ZiPatchReader};

// --- Apply primary types ---
pub use apply::{ApplyConfig, ApplyObserver, ApplySession, CancelToken, ChunkEvent};

// --- Indexed-pipeline primary types ---
pub use index::{IndexApplier, Plan, PlanBuilder};

// --- Central domain types ---
// `Platform` is defined at the crate root (below) since it has no natural home
// in a sub-module — every layer references it.

// --- Error umbrella + per-domain errors and result aliases ---
pub use error::{
    ApplyError, ApplyResult, Error, IndexError, IndexResult, ParseError, ParseResult, Result,
    VerifyError, VerifyResult,
};

/// One-shot: open `patch_path` and apply every chunk to `install_root` with
/// all defaults.
///
/// Equivalent to:
///
/// ```ignore
/// let reader = zipatch_rs::open_patch(patch_path)?;
/// zipatch_rs::ApplyConfig::new(install_root).apply_patch(reader)?;
/// ```
///
/// The returned [`ApplyResult`] surfaces parsing failures as
/// [`ApplyError::Parse`] and apply-side failures as their respective
/// [`ApplyError`] variants, so a single match arm covers both layers.
///
/// Use the two-step form ([`open_patch`] + [`ApplyConfig::apply_patch`])
/// when you need to install an [`ApplyObserver`], a [`apply::CheckpointSink`],
/// a custom [`apply::Vfs`], a non-default [`Platform`], or to reuse one
/// [`ApplySession`] across multiple patches.
///
/// # Errors
///
/// Returns the first failure surfaced by either layer:
///
/// - [`ApplyError::Parse`] wrapping a [`ParseError`] for header, chunk, or
///   stream-shape problems (including the initial file open).
/// - [`ApplyError::Io`] for filesystem failures against `install_root`.
/// - [`ApplyError::UnsupportedPlatform`] if the patch declares a platform
///   this build does not know how to resolve `SqPack` paths for.
///
/// # Example
///
/// ```no_run
/// zipatch_rs::apply_patch_file(
///     "H2017.07.11.0000.0000a.patch",
///     "/opt/ffxiv/game",
/// ).unwrap();
/// ```
pub fn apply_patch_file(
    patch_path: impl AsRef<std::path::Path>,
    install_root: impl AsRef<std::path::Path>,
) -> ApplyResult<()> {
    let reader = open_patch(patch_path)?;
    ApplyConfig::new(install_root.as_ref().to_path_buf()).apply_patch(reader)
}

/// 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
/// [`ApplyConfig`] selects which suffix is used when resolving chunk targets
/// to filesystem paths.
///
/// # Default
///
/// An [`ApplyConfig`] defaults to [`Platform::Win32`]. Override this at
/// construction time with [`ApplyConfig::with_platform`].
///
/// # Runtime override via `SqpkTargetInfo`
///
/// In practice, real FFXIV patch files begin with an `SQPK T` chunk
/// (`SqpkTargetInfo`) that declares the target platform. When
/// [`Chunk::apply`] is called on that chunk, it overwrites
/// [`ApplyConfig::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]` because Square Enix has shipped console
/// targets on a sliding schedule (Win32, PS3, PS4) and a future PS5 / Switch
/// build would land here as a new named variant. 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
/// [`ApplyError::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::{ApplyConfig, Platform};
///
/// let ctx = ApplyConfig::new("/opt/ffxiv/game")
///     .with_platform(Platform::Win32);
///
/// assert_eq!(ctx.platform(), Platform::Win32);
/// assert_eq!(format!("{}", Platform::Unknown(99)), "Unknown(99)");
/// ```
///
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
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 [`ApplyConfig`].
    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 the apply layer 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
    /// [`ApplyError::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 a
    /// 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})"),
        }
    }
}