//! 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, pub drawings: Vec, } /// 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, } /// 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>, } /// 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, 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 { 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, 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>) -> 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 { 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(¬_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]); } }