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(Error, Debug)]
24pub enum SendError {
25    /// The send input is invalid.
26    #[error("send failed: invalid input ({0})")]
27    InvalidInput(String),
28    /// The client has been closed or is disconnecting.
29    #[error("send failed: client closed or disconnecting")]
30    Closed,
31    /// Timed out waiting for the client to become active.
32    #[error("send failed: timeout waiting for active state")]
33    Timeout,
34    /// Timed out while writing to the transport, so delivery is undetermined.
35    ///
36    /// Unlike [`SendError::Timeout`], which reports that a send never started, the write was
37    /// cancelled after it began: the peer may or may not have received the message. Callers must
38    /// not treat this as a plain retry.
39    #[error("send failed: timed out writing to transport, delivery undetermined")]
40    WriteTimeout,
41    /// The connection changed before an ownership-bound message reached the writer.
42    #[error("send failed: connection changed before write")]
43    ConnectionChanged,
44    /// Failed to send because the writer channel is closed.
45    #[error("send failed: broken pipe ({0})")]
46    BrokenPipe(String),
47}
48
49/// Result type for client configuration validation.
50pub type NetworkConfigResult<T> = Result<T, NetworkConfigError>;
51
52/// A validation error for a network client configuration.
53#[derive(Debug, Clone, PartialEq, Eq)]
54pub enum NetworkConfigError {
55    /// A field value is empty or outside its accepted range.
56    Invalid { field: String, reason: String },
57    /// Multiple validation errors were collected.
58    Multiple { errors: Vec<Self> },
59}
60
61impl NetworkConfigError {
62    /// Creates a [`NetworkConfigError::Invalid`] for `field` with the given `reason`.
63    pub fn invalid(field: impl Into<String>, reason: impl Into<String>) -> Self {
64        Self::Invalid {
65            field: field.into(),
66            reason: reason.into(),
67        }
68    }
69
70    /// Converts collected errors into a single result.
71    ///
72    /// Returns `Ok(())` when `errors` is empty, the sole error when one was collected, or a
73    /// [`NetworkConfigError::Multiple`] otherwise.
74    pub(crate) fn collect(mut errors: Vec<Self>) -> NetworkConfigResult<()> {
75        match errors.len() {
76            0 => Ok(()),
77            1 => Err(errors.remove(0)),
78            _ => Err(Self::Multiple { errors }),
79        }
80    }
81}
82
83impl Display for NetworkConfigError {
84    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
85        match self {
86            Self::Invalid { field, reason } => write!(f, "invalid {field}: {reason}"),
87            Self::Multiple { errors } => {
88                for (index, error) in errors.iter().enumerate() {
89                    if index > 0 {
90                        write!(f, "; ")?;
91                    }
92                    write!(f, "{error}")?;
93                }
94                Ok(())
95            }
96        }
97    }
98}
99
100impl std::error::Error for NetworkConfigError {}
101
102pub(crate) fn is_connection_drop_io_error(err: &io::Error) -> bool {
103    matches!(
104        err.kind(),
105        io::ErrorKind::BrokenPipe
106            | io::ErrorKind::ConnectionAborted
107            | io::ErrorKind::ConnectionReset
108            | io::ErrorKind::NotConnected
109            | io::ErrorKind::TimedOut
110            | io::ErrorKind::UnexpectedEof
111    )
112}
113
114#[cfg(test)]
115mod tests {
116    use rstest::rstest;
117
118    use super::*;
119
120    #[rstest]
121    #[case(io::ErrorKind::BrokenPipe, true)]
122    #[case(io::ErrorKind::ConnectionAborted, true)]
123    #[case(io::ErrorKind::ConnectionReset, true)]
124    #[case(io::ErrorKind::NotConnected, true)]
125    #[case(io::ErrorKind::TimedOut, true)]
126    #[case(io::ErrorKind::UnexpectedEof, true)]
127    #[case(io::ErrorKind::InvalidInput, false)]
128    #[case(io::ErrorKind::PermissionDenied, false)]
129    fn connection_drop_io_error_classification(
130        #[case] kind: io::ErrorKind,
131        #[case] expected: bool,
132    ) {
133        let err = io::Error::from(kind);
134
135        assert_eq!(is_connection_drop_io_error(&err), expected);
136    }
137
138    #[rstest]
139    fn test_invalid_display() {
140        let err = NetworkConfigError::invalid("url", "must not be empty");
141
142        assert_eq!(err.to_string(), "invalid url: must not be empty");
143    }
144
145    #[rstest]
146    fn test_multiple_display_joins_errors() {
147        let err = NetworkConfigError::Multiple {
148            errors: vec![
149                NetworkConfigError::invalid("url", "must not be empty"),
150                NetworkConfigError::invalid("idle_timeout_ms", "must be positive, was 0"),
151            ],
152        };
153
154        assert_eq!(
155            err.to_string(),
156            "invalid url: must not be empty; invalid idle_timeout_ms: must be positive, was 0"
157        );
158    }
159
160    #[rstest]
161    fn test_collect_returns_bare_error_for_single() {
162        let errors = vec![NetworkConfigError::invalid("url", "must not be empty")];
163
164        let result = NetworkConfigError::collect(errors);
165
166        assert!(matches!(result, Err(NetworkConfigError::Invalid { field, .. }) if field == "url"));
167    }
168}
nautilus_network/error.rs

nautilus_network/
error.rs
