Struct StreamingContext 

pub struct StreamingContext { /* private fields */ }

Per-invocation streaming context. Owns the producer end of the mpsc::Sender<Vec<u8>> channel into which guest-emitted chunks are pushed; the API gateway holds the matching receiver and forwards the bytes onto the wire.

Cloning is cheap (a refcount bump on each of the two Arc fields). The atomic byte-counter is shared across clones so the per-invocation cap remains a single source of truth even if the context is duplicated across host-fn closures.

Implementations

impl StreamingContext

pub fn disabled() -> Self

Construct a context with streaming disabled. Every emit_chunk returns -1; useful as the default for invocations the gateway did not opt into the streaming response path.

pub fn with_channel(sender: Sender<Vec<u8>>) -> Self

Construct a context wired to sender. Bytes pushed via emit_chunk are forwarded onto the channel; the gateway-side receiver drives the SSE / chunked response body.

The total-bytes cap defaults to MAX_TOTAL_STREAM_BYTES — embedders that need a different cap should construct the context directly via Self::with_channel_and_cap.

pub fn with_channel_and_cap(sender: Sender<Vec<u8>>, max_total: u64) -> Self

Construct a context wired to sender with an explicit total-bytes cap. Intended primarily for tests that exercise the cap branch without having to emit 64 MiB of data.

pub async fn emit_chunk(&self, bytes: Vec<u8>) -> i32

Forward bytes to the downstream receiver if streaming is enabled.

Returns:

• 0 on success (bytes accepted). The chunk’s contribution is added to Self::bytes_emitted.
• -1 if streaming is disabled (no channel attached).
• -2 if accepting this chunk would push the total past max_total. The counter is rolled back afterward.
• -3 if the receiver has been dropped — the downstream HTTP client disconnected. The counter is rolled back symmetrically.

Concurrency note: the running total is maintained with an optimistic fetch_add followed by a rollback on the failure branches, so it reflects only successfully forwarded bytes once quiescent. While concurrent emits are in flight, a reader of Self::bytes_emitted may briefly observe a value above the bytes actually forwarded — each in-flight emit can overshoot by its own chunk size before its rollback lands, so with the per-call cap the transient overshoot is bounded by roughly 2 * MAX_CHUNK_BYTES per racing emit. The overshoot is reconciled (rolled back) before each failing call returns; it never causes the cap to under-count accepted bytes.

pub fn flush(&self) -> i32

Flush any buffered chunks. The scaffold uses an unbuffered mpsc::Sender whose send already delivers per-call, so this is a no-op. v0.4 may introduce a coalescing buffer in front of the channel; the flush hook is reserved for that.

Returns 0 on success, -1 when streaming is disabled.

pub fn bytes_emitted(&self) -> u64

Snapshot of bytes successfully emitted so far. Reads through Ordering::SeqCst for symmetry with Self::emit_chunk.

pub fn is_enabled(&self) -> bool

true if a receiver channel is attached (i.e. the invocation was dispatched through the streaming response path).

Trait Implementations

impl Clone for StreamingContext

fn clone(&self) -> StreamingContext

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StreamingContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.