fidius-guest::frame
Rust
Streaming frame format for the server-streaming plugin boundary (FIDIUS-I-0026, design decision D2).
A streaming method call yields a sequence of frames rather than one buffer. Each frame is length-delimited and self-identifying:
[ tag: u8 ][ len: u32 little-endian ][ payload: len bytes ]Three tags exist:
FRAME_ITEM— one streamed item;payloadis the existing bincode/Valuewire bytes, identical to a unary return value. Streaming therefore inherits the unary wire format verbatim (one item == one unary payload).FRAME_END— clean end of stream;len == 0, no payload.FRAME_ERROR— the producer failed mid-stream;payloadis a bincodePluginError. An error frame terminates the stream: no frames may follow it (enforced by the host-side decoder,crate::frameconsumers).
This framing is identical across every backend — a WIT list<u8> returned
per next() (WASM), a bytes object yielded by a generator (Python), or a
host-allocated buffer filled by an FFI next() export (cdylib). The scheme
is deliberately batch-compatible: a future next_batch(n) (design decision
D5) is simply n ITEM frames concatenated, needing no wire change.
enum Frame
Section titled “enum Frame”pub
One frame crossing the streaming boundary.
Item carries opaque payload bytes (the caller decides how to decode them —
typically wire::deserialize::<T>() or a Value), so this type stays
backend- and schema-neutral.
Variants
Section titled “Variants”Item- One streamed item; bytes are the bincode/Valuepayload.End- Clean end of stream.Error- Producer failed mid-stream; the stream terminates here.
Methods
Section titled “Methods”encode
Section titled “encode”pub
fn encode(&self) -> Result<Vec<u8>, WireError>Encode this frame as [tag][len][payload].
Source
pub fn encode(&self) -> Result<Vec<u8>, WireError> { let (tag, payload): (u8, Vec<u8>) = match self { Frame::Item(bytes) => (FRAME_ITEM, bytes.clone()), Frame::End => (FRAME_END, Vec::new()), Frame::Error(err) => (FRAME_ERROR, wire::serialize(err)?), }; let mut out = Vec::with_capacity(FRAME_HEADER_LEN + payload.len()); out.push(tag); out.extend_from_slice(&(payload.len() as u32).to_le_bytes()); out.extend_from_slice(&payload); Ok(out) }decode
Section titled “decode”pub
fn decode(bytes: &[u8]) -> Result<Frame, FrameError>Decode exactly one frame from bytes, which must contain a single frame and nothing more. Use Frame::read to pull one frame from a larger buffer and learn how many bytes were consumed.
Source
pub fn decode(bytes: &[u8]) -> Result<Frame, FrameError> { let (frame, consumed) = Frame::read(bytes)?; if consumed != bytes.len() { return Err(FrameError::Malformed(format!( "{} trailing byte(s) after frame", bytes.len() - consumed ))); } Ok(frame) }pub
fn read(bytes: &[u8]) -> Result<(Frame, usize), FrameError>Read one frame from the front of bytes, returning the frame and the number of bytes consumed. Lets a decoder walk a buffer holding several concatenated frames (the cdylib next_batch / Value-rail path).
Source
pub fn read(bytes: &[u8]) -> Result<(Frame, usize), FrameError> { if bytes.len() < FRAME_HEADER_LEN { return Err(FrameError::Truncated { needed: FRAME_HEADER_LEN, had: bytes.len(), }); } let tag = bytes[0]; let len = u32::from_le_bytes([bytes[1], bytes[2], bytes[3], bytes[4]]) as usize; let end = FRAME_HEADER_LEN + len; if bytes.len() < end { return Err(FrameError::Truncated { needed: end, had: bytes.len(), }); } let payload = &bytes[FRAME_HEADER_LEN..end]; let frame = match tag { FRAME_ITEM => Frame::Item(payload.to_vec()), FRAME_END => { if len != 0 { return Err(FrameError::Malformed(format!( "END frame carries {len} payload byte(s)" ))); } Frame::End } FRAME_ERROR => Frame::Error(wire::deserialize::<PluginError>(payload)?), other => return Err(FrameError::UnknownTag(other)), }; Ok((frame, end)) }enum FrameError
Section titled “enum FrameError”pub
Errors decoding a Frame from bytes.
Variants
Section titled “Variants”Truncated- Buffer ended before a full header or the declared payload was read.UnknownTag- The tag byte was not one of the known frame tags.Payload- TheERRORframe payload failed to decode as aPluginError.Malformed- AnENDorERRORframe declared a payload length it must not have, or trailing bytes followed a terminal frame in a single-frame decode.
Constants
Section titled “Constants”| Name | Type | Value | Description |
|---|---|---|---|
FRAME_ITEM |
u8 |
0 |
Frame tag: one streamed item. Payload is bincode/Value wire bytes. |
FRAME_END |
u8 |
1 |
Frame tag: clean end of stream. No payload. |
FRAME_ERROR |
u8 |
2 |
Frame tag: producer error. Payload is a bincode PluginError. |
FRAME_HEADER_LEN |
usize |
1 + 4 |
Fixed size of a frame header: one tag byte plus a u32 length. |