Struct Context 

pub struct Context { /* private fields */ }

Provides invocation metadata and staged durable changes to Step and RPC handlers.

A Context belongs to one handler attempt and must not outlive the call. Attribute writes, Channel publications, locals, and events become visible atomically only when the handler returns successfully. Application values are freshly decoded and owned by the invocation. Heartbeats and Stream messages are emitted during the call, independently of the final result.

The Rust Context exposes cancellation, not an absolute attempt-deadline accessor. Bound external calls with their own timeout and check Self::is_cancelled between bounded units of work. The Worker observes the server-supplied attempt deadline and requests cancellation on expiry. There is no separate attempt ID accessor: use Flow ID, run ID, Step execution ID, and attempt number together for diagnostics. These identifiers do not make external effects idempotent. A re-run after crate::Client::time_travel reuses the Flow ID, run ID, and Step execution ID, and its attempt number can repeat. The Rust Context does not expose the run attempt. An idempotency key built from these values matches the effect from before time travel.

Implementations

impl Context

pub fn flow_id(&self) -> &str

Returns the application-assigned Flow ID.

pub fn run_id(&self) -> &str

Returns the server-assigned run ID for this execution.

A Flow ID identifies the application operation; a run ID identifies one server execution. Do not assume a run ID remains fixed for the entire lifetime of a Flow ID. crate::Client::time_travel keeps the run ID and starts a new run attempt of that run. A Step re-run after time travel therefore sees the same run ID as before.

pub fn flow_started_at(&self) -> SystemTime

Returns when the current Flow run started.

pub fn step_execution_id(&self) -> &str

Returns the current Step execution ID, or an empty string for an RPC.

A Step re-run after crate::Client::time_travel reuses its Step execution ID.

pub fn from_step_execution_id(&self) -> &str

Returns the predecessor Step execution ID, or an empty string when absent.

pub fn recovery_error(&self) -> Option<&RecoveryErrorInfo>

Returns the final failure that caused recovery, or None outside a recovery Step.

pub fn first_attempt_at(&self) -> SystemTime

Returns when the first attempt of this handler invocation started.

pub fn attempt(&self) -> u32

Returns the one-based handler attempt number.

With 1.35.0 (Server protocol 4): an unpersisted Async attempt start can replay with the same number. Attempts count within one method call; they are not unique external-effect identifiers. This is the handler attempt, not the run attempt. A Step re-run after crate::Client::time_travel can report attempt numbers seen before time travel.

pub fn record_heartbeat(&mut self) -> HandlerResult<()>

Records a heartbeat without a Value and clears persisted heartbeat details.

The call blocks only while the Worker’s one-frame output buffer is full. It does not wait for Dex to process the heartbeat. Flow RPC Contexts reject this operation.

Errors

Returns HandlerError for an RPC Context, cancellation, or a closed Worker response stream.

pub fn record_heartbeat_value<T: Value>( &mut self, value: T, ) -> HandlerResult<()>

Records a heartbeat carrying a typed checkpoint Value.

A later attempt can decode the most recently accepted checkpoint with Self::last_heartbeat_value. Both durability modes preserve checkpoint values. The call uses the same bounded local buffering as Self::record_heartbeat.

Examples

use dex_sdk::{Context, HandlerResult};
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
struct Checkpoint {
    offset: u64,
}

fn import_batch(context: &mut Context, next_offset: u64) -> HandlerResult<()> {
    let previous = context.last_heartbeat_value::<Checkpoint>()?;
    let offset = previous.map_or(next_offset, |checkpoint| checkpoint.offset);
    context.record_heartbeat_value(Checkpoint { offset })
}

Errors

Returns HandlerError for an RPC Context, encoding failure, cancellation, or a closed Worker response stream.

pub fn last_heartbeat_value<T: Value>(&self) -> HandlerResult<Option<T>>

Decodes the checkpoint persisted by the previous regular attempt.

None means no heartbeat Value is present. To distinguish a null Value, request an optional application type: last_heartbeat_value::<Option<T>>() returns Some(None) for a present null Value.

Errors

Returns HandlerError for an RPC Context or when the persisted Value cannot be decoded as T.

pub fn has_any_timer_fired(&self) -> bool

Returns whether any timer condition completed for this execute invocation.

pub fn has_timer_fired(&self, index: usize) -> bool

Returns whether the zero-based timer at index completed.

Missing indexes return false.

pub fn wait_for_method_failed(&self) -> bool

Returns whether execute is running because wait_for exhausted retries with Proceed.

pub fn wait_for_cancellation(&self)

Blocks the current thread until Dex cancels this handler attempt.

Use this only for interruptible application work; ordinary handlers should return normally.

pub fn is_cancelled(&self) -> bool

Returns immediately with the current handler-cancellation state.

pub fn set_step_execution_local<T: Value>( &mut self, key: &str, value: T, ) -> HandlerResult<()>

Stages a Step-execution-local value visible to later attempts of the same execution.

Errors

Returns HandlerError for an empty key or an encoding failure.

pub fn step_execution_local<T: Value>(&self, key: &str) -> HandlerResult<T>

Reads a required Step-execution-local value, including writes staged by this attempt.

Errors

Returns HandlerError for an empty key, a missing value, or a decoding failure.

pub fn record_event<T: Value>( &mut self, name: &str, value: T, ) -> HandlerResult<()>

Records one named diagnostic event with a typed payload.

Event names must be unique within the invocation.

Errors

Returns HandlerError for an empty or duplicate name or an encoding failure.

pub fn get_attribute<T: Value>( &self, attribute: &Attribute<T>, ) -> HandlerResult<Option<T>>

Reads an Attribute value, including writes staged by this invocation.

pub fn get_attribute_map<T: Value>( &self, attribute: &AttributeMap<T>, instance: &str, ) -> HandlerResult<Option<T>>

Reads one Attribute-map instance, including staged writes.

pub fn set_attribute<T: Value>( &mut self, attribute: &Attribute<T>, value: T, ) -> HandlerResult<()>

Stages a typed Attribute write.

pub fn set_attribute_map<T: Value>( &mut self, attribute: &AttributeMap<T>, instance: &str, value: T, ) -> HandlerResult<()>

Stages a typed write for one Attribute-map instance.

pub fn delete_attribute<T>( &mut self, attribute: &Attribute<T>, ) -> HandlerResult<()>

Stages deletion of an Attribute value.

pub fn delete_attribute_map<T>( &mut self, attribute: &AttributeMap<T>, instance: &str, ) -> HandlerResult<()>

Stages deletion of one Attribute-map instance.

pub fn publish<T: Value>( &mut self, channel: &Channel<T>, value: T, ) -> HandlerResult<()>

Stages one typed Channel publication.

pub fn publish_map<T: Value>( &mut self, channel: &ChannelMap<T>, instance: &str, value: T, ) -> HandlerResult<()>

Stages one typed publication to a Channel-map instance.

pub fn channel_size<T>(&self, channel: &Channel<T>) -> HandlerResult<usize>

Returns the current invocation snapshot’s Channel queue size.

pub fn channel_map_size<T>( &self, channel: &ChannelMap<T>, instance: &str, ) -> HandlerResult<usize>

Returns one Channel-map instance’s queue size.

pub fn pending_channel_messages<T: Value>( &self, channel: &Channel<T>, ) -> HandlerResult<Vec<ChannelMessage<T>>>

Returns one singleton Channel’s loaded pending-message snapshot.

pub fn pending_channel_map_messages<T: Value>( &self, channel: &ChannelMap<T>, instance: &str, ) -> HandlerResult<Vec<ChannelMessage<T>>>

Returns one Channel-map instance’s loaded pending-message snapshot.

pub fn channel_results<T: Value>( &self, channel: &Channel<T>, ) -> HandlerResult<Vec<T>>

Decodes the messages consumed by a satisfied Channel condition.

pub fn channel_map_results<T: Value>( &self, channel: &ChannelMap<T>, instance: &str, ) -> HandlerResult<Vec<T>>

Decodes messages consumed by one satisfied Channel-map condition.

pub fn write_stream<T: Value>( &mut self, stream: &Stream<T>, value: T, ) -> HandlerResult<()>

Appends one best-effort Stream message to the current Worker response stream.

The call returns after the Worker’s bounded output buffer accepts the frame. It does not wait for Dex or the Stream Store, and a later server-side write failure is not returned to the handler. One invocation may append any number of messages to the same Stream.

Errors

Returns HandlerError for an RPC or Flow timeout Context, an unregistered Stream, a capacity mismatch, encoding failure, cancellation, or a closed Worker response stream.

pub fn delete_channel_message<T>( &mut self, channel: &Channel<T>, message_id: &str, ) -> HandlerResult<()>

Stages best-effort deletion of one singleton Channel message.

pub fn delete_channel_map_message<T>( &mut self, channel: &ChannelMap<T>, instance: &str, message_id: &str, ) -> HandlerResult<()>

Stages best-effort deletion of one Channel-map message.