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}