clavis 0.1.1-rc7

High-performance async network encryption library featuring XChaCha20-Poly1305, type-safe protocol DSL, and zero-copy packet streaming for secure communication channels
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

use std::fmt;
use thiserror::Error;

/// Represents the type of a cryptographic operation that failed
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CryptoOperation {
    Authentication,
    Encryption,
    Decryption,
    KeyExchange,
    Handshake,
}

impl fmt::Display for CryptoOperation {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            CryptoOperation::Authentication => write!(f, "authentication"),
            CryptoOperation::Encryption => write!(f, "encryption"),
            CryptoOperation::Decryption => write!(f, "decryption"),
            CryptoOperation::KeyExchange => write!(f, "key exchange"),
            CryptoOperation::Handshake => write!(f, "handshake"),
        }
    }
}

/// Represents cryptographic errors
#[derive(Debug, Error)]
pub enum CryptoError {
    #[error("Cryptographic operation failed during {operation}: {details}")]
    OperationFailure {
        operation: CryptoOperation,
        details: String,
    },

    #[error("Authentication failed: {0}")]
    AuthenticationFailure(String),

    #[error("Invalid key material: {0}")]
    InvalidKeyMaterial(String),

    #[error("Key derivation failed: {0}")]
    KeyDerivationFailure(String),
}

/// Represents message format and processing errors
#[derive(Debug, Error)]
pub enum MessageError {
    #[error("Message size {size} exceeds maximum allowed size of {max_size}")]
    MessageTooLarge { size: usize, max_size: usize },

    #[error("Message serialization failed: {0}")]
    SerializationFailed(String),

    #[error("Message deserialization failed: {0}")]
    DeserializationFailed(String),

    #[error("Invalid message format: {0}")]
    InvalidFormat(String),
}

/// Represents stream operation errors
#[derive(Debug, Error)]
pub enum StreamError {
    #[error("Invalid stream operation: {0}")]
    InvalidOperation(String),

    #[error("Stream closed unexpectedly")]
    UnexpectedClose,

    #[error("Stream timeout after {timeout_ms}ms")]
    Timeout { timeout_ms: u64 },

    #[error(transparent)]
    Io(#[from] std::io::Error),
}

/// Main error type for the Clavis library
#[derive(Debug, Error)]
pub enum ClavisError {
    #[error(transparent)]
    Crypto(#[from] CryptoError),

    #[error(transparent)]
    Message(#[from] MessageError),

    #[error(transparent)]
    Stream(#[from] StreamError),

    #[error("Configuration error: {0}")]
    Config(String),

    #[error(transparent)]
    Other(#[from] anyhow::Error),
}

impl ClavisError {
    /// Returns true if the error is related to cryptographic operations
    pub fn is_crypto_error(&self) -> bool {
        matches!(self, ClavisError::Crypto(_))
    }

    /// Returns true if the error is related to message processing
    pub fn is_message_error(&self) -> bool {
        matches!(self, ClavisError::Message(_))
    }

    /// Returns true if the error is related to stream operations
    pub fn is_stream_error(&self) -> bool {
        matches!(self, ClavisError::Stream(_))
    }

    /// Returns true if the error might be resolved by retrying the operation
    pub fn is_retriable(&self) -> bool {
        match self {
            ClavisError::Stream(StreamError::Timeout { .. }) => true,
            ClavisError::Stream(StreamError::Io(e)) => {
                e.kind() == std::io::ErrorKind::WouldBlock
                    || e.kind() == std::io::ErrorKind::TimedOut
                    || e.kind() == std::io::ErrorKind::Interrupted
            }
            _ => false,
        }
    }

    /// Creates a new cryptographic error for a failed operation
    pub fn crypto_failure(operation: CryptoOperation, details: impl Into<String>) -> Self {
        ClavisError::Crypto(CryptoError::OperationFailure {
            operation,
            details: details.into(),
        })
    }

    /// Creates a new error for message serialization failures
    pub fn serialization_failed(details: impl Into<String>) -> Self {
        ClavisError::Message(MessageError::SerializationFailed(details.into()))
    }

    /// Creates a new error for message deserialization failures
    pub fn deserialization_failed(details: impl Into<String>) -> Self {
        ClavisError::Message(MessageError::DeserializationFailed(details.into()))
    }

    /// Creates a new error for invalid stream operations
    pub fn invalid_operation(details: impl Into<String>) -> Self {
        ClavisError::Stream(StreamError::InvalidOperation(details.into()))
    }
}

/// Type alias for Result with ClavisError as the error type
pub type ClavisResult<T> = std::result::Result<T, ClavisError>;