bookclerk_cover::wire
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. |
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
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
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.id: The request's id.message: Why, for logs; at mostMAX_ERROR_BYTES.
pub fn id(&self) -> u64
The id of the request this answers.
Implements: Clone, Debug, Eq, PartialEq
pub fn body_len(prefix: [u8; 4]) -> usize
Reads a frame's length prefix.
prefix- The four bytes before the body.
The body length in bytes.
pub fn encode_request(request: &Request) -> Result<Vec<u8>, WireError>
Encodes a request as a whole frame, length prefix included.
WireError::TooLarge for a cover over MAX_INPUT_BYTES.
pub fn decode_request(body: &[u8]) -> Result<Request, WireError>
Decodes a request body (the bytes after the length prefix).
WireError::Truncated without a full id, WireError::TooLarge over
MAX_REQUEST_BODY.
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.
WireError::TooLarge when an image does not fit a u32 length or the
body is over MAX_REPLY_BODY.
pub fn decode_reply(body: &[u8]) -> Result<Reply, WireError>
Decodes a reply body (the bytes after the length prefix).
A WireError for a truncated, oversized or trailing body, an unknown
tag, a bad message, zero dimensions, or an image without the JPEG
signature.
pub const MAX_ERROR_BYTES: usize = 1024;
Longest error message a reply carries, in bytes.
pub const MAX_REQUEST_BODY: usize = _;
Largest request body: an id and a cover.
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