Skip to main content

Module info

hexz_cli::cmd::data

Module info 

Source
Expand description

Inspect archive metadata and display snapshot information.

This command provides a detailed inspection of Hexz snapshot files (.st), reading the file header and master index to display metadata about the snapshot’s structure, compression, encryption status, and storage statistics.

§Use Cases

  • Snapshot Inspection: Verify snapshot format version and feature flags
  • Compression Analysis: Check compression algorithm and ratio achieved
  • Capacity Planning: View original vs. compressed size for storage estimates
  • Debugging: Identify snapshot corruption or format mismatches
  • Automation: JSON output mode enables scripting and tooling integration

§Workflow

The command performs these steps:

  1. Header Reading: Reads the fixed-size header (4096 bytes) from file start
  2. Index Location: Uses index_offset from header to locate the master index
  3. Index Parsing: Deserializes the master index to extract page metadata
  4. Compression Ratio: Calculates ratio from uncompressed vs. file size
  5. Output Formatting: Renders human-readable or JSON output

§Output Format

The command displays:

Header Information:

  • Format version (currently v1)
  • Compression algorithm (LZ4 or Zstd)
  • Block size used for chunking

Feature Flags:

  • Encryption status (encrypted or plaintext)
  • Disk presence (whether snapshot contains disk image)
  • Memory presence (whether snapshot contains memory dump)
  • Variable blocks (whether CDC chunking was used)

Storage Statistics:

  • Original size (sum of uncompressed disk + memory)
  • Compressed size (total file size on disk)
  • Compression ratio (multiplier showing space savings)

Index Details:

  • Index offset in file (byte position)
  • Disk pages (number of index pages for disk stream)
  • Memory pages (number of index pages for memory stream)

§Common Usage Patterns

# Inspect a snapshot with human-readable output
hexz info vm-snapshot.st

# Get machine-readable JSON for scripting
hexz info vm-snapshot.st --json | jq .compression_ratio

# Verify snapshot integrity
hexz info corrupted.st  # Will fail if header is malformed

Functions§

run
Executes the info command to display snapshot metadata.