bookclerk_cover::wire

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Frames the host and the cover worker exchange over the worker's stdio.

The worker is long-lived and handles many covers at once, so each request carries an id and replies may come back in any order. Every frame is a four-byte big-endian length followed by that many bytes of body:

Frame Body
Request id: u64, then the cover bytes (at most MAX_INPUT_BYTES)
Reply, ok id: u64, 0u8, width: u32, height: u32, then for each CoverSize in order a u32 length and that many JPEG bytes
Reply, error id: u64, 1u8, then a UTF-8 message of at most MAX_ERROR_BYTES

All integers are big-endian. The host reads replies from a process that decoded untrusted bytes, so decode_reply checks every length, and accepts an ok reply only when each image starts with the JPEG signature.

Item Kind Summary
Request struct One cover the host asks the worker to process.
WireError enum Why a frame body could not be read.
Reply enum The worker's answer to one Request.
body_len function Reads a frame's length prefix.
encode_request function Encodes a request as a whole frame, length prefix included.
decode_request function Decodes a request body (the bytes after the length prefix).
encode_reply function Encodes a reply as a whole frame, length prefix included.
decode_reply function Decodes a reply body (the bytes after the length prefix).
MAX_ERROR_BYTES constant Longest error message a reply carries, in bytes.
MAX_REQUEST_BODY constant Largest request body: an id and a cover.
MAX_REPLY_BODY constant Largest reply body. A JPEG of a cover that fits the decode limits is far smaller than this; a longer frame means the worker is broken.

Structs

Request

pub struct Request {
    pub id: u64,
    pub cover: Vec<u8>,
}

One cover the host asks the worker to process.

Fields

  • id: Id the reply echoes.
  • cover: The untrusted cover bytes.

Implements: Clone, Debug, Eq, PartialEq

Enums

WireError

pub enum WireError {
    Truncated,
    Trailing,
    TooLarge,
    UnknownTag(u8),
    BadMessage,
    NotJpeg,
}

Why a frame body could not be read.

Variants

  • Truncated: The body ended before a field it promised.
  • Trailing: The body has bytes after its last field.
  • TooLarge: The body is over the frame's size cap.
  • UnknownTag: The reply tag is neither ok nor error.
  • BadMessage: An error message is not UTF-8 or is too long.
  • NotJpeg: An ok reply carries an image that is not a JPEG, or zero dimensions.

Implements: Clone, Debug, Display, Eq, Error, PartialEq

Reply

pub enum Reply {
    Ok { id: u64, set: CoverSet },
    Err { id: u64, message: String },
}

The worker's answer to one Request.

Variants

  • Ok: The cover was processed.
    • id: The request's id.
    • set: The JPEGs.
  • Err: The cover was refused.

Reply::id

pub fn id(&self) -> u64

The id of the request this answers.

Implements: Clone, Debug, Eq, PartialEq

Functions

body_len

pub fn body_len(prefix: [u8; 4]) -> usize

Reads a frame's length prefix.

Arguments

  • prefix - The four bytes before the body.

Returns

The body length in bytes.

encode_request

pub fn encode_request(request: &Request) -> Result<Vec<u8>, WireError>

Encodes a request as a whole frame, length prefix included.

Errors

WireError::TooLarge for a cover over MAX_INPUT_BYTES.

decode_request

pub fn decode_request(body: &[u8]) -> Result<Request, WireError>

Decodes a request body (the bytes after the length prefix).

Errors

WireError::Truncated without a full id, WireError::TooLarge over MAX_REQUEST_BODY.

encode_reply

pub fn encode_reply(reply: &Reply) -> Result<Vec<u8>, WireError>

Encodes a reply as a whole frame, length prefix included.

An error message is cut to MAX_ERROR_BYTES at a character boundary.

Errors

WireError::TooLarge when an image does not fit a u32 length or the body is over MAX_REPLY_BODY.

decode_reply

pub fn decode_reply(body: &[u8]) -> Result<Reply, WireError>

Decodes a reply body (the bytes after the length prefix).

Errors

A WireError for a truncated, oversized or trailing body, an unknown tag, a bad message, zero dimensions, or an image without the JPEG signature.

Constants

MAX_ERROR_BYTES

pub const MAX_ERROR_BYTES: usize = 1024;

Longest error message a reply carries, in bytes.

MAX_REQUEST_BODY

pub const MAX_REQUEST_BODY: usize = _;

Largest request body: an id and a cover.

MAX_REPLY_BODY

pub const MAX_REPLY_BODY: usize = _;

Largest reply body. A JPEG of a cover that fits the decode limits is far smaller than this; a longer frame means the worker is broken.

Generated from crates/bookclerk-cover at main · View as Markdown