fidius_guest/
stream_ffi.rs

1// Copyright 2026 Colliery, Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! cdylib server-streaming FFI handle (FIDIUS-I-0026 Phase 3 / CS.1, T-0138).
16//!
17//! A `-> fidius::Stream<T>` method on the **cdylib** backend can't be a single
18//! unary call. Instead its vtable slot holds an *init* shim (with the ordinary
19//! `(in_ptr, in_len, *mut *mut u8, *mut u32) -> i32` signature, so the vtable
20//! layout is unchanged) that returns — via the standard `out_ptr` slot — a
21//! pointer to a [`FidiusStreamHandle`]. The host then pulls the stream with an
22//! **arena-style `next`** (FIDIUS-T-0138): the host passes a *reusable* buffer it
23//! owns, and the guest writes the bincode-encoded item into it — no per-item
24//! heap alloc, and no `free_buffer` FFI crossing.
25//!
26//! ```text
27//! status = (handle.next)(handle, buf_ptr, buf_cap, &mut out_len);
28//!   STATUS_OK                → one item: buf[..out_len] is the bincode-encoded item.
29//!   STATUS_STREAM_END        → clean end of stream (no item).
30//!   STATUS_BUFFER_TOO_SMALL  → out_len = required size; host grows + retries once.
31//!                              (The guest holds the serialized item across the
32//!                              retry, so no item is lost.)
33//!   STATUS_PLUGIN_ERROR      → buf[..out_len] is a bincode `PluginError`.
34//!   STATUS_SERIALIZATION_ERROR / STATUS_PANIC → as usual.
35//! (handle.drop_fn)(handle);  // run once: drops the producer + frees the handle
36//! ```
37//!
38//! Items cross as **concrete bincode of the item type** — byte-identical to the
39//! unary cdylib wire (FIDIUS-T-0137). The host decodes each item with a
40//! caller-supplied `bincode::<O>` decoder (the typed Client knows `O`).
41
42use core::ffi::c_void;
43
44use serde::Serialize;
45
46/// Per-stream handle returned by a cdylib streaming method's init shim. See the
47/// module docs for the pull protocol. `#[repr(C)]` so the guest (which builds it)
48/// and the host (which drives it) agree on the layout across the FFI boundary.
49#[repr(C)]
50pub struct FidiusStreamHandle {
51    /// Advance one item into a host-provided buffer.
52    /// `(handle, buf_ptr, buf_cap, &mut out_len) -> status`.
53    pub next: unsafe extern "C" fn(*mut FidiusStreamHandle, *mut u8, u32, *mut u32) -> i32,
54    /// Finish/cancel: drops the producer and frees the handle box. Call exactly once.
55    pub drop_fn: unsafe extern "C" fn(*mut FidiusStreamHandle),
56    /// Opaque pointer to the boxed [`StreamState<T>`], owned by the guest; freed
57    /// by `drop_fn`.
58    pub state: *mut c_void,
59}
60
61/// Outcome of [`StreamState::next_into`] — mapped to FFI status codes by the
62/// macro-generated `next` shim.
63pub enum NextStatus {
64    /// An item was written; payload is `buf[..n]`.
65    Item(usize),
66    /// No more items.
67    End,
68    /// The buffer was too small; `usize` is the size required. The item is
69    /// retained for the next call (no item lost on grow-and-retry).
70    TooSmall(usize),
71    /// Serializing the item failed.
72    SerErr,
73}
74
75/// Guest-side driver for an arena-style cdylib stream (FIDIUS-T-0138). Wraps the
76/// producer [`Stream<T>`](crate::stream_marker::Stream) and holds the *current
77/// item value* (not its bytes), so a `BUFFER_TOO_SMALL` retry re-serializes the
78/// same item rather than advancing the iterator (which would drop it) — and so
79/// the happy path serializes **directly into the host buffer with no `Vec`
80/// allocation**.
81pub struct StreamState<T> {
82    stream: crate::stream_marker::Stream<T>,
83    /// The current item awaiting delivery; `None` between items.
84    pending: Option<T>,
85}
86
87impl<T: Serialize> StreamState<T> {
88    /// Wrap a producer stream.
89    pub fn new(stream: crate::stream_marker::Stream<T>) -> Self {
90        Self {
91            stream,
92            pending: None,
93        }
94    }
95
96    /// Pull the next item (if needed) and serialize it **directly into `buf`** —
97    /// no intermediate allocation. On `TooSmall` the item value is retained and
98    /// re-serialized on the next (larger-buffer) call, so nothing is lost.
99    pub fn next_into(&mut self, buf: &mut [u8]) -> NextStatus {
100        if self.pending.is_none() {
101            match self.stream.next_item() {
102                Some(item) => self.pending = Some(item),
103                None => return NextStatus::End,
104            }
105        }
106        // SAFETY of unwrap: pending is Some by the block above.
107        let item = self.pending.as_ref().unwrap();
108        let size = match crate::wire::serialized_size(item) {
109            Ok(s) => s as usize,
110            Err(_) => return NextStatus::SerErr,
111        };
112        if size > buf.len() {
113            return NextStatus::TooSmall(size);
114        }
115        if crate::wire::serialize_into(&mut buf[..size], item).is_err() {
116            return NextStatus::SerErr;
117        }
118        self.pending = None;
119        NextStatus::Item(size)
120    }
121}
fidius_guest/stream_ffi.rs

fidius_guest/
stream_ffi.rs
