Skip to content

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_streaming starts a server-streaming method and returns a ChunkStream. Implemented by all three backends (Python and WASM via self-describing values; cdylib via its FFI iterator-handle ABI).
  • ChunkStream — the host-side handle: a futures::Stream of Result<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 the ChunkStream drops 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.

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.

pub

fn new<S>(stream: S) -> Self
where
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),
}
}

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,

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 → one Err(CallError::Plugin), then stop.
  • a malformed/truncated frame → one Err(CallError::MalformedFrame), stop.
  • an ITEM whose payload fails decode_item → that Err, 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)
}

pub

fn from_frames<D>(frames: Vec<Frame>, decode_item: D) -> Self
where
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)
}

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.

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>;