hexz_core/ops/mod.rs
1//! High-level operations for Hexz snapshot files.
2//!
3//! This module provides the orchestration layer that combines low-level format,
4//! storage, and algorithm primitives into complete end-to-end workflows for
5//! creating, reading, and modifying Hexz archives.
6//!
7//! # Architecture
8//!
9//! The operations layer sits between command-line interfaces (CLI, Python) and
10//! core primitives (format, store, algo):
11//!
12//! ```text
13//! ┌─────────────────────────────────┐
14//! │ Interfaces (CLI, Python, FUSE) │
15//! └────────────┬────────────────────┘
16//! │
17//! ┌────────────┴────────────┐
18//! │ Operations (this mod) │ High-level workflows
19//! │ - pack: Create archives│
20//! │ - write: Incremental │
21//! └────────────┬────────────┘
22//! │
23//! ┌────────────┴─────────────────────────┐
24//! │ Core Primitives │
25//! │ - format: Headers, indices │
26//! │ - store: Backends (file, S3, HTTP) │
27//! │ - algo: Compression, encryption │
28//! └──────────────────────────────────────┘
29//! ```
30//!
31//! # Available Operations
32//!
33//! ## Archive Creation
34//!
35//! - [`pack`]: Complete archive creation from disk/memory dumps
36//! - Chunking (fixed-size or CDC)
37//! - Compression (LZ4 or Zstandard)
38//! - Deduplication (BLAKE3 based)
39//! - Optional encryption (AES-256-GCM)
40//! - Dictionary training
41//!
42//! ## Incremental Writing
43//!
44//! - [`write`]: Write operations for overlay commits
45//! - Merge overlay deltas with base snapshot
46//! - Support for thin snapshots (reference parent)
47//! - Efficient delta encoding
48//!
49//! # Design Principles
50//!
51//! 1. **Interface Independence**: Operations are pure Rust functions, not CLI-specific
52//! 2. **Composability**: Operations can be chained and reused across interfaces
53//! 3. **Progress Reporting**: All long-running operations support progress callbacks
54//! 4. **Error Handling**: Consistent `Result<T>` returns with descriptive errors
55//!
56//! # Usage from Python
57//!
58//! The operations in this module are exposed to Python via the `hexz_loader` extension:
59//!
60//! ```python
61//! from hexz import pack
62//!
63//! # Create archive from Python
64//! pack(
65//! disk="/path/to/disk.img",
66//! output="snapshot.hxz",
67//! compression="lz4",
68//! encrypt=False
69//! )
70//! ```
71
72pub mod inspect;
73pub mod pack;
74#[cfg(feature = "signing")]
75pub mod sign;
76pub mod snapshot_writer;
77pub mod write;