hexz_common/
error.rs

1//! Unified error type and result alias for Hexz.
2//!
3//! Defines `Error` and the crate-wide `Result<T>` alias so that all
4//! library and CLI code can report I/O, format, compression, and
5//! encryption failures through a single type.
6
7use thiserror::Error;
8
9/// Unified error type for all Hexz library and CLI operations.
10///
11/// **Architectural intent:** Provides a single error surface that callers can
12/// use for I/O, format, compression, encryption, and feature-negotiation
13/// failures, enabling consistent reporting across crates.
14///
15/// **Constraints:** Variants must remain serializable as user-facing strings
16/// and stable enough for log analysis; binary compatibility is not guaranteed
17/// across releases.
18///
19/// **Side effects:** Many variants wrap underlying error types; formatting the
20/// error may allocate and may expose details from lower layers that should not
21/// be relied upon for programmatic decisions.
22#[derive(Error, Debug)]
23pub enum Error {
24    /// Underlying I/O failure (file, network, or OS-level).
25    #[error("IO Error: {0}")]
26    Io(#[from] std::io::Error),
27
28    /// Binary serialization/deserialization failure (bincode layer).
29    #[error("Serialization Error: {0}")]
30    Serialization(#[from] bincode::Error),
31
32    /// Compression or decompression failure.
33    #[error("Compression Error: {0}")]
34    Compression(String),
35
36    /// Encryption or decryption failure (wrong key, corrupted ciphertext).
37    #[error("Encryption Error: {0}")]
38    Encryption(String),
39
40    /// Integrity check failure — stored checksum does not match computed value.
41    #[error("Corrupted Data: Checksum mismatch at block {0}")]
42    Corruption(u64),
43
44    /// Archive format violation (bad magic, unsupported version, truncation).
45    #[error("Invalid Format: {0}")]
46    Format(String),
47
48    /// Block index exceeds the archive's block count.
49    #[error("Block index {0} out of bounds")]
50    OutOfBounds(u64),
51
52    /// Requested feature requires a build flag or version that is not present.
53    #[error("Feature Not Supported: {0}")]
54    NotSupported(String),
55}
56
57/// Convenience result alias for functions that can fail with `Error`.
58///
59/// **Architectural intent:** Standardizes the error channel across the
60/// codebase so APIs clearly communicate that failures are domain-specific
61/// Hexz errors rather than arbitrary `std` errors.
62///
63/// **Constraints:** Callers should treat `Error` as opaque and avoid
64/// depending on the exact display text; matching on variants is preferred for
65/// structured handling.
66///
67/// **Side effects:** No additional side effects beyond those of the underlying
68/// operation whose result is being wrapped.
69pub type Result<T> = std::result::Result<T, Error>;
hexz_common/error.rs

hexz_common/
error.rs
