netconf_async/framer/
async_framer.rs1use 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
10pub const DEFAULT_MAX_MESSAGE_SIZE: usize = 256 * 1024 * 1024;
12
13const MAX_CHUNK_DIGITS: usize = 10;
15
16const READ_CHUNK: usize = 8 * 1024;
17
18pub 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 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 pub fn set_max_message_size(&mut self, limit: usize) {
53 self.max_message_size = limit;
54 }
55
56 pub(crate) fn push_incoming(&mut self, bytes: &[u8]) {
58 self.read_buffer.extend_from_slice(bytes);
59 }
60
61 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 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 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 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 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 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}