Struct Stream 

pub struct Stream<T> { /* private fields */ }

Defines a typed best-effort resumable message Stream owned by one Flow type.

Register the same definition in exactly one crate::PersistenceSchema. Clones share identity and may be used at Client and Step call sites. T implements Value when messages are written or read. Prefer a module-level std::sync::LazyLock definition. Capacity is a shared approximate retention budget across executions of the Flow type, not a maximum message size. Old messages can be trimmed. Streams are progress output, not durable proof that an application mutation committed. The shared budget covers one Flow type and Stream name across all Flow IDs. Background trimming removes oldest messages. At capacity a Client write can return ResourceExhausted; a message larger than the capacity can never fit and must not be retried unchanged.

Step writes also heartbeat without clearing the last checkpoint. They can be observed before the handler finishes and can repeat after retry or replay. Client reads use opaque resume tokens; pass each token unchanged. Use crate::Client::read_stream_with_timeout for forward long polling and crate::Client::list_stream_messages for newest-first retained pages.

use dex_sdk::{Context, HandlerResult, Stream};
use std::sync::LazyLock;
static PROGRESS: LazyLock<Stream<String>> =
    LazyLock::new(|| Stream::new("progress", 1024 * 1024));
fn report_progress(context: &mut Context) -> HandlerResult<()> {
    let writer = PROGRESS.buffered_text(context)?;
    writer.write("Processing started")?;
    writer.write("Processing finished")?;
    Ok(())
}

Implementations

impl<T> Stream<T>

pub fn new(name: impl Into<String>, stream_capacity_bytes: i64) -> Self

Creates a Stream with a positive approximate budget shared by all instances of its Flow.

Panics

Panics when name is empty or stream_capacity_bytes is not positive.

pub fn name(&self) -> &str

Returns the stable logical Stream name.

pub fn stream_capacity_bytes(&self) -> i64

Returns the approximate shared byte budget.

pub fn write(&self, context: &mut Context, value: T) -> HandlerResult<()>

where T: Value,

Appends one message immediately from the current Step execution.

Errors

Returns crate::HandlerError for RPC or Flow timeout Contexts, unregistered Streams, encoding failures, cancellation, or a closed Worker output stream. Dex storage failures are not acknowledged.

impl Stream<String>

pub fn buffered_text( &self, context: &mut Context, ) -> HandlerResult<BufferedTextStream>

Creates an invocation-managed writer with a one-second interval and 16 KiB threshold.

The Worker flushes remaining text before the handler result or error. The writer preserves chunks exactly, ignores empty chunks, and never splits a chunk. An empty buffer does not heartbeat. Retry does not restore unsent text and can repeat batches already sent. The threshold is soft: one large chunk can exceed it. See Stream for an example; the invocation owns final flushing.

Errors

Returns HandlerError unless this registered String Stream is used by an active Step.

pub fn buffered_text_with_options( &self, context: &mut Context, options: BufferedTextStreamOptions, ) -> HandlerResult<BufferedTextStream>

Creates an invocation-managed writer with explicit buffering settings.

Errors

Returns HandlerError for invalid settings, an unregistered Stream, cancellation, or a Context that does not belong to a Step.

Trait Implementations

impl<T: Clone> Clone for Stream<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Stream<T>

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

Formats the value using the given formatter.