Files
faunosteo/crates/worker/src/verify_frame.rs
T

322 lines
11 KiB
Rust

//! The framed stdin input of the `verify` child (V1-2.3), written by the parent and read by
//! the child: `[u32 LE header length][header JSON][document][base?][drawing bytes in header
//! order]`. The parent frames bytes it never parses (document, base, drawings); the child
//! reads them as borrowed slices.
use std::fmt;
use faunosteo_core::domain::sheet::verdict::{VerdictBinding, VerdictDrawing, VerdictInput};
use serde::{Deserialize, Serialize};
use crate::limits::VERIFY_MAX_HEADER_BYTES;
/// The header: the round, the lengths of the parts that follow, the drawing rows.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FrameHeader {
pub sheet_id: String,
pub version_id: String,
pub revision: u32,
pub review_id: String,
pub document_len: usize,
pub base_len: Option<usize>,
pub drawings: Vec<FrameDrawing>,
}
/// One drawing row; `bytes_len` is absent when the parent passes the row without bytes.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FrameDrawing {
pub asset_id: String,
pub sha256: String,
pub byte_size: u64,
pub bytes_len: Option<usize>,
}
/// A decoded frame, borrowing the input buffer.
#[derive(Debug)]
pub struct Frame<'a> {
pub header: FrameHeader,
pub document: &'a str,
pub base: Option<&'a str>,
/// One entry per header drawing, in header order.
pub drawing_bytes: Vec<Option<&'a [u8]>>,
}
/// Why a frame could not be built or read (closed: the child's stderr names it).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FrameError {
Truncated,
HeaderTooLarge,
HeaderInvalid,
LengthMismatch,
NotUtf8,
}
impl fmt::Display for FrameError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let text = match self {
Self::Truncated => "frame shorter than its header",
Self::HeaderTooLarge => "header over its cap",
Self::HeaderInvalid => "header is not the expected JSON",
Self::LengthMismatch => "part lengths do not sum to the frame",
Self::NotUtf8 => "document or base is not UTF-8",
};
f.write_str(text)
}
}
impl std::error::Error for FrameError {}
/// Frames a verification input (the parent side).
pub fn encode(input: &VerdictInput<'_>) -> Result<Vec<u8>, FrameError> {
let header = header_of(input);
let header_json = serde_json::to_vec(&header).map_err(|_| FrameError::HeaderInvalid)?;
if header_json.len() > VERIFY_MAX_HEADER_BYTES {
return Err(FrameError::HeaderTooLarge);
}
let header_len = u32::try_from(header_json.len()).map_err(|_| FrameError::HeaderTooLarge)?;
let body = checked_body_len(&header).unwrap_or(0);
let mut out = Vec::with_capacity(4 + header_json.len() + body);
out.extend_from_slice(&header_len.to_le_bytes());
out.extend_from_slice(&header_json);
out.extend_from_slice(input.document.as_bytes());
if let Some(base) = input.base_document {
out.extend_from_slice(base.as_bytes());
}
for bytes in input.drawings.iter().filter_map(|d| d.bytes) {
out.extend_from_slice(bytes);
}
Ok(out)
}
fn header_of(input: &VerdictInput<'_>) -> FrameHeader {
FrameHeader {
sheet_id: input.binding.sheet_id.clone(),
version_id: input.binding.version_id.clone(),
revision: input.binding.revision,
review_id: input.binding.review_id.clone(),
document_len: input.document.len(),
base_len: input.base_document.map(str::len),
drawings: input
.drawings
.iter()
.map(|d| FrameDrawing {
asset_id: d.asset_id.to_owned(),
sha256: d.sha256.to_owned(),
byte_size: d.byte_size,
bytes_len: d.bytes.map(<[u8]>::len),
})
.collect(),
}
}
/// Total length of the parts after the header; `None` on overflow.
fn checked_body_len(header: &FrameHeader) -> Option<usize> {
header
.drawings
.iter()
.filter_map(|d| d.bytes_len)
.try_fold(header.document_len, usize::checked_add)?
.checked_add(header.base_len.unwrap_or(0))
}
/// Reads a frame (the child side): every length must be exact, nothing may trail.
pub fn decode(bytes: &[u8]) -> Result<Frame<'_>, FrameError> {
let (prefix, rest) = bytes.split_at_checked(4).ok_or(FrameError::Truncated)?;
let mut length = [0u8; 4];
length.copy_from_slice(prefix);
let header_len =
usize::try_from(u32::from_le_bytes(length)).map_err(|_| FrameError::HeaderTooLarge)?;
if header_len > VERIFY_MAX_HEADER_BYTES {
return Err(FrameError::HeaderTooLarge);
}
let (header_json, mut body) = rest
.split_at_checked(header_len)
.ok_or(FrameError::Truncated)?;
let header: FrameHeader =
serde_json::from_slice(header_json).map_err(|_| FrameError::HeaderInvalid)?;
if checked_body_len(&header) != Some(body.len()) {
return Err(FrameError::LengthMismatch);
}
let document = take_text(&mut body, header.document_len)?;
let base = header
.base_len
.map(|len| take_text(&mut body, len))
.transpose()?;
let drawing_bytes = header
.drawings
.iter()
.map(|d| d.bytes_len.map(|len| take(&mut body, len)))
.collect();
Ok(Frame {
header,
document,
base,
drawing_bytes,
})
}
/// Splits `len` bytes off the front; the lengths were checked against the body beforehand.
fn take<'a>(body: &mut &'a [u8], len: usize) -> &'a [u8] {
let (head, tail) = body.split_at(len.min(body.len()));
*body = tail;
head
}
fn take_text<'a>(body: &mut &'a [u8], len: usize) -> Result<&'a str, FrameError> {
std::str::from_utf8(take(body, len)).map_err(|_| FrameError::NotUtf8)
}
impl Frame<'_> {
/// The core's input, borrowing the frame.
pub fn input(&self) -> VerdictInput<'_> {
VerdictInput {
binding: VerdictBinding {
sheet_id: self.header.sheet_id.clone(),
version_id: self.header.version_id.clone(),
revision: self.header.revision,
review_id: self.header.review_id.clone(),
},
document: self.document,
base_document: self.base,
drawings: self
.header
.drawings
.iter()
.zip(&self.drawing_bytes)
.map(|(row, bytes)| VerdictDrawing {
asset_id: &row.asset_id,
sha256: &row.sha256,
byte_size: row.byte_size,
bytes: *bytes,
})
.collect(),
}
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used)]
use super::*;
fn binding() -> VerdictBinding {
VerdictBinding {
sheet_id: "s".to_owned(),
version_id: "v".to_owned(),
revision: 3,
review_id: "r".to_owned(),
}
}
fn input<'a>(base: Option<&'a str>, drawings: Vec<VerdictDrawing<'a>>) -> VerdictInput<'a> {
VerdictInput {
binding: binding(),
document: "{\"d\":\"é\"}",
base_document: base,
drawings,
}
}
fn drawing(bytes: Option<&[u8]>) -> VerdictDrawing<'_> {
VerdictDrawing {
asset_id: "a",
sha256: "h",
byte_size: 3,
bytes,
}
}
/// Rewrites the header of a valid frame with `edit`, keeping its body.
fn with_header(frame: &[u8], edit: impl Fn(&mut serde_json::Value)) -> Vec<u8> {
let len = u32::from_le_bytes(frame[..4].try_into().unwrap()) as usize;
let mut header: serde_json::Value = serde_json::from_slice(&frame[4..4 + len]).unwrap();
edit(&mut header);
let json = serde_json::to_vec(&header).unwrap();
let mut out = (json.len() as u32).to_le_bytes().to_vec();
out.extend_from_slice(&json);
out.extend_from_slice(&frame[4 + len..]);
out
}
#[test]
fn a_frame_round_trips() {
let original = input(
Some("{}"),
vec![drawing(Some(b"abc")), drawing(None), drawing(Some(b"xyz"))],
);
let bytes = encode(&original).unwrap();
let frame = decode(&bytes).unwrap();
assert_eq!(frame.document, original.document);
assert_eq!(frame.base, Some("{}"));
assert_eq!(
frame.drawing_bytes,
vec![Some(&b"abc"[..]), None, Some(&b"xyz"[..])]
);
let read = frame.input();
assert_eq!(read.binding, original.binding);
assert_eq!(read.drawings.len(), 3);
assert_eq!(read.drawings[1].bytes, None);
assert_eq!(read.drawings[2].byte_size, 3);
}
#[test]
fn an_absent_and_an_empty_base_differ() {
let none = encode(&input(None, vec![])).unwrap();
assert_eq!(decode(&none).unwrap().base, None);
let empty = encode(&input(Some(""), vec![])).unwrap();
assert_eq!(decode(&empty).unwrap().base, Some(""));
}
#[test]
fn malformed_frames_are_refused() {
let good = encode(&input(Some("{}"), vec![drawing(Some(b"abc"))])).unwrap();
assert_eq!(decode(&good[..3]).err(), Some(FrameError::Truncated));
assert_eq!(decode(&good[..10]).err(), Some(FrameError::Truncated));
assert_eq!(
decode(&good[..good.len() - 1]).err(),
Some(FrameError::LengthMismatch)
);
let mut trailing = good.clone();
trailing.push(0);
assert_eq!(decode(&trailing).err(), Some(FrameError::LengthMismatch));
let mut huge = ((VERIFY_MAX_HEADER_BYTES + 1) as u32)
.to_le_bytes()
.to_vec();
huge.extend(vec![b' '; VERIFY_MAX_HEADER_BYTES + 1]);
assert_eq!(decode(&huge).err(), Some(FrameError::HeaderTooLarge));
let mut not_json = 3u32.to_le_bytes().to_vec();
not_json.extend_from_slice(b"{x}");
assert_eq!(decode(&not_json).err(), Some(FrameError::HeaderInvalid));
let unknown = with_header(&good, |h| h["extra"] = 1.into());
assert_eq!(decode(&unknown).err(), Some(FrameError::HeaderInvalid));
let overflow = with_header(&good, |h| h["document_len"] = usize::MAX.into());
assert_eq!(decode(&overflow).err(), Some(FrameError::LengthMismatch));
}
#[test]
fn a_document_or_base_that_is_not_utf8_is_refused() {
let good = encode(&input(Some("ab"), vec![])).unwrap();
let mut bad_base = good.clone();
let last = bad_base.len() - 1;
bad_base[last] = 0xff;
assert_eq!(decode(&bad_base).err(), Some(FrameError::NotUtf8));
let mut bad_document = good;
let len = u32::from_le_bytes(bad_document[..4].try_into().unwrap()) as usize;
bad_document[4 + len] = 0xc3;
assert_eq!(decode(&bad_document).err(), Some(FrameError::NotUtf8));
}
#[test]
fn missing_drawing_bytes_are_a_length_mismatch() {
let good = encode(&input(None, vec![drawing(Some(b"abc"))])).unwrap();
let missing = &good[..good.len() - 3];
assert_eq!(decode(missing).err(), Some(FrameError::LengthMismatch));
let without = with_header(&good[..good.len() - 3], |h| {
h["drawings"][0]["bytes_len"] = serde_json::Value::Null;
});
assert_eq!(decode(&without).unwrap().drawing_bytes, vec![None]);
}
}