nautilus_network/
error.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Network error types.
17
18use std::{fmt::Display, io};
19
20use thiserror::Error;
21
22/// Error type for send operations in network clients.
23#[derive(Clone, Error, Debug)]
24pub enum SendError {
25    /// The send input is invalid.
26    #[error("send failed: invalid input ({0})")]
27    InvalidInput(String),
28    /// The writer has reached the message limit for this send.
29    #[error("send failed: writer buffer full")]
30    BufferFull,
31    /// The client has been closed or is disconnecting.
32    #[error("send failed: client closed or disconnecting")]
33    Closed,
34    /// Timed out waiting for the client to become active.
35    #[error("send failed: timeout waiting for active state")]
36    Timeout,
37    /// Timed out while writing to the transport, so delivery is undetermined.
38    ///
39    /// Unlike [`SendError::Timeout`], which reports that a send never started, the write was
40    /// cancelled after it began: the peer may or may not have received the message. Callers must
41    /// not treat this as a plain retry.
42    #[error("send failed: timed out writing to transport, delivery undetermined")]
43    WriteTimeout,
44    /// The connection changed before an ownership-bound message reached the writer.
45    #[error("send failed: connection changed before write")]
46    ConnectionChanged,
47    /// Failed to send because the writer channel is closed.
48    #[error("send failed: broken pipe ({0})")]
49    BrokenPipe(String),
50}
51
52/// Result type for client configuration validation.
53pub type NetworkConfigResult<T> = Result<T, NetworkConfigError>;
54
55/// A validation error for a network client configuration.
56#[derive(Debug, Clone, PartialEq, Eq)]
57pub enum NetworkConfigError {
58    /// A field value is empty or outside its accepted range.
59    Invalid { field: String, reason: String },
60    /// Multiple validation errors were collected.
61    Multiple { errors: Vec<Self> },
62}
63
64impl NetworkConfigError {
65    /// Creates a [`NetworkConfigError::Invalid`] for `field` with the given `reason`.
66    pub fn invalid(field: impl Into<String>, reason: impl Into<String>) -> Self {
67        Self::Invalid {
68            field: field.into(),
69            reason: reason.into(),
70        }
71    }
72
73    /// Converts collected errors into a single result.
74    ///
75    /// Returns `Ok(())` when `errors` is empty, the sole error when one was collected, or a
76    /// [`NetworkConfigError::Multiple`] otherwise.
77    pub(crate) fn collect(mut errors: Vec<Self>) -> NetworkConfigResult<()> {
78        match errors.len() {
79            0 => Ok(()),
80            1 => Err(errors.remove(0)),
81            _ => Err(Self::Multiple { errors }),
82        }
83    }
84}
85
86impl Display for NetworkConfigError {
87    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
88        match self {
89            Self::Invalid { field, reason } => write!(f, "invalid {field}: {reason}"),
90            Self::Multiple { errors } => {
91                for (index, error) in errors.iter().enumerate() {
92                    if index > 0 {
93                        write!(f, "; ")?;
94                    }
95
96                    write!(f, "{error}")?;
97                }
98
99                Ok(())
100            }
101        }
102    }
103}
104
105impl std::error::Error for NetworkConfigError {}
106
107pub(crate) fn is_connection_drop_io_error(err: &io::Error) -> bool {
108    matches!(
109        err.kind(),
110        io::ErrorKind::BrokenPipe
111            | io::ErrorKind::ConnectionAborted
112            | io::ErrorKind::ConnectionReset
113            | io::ErrorKind::NotConnected
114            | io::ErrorKind::TimedOut
115            | io::ErrorKind::UnexpectedEof
116    )
117}
118
119#[cfg(test)]
120mod tests {
121    use rstest::rstest;
122
123    use super::*;
124
125    #[rstest]
126    #[case(io::ErrorKind::BrokenPipe, true)]
127    #[case(io::ErrorKind::ConnectionAborted, true)]
128    #[case(io::ErrorKind::ConnectionReset, true)]
129    #[case(io::ErrorKind::NotConnected, true)]
130    #[case(io::ErrorKind::TimedOut, true)]
131    #[case(io::ErrorKind::UnexpectedEof, true)]
132    #[case(io::ErrorKind::InvalidInput, false)]
133    #[case(io::ErrorKind::PermissionDenied, false)]
134    fn connection_drop_io_error_classification(
135        #[case] kind: io::ErrorKind,
136        #[case] expected: bool,
137    ) {
138        let err = io::Error::from(kind);
139
140        assert_eq!(is_connection_drop_io_error(&err), expected);
141    }
142
143    #[rstest]
144    fn test_invalid_display() {
145        let err = NetworkConfigError::invalid("url", "must not be empty");
146
147        assert_eq!(err.to_string(), "invalid url: must not be empty");
148    }
149
150    #[rstest]
151    fn test_multiple_display_joins_errors() {
152        let err = NetworkConfigError::Multiple {
153            errors: vec![
154                NetworkConfigError::invalid("url", "must not be empty"),
155                NetworkConfigError::invalid("idle_timeout_ms", "must be positive, was 0"),
156            ],
157        };
158
159        assert_eq!(
160            err.to_string(),
161            "invalid url: must not be empty; invalid idle_timeout_ms: must be positive, was 0"
162        );
163    }
164
165    #[rstest]
166    fn test_collect_returns_bare_error_for_single() {
167        let errors = vec![NetworkConfigError::invalid("url", "must not be empty")];
168
169        let result = NetworkConfigError::collect(errors);
170
171        assert!(matches!(result, Err(NetworkConfigError::Invalid { field, .. }) if field == "url"));
172    }
173}
nautilus_network/error.rs

nautilus_network/
error.rs
