Skip to main content

protocol/
framing.rs

1//! Length-prefixed framing: each payload is preceded by its unsigned 32-bit big-endian length.
2
3use std::fmt;
4
5/// Default upper bound for one framed CBOR payload.
6pub const DEFAULT_MAX_FRAME_LENGTH: usize = 16 * 1024 * 1024;
7
8/// Upper bound for one server message on the local socket. A session's transcript snapshot travels in one
9/// subscribe response, and a long session's runs past 16 MiB (a 186 MB journal held 19 MB of transcript).
10// ponytail: one bigger frame, not a paged snapshot; the client holds the whole transcript in memory either way.
11// Page it when a snapshot nears this bound.
12pub const MAX_SERVER_FRAME_LENGTH: usize = 256 * 1024 * 1024;
13
14#[derive(Debug, Clone, PartialEq, Eq)]
15pub struct FrameError(pub String);
16
17impl fmt::Display for FrameError {
18    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
19        f.write_str(&self.0)
20    }
21}
22
23impl std::error::Error for FrameError {}
24
25pub fn encode_frame(payload: &[u8]) -> Result<Vec<u8>, FrameError> {
26    let Ok(length) = u32::try_from(payload.len()) else {
27        return Err(FrameError(
28            "Frame payload exceeds the unsigned 32-bit length limit".into(),
29        ));
30    };
31    let mut frame = Vec::with_capacity(4 + payload.len());
32    frame.extend_from_slice(&length.to_be_bytes());
33    frame.extend_from_slice(payload);
34    Ok(frame)
35}
36
37#[derive(Debug, Clone, Copy, PartialEq, Eq)]
38enum State {
39    Open,
40    Ended,
41    Failed,
42}
43
44#[derive(Debug)]
45pub struct FrameDecoder {
46    header: Vec<u8>,
47    payload: Vec<u8>,
48    expected: Option<usize>,
49    max_frame_length: usize,
50    state: State,
51}
52
53impl FrameDecoder {
54    pub fn new(max_frame_length: usize) -> Result<Self, FrameError> {
55        if max_frame_length > u32::MAX as usize {
56            return Err(FrameError(format!(
57                "maxFrameLength must be an integer between 0 and {}",
58                u32::MAX
59            )));
60        }
61        Ok(Self {
62            header: Vec::with_capacity(4),
63            payload: Vec::new(),
64            expected: None,
65            max_frame_length,
66            state: State::Open,
67        })
68    }
69
70    fn check_open(&self) -> Result<(), FrameError> {
71        match self.state {
72            State::Open => Ok(()),
73            State::Ended => Err(FrameError("Frame decoder has ended".into())),
74            State::Failed => Err(FrameError("Frame decoder has failed".into())),
75        }
76    }
77
78    pub fn push(&mut self, mut chunk: &[u8]) -> Result<Vec<Vec<u8>>, FrameError> {
79        self.check_open()?;
80        let mut frames = Vec::new();
81        while !chunk.is_empty() {
82            let expected = match self.expected {
83                Some(expected) => expected,
84                None => {
85                    let take = (4 - self.header.len()).min(chunk.len());
86                    self.header.extend_from_slice(&chunk[..take]);
87                    chunk = &chunk[take..];
88                    if self.header.len() < 4 {
89                        continue;
90                    }
91                    let length =
92                        u32::from_be_bytes([self.header[0], self.header[1], self.header[2], self.header[3]]) as usize;
93                    self.header.clear();
94                    if length > self.max_frame_length {
95                        return Err(self.fail(format!(
96                            "Frame length {length} exceeds configured limit of {}",
97                            self.max_frame_length
98                        )));
99                    }
100                    if length == 0 {
101                        frames.push(Vec::new());
102                        continue;
103                    }
104                    self.expected = Some(length);
105                    length
106                }
107            };
108            let take = (expected - self.payload.len()).min(chunk.len());
109            self.payload.extend_from_slice(&chunk[..take]);
110            chunk = &chunk[take..];
111            if self.payload.len() == expected {
112                frames.push(std::mem::take(&mut self.payload));
113                self.expected = None;
114            }
115        }
116        Ok(frames)
117    }
118
119    pub fn end(&mut self) -> Result<(), FrameError> {
120        self.check_open()?;
121        if !self.header.is_empty() || self.expected.is_some() {
122            return Err(self.fail("Truncated frame at end of stream".into()));
123        }
124        self.state = State::Ended;
125        Ok(())
126    }
127
128    fn fail(&mut self, message: String) -> FrameError {
129        self.state = State::Failed;
130        self.header.clear();
131        self.payload = Vec::new();
132        self.expected = None;
133        FrameError(message)
134    }
135}
136
137impl Default for FrameDecoder {
138    fn default() -> Self {
139        Self {
140            header: Vec::with_capacity(4),
141            payload: Vec::new(),
142            expected: None,
143            max_frame_length: DEFAULT_MAX_FRAME_LENGTH,
144            state: State::Open,
145        }
146    }
147}