hexz-common

Common utilities, configuration, and shared types for the Hexz ecosystem.

Overview

hexz-common centralizes configuration loading, error types, logging setup, and format constants that are shared across all Hexz crates (core, CLI, FUSE, server, loader). This ensures a single source of truth for defaults, wire formats, and runtime parameters.

This is an internal crate used by other Hexz components—it's not typically used directly by end users.

Architecture

hexz-common/
├── src/
│   ├── lib.rs          # Public exports
│   ├── config.rs       # Configuration loading and management
│   ├── constants.rs    # Format constants (magic bytes, sizes, versions)
│   ├── error.rs        # Shared error types (Error, Result)
│   ├── logging.rs      # Logging initialization (tracing)
│   ├── crypto.rs       # Cryptographic utilities
│   └── sign.rs         # Ed25519 signing (optional feature)

Key Components

Configuration (config.rs)

Runtime parameter management for Hexz tools:

use hexz_common::Config;

// Load configuration (from env, files, defaults)
let config = Config::load()?;

// Access settings
println!("Cache size: {}", config.cache_size);
println!("Log level: {}", config.log_level);

Constants (constants.rs)

Format constants and wire format definitions:

use hexz_common::constants::*;

// Magic bytes for format identification
assert_eq!(MAGIC, b"HEXZ");

// Header and block sizes
println!("Header size: {} bytes", HEADER_SIZE);
println!("Default block size: {} bytes", DEFAULT_BLOCK_SIZE);

// Format version
println!("Format version: {}", FORMAT_VERSION);

These constants are used across all crates to ensure consistent on-disk layout.

Error Types (error.rs)

Shared error types using thiserror:

use hexz_common::{Result, Error};

fn read_header() -> Result<Vec<u8>> {
    // Returns Result<T> = std::result::Result<T, Error>
    Err(Error::Io(std::io::Error::new(
        std::io::ErrorKind::NotFound,
        "File not found"
    )))
}

Common error variants:

• Io(io::Error) - I/O errors
• Format(String) - Invalid format or corruption
• Compression(String) - Compression/decompression failures
• Encryption(String) - Encryption/decryption failures
• InvalidParameter(String) - Invalid configuration

Logging (logging.rs)

Unified logging setup using tracing:

use hexz_common::logging;

fn main() {
    // Initialize logging with default settings
    logging::init();

    // Now all crates can use tracing macros
    tracing::info!("Application started");
    tracing::debug!("Debug information");
}

Cryptographic Utilities (crypto.rs)

Password-based key derivation parameters:

use hexz_common::crypto;

// Key derivation for encryption
let salt = crypto::generate_salt();
let key = crypto::derive_key(password, &salt)?;

Signing (sign.rs) - Optional Feature

Ed25519 signing for snapshot integrity (requires signing feature):

use hexz_common::sign::{Keypair, sign, verify};

// Generate keypair
let keypair = Keypair::generate();

// Sign data
let signature = sign(&keypair, b"snapshot data");

// Verify signature
verify(&keypair.public, b"snapshot data", &signature)?;

Usage in Other Crates

Core Library

use hexz_common::{Result, Error};
use hexz_common::constants::*;

fn validate_header(magic: &[u8]) -> Result<()> {
    if magic != MAGIC {
        return Err(Error::Format(
            "Invalid magic bytes".to_string()
        ));
    }
    Ok(())
}

CLI Tool

use hexz_common::{Config, logging};

fn main() -> anyhow::Result<()> {
    // Initialize logging
    logging::init();

    // Load configuration
    let config = Config::load()?;

    // Use shared error types
    let result = operation();
    match result {
        Ok(data) => println!("Success"),
        Err(e) => eprintln!("Error: {}", e),
    }

    Ok(())
}

Features

• default: No features enabled by default
• signing: Enable Ed25519 signing support

Build with signing:

cargo build -p hexz-common --features signing

Development

From the repository root:

# Build the common crate
cargo build -p hexz-common

# Run tests
cargo test -p hexz-common

# Build with all features
cargo build -p hexz-common --all-features

Constants Reference

Key constants defined in constants.rs:

These values affect on-disk format and must be coordinated across all crates.

See Also

• hexz-core - Core engine (uses common types)
• hexz-cli - CLI tool (uses config and logging)
• Project README - Main project overview