bibeam_core/error.rs
1#![forbid(unsafe_code)]
2//! Top-level error type for the `BiBeam` core crate.
3//!
4//! [`enum@Error`] groups failures by class — config / crypto / transport /
5//! protocol / storage / geoip / io — so downstream callers can match on the
6//! cause without needing to know the precise sub-error type. Each variant
7//! carries a human-readable string except [`Error::Io`], which re-wraps
8//! [`std::io::Error`] losslessly via `#[from]`.
9
10use thiserror::Error;
11
12/// Class-tagged error type for the core crate.
13///
14/// Higher layers convert their own error types into one of these classes
15/// (typically `Crypto`, `Protocol`, or `Transport`) so the surface presented
16/// to applications stays compact.
17#[derive(Debug, Error)]
18pub enum Error {
19 /// Configuration could not be loaded, validated, or applied.
20 #[error("config error: {0}")]
21 Config(String),
22 /// A cryptographic primitive or handshake failed.
23 #[error("crypto error: {0}")]
24 Crypto(String),
25 /// A transport-layer failure (WireGuard/UDP, TCP).
26 #[error("transport error: {0}")]
27 Transport(String),
28 /// A protocol-layer violation or unexpected message.
29 #[error("protocol error: {0}")]
30 Protocol(String),
31 /// Persistent storage failed (read, write, schema, etc.).
32 #[error("storage error: {0}")]
33 Storage(String),
34 /// `GeoIP` DB open / parse / lookup failed (R-REGION.2 / D-5).
35 ///
36 /// Surfaces failures from the operator-supplied
37 /// `GeoLite2-Country` `.mmdb` file — both file-open / I/O errors
38 /// and structural (`InvalidDatabase` / `Decoding`) errors fold
39 /// into the same `String` form so downstream callers can match
40 /// on the variant without depending on the upstream `maxminddb`
41 /// crate. Per D-5, the cross-check is warn-only at MVP —
42 /// callers convert this error class into an audit-log entry
43 /// rather than refusing admission.
44 #[error("geoip error: {0}")]
45 Geoip(String),
46 /// An underlying [`std::io::Error`] propagated unchanged.
47 #[error("io error: {0}")]
48 Io(#[from] std::io::Error),
49}