Skip to main content

Module format

hexz_core

Module format 

Source
Expand description

On-disk format structures: headers, indices, and serialization.

These types define the binary wire format for Hexz snapshots. All structures use bincode for serialization and are versioned for forward compatibility.

See submodules for detailed format specification:

  • magic: Magic bytes and version constants
  • header: File header structure and enums
  • index: Index pages and block metadata
  • version: Version compatibility checking On-disk format structures for Hexz snapshot files.

This module defines the binary format of .hxz files, including headers, indices, and metadata structures. All types are serialized with bincode and must maintain backward compatibility across versions.

§File Structure

A complete Hexz archive has the following layout:

╔══════════════════════════════════════════════════════════╗
║                  HEXZ ARCHIVE (.hxz)                    ║
╠══════════════════════════════════════════════════════════╣
║ Offset 0: HEADER (4096 bytes)                           ║
║   - Magic: "HEXZ" (4 bytes)                             ║
║   - Version: u32                                         ║
║   - Block size: u32                                      ║
║   - Index offset: u64                                    ║
║   - Compression: enum (LZ4/Zstd)                         ║
║   - Features: bitflags                                   ║
║   - Optional: dictionary, metadata, signature offsets    ║
╠══════════════════════════════════════════════════════════╣
║ DATA REGION (variable size)                             ║
║   - Compressed blocks                                    ║
║   - Optional: encrypted blocks                           ║
║   - Optional: compression dictionary                     ║
╠══════════════════════════════════════════════════════════╣
║ INDEX REGION (variable size)                            ║
║   - Index pages (B-tree or hash-based)                   ║
║   - Block metadata (offset, length, CRC32)               ║
╠══════════════════════════════════════════════════════════╣
║ MASTER INDEX (at header.index_offset)                   ║
║   - Page entries                                         ║
║   - Stream sizes (disk, memory)                          ║
║   - Deduplication statistics                             ║
╠══════════════════════════════════════════════════════════╣
║ Optional: SIGNATURE (Ed25519, 64 bytes)                 ║
╚══════════════════════════════════════════════════════════╝

§Format Versioning

The format version follows semantic versioning:

  • Major: Incompatible changes (readers must reject)
  • Minor: Backward-compatible additions (old readers work)
  • Patch: Bug fixes, no format changes

Current version: See [magic] module for version constants

§Serialization

All structures use bincode with the following settings:

  • Endianness: Little-endian
  • Size limits: Bounded (prevents DOS attacks)
  • Compatibility: Fixed-size where possible

§Submodules

  • magic: Magic bytes and version constants
  • header: File header structure and enums
  • index: Index pages and block metadata
  • version: Version compatibility checking

Modules§

header
Snapshot on-disk header format.
index
Snapshot index layout and block metadata structures.
magic
Magic bytes and version constants.
version
Version compatibility checking.