hexz_common/
constants.rs

1//! Shared constants for the Hexz ecosystem.
2//!
3//! Tunable parameters governing performance, memory usage, and security.
4//! Magic bytes, format version, and header size live in `hexz-core::format::magic`.
5
6/// Default block size for snapshot compression (64 KiB).
7///
8/// Balances compression ratio, read amplification, and cache efficiency.
9/// Smaller values (16-32 KiB) reduce read amplification for random I/O;
10/// larger values (128-256 KiB) improve compression ratio and sequential throughput.
11pub const DEFAULT_BLOCK_SIZE: u32 = 65536;
12
13/// Default Zstd compression level.
14///
15/// Level 3 provides ~200 MB/s compression with good ratios (~2.5-3.5x on typical data).
16/// Decompression speed is ~600+ MB/s regardless of level.
17pub const DEFAULT_ZSTD_LEVEL: i32 = 3;
18
19/// Salt size for PBKDF2 key derivation (128 bits).
20///
21/// Per NIST SP 800-132, 128 bits provides sufficient collision resistance.
22pub const SALT_SIZE: usize = 16;
23
24/// PBKDF2 iteration count for password-based key derivation.
25///
26/// 600,000 iterations per OWASP 2023 guidelines for PBKDF2-HMAC-SHA256.
27/// Yields ~200-500ms key derivation on modern hardware.
28pub const PBKDF2_ITERATIONS: u32 = 600_000;
29
30/// Default block cache size (512 MiB).
31///
32/// Stores decompressed blocks in an LRU cache to avoid repeated decompression.
33/// With 64 KiB blocks this holds ~8,192 blocks.
34pub const DEFAULT_CACHE_SIZE: usize = 512 * 1024 * 1024;
35
36/// Default number of blocks to prefetch ahead for sequential access patterns.
37pub const DEFAULT_PREFETCH_COUNT: u32 = 4;
38
39/// Default network timeout in seconds for HTTP/S3 backends.
40pub const DEFAULT_NETWORK_TIMEOUT: u64 = 30;
41
42/// AES-256 key length in bytes (256 bits).
43pub const AES_KEY_LENGTH: usize = 32;
44
45/// AES-GCM nonce length in bytes (96 bits).
46///
47/// Per NIST SP 800-38D, 96-bit nonces are recommended for AES-GCM.
48/// Each block uses a deterministic nonce derived from the block index.
49pub const AES_NONCE_LENGTH: usize = 12;
50
51/// Shannon entropy threshold for dictionary training eligibility.
52///
53/// Blocks with entropy above this value (near-random data) are excluded from
54/// dictionary training since they won't benefit from it.
55pub const ENTROPY_THRESHOLD: f64 = 6.0;
56
57/// Number of sample blocks for Zstd dictionary training.
58pub const DICT_TRAINING_SAMPLE_COUNT: usize = 4000;
59
60/// Maximum dictionary size for Zstd training (110 KiB).
61///
62/// Fits in L2 cache during decompression. Zstd's recommended max is 112 KiB.
63pub const DICT_TRAINING_SIZE: usize = 110 * 1024;
64
65/// Sentinel offset indicating a block is stored in the parent snapshot.
66pub const BLOCK_OFFSET_PARENT: u64 = u64::MAX;
67
68/// Default minimum chunk size for content-defined chunking (16 KiB).
69pub const DEFAULT_CDC_MIN_CHUNK: u32 = 16384;
70
71/// Default average chunk size for content-defined chunking (64 KiB).
72pub const DEFAULT_CDC_AVG_CHUNK: u32 = 65536;
73
74/// Default maximum chunk size for content-defined chunking (128 KiB).
75pub const DEFAULT_CDC_MAX_CHUNK: u32 = 131072;
76
77/// Overlay block granularity (4 KiB).
78///
79/// Matches standard filesystem block size for copy-on-write compatibility.
80pub const OVERLAY_BLOCK_SIZE: u64 = 4096;
81
82/// Size of a single overlay metadata entry in bytes (`u64` block index).
83pub const META_ENTRY_SIZE: usize = 8;
hexz_common/constants.rs

hexz_common/
constants.rs
