ap_proxy_protocol/
error.rs

1//! Error types for proxy operations.
2//!
3//! This module defines all error conditions that can occur during proxy client
4//! and server operations.
5
6use crate::auth::IdentityFingerprint;
7use thiserror::Error;
8
9/// Errors that can occur during proxy client or server operations.
10#[derive(Debug, Error)]
11pub enum ProxyError {
12    /// WebSocket connection or communication error.
13    ///
14    /// Occurs when the underlying WebSocket connection fails, including network
15    /// errors, protocol violations, or connection drops.
16    ///
17    /// # Example
18    /// ```text
19    /// WebSocket error: Connection refused (os error 61)
20    /// ```
21    #[error("WebSocket error: {0}")]
22    WebSocket(String),
23
24    /// Client authentication failed.
25    ///
26    /// Occurs when:
27    /// - The client's signature verification fails
28    /// - The challenge response is invalid
29    /// - The authentication handshake times out
30    ///
31    /// # Example
32    /// ```text
33    /// Authentication failed: Invalid signature
34    /// ```
35    #[error("Authentication failed: {0}")]
36    AuthenticationFailed(String),
37
38    /// Attempted to send a message to a client that is not connected.
39    ///
40    /// Occurs when sending a message to a fingerprint that:
41    /// - Never connected to the proxy
42    /// - Has disconnected
43    /// - Does not exist
44    ///
45    /// # Example
46    /// ```text
47    /// Destination not found: IdentityFingerprint("abc123...")
48    /// ```
49    #[error("Destination not found: {0:?}")]
50    DestinationNotFound(IdentityFingerprint),
51
52    /// Failed to serialize or deserialize a message.
53    ///
54    /// Occurs when JSON encoding/decoding fails, usually due to:
55    /// - Corrupted message data
56    /// - Protocol version mismatch
57    /// - Invalid message format
58    #[error("Message serialization error: {0}")]
59    Serialization(#[from] serde_json::Error),
60
61    /// The WebSocket connection has been closed.
62    ///
63    /// Occurs when attempting operations on a closed connection, either due to:
64    /// - Normal disconnection
65    /// - Network failure
66    /// - Server shutdown
67    #[error("Connection closed")]
68    ConnectionClosed,
69
70    /// Received a message that violates the protocol.
71    ///
72    /// Occurs when:
73    /// - A message is received in the wrong protocol phase
74    /// - Required authentication is missing
75    /// - Message format is invalid
76    ///
77    /// # Example
78    /// ```text
79    /// Invalid message: Cannot send messages before authentication
80    /// ```
81    #[error("Invalid message: {0}")]
82    InvalidMessage(String),
83
84    /// Underlying I/O operation failed.
85    ///
86    /// Occurs during file operations, socket operations, or other I/O tasks.
87    #[error("IO error: {0}")]
88    Io(#[from] std::io::Error),
89
90    /// Attempted an operation that requires an active connection.
91    ///
92    /// Occurs when calling methods like `send_to()` before calling `connect()`.
93    #[error("Not connected")]
94    NotConnected,
95
96    /// Attempted to connect when already connected.
97    ///
98    /// Occurs when calling `connect()` multiple times without disconnecting.
99    #[error("Already connected")]
100    AlreadyConnected,
101
102    /// Authentication handshake did not complete within the timeout period.
103    ///
104    /// Occurs when the client fails to respond to the authentication challenge
105    /// in time. Default timeout is implementation-defined.
106    #[error("Authentication timeout")]
107    AuthenticationTimeout,
108
109    /// Failed to send a message through an internal channel.
110    ///
111    /// Occurs when internal message passing fails, usually because:
112    /// - The receiving end has been dropped
113    /// - The channel is closed
114    ///
115    /// This typically indicates a programming error or resource cleanup issue.
116    #[error("Channel send failed")]
117    ChannelSendFailed,
118}
ap_proxy_protocol/error.rs

ap_proxy_protocol/
error.rs
