hexz_core/format/mod.rs
1//! On-disk format structures for Hexz snapshot files.
2//!
3//! This module defines the binary format of `.hxz` files, including headers,
4//! indices, and metadata structures. All types are serialized with `bincode`
5//! and must maintain backward compatibility across versions.
6//!
7//! # File Structure
8//!
9//! A complete Hexz archive has the following layout:
10//!
11//! ```text
12//! ╔══════════════════════════════════════════════════════════╗
13//! ║ HEXZ ARCHIVE (.hxz) ║
14//! ╠══════════════════════════════════════════════════════════╣
15//! ║ Offset 0: HEADER (4096 bytes) ║
16//! ║ - Magic: "HEXZ" (4 bytes) ║
17//! ║ - Version: u32 ║
18//! ║ - Block size: u32 ║
19//! ║ - Index offset: u64 ║
20//! ║ - Compression: enum (LZ4/Zstd) ║
21//! ║ - Features: bitflags ║
22//! ║ - Optional: dictionary, metadata, signature offsets ║
23//! ╠══════════════════════════════════════════════════════════╣
24//! ║ DATA REGION (variable size) ║
25//! ║ - Compressed blocks ║
26//! ║ - Optional: encrypted blocks ║
27//! ║ - Optional: compression dictionary ║
28//! ╠══════════════════════════════════════════════════════════╣
29//! ║ INDEX REGION (variable size) ║
30//! ║ - Index pages (B-tree or hash-based) ║
31//! ║ - Block metadata (offset, length, CRC32) ║
32//! ╠══════════════════════════════════════════════════════════╣
33//! ║ MASTER INDEX (at header.index_offset) ║
34//! ║ - Page entries ║
35//! ║ - Stream sizes (disk, memory) ║
36//! ║ - Deduplication statistics ║
37//! ╠══════════════════════════════════════════════════════════╣
38//! ║ Optional: SIGNATURE (Ed25519, 64 bytes) ║
39//! ╚══════════════════════════════════════════════════════════╝
40//! ```
41//!
42//! # Format Versioning
43//!
44//! The format version follows semantic versioning:
45//! - **Major**: Incompatible changes (readers must reject)
46//! - **Minor**: Backward-compatible additions (old readers work)
47//! - **Patch**: Bug fixes, no format changes
48//!
49//! Current version: See [`magic`] module for version constants
50//!
51//! # Serialization
52//!
53//! All structures use `bincode` with the following settings:
54//! - **Endianness**: Little-endian
55//! - **Size limits**: Bounded (prevents DOS attacks)
56//! - **Compatibility**: Fixed-size where possible
57//!
58//! # Submodules
59//!
60//! - `magic`: Magic bytes and version constants
61//! - `header`: File header structure and enums
62//! - `index`: Index pages and block metadata
63//! - `version`: Version compatibility checking
64
65/// Magic bytes and version constants.
66///
67/// Defines the file signature (`HEXZ`) and format version that identify
68/// a valid snapshot file.
69///
70/// **Critical Note:** The magic bytes **never change**—they permanently identify
71/// this as a Hexz file across all versions. Altering them would make all
72/// existing files unreadable.
73///
74/// The format version constant, however, **can and will change** to indicate
75/// incompatible format updates. Readers must check this version and reject files
76/// they cannot decode.
77pub mod magic;
78
79/// Snapshot on-disk header format.
80///
81/// Types in this module define the fixed-size header that precedes all other
82/// data in a `.hxz` file and describe global format parameters.
83pub mod header;
84
85/// Snapshot index layout and block metadata structures.
86///
87/// This module contains the master index and per-page entries that map
88/// logical blocks to their physical location in the file.
89pub mod index;
90
91/// Version compatibility checking.
92///
93/// Provides version range checking and graceful degradation for reading
94/// files created with different format versions.
95pub mod version;