Skip to main content

netconf_async/framer/
async_framer.rs

1use crate::error::{NetconfClientError, NetconfClientResult};
2use crate::framer::{Framer, NETCONF_1_0_TERMINATOR};
3use async_trait::async_trait;
4use core::fmt;
5use log::{debug, trace};
6use memchr::memmem;
7use std::io;
8use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
9
10/// Default cap on one reply, in bytes.
11pub const DEFAULT_MAX_MESSAGE_SIZE: usize = 256 * 1024 * 1024;
12
13/// A chunk header carries at most 10 digits ([RFC6242 §4.2](https://www.rfc-editor.org/rfc/rfc6242.html#section-4.2)).
14const MAX_CHUNK_DIGITS: usize = 10;
15
16const READ_CHUNK: usize = 8 * 1024;
17
18/// Async 1.0 / 1.1 message framer ([RFC6242 §4](https://www.rfc-editor.org/rfc/rfc6242.html#section-4)).
19pub struct AsyncFramer<T> {
20    read_buffer: Vec<u8>,
21    upgraded: bool,
22    max_message_size: usize,
23
24    channel: T,
25}
26
27impl<T> fmt::Debug for AsyncFramer<T> {
28    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
29        f.debug_struct("AsyncFramer")
30            .field("upgraded", &self.upgraded)
31            .field("max_message_size", &self.max_message_size)
32            .field("buffered", &self.read_buffer.len())
33            .finish_non_exhaustive()
34    }
35}
36
37impl<T: AsyncRead + AsyncWrite + Unpin> AsyncFramer<T> {
38    /// Frame `channel` starting in 1.0 mode (`]]>]]>`).
39    pub fn new(channel: T) -> Self {
40        AsyncFramer {
41            read_buffer: Vec::new(),
42            upgraded: false,
43            max_message_size: DEFAULT_MAX_MESSAGE_SIZE,
44            channel,
45        }
46    }
47
48    /// Cap a single reply at `limit` bytes; defaults to [`DEFAULT_MAX_MESSAGE_SIZE`].
49    ///
50    /// Replies past the limit fail with [`NetconfClientError::MessageTooLarge`]
51    /// instead of growing the read buffer without bound.
52    pub fn set_max_message_size(&mut self, limit: usize) {
53        self.max_message_size = limit;
54    }
55
56    /// Bytes already read from the channel (e.g. before subsystem Success).
57    pub(crate) fn push_incoming(&mut self, bytes: &[u8]) {
58        self.read_buffer.extend_from_slice(bytes);
59    }
60
61    /// Borrow the underlying channel, e.g. to shut it down.
62    pub fn channel_mut(&mut self) -> &mut T {
63        &mut self.channel
64    }
65
66    fn too_large(&self) -> NetconfClientError {
67        NetconfClientError::MessageTooLarge {
68            limit: self.max_message_size,
69        }
70    }
71
72    fn unexpected_eof(msg: &str) -> NetconfClientError {
73        io::Error::new(io::ErrorKind::UnexpectedEof, msg).into()
74    }
75
76    /// Pull `dest.len()` bytes, leftover from a prior 1.0 read first.
77    async fn read_exact_from_incoming(&mut self, dest: &mut [u8]) -> NetconfClientResult<()> {
78        let mut filled = 0;
79        while filled < dest.len() {
80            if self.read_buffer.is_empty() {
81                let mut buf = [0u8; READ_CHUNK];
82                let n = self.channel.read(&mut buf).await?;
83                if n == 0 {
84                    return Err(Self::unexpected_eof(
85                        "connection closed in NETCONF 1.1 chunk",
86                    ));
87                }
88                self.read_buffer.extend_from_slice(&buf[..n]);
89            }
90            let take = (dest.len() - filled).min(self.read_buffer.len());
91            dest[filled..filled + take].copy_from_slice(&self.read_buffer[..take]);
92            self.read_buffer.drain(..take);
93            filled += take;
94        }
95        Ok(())
96    }
97
98    /// Read a `\n#N\n` chunk header, or `0` for the `\n##\n` end marker.
99    async fn read_header(&mut self) -> NetconfClientResult<u32> {
100        let mut buffer = [0u8; 2];
101        self.read_exact_from_incoming(&mut buffer).await?;
102        if buffer[0] != b'\n' {
103            return Err(NetconfClientError::MalformedChunk {
104                expected: '\n',
105                actual: buffer[0].into(),
106            });
107        }
108
109        if buffer[1] != b'#' {
110            return Err(NetconfClientError::MalformedChunk {
111                expected: '#',
112                actual: buffer[1].into(),
113            });
114        }
115
116        let mut chunk_size: u32 = 0;
117        let mut digits = 0usize;
118        loop {
119            let mut buffer = [0u8; 1];
120            self.read_exact_from_incoming(&mut buffer).await?;
121            let last_read = buffer[0];
122            // Second `#` of the `\n##\n` end-of-chunks marker.
123            if last_read == b'#' && digits == 0 {
124                continue;
125            }
126            if last_read == b'\n' {
127                return Ok(chunk_size);
128            }
129            if !last_read.is_ascii_digit() {
130                return Err(NetconfClientError::MalformedChunk {
131                    expected: '0',
132                    actual: last_read.into(),
133                });
134            }
135            digits += 1;
136            if digits > MAX_CHUNK_DIGITS {
137                return Err(self.too_large());
138            }
139            chunk_size = chunk_size
140                .checked_mul(10)
141                .and_then(|size| size.checked_add(u32::from(last_read - b'0')))
142                .ok_or_else(|| self.too_large())?;
143        }
144    }
145
146    async fn read_chunked(&mut self) -> NetconfClientResult<String> {
147        let mut message = Vec::new();
148        loop {
149            let chunk_size = self.read_header().await? as usize;
150            if chunk_size == 0 {
151                break;
152            }
153            if chunk_size > self.max_message_size.saturating_sub(message.len()) {
154                return Err(self.too_large());
155            }
156            let start = message.len();
157            message.resize(start + chunk_size, 0);
158            self.read_exact_from_incoming(&mut message[start..]).await?;
159        }
160        Ok(String::from_utf8_lossy(&message).trim_end().to_string())
161    }
162
163    async fn read_end_of_message(&mut self) -> NetconfClientResult<String> {
164        let terminator = NETCONF_1_0_TERMINATOR.as_bytes();
165        let mut buffer = [0u8; READ_CHUNK];
166        // Bytes already scanned; a terminator can straddle two reads, so keep
167        // the last `terminator.len() - 1` bytes in scope.
168        let mut scanned = 0;
169        loop {
170            if let Some(offset) = memmem::find(&self.read_buffer[scanned..], terminator) {
171                let end = scanned + offset;
172                let response = String::from_utf8_lossy(&self.read_buffer[..end])
173                    .trim_end()
174                    .to_string();
175                self.read_buffer.drain(..end + terminator.len());
176                if !self.read_buffer.is_empty() {
177                    debug!(
178                        "1.0 leftover {} bytes after terminator",
179                        self.read_buffer.len()
180                    );
181                }
182                return Ok(response);
183            }
184            scanned = self.read_buffer.len().saturating_sub(terminator.len() - 1);
185            if self.read_buffer.len() > self.max_message_size {
186                return Err(self.too_large());
187            }
188
189            let bytes = self.channel.read(&mut buffer).await?;
190            if bytes == 0 {
191                return Err(io::Error::new(
192                    io::ErrorKind::UnexpectedEof,
193                    "connection closed before the NETCONF 1.0 message terminator",
194                )
195                .into());
196            }
197            self.read_buffer.extend_from_slice(&buffer[..bytes]);
198        }
199    }
200}
201
202#[async_trait]
203impl<T: AsyncRead + AsyncWrite + Unpin + Send> Framer for AsyncFramer<T> {
204    async fn upgrade(&mut self) {
205        self.upgraded = true;
206    }
207
208    async fn read_async(&mut self) -> NetconfClientResult<String> {
209        let result = if self.upgraded {
210            self.read_chunked().await
211        } else {
212            self.read_end_of_message().await
213        };
214        if result.is_err() {
215            // Buffer holds a partial message the caller can no longer use.
216            self.read_buffer.clear();
217        }
218        result
219    }
220
221    async fn write_async(&mut self, rpc: &str) -> NetconfClientResult<()> {
222        trace!("rpc:\n{}", rpc);
223        let bytes = rpc.as_bytes();
224        if self.upgraded {
225            let header = format!("\n#{}\n", bytes.len());
226            let mut frame = Vec::with_capacity(header.len() + bytes.len() + 4);
227            frame.extend_from_slice(header.as_bytes());
228            frame.extend_from_slice(bytes);
229            frame.extend_from_slice(b"\n##\n");
230            debug!(
231                "1.1 write {} payload bytes (frame {})",
232                bytes.len(),
233                frame.len()
234            );
235            self.channel.write_all(&frame).await?;
236        } else {
237            self.channel.write_all(bytes).await?;
238            self.channel
239                .write_all(NETCONF_1_0_TERMINATOR.as_bytes())
240                .await?;
241        }
242        self.channel.flush().await?;
243        Ok(())
244    }
245}
246
247#[cfg(test)]
248mod tests {
249    use super::*;
250    use pretty_assertions::assert_eq;
251    use std::io::Cursor;
252
253    #[test]
254    fn debug_omits_channel() {
255        let framer = AsyncFramer::new(Cursor::new(Vec::<u8>::new()));
256        let dbg = format!("{framer:?}");
257        assert!(dbg.contains("upgraded: false"), "{dbg}");
258        assert!(dbg.contains("buffered: 0"), "{dbg}");
259    }
260
261    #[tokio::test]
262    async fn test_chunked_framer() {
263        let rpc_error = r#"
264#38
265<?xml version="1.0" encoding="UTF-8"?>
266#1
267
268
269#10
270<rpc-reply
271#50
272 message-id="8ddd59e5-96fc-4a55-a75f-a3fae2d9f712"
273#48
274 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
275#1
276>
277#1
278
279
280#14
281    <rpc-error
282#1
283>
284#1
285
286
287#41
288        <error-type>protocol</error-type>
289#1
290
291
292#42
293        <error-tag>bad-element</error-tag>
294#1
295
296
297#46
298        <error-severity>error</error-severity>
299#1
300
301
302#22
303        <error-message
304#1
305>
306#1
307
308
309#58
310            Element is not valid in the specified context.
311#1
312
313
314#24
315        </error-message>
316#1
317
318
319#19
320        <error-info
321#1
322>
323#1
324
325
326#45
327            <bad-element>startu</bad-element>
328#1
329
330
331#21
332        </error-info>
333#1
334
335
336#16
337    </rpc-error>
338#1
339
340
341#12
342</rpc-reply>
343##
344
345"#
346        .to_string();
347        let channel = Cursor::new(rpc_error.into_bytes());
348        let mut framer = AsyncFramer::new(channel);
349        framer.upgrade().await;
350
351        let resp = framer.read_async().await.unwrap();
352        let expected = r#"
353<?xml version="1.0" encoding="UTF-8"?>
354<rpc-reply message-id="8ddd59e5-96fc-4a55-a75f-a3fae2d9f712" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
355    <rpc-error>
356        <error-type>protocol</error-type>
357        <error-tag>bad-element</error-tag>
358        <error-severity>error</error-severity>
359        <error-message>
360            Element is not valid in the specified context.
361        </error-message>
362        <error-info>
363            <bad-element>startu</bad-element>
364        </error-info>
365    </rpc-error>
366</rpc-reply>
367"#;
368        assert_eq!(resp, expected.trim());
369    }
370
371    #[tokio::test]
372    async fn test_eof_framer() {
373        let rpc_error = r#"
374<?xml version="1.0" encoding="UTF-8"?>
375<rpc-reply message-id="8ddd59e5-96fc-4a55-a75f-a3fae2d9f712" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
376    <rpc-error>
377        <error-type>protocol</error-type>
378        <error-tag>bad-element</error-tag>
379        <error-severity>error</error-severity>
380        <error-message>
381            Element is not valid in the specified context.
382        </error-message>
383        <error-info>
384            <bad-element>startu</bad-element>
385        </error-info>
386    </rpc-error>
387</rpc-reply>
388]]>]]>"#;
389        let channel = Cursor::new(rpc_error.trim().as_bytes().to_vec());
390        let mut framer = AsyncFramer::new(channel);
391        let resp = framer.read_async().await.unwrap();
392        let expected = r#"
393<?xml version="1.0" encoding="UTF-8"?>
394<rpc-reply message-id="8ddd59e5-96fc-4a55-a75f-a3fae2d9f712" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
395    <rpc-error>
396        <error-type>protocol</error-type>
397        <error-tag>bad-element</error-tag>
398        <error-severity>error</error-severity>
399        <error-message>
400            Element is not valid in the specified context.
401        </error-message>
402        <error-info>
403            <bad-element>startu</bad-element>
404        </error-info>
405    </rpc-error>
406</rpc-reply>
407"#;
408        assert_eq!(resp, expected.trim());
409    }
410
411    #[tokio::test]
412    async fn eof_without_terminator_is_an_error() {
413        let channel = Cursor::new(b"<rpc-reply/>".to_vec());
414        let mut framer = AsyncFramer::new(channel);
415        let err = framer.read_async().await.unwrap_err();
416        assert!(
417            matches!(&err, NetconfClientError::Io(io) if io.kind() == io::ErrorKind::UnexpectedEof),
418            "expected UnexpectedEof, got {err:?}"
419        );
420    }
421
422    #[tokio::test]
423    async fn terminator_split_across_reads_is_found() {
424        let (client, mut server) = tokio::io::duplex(64);
425        let writer = tokio::spawn(async move {
426            server.write_all(b"<ok/>]]").await.unwrap();
427            server.write_all(b">]]>rest").await.unwrap();
428        });
429        let mut framer = AsyncFramer::new(client);
430        assert_eq!(framer.read_async().await.unwrap(), "<ok/>");
431        writer.await.unwrap();
432    }
433
434    #[tokio::test]
435    async fn chunk_header_digits_are_bounded() {
436        let channel = Cursor::new(b"\n#99999999999\nx".to_vec());
437        let mut framer = AsyncFramer::new(channel);
438        framer.upgrade().await;
439        assert!(matches!(
440            framer.read_async().await.unwrap_err(),
441            NetconfClientError::MessageTooLarge { .. }
442        ));
443    }
444
445    #[tokio::test]
446    async fn chunk_larger_than_limit_is_rejected() {
447        let channel = Cursor::new(b"\n#4000000000\n".to_vec());
448        let mut framer = AsyncFramer::new(channel);
449        framer.upgrade().await;
450        assert!(matches!(
451            framer.read_async().await.unwrap_err(),
452            NetconfClientError::MessageTooLarge { .. }
453        ));
454    }
455
456    #[tokio::test]
457    async fn garbage_in_chunk_header_is_rejected() {
458        let channel = Cursor::new(b"\n#12#34\nx".to_vec());
459        let mut framer = AsyncFramer::new(channel);
460        framer.upgrade().await;
461        assert!(matches!(
462            framer.read_async().await.unwrap_err(),
463            NetconfClientError::MalformedChunk { .. }
464        ));
465    }
466
467    #[tokio::test]
468    async fn eof_framer_keeps_pipelined_bytes() {
469        let channel = Cursor::new(b"<one/>]]>]]><two/>]]>]]>".to_vec());
470        let mut framer = AsyncFramer::new(channel);
471        assert_eq!(framer.read_async().await.unwrap(), "<one/>");
472        assert_eq!(framer.read_async().await.unwrap(), "<two/>");
473    }
474
475    fn chunked(xml: &str) -> Vec<u8> {
476        let mut out = format!("\n#{}\n", xml.len()).into_bytes();
477        out.extend_from_slice(xml.as_bytes());
478        out.extend_from_slice(b"\n##\n");
479        out
480    }
481
482    #[tokio::test]
483    async fn chunked_read_uses_bytes_left_after_1_0_hello() {
484        let reply =
485            "<rpc-reply xmlns=\"urn:ietf:params:xml:ns:netconf:base:1.0\"><ok/></rpc-reply>";
486        let mut wire = b"<hello/>]]>]]>".to_vec();
487        wire.extend_from_slice(&chunked(reply));
488        let mut framer = AsyncFramer::new(Cursor::new(wire));
489        assert_eq!(framer.read_async().await.unwrap(), "<hello/>");
490        framer.upgrade().await;
491        assert_eq!(framer.read_async().await.unwrap(), reply);
492    }
493}