sapphire_framework_session/
frame.rs1use 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;
18const BLOB_START_LEN: usize = HASH_LEN + 8;
20
21#[derive(Debug)]
26pub enum Frame {
27 Control(Message),
29 BlobStart {
31 hash: ContentHash,
33 len: u64,
35 },
36 BlobChunk(Vec<u8>),
38 BlobEnd,
40}
41
42pub 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
51pub 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
62pub 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
77pub 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
85pub 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
107pub 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 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
167pub 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 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 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 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 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 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 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 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}