Skip to main content

sapphire_framework_session/
frame.rs

1//! Framing: one tag byte, a four-byte big-endian length, then the payload.
2//!
3//! Not the line framing of `sapphire-framework-ipc`: content is bytes, and base64 inside
4//! JSON would inflate every file by a third to no purpose.
5
6use sapphire_sync::ContentHash;
7use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
8
9use crate::error::{Error, Result};
10use crate::message::Message;
11use crate::{CHUNK, MAX_FRAME_LEN};
12
13const TAG_CONTROL: u8 = 0;
14const TAG_BLOB_START: u8 = 1;
15const TAG_BLOB_CHUNK: u8 = 2;
16const TAG_BLOB_END: u8 = 3;
17const HASH_LEN: usize = 32;
18/// A `BLOB_START` payload: the hash, then the length as a big-endian `u64`.
19const BLOB_START_LEN: usize = HASH_LEN + 8;
20
21/// One frame off the wire.
22///
23/// Content travels as one `BlobStart`, its chunks in order, then `BlobEnd` — or a
24/// [`Message::Aborted`] in place of the end. Control frames may come between the chunks.
25#[derive(Debug)]
26pub enum Frame {
27    /// A control message.
28    Control(Message),
29    /// The start of a piece of content.
30    BlobStart {
31        /// The content's hash, which the receiver must verify once it is all in.
32        hash: ContentHash,
33        /// How many bytes the chunks that follow add up to.
34        len: u64,
35    },
36    /// The next piece of the content started last, at most [`CHUNK`] bytes.
37    BlobChunk(Vec<u8>),
38    /// The content started last is complete.
39    BlobEnd,
40}
41
42/// Send a control message.
43pub async fn write_control<W>(w: &mut W, msg: &Message) -> Result<()>
44where
45    W: AsyncWrite + Unpin,
46{
47    let payload = serde_json::to_vec(msg)?;
48    write_framed(w, TAG_CONTROL, &payload).await
49}
50
51/// Start sending the content `hash`, `len` bytes long.
52pub async fn write_blob_start<W>(w: &mut W, hash: &ContentHash, len: u64) -> Result<()>
53where
54    W: AsyncWrite + Unpin,
55{
56    let mut payload = [0u8; BLOB_START_LEN];
57    payload[..HASH_LEN].copy_from_slice(&hash.0);
58    payload[HASH_LEN..].copy_from_slice(&len.to_be_bytes());
59    write_framed(w, TAG_BLOB_START, &payload).await
60}
61
62/// Send the next piece of the content started last. More than [`CHUNK`] bytes is
63/// [`Error::FrameTooLarge`], and nothing is written.
64pub async fn write_blob_chunk<W>(w: &mut W, bytes: &[u8]) -> Result<()>
65where
66    W: AsyncWrite + Unpin,
67{
68    if bytes.len() > CHUNK {
69        return Err(Error::FrameTooLarge {
70            len: bytes.len(),
71            max: CHUNK,
72        });
73    }
74    write_framed(w, TAG_BLOB_CHUNK, bytes).await
75}
76
77/// Say the content started last is complete.
78pub async fn write_blob_end<W>(w: &mut W) -> Result<()>
79where
80    W: AsyncWrite + Unpin,
81{
82    write_framed(w, TAG_BLOB_END, &[]).await
83}
84
85/// Send one frame: `tag`, then a four-byte big-endian length, then `payload`.
86///
87/// Public so a protocol riding on the same framing — the pairing exchange — writes with
88/// it rather than growing a second copy of the format. The payload is bounded by
89/// [`MAX_FRAME_LEN`] and flushed before returning.
90pub async fn write_framed<W>(w: &mut W, tag: u8, payload: &[u8]) -> Result<()>
91where
92    W: AsyncWrite + Unpin,
93{
94    if payload.len() > MAX_FRAME_LEN {
95        return Err(Error::FrameTooLarge {
96            len: payload.len(),
97            max: MAX_FRAME_LEN,
98        });
99    }
100    w.write_u8(tag).await?;
101    w.write_u32(payload.len() as u32).await?;
102    w.write_all(payload).await?;
103    w.flush().await?;
104    Ok(())
105}
106
107/// Read one frame. `None` at a clean end of stream.
108///
109/// The length each tag announces is checked before anything is allocated: a control frame
110/// may be up to [`MAX_FRAME_LEN`] and a chunk up to [`CHUNK`] ([`Error::FrameTooLarge`]
111/// past either), while a `BLOB_START` is exactly a hash and a length and a `BLOB_END` is
112/// empty ([`Error::Protocol`] otherwise).
113pub async fn read_frame<R>(r: &mut R) -> Result<Option<Frame>>
114where
115    R: AsyncRead + Unpin,
116{
117    let tag = match r.read_u8().await {
118        Ok(tag) => tag,
119        Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None),
120        Err(e) => return Err(Error::Io(e)),
121    };
122    let len = r.read_u32().await? as usize;
123    // Check before allocating: a peer that announces 4 GiB must not make us try.
124    let fits = |max: usize| {
125        if len > max {
126            Err(Error::FrameTooLarge { len, max })
127        } else {
128            Ok(())
129        }
130    };
131    let exactly = |want: usize, name: &str| {
132        if len != want {
133            Err(Error::Protocol(format!(
134                "a {name} frame of {len} bytes, expected {want}"
135            )))
136        } else {
137            Ok(())
138        }
139    };
140    match tag {
141        TAG_CONTROL => fits(MAX_FRAME_LEN)?,
142        TAG_BLOB_START => exactly(BLOB_START_LEN, "BLOB_START")?,
143        TAG_BLOB_CHUNK => fits(CHUNK)?,
144        TAG_BLOB_END => exactly(0, "BLOB_END")?,
145        other => return Err(Error::Protocol(format!("unknown frame tag {other}"))),
146    }
147    let mut payload = vec![0u8; len];
148    r.read_exact(&mut payload).await?;
149
150    Ok(Some(match tag {
151        TAG_CONTROL => Frame::Control(serde_json::from_slice(&payload)?),
152        TAG_BLOB_START => {
153            let mut hash = [0u8; HASH_LEN];
154            hash.copy_from_slice(&payload[..HASH_LEN]);
155            let mut len = [0u8; 8];
156            len.copy_from_slice(&payload[HASH_LEN..]);
157            Frame::BlobStart {
158                hash: ContentHash(hash),
159                len: u64::from_be_bytes(len),
160            }
161        }
162        TAG_BLOB_CHUNK => Frame::BlobChunk(payload),
163        _ => Frame::BlobEnd,
164    }))
165}
166
167/// Read one tagged frame's payload. `None` at a clean end of stream.
168///
169/// The caller decides what a tag means and what type the payload decodes to; this is
170/// the half of [`write_framed`] a protocol other than the session needs. Reading is
171/// bounded by [`MAX_FRAME_LEN`], so a peer that announces more than that is refused
172/// before anything is allocated.
173pub async fn read_framed<R>(r: &mut R) -> Result<Option<(u8, Vec<u8>)>>
174where
175    R: AsyncRead + Unpin,
176{
177    let tag = match r.read_u8().await {
178        Ok(tag) => tag,
179        Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None),
180        Err(e) => return Err(Error::Io(e)),
181    };
182    let len = r.read_u32().await? as usize;
183    // Check before allocating: a peer that announces 4 GiB must not make us try.
184    if len > MAX_FRAME_LEN {
185        return Err(Error::FrameTooLarge {
186            len,
187            max: MAX_FRAME_LEN,
188        });
189    }
190    let mut payload = vec![0u8; len];
191    r.read_exact(&mut payload).await?;
192    Ok(Some((tag, payload)))
193}
194
195#[cfg(test)]
196mod tests {
197    use super::*;
198    use crate::SESSION_FORMAT_VERSION;
199    use sapphire_sync::{ContentHash, VersionVector};
200
201    fn hello() -> Message {
202        Message::Hello {
203            format: SESSION_FORMAT_VERSION,
204            workspace_id: grain_id::GrainId::random(),
205            replica_id: sapphire_sync::ReplicaId::new(),
206            vv: VersionVector::new(),
207            max_file_size: sapphire_sync::DEFAULT_MAX_FILE_SIZE,
208            acks: false,
209        }
210    }
211
212    #[tokio::test]
213    async fn a_control_frame_round_trips() {
214        let mut buf: Vec<u8> = Vec::new();
215        let msg = hello();
216        write_control(&mut buf, &msg).await.unwrap();
217
218        let mut cursor = std::io::Cursor::new(buf);
219        match read_frame(&mut cursor).await.unwrap().unwrap() {
220            Frame::Control(back) => assert_eq!(format!("{back:?}"), format!("{msg:?}")),
221            other => panic!("got {other:?}"),
222        }
223    }
224
225    async fn read_back(buf: Vec<u8>) -> Frame {
226        let mut cursor = std::io::Cursor::new(buf);
227        let frame = read_frame(&mut cursor).await.unwrap().unwrap();
228        assert!(read_frame(&mut cursor).await.unwrap().is_none());
229        frame
230    }
231
232    /// A frame header announcing `len` bytes under `tag`, and no payload.
233    fn header(tag: u8, len: usize) -> Vec<u8> {
234        let mut buf = vec![tag];
235        buf.extend_from_slice(&(len as u32).to_be_bytes());
236        buf
237    }
238
239    #[tokio::test]
240    async fn a_blob_start_round_trips() {
241        let hash = ContentHash::of_bytes(b"content");
242        let mut buf: Vec<u8> = Vec::new();
243        write_blob_start(&mut buf, &hash, 1 << 30).await.unwrap();
244        match read_back(buf).await {
245            Frame::BlobStart { hash: back, len } => {
246                assert_eq!(back, hash);
247                assert_eq!(len, 1 << 30);
248            }
249            other => panic!("got {other:?}"),
250        }
251    }
252
253    #[tokio::test]
254    async fn a_blob_chunk_round_trips() {
255        let content: Vec<u8> = (0..CHUNK).map(|i| i as u8).collect();
256        let mut buf: Vec<u8> = Vec::new();
257        write_blob_chunk(&mut buf, &content).await.unwrap();
258        // Tag, length, content — and not a byte more.
259        assert_eq!(buf.len(), 1 + 4 + CHUNK);
260        match read_back(buf).await {
261            Frame::BlobChunk(bytes) => assert_eq!(bytes, content),
262            other => panic!("got {other:?}"),
263        }
264    }
265
266    #[tokio::test]
267    async fn a_blob_end_round_trips() {
268        let mut buf: Vec<u8> = Vec::new();
269        write_blob_end(&mut buf).await.unwrap();
270        assert!(matches!(read_back(buf).await, Frame::BlobEnd));
271    }
272
273    #[tokio::test]
274    async fn a_chunk_over_the_limit_is_refused_before_allocating() {
275        // The header alone: a reader that trusted the length would wait for the payload.
276        let mut cursor = std::io::Cursor::new(header(TAG_BLOB_CHUNK, CHUNK + 1));
277        let err = read_frame(&mut cursor).await.unwrap_err();
278        assert!(
279            matches!(err, Error::FrameTooLarge { len, max } if len == CHUNK + 1 && max == CHUNK),
280            "got {err:?}"
281        );
282
283        // And it is not written either.
284        let mut buf: Vec<u8> = Vec::new();
285        let err = write_blob_chunk(&mut buf, &vec![0u8; CHUNK + 1])
286            .await
287            .unwrap_err();
288        assert!(matches!(err, Error::FrameTooLarge { .. }), "got {err:?}");
289        assert!(buf.is_empty());
290    }
291
292    #[tokio::test]
293    async fn a_blob_start_of_the_wrong_size_is_refused() {
294        let mut buf = header(TAG_BLOB_START, 39);
295        buf.extend_from_slice(&[0u8; 39]);
296        let mut cursor = std::io::Cursor::new(buf);
297        assert!(matches!(
298            read_frame(&mut cursor).await.unwrap_err(),
299            Error::Protocol(_)
300        ));
301    }
302
303    #[tokio::test]
304    async fn several_frames_read_back_in_order() {
305        let mut buf: Vec<u8> = Vec::new();
306        write_control(&mut buf, &hello()).await.unwrap();
307        write_control(&mut buf, &Message::Done).await.unwrap();
308
309        let mut cursor = std::io::Cursor::new(buf);
310        assert!(matches!(
311            read_frame(&mut cursor).await.unwrap(),
312            Some(Frame::Control(Message::Hello { .. }))
313        ));
314        assert!(matches!(
315            read_frame(&mut cursor).await.unwrap(),
316            Some(Frame::Control(Message::Done))
317        ));
318        assert!(read_frame(&mut cursor).await.unwrap().is_none());
319    }
320
321    #[tokio::test]
322    async fn a_control_frame_over_16_mib_is_refused_before_allocating() {
323        // Tag 0, length just over the limit, and nothing else: a reader that trusted the
324        // length would try to allocate 16 MiB + 1 before discovering the stream is empty.
325        assert_eq!(MAX_FRAME_LEN, 16 * 1024 * 1024);
326        let mut cursor = std::io::Cursor::new(header(TAG_CONTROL, MAX_FRAME_LEN + 1));
327        let err = read_frame(&mut cursor).await.unwrap_err();
328        assert!(matches!(err, Error::FrameTooLarge { .. }), "got {err:?}");
329    }
330
331    #[tokio::test]
332    async fn an_unknown_tag_is_a_protocol_error() {
333        let mut buf = vec![99u8];
334        buf.extend_from_slice(&0u32.to_be_bytes());
335        let mut cursor = std::io::Cursor::new(buf);
336        assert!(matches!(
337            read_frame(&mut cursor).await.unwrap_err(),
338            Error::Protocol(_)
339        ));
340    }
341
342    #[tokio::test]
343    async fn a_truncated_frame_is_an_error_not_a_silent_short_read() {
344        let mut buf = vec![0u8];
345        buf.extend_from_slice(&64u32.to_be_bytes());
346        buf.extend_from_slice(b"only ten b");
347
348        let mut cursor = std::io::Cursor::new(buf);
349        assert!(read_frame(&mut cursor).await.is_err());
350    }
351
352    #[tokio::test]
353    async fn a_raw_frame_round_trips_through_the_public_pair() {
354        let mut buf: Vec<u8> = Vec::new();
355        write_framed(&mut buf, 9, b"payload").await.unwrap();
356
357        let mut cursor = std::io::Cursor::new(buf);
358        assert_eq!(
359            read_framed(&mut cursor).await.unwrap(),
360            Some((9u8, b"payload".to_vec()))
361        );
362        // And a clean end of stream is `None`, as for `read_frame`.
363        assert!(read_framed(&mut cursor).await.unwrap().is_none());
364    }
365
366    #[tokio::test]
367    async fn a_raw_frame_that_is_too_large_to_write_is_refused() {
368        let mut buf: Vec<u8> = Vec::new();
369        let err = write_framed(&mut buf, 9, &vec![0u8; MAX_FRAME_LEN + 1])
370            .await
371            .unwrap_err();
372        assert!(matches!(err, Error::FrameTooLarge { .. }), "got {err:?}");
373        assert!(buf.is_empty(), "nothing must be written: {buf:?}");
374    }
375
376    #[tokio::test]
377    async fn a_raw_frame_that_announces_too_much_is_refused_before_allocating() {
378        let mut buf = vec![9u8];
379        buf.extend_from_slice(&((MAX_FRAME_LEN + 1) as u32).to_be_bytes());
380        let mut cursor = std::io::Cursor::new(buf);
381        assert!(matches!(
382            read_framed(&mut cursor).await.unwrap_err(),
383            Error::FrameTooLarge { .. }
384        ));
385    }
386}