Skip to main content

netconf_async/
error.rs

1//! Error type and `Result` alias for the client.
2
3use crate::message;
4use thiserror::Error;
5
6/// `Result` alias used by the public API.
7pub type NetconfClientResult<T> = Result<T, NetconfClientError>;
8
9/// Transport, framing, XML, or NETCONF `<rpc-error>` failure.
10#[derive(Debug, Error)]
11#[non_exhaustive]
12pub enum NetconfClientError {
13    /// I/O failure on the underlying stream.
14    #[error(transparent)]
15    Io(#[from] std::io::Error),
16    /// SSH handshake, auth, or subsystem error.
17    #[cfg(feature = "ssh")]
18    #[cfg_attr(docsrs, doc(cfg(feature = "ssh")))]
19    #[error("{0}")]
20    Ssh(String),
21    /// XML serialize or deserialize failure.
22    #[error("{0}")]
23    SerializingFailure(String),
24    /// Device returned one or more `<rpc-error>` elements.
25    #[error("{operation} failed:\n{reply}")]
26    Netconf {
27        /// RPC local-name that failed (`get-config`, `edit-config`, …).
28        operation: String,
29        /// Parsed `<rpc-reply>`.
30        reply: message::RpcReply,
31    },
32    /// Datastore name was not `running`, `candidate`, `startup`, or a URL.
33    #[error("unknown datastore {}, (expected {:?})", unknown, expected)]
34    UnknownDatastore {
35        /// Datastore names the parser accepts.
36        expected: Vec<String>,
37        /// The name that was supplied.
38        unknown: String,
39    },
40    /// 1.1 chunk header did not match `\n#N\n` / `\n##\n`.
41    #[error(
42        "malformed message chunk (expected {:?}, actual {:?})",
43        expected,
44        actual
45    )]
46    MalformedChunk {
47        /// Byte the framer required at this position.
48        expected: char,
49        /// Byte the device actually sent.
50        actual: char,
51    },
52    /// Reply exceeded the framer's size limit.
53    ///
54    /// Raised for an over-long chunk header as well as for a body that grows
55    /// past the limit. Tune with
56    /// [`AsyncFramer::set_max_message_size`](crate::framer::async_framer::AsyncFramer::set_max_message_size).
57    #[error("message exceeds the configured limit of {limit} bytes")]
58    MessageTooLarge {
59        /// Configured maximum, in bytes.
60        limit: usize,
61    },
62    /// RPC exceeded [`Connection::set_timeout`](crate::connection::Connection::set_timeout).
63    ///
64    /// The reply may still be in flight, so the session is left unusable.
65    #[cfg(feature = "tokio")]
66    #[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
67    #[error("no reply within {}s; session is no longer usable", timeout.as_secs_f32())]
68    Timeout {
69        /// Configured per-RPC timeout.
70        timeout: core::time::Duration,
71    },
72    /// An RPC was attempted after a timeout left the session out of sync.
73    #[error("session is out of sync after an earlier timeout")]
74    SessionDesynchronized,
75    /// Reply `message-id` did not match the request ([RFC6241 4.1](https://www.rfc-editor.org/rfc/rfc6241.html#section-4.1)).
76    ///
77    /// The mismatched message has been consumed, so the real reply may still
78    /// be in flight. The session is left unusable.
79    #[error("rpc-reply message-id mismatch: expected {expected}, got {actual}")]
80    MessageIdMismatch {
81        /// `message-id` sent on the request.
82        expected: String,
83        /// `message-id` on the reply.
84        actual: String,
85    },
86    /// Connection dropped after `<commit>` / `<commit-configuration>` was sent.
87    ///
88    /// The device may already have applied the change. This is not a clean
89    /// I/O error — verify device state before retrying.
90    #[error(
91        "commit status unknown: connection lost after sending <commit>; the device may have committed — verify device state"
92    )]
93    CommitUnknown,
94    /// Server host key was rejected by the configured [`crate::transport::ssh::HostKeyPolicy`].
95    #[cfg(feature = "ssh")]
96    #[cfg_attr(docsrs, doc(cfg(feature = "ssh")))]
97    #[error("SSH host key for {host} rejected ({reason}); server presented {fingerprint}")]
98    HostKeyRejected {
99        /// Host whose key was checked.
100        host: String,
101        /// SHA-256 fingerprint the server presented (`SHA256:…`).
102        fingerprint: String,
103        /// Why the policy rejected it.
104        reason: String,
105    },
106    /// Anything that does not fit the other variants.
107    #[error("{0}")]
108    Other(String),
109}
110
111impl From<quick_xml::DeError> for NetconfClientError {
112    fn from(err: quick_xml::DeError) -> Self {
113        Self::SerializingFailure(err.to_string())
114    }
115}
116
117impl From<quick_xml::SeError> for NetconfClientError {
118    fn from(err: quick_xml::SeError) -> Self {
119        Self::SerializingFailure(err.to_string())
120    }
121}
122
123impl NetconfClientError {
124    /// Wrap an arbitrary message as [`NetconfClientError::Other`].
125    pub fn new(msg: impl Into<String>) -> Self {
126        NetconfClientError::Other(msg.into())
127    }
128
129    /// True when the transport hit EOF mid-read.
130    pub(crate) fn is_unexpected_eof(&self) -> bool {
131        matches!(self, Self::Io(err) if err.kind() == std::io::ErrorKind::UnexpectedEof)
132    }
133}