Skip to main content

bornera_core/framing/
driver.rs

1//! Retained-byte enforcement around one protocol-owned decoder.
2
3use core::fmt;
4
5use calandria::RetainedBytes;
6
7use super::{FrameDecodeError, FrameDecoder};
8
9/// Bounded, terminal-on-malformation driver for one incremental decoder.
10pub struct FrameDriver<D> {
11    decoder: D,
12    max_retained_bytes: RetainedBytes,
13    failed: bool,
14}
15
16impl<D: FrameDecoder> FrameDriver<D> {
17    /// Wraps a decoder if its initial retained memory is within the bound.
18    pub fn new(
19        decoder: D,
20        max_retained_bytes: RetainedBytes,
21    ) -> Result<Self, FrameDecodeError<D::Error>> {
22        let retained = decoder.retained_bytes();
23        if retained > max_retained_bytes {
24            return Err(FrameDecodeError::RetainedContractViolation {
25                retained,
26                limit: max_retained_bytes,
27            });
28        }
29        Ok(Self {
30            decoder,
31            max_retained_bytes,
32            failed: false,
33        })
34    }
35
36    /// Admits a borrowed byte chunk or leaves it entirely with the caller.
37    pub fn feed(&mut self, bytes: &[u8]) -> Result<(), FrameDecodeError<D::Error>> {
38        if self.failed {
39            return Err(FrameDecodeError::DecoderFailed);
40        }
41        let incoming = RetainedBytes::try_from(bytes.len())
42            .map_err(|_| FrameDecodeError::InputSizeOverflow)?;
43        let retained = self.decoder.retained_bytes();
44        let Some(accepted) = retained.checked_add(incoming) else {
45            return Err(FrameDecodeError::RetainedByteCapacity {
46                retained,
47                incoming: bytes.len(),
48                limit: self.max_retained_bytes,
49            });
50        };
51        if accepted > self.max_retained_bytes {
52            return Err(FrameDecodeError::RetainedByteCapacity {
53                retained,
54                incoming: bytes.len(),
55                limit: self.max_retained_bytes,
56            });
57        }
58        if let Err(error) = self.decoder.feed(bytes) {
59            self.failed = true;
60            return Err(FrameDecodeError::Decoder(error));
61        }
62        self.validate_retained()
63    }
64
65    /// Extracts at most one complete opaque frame.
66    pub fn next_frame(&mut self) -> Result<Option<D::Frame>, FrameDecodeError<D::Error>> {
67        if self.failed {
68            return Err(FrameDecodeError::DecoderFailed);
69        }
70        let frame = match self.decoder.next_frame() {
71            Ok(frame) => frame,
72            Err(error) => {
73                self.failed = true;
74                return Err(FrameDecodeError::Decoder(error));
75            }
76        };
77        self.validate_retained()?;
78        Ok(frame)
79    }
80
81    /// Returns variable memory retained by the adapter decoder.
82    pub fn retained_bytes(&self) -> RetainedBytes {
83        self.decoder.retained_bytes()
84    }
85
86    /// Returns whether a terminal adapter or accounting failure occurred.
87    pub const fn is_failed(&self) -> bool {
88        self.failed
89    }
90
91    /// Recovers the protocol-owned decoder.
92    pub fn into_decoder(self) -> D {
93        self.decoder
94    }
95
96    fn validate_retained(&mut self) -> Result<(), FrameDecodeError<D::Error>> {
97        let retained = self.decoder.retained_bytes();
98        if retained > self.max_retained_bytes {
99            self.failed = true;
100            return Err(FrameDecodeError::RetainedContractViolation {
101                retained,
102                limit: self.max_retained_bytes,
103            });
104        }
105        Ok(())
106    }
107}
108
109impl<D: FrameDecoder> fmt::Debug for FrameDriver<D> {
110    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
111        formatter
112            .debug_struct("FrameDriver")
113            .field("max_retained_bytes", &self.max_retained_bytes)
114            .field("retained_bytes", &self.decoder.retained_bytes())
115            .field("failed", &self.failed)
116            .finish_non_exhaustive()
117    }
118}