use sapphire_sync::ContentHash;
use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
use crate::error::{Error, Result};
use crate::message::Message;
use crate::{CHUNK, MAX_FRAME_LEN};
const TAG_CONTROL: u8 = 0;
const TAG_BLOB_START: u8 = 1;
const TAG_BLOB_CHUNK: u8 = 2;
const TAG_BLOB_END: u8 = 3;
const HASH_LEN: usize = 32;
const BLOB_START_LEN: usize = HASH_LEN + 8;
#[derive(Debug)]
pub enum Frame {
Control(Message),
BlobStart {
hash: ContentHash,
len: u64,
},
BlobChunk(Vec<u8>),
BlobEnd,
}
pub async fn write_control<W>(w: &mut W, msg: &Message) -> Result<()>
where
W: AsyncWrite + Unpin,
{
let payload = serde_json::to_vec(msg)?;
write_framed(w, TAG_CONTROL, &payload).await
}
pub async fn write_blob_start<W>(w: &mut W, hash: &ContentHash, len: u64) -> Result<()>
where
W: AsyncWrite + Unpin,
{
let mut payload = [0u8; BLOB_START_LEN];
payload[..HASH_LEN].copy_from_slice(&hash.0);
payload[HASH_LEN..].copy_from_slice(&len.to_be_bytes());
write_framed(w, TAG_BLOB_START, &payload).await
}
pub async fn write_blob_chunk<W>(w: &mut W, bytes: &[u8]) -> Result<()>
where
W: AsyncWrite + Unpin,
{
if bytes.len() > CHUNK {
return Err(Error::FrameTooLarge {
len: bytes.len(),
max: CHUNK,
});
}
write_framed(w, TAG_BLOB_CHUNK, bytes).await
}
pub async fn write_blob_end<W>(w: &mut W) -> Result<()>
where
W: AsyncWrite + Unpin,
{
write_framed(w, TAG_BLOB_END, &[]).await
}
pub async fn write_framed<W>(w: &mut W, tag: u8, payload: &[u8]) -> Result<()>
where
W: AsyncWrite + Unpin,
{
if payload.len() > MAX_FRAME_LEN {
return Err(Error::FrameTooLarge {
len: payload.len(),
max: MAX_FRAME_LEN,
});
}
w.write_u8(tag).await?;
w.write_u32(payload.len() as u32).await?;
w.write_all(payload).await?;
w.flush().await?;
Ok(())
}
pub async fn read_frame<R>(r: &mut R) -> Result<Option<Frame>>
where
R: AsyncRead + Unpin,
{
let tag = match r.read_u8().await {
Ok(tag) => tag,
Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None),
Err(e) => return Err(Error::Io(e)),
};
let len = r.read_u32().await? as usize;
let fits = |max: usize| {
if len > max {
Err(Error::FrameTooLarge { len, max })
} else {
Ok(())
}
};
let exactly = |want: usize, name: &str| {
if len != want {
Err(Error::Protocol(format!(
"a {name} frame of {len} bytes, expected {want}"
)))
} else {
Ok(())
}
};
match tag {
TAG_CONTROL => fits(MAX_FRAME_LEN)?,
TAG_BLOB_START => exactly(BLOB_START_LEN, "BLOB_START")?,
TAG_BLOB_CHUNK => fits(CHUNK)?,
TAG_BLOB_END => exactly(0, "BLOB_END")?,
other => return Err(Error::Protocol(format!("unknown frame tag {other}"))),
}
let mut payload = vec![0u8; len];
r.read_exact(&mut payload).await?;
Ok(Some(match tag {
TAG_CONTROL => Frame::Control(serde_json::from_slice(&payload)?),
TAG_BLOB_START => {
let mut hash = [0u8; HASH_LEN];
hash.copy_from_slice(&payload[..HASH_LEN]);
let mut len = [0u8; 8];
len.copy_from_slice(&payload[HASH_LEN..]);
Frame::BlobStart {
hash: ContentHash(hash),
len: u64::from_be_bytes(len),
}
}
TAG_BLOB_CHUNK => Frame::BlobChunk(payload),
_ => Frame::BlobEnd,
}))
}
pub async fn read_framed<R>(r: &mut R) -> Result<Option<(u8, Vec<u8>)>>
where
R: AsyncRead + Unpin,
{
let tag = match r.read_u8().await {
Ok(tag) => tag,
Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None),
Err(e) => return Err(Error::Io(e)),
};
let len = r.read_u32().await? as usize;
if len > MAX_FRAME_LEN {
return Err(Error::FrameTooLarge {
len,
max: MAX_FRAME_LEN,
});
}
let mut payload = vec![0u8; len];
r.read_exact(&mut payload).await?;
Ok(Some((tag, payload)))
}
#[cfg(test)]
mod tests {
use super::*;
use crate::SESSION_FORMAT_VERSION;
use sapphire_sync::{ContentHash, VersionVector};
fn hello() -> Message {
Message::Hello {
format: SESSION_FORMAT_VERSION,
workspace_id: grain_id::GrainId::random(),
replica_id: sapphire_sync::ReplicaId::new(),
vv: VersionVector::new(),
max_file_size: sapphire_sync::DEFAULT_MAX_FILE_SIZE,
acks: false,
}
}
#[tokio::test]
async fn a_control_frame_round_trips() {
let mut buf: Vec<u8> = Vec::new();
let msg = hello();
write_control(&mut buf, &msg).await.unwrap();
let mut cursor = std::io::Cursor::new(buf);
match read_frame(&mut cursor).await.unwrap().unwrap() {
Frame::Control(back) => assert_eq!(format!("{back:?}"), format!("{msg:?}")),
other => panic!("got {other:?}"),
}
}
async fn read_back(buf: Vec<u8>) -> Frame {
let mut cursor = std::io::Cursor::new(buf);
let frame = read_frame(&mut cursor).await.unwrap().unwrap();
assert!(read_frame(&mut cursor).await.unwrap().is_none());
frame
}
fn header(tag: u8, len: usize) -> Vec<u8> {
let mut buf = vec![tag];
buf.extend_from_slice(&(len as u32).to_be_bytes());
buf
}
#[tokio::test]
async fn a_blob_start_round_trips() {
let hash = ContentHash::of_bytes(b"content");
let mut buf: Vec<u8> = Vec::new();
write_blob_start(&mut buf, &hash, 1 << 30).await.unwrap();
match read_back(buf).await {
Frame::BlobStart { hash: back, len } => {
assert_eq!(back, hash);
assert_eq!(len, 1 << 30);
}
other => panic!("got {other:?}"),
}
}
#[tokio::test]
async fn a_blob_chunk_round_trips() {
let content: Vec<u8> = (0..CHUNK).map(|i| i as u8).collect();
let mut buf: Vec<u8> = Vec::new();
write_blob_chunk(&mut buf, &content).await.unwrap();
assert_eq!(buf.len(), 1 + 4 + CHUNK);
match read_back(buf).await {
Frame::BlobChunk(bytes) => assert_eq!(bytes, content),
other => panic!("got {other:?}"),
}
}
#[tokio::test]
async fn a_blob_end_round_trips() {
let mut buf: Vec<u8> = Vec::new();
write_blob_end(&mut buf).await.unwrap();
assert!(matches!(read_back(buf).await, Frame::BlobEnd));
}
#[tokio::test]
async fn a_chunk_over_the_limit_is_refused_before_allocating() {
let mut cursor = std::io::Cursor::new(header(TAG_BLOB_CHUNK, CHUNK + 1));
let err = read_frame(&mut cursor).await.unwrap_err();
assert!(
matches!(err, Error::FrameTooLarge { len, max } if len == CHUNK + 1 && max == CHUNK),
"got {err:?}"
);
let mut buf: Vec<u8> = Vec::new();
let err = write_blob_chunk(&mut buf, &vec![0u8; CHUNK + 1])
.await
.unwrap_err();
assert!(matches!(err, Error::FrameTooLarge { .. }), "got {err:?}");
assert!(buf.is_empty());
}
#[tokio::test]
async fn a_blob_start_of_the_wrong_size_is_refused() {
let mut buf = header(TAG_BLOB_START, 39);
buf.extend_from_slice(&[0u8; 39]);
let mut cursor = std::io::Cursor::new(buf);
assert!(matches!(
read_frame(&mut cursor).await.unwrap_err(),
Error::Protocol(_)
));
}
#[tokio::test]
async fn several_frames_read_back_in_order() {
let mut buf: Vec<u8> = Vec::new();
write_control(&mut buf, &hello()).await.unwrap();
write_control(&mut buf, &Message::Done).await.unwrap();
let mut cursor = std::io::Cursor::new(buf);
assert!(matches!(
read_frame(&mut cursor).await.unwrap(),
Some(Frame::Control(Message::Hello { .. }))
));
assert!(matches!(
read_frame(&mut cursor).await.unwrap(),
Some(Frame::Control(Message::Done))
));
assert!(read_frame(&mut cursor).await.unwrap().is_none());
}
#[tokio::test]
async fn a_control_frame_over_16_mib_is_refused_before_allocating() {
assert_eq!(MAX_FRAME_LEN, 16 * 1024 * 1024);
let mut cursor = std::io::Cursor::new(header(TAG_CONTROL, MAX_FRAME_LEN + 1));
let err = read_frame(&mut cursor).await.unwrap_err();
assert!(matches!(err, Error::FrameTooLarge { .. }), "got {err:?}");
}
#[tokio::test]
async fn an_unknown_tag_is_a_protocol_error() {
let mut buf = vec![99u8];
buf.extend_from_slice(&0u32.to_be_bytes());
let mut cursor = std::io::Cursor::new(buf);
assert!(matches!(
read_frame(&mut cursor).await.unwrap_err(),
Error::Protocol(_)
));
}
#[tokio::test]
async fn a_truncated_frame_is_an_error_not_a_silent_short_read() {
let mut buf = vec![0u8];
buf.extend_from_slice(&64u32.to_be_bytes());
buf.extend_from_slice(b"only ten b");
let mut cursor = std::io::Cursor::new(buf);
assert!(read_frame(&mut cursor).await.is_err());
}
#[tokio::test]
async fn a_raw_frame_round_trips_through_the_public_pair() {
let mut buf: Vec<u8> = Vec::new();
write_framed(&mut buf, 9, b"payload").await.unwrap();
let mut cursor = std::io::Cursor::new(buf);
assert_eq!(
read_framed(&mut cursor).await.unwrap(),
Some((9u8, b"payload".to_vec()))
);
assert!(read_framed(&mut cursor).await.unwrap().is_none());
}
#[tokio::test]
async fn a_raw_frame_that_is_too_large_to_write_is_refused() {
let mut buf: Vec<u8> = Vec::new();
let err = write_framed(&mut buf, 9, &vec![0u8; MAX_FRAME_LEN + 1])
.await
.unwrap_err();
assert!(matches!(err, Error::FrameTooLarge { .. }), "got {err:?}");
assert!(buf.is_empty(), "nothing must be written: {buf:?}");
}
#[tokio::test]
async fn a_raw_frame_that_announces_too_much_is_refused_before_allocating() {
let mut buf = vec![9u8];
buf.extend_from_slice(&((MAX_FRAME_LEN + 1) as u32).to_be_bytes());
let mut cursor = std::io::Cursor::new(buf);
assert!(matches!(
read_framed(&mut cursor).await.unwrap_err(),
Error::FrameTooLarge { .. }
));
}
}