fidius-host::stream
Rust
Server-streaming dispatch (FIDIUS-I-0026).
The unary seam (crate::executor) carries one value in and one value out.
This module adds the streaming seam: one call in, an unbounded pull
handle of values out.
The pieces (design decisions D1–D3)
StreamExecutor— the backend-side trait.async fn call_streamingstarts a server-streaming method and returns aChunkStream. Implemented by all three backends (Python and WASM via self-describing values; cdylib via its FFI iterator-handle ABI).ChunkStream— the host-side handle: afutures::StreamofResult<Value, CallError>. Native async (D1) — every consuming host is a tokio app, so the handle is awaited, not polled on a blocked thread.- Backpressure & cancel are structural. The host pulls with
.next().await; a backend bridge that fills a bounded channel blocks when the host stops pulling (REQ-003). Dropping theChunkStreamdrops the bridge, which tears the producer down (D3 / REQ-002).
Wire
On the wire a stream is a sequence of Frames (see fidius_core::frame):
zero or more ITEM frames terminated by exactly one END or ERROR.
ChunkStream::from_frame_bytes runs the terminal-frame state machine that
turns that byte sequence into the item stream every backend bridge feeds.
Structs
Section titled “Structs”struct ChunkStream
Section titled “struct ChunkStream”pub
Host-facing pull handle for a server-streaming plugin call.
A futures::Stream of decoded items. Pull with .next().await; the stream
ends after the producer’s END frame, or yields one final Err and then
ends on an ERROR/abort/malformed frame. Dropping the handle cancels the
call — the backend bridge observes the drop and tears its producer down.
Methods
Section titled “Methods”pub
fn new<S>(stream: S) -> Selfwhere S: Stream<Item = Result<Value, CallError>> + Send + 'static,Wrap any item stream as a ChunkStream. Backends that already produce Result<Value, CallError> items use this directly.
Source
pub fn new<S>(stream: S) -> Self where S: Stream<Item = Result<Value, CallError>> + Send + 'static, { Self { inner: Box::pin(stream), } }from_frame_bytes
Section titled “from_frame_bytes”pub
fn from_frame_bytes<S, D>(frames: S, decode_item: D) -> Selfwhere S: Stream<Item = Vec<u8>> + Send + 'static, D: Fn(&[u8]) -> Result<Value, CallError> + Send + 'static,Build a ChunkStream from a stream of raw, length-delimited frame bytes (one encoded Frame per element — the shape a serialized backend’s next() hands back: a WASM list<u8>, a cdylib buffer), applying the terminal-frame state machine:
ITEM→decode_item(payload)→Ok(value), continue.END→ stop (no item).ERROR→ oneErr(CallError::Plugin), then stop.- a malformed/truncated frame → one
Err(CallError::MalformedFrame), stop. - an
ITEMwhose payload failsdecode_item→ thatErr, then stop. - the byte source ending without a terminal frame → one
Err(CallError::StreamAborted), stop.
decode_item is caller-supplied because the ITEM payload is “one unary
return value”: for cdylib that is concrete-type bincode the typed client
decodes via wire::deserialize::<T>() then to_value; for a #[wire(raw)]
stream it is the bytes themselves. (Vanilla bincode cannot reconstruct a
self-describing Value — deserialize_any is unsupported — so there is
deliberately no fixed “bytes → Value” decode here.) The self-describing
in-process backends (Python) skip framing entirely and use Self::new.
After any error the stream is fused: subsequent polls yield None.
Source
pub fn from_frame_bytes<S, D>(frames: S, decode_item: D) -> Self where S: Stream<Item = Vec<u8>> + Send + 'static, D: Fn(&[u8]) -> Result<Value, CallError> + Send + 'static, { let stream = futures::stream::unfold( (frames.boxed(), decode_item, false), |(mut src, decode_item, done)| async move { if done { return None; } match src.next().await { // Source dried up before a terminal frame: the producer vanished. None => Some((Err(CallError::StreamAborted), (src, decode_item, true))), Some(bytes) => match Frame::decode(&bytes) { Err(e) => Some(( Err(CallError::MalformedFrame(e.to_string())), (src, decode_item, true), )), Ok(Frame::Item(payload)) => match decode_item(&payload) { Ok(v) => Some((Ok(v), (src, decode_item, false))), Err(e) => Some((Err(e), (src, decode_item, true))), }, Ok(Frame::End) => None, Ok(Frame::Error(pe)) => { Some((Err(CallError::Plugin(pe)), (src, decode_item, true))) } }, } }, ); Self::new(stream) }from_frames
Section titled “from_frames”pub
fn from_frames<D>(frames: Vec<Frame>, decode_item: D) -> Selfwhere D: Fn(&[u8]) -> Result<Value, CallError> + Send + 'static,Build a ChunkStream over a fixed, in-memory sequence of Frames. A convenience for tests and serialized-backend fixtures; runs the same terminal-frame state machine as Self::from_frame_bytes with the same caller-supplied decode_item.
Source
pub fn from_frames<D>(frames: Vec<Frame>, decode_item: D) -> Self where D: Fn(&[u8]) -> Result<Value, CallError> + Send + 'static, { let bytes: Vec<Vec<u8>> = frames .iter() .map(|f| f.encode().expect("frame encodes")) .collect(); Self::from_frame_bytes(futures::stream::iter(bytes), decode_item) }Traits
Section titled “Traits”trait StreamExecutor
Section titled “trait StreamExecutor”pub
Supertraits: PluginExecutor
Backends whose typed boundary can produce a server-streaming result.
Sits beside crate::executor::ValueExecutor: that returns one Value,
this returns a ChunkStream of them. Implemented by all three backends
(Python and WASM via self-describing values; cdylib via its FFI
iterator-handle ABI). PluginHandle routes a streaming method to
call_streaming exactly as it routes a unary one to call.
Methods
Section titled “Methods”call_streaming
Section titled “call_streaming”async
async fn call_streaming( &self, method: usize, args: Value,) -> Result<ChunkStream, CallError>Start a server-streaming call by method index. args crosses as a self-describing Value (same as the unary typed path); the result is a pull handle over the produced items.
Source
async fn call_streaming(&self, method: usize, args: Value) -> Result<ChunkStream, CallError>;