binary_patch 1.0.0

binary_patch is a Dart/Flutter library for creating and applying efficient binary diffs using the bsdiff algorithm, reducing update sizes with support for zstd, bzip2, and lzma compression.

Changelog

All notable changes to binary_patch will be documented in this file.

The format follows Keep a Changelog and this project adheres to Semantic Versioning.

---

1.0.0 — 2026-06-01

Added

Core Engine

• Full bsdiff algorithm implementation in Pure Dart (BsdiffEngine)
• Suffix Array construction via prefix-doubling in O(n log² n) (SuffixArray)
• Forward/backward scan overlap resolution — identical to the C reference
• bspatch reconstruction engine in O(m) (BspatchEngine)
• All heavy computation runs in Dart Isolates — never blocks the UI thread

Compression

• Multi-algorithm compression support via CompressorInterface abstraction
• zstd backend (GZip as Dart-native portable fallback)
• bzip2 backend (compatible with original C bsdiff tool)
• lzma backend (maximum compression ratio)
• none (debug / testing)
• CompressorFactory singleton for type-safe compressor construction
• PatchOptions.fast(), .balanced(), .maximum(), .uncompressed() presets

Binary Format

• Versioned binary patch format (BPATCH\x01) with 8-byte magic header
• Embedded JSON metadata (checksums, sizes, timestamps, optional label)
• Little-endian int64 section lengths for 64-bit file support
• PatchFormat.encode() / .decode() — zero-copy BytesBuilder path

Validation

• SHA-256 checksum verification for old file, new file, and patch file
• CRC-32 utility (IEEE 802.3 polynomial)
• IntegrityGuard — pre- and post-apply verification
• Typed exception hierarchy: PatchException → ChecksumException / PatchFormatException

Public API

• BinaryPatch.create() — file-based patch creation
• BinaryPatch.apply() — file-based patch application
• BinaryPatch.analyze() — dry-run size estimation (no disk write)
• BinaryPatch.verify() — fast magic-header check
• BinaryPatch.readMeta() — metadata inspection without applying
• BinaryPatch.createBytes() — in-memory create (Flutter-ready)
• BinaryPatch.applyBytes() — in-memory apply (Flutter-ready)

I/O

• PatchWriter.writeRaw() — atomic file write (temp + rename)
• PatchReader.decode() / .readMetadata() / .verify() — layered reader
• BinaryReader — cursor-based binary buffer reader

CLI Tool (binary_patch)

• create, apply, verify, analyze, info, help commands
• ANSI colour-coded progress bar and output
• --compression, --level, --no-verify flags

Tests & Documentation

• 8 unit test files covering all subsystems
• 12 integration round-trip tests across sizes, compression types, and edge cases
• benchmark/diff_benchmark.dart — async harness for create + apply
• doc/getting_started.md — format spec, usage, performance table
• Complete example/main.dart with 9-step walkthrough
• example/ota_update_example.dart — OTA update simulation

---

1.1.0 — Planned

Planned

• Streaming API for files > 2 GiB (chunked Isolate communication)
• Delta patching for directories (recursive folder diff)
• Brotli compression support (for web/WASM targets)
• Progress reporting with byte-level granularity
• BinaryPatch.createStream() / applyStream() for Stream<List<int>>
• Interactive CLI mode with coloured diff statistics
• Native zstd FFI binding (replace GZip fallback)
• pub.dev score optimisations (100/130 target)

---

2.0.0 — Future

Possible Breaking Changes

• Remove CompressionType.none from the default CompressorFactory (keep as explicit opt-in via PatchOptions.uncompressed() only)
• Rename PatchOptions.compressionLevel to level for brevity