Struct Client 

pub struct Client { /* private fields */ }

Provides blocking, typed control of registered Dex Flows.

Client methods block the calling thread while an internal Tokio runtime performs gRPC and blob hydration. The Client owns its transport resources; dropping it releases them. Flow, Step, RPC, Attribute, and Channel arguments are checked against the Registry.

Examples

use dex_sdk::{BlobCache, BlobCacheConfig, Client, ClientOptions, Registry};
use std::sync::Arc;

let cache = Arc::new(BlobCache::open(BlobCacheConfig::new(
    "/tmp/dex-blobs", 64 * 1024 * 1024, 0,
)?)?);
let client = Client::try_new(Registry::new(), cache, ClientOptions::new())?;
client.health_check()?;

Implementations

impl Client

pub fn new( registry: Registry, blob_cache: Arc<BlobCache>, options: ClientOptions, ) -> Self

Creates a Client or panics when runtime or endpoint initialization fails.

Prefer Self::try_new when the application can recover from startup configuration errors.

Panics

Panics if a Tokio runtime cannot be created or the server address is invalid.

pub fn try_new( registry: Registry, blob_cache: Arc<BlobCache>, options: ClientOptions, ) -> SdkResult<Self>

Creates a Client from validated definitions, a shared BlobCache, and connection options.

Errors

Returns SdkError::Service if runtime or endpoint initialization fails. The transport connects lazily, so server availability is checked by the first operation.

pub fn start_flow<SomeFlow: Flow>( &self, flow: &SomeFlow, flow_id: &str, input: SomeFlow::StartInput, ) -> SdkResult<String>

Starts a registered Flow with server-default options.

Returns the server-assigned run ID. input is encoded for the registered starting Step.

Errors

Returns a definition or mapping error locally, SdkError::FlowAlreadyStarted for a reuse conflict, or another service-backed SdkError when Dex rejects the request.

pub fn start_flow_with_options<SomeFlow: Flow>( &self, flow: &SomeFlow, flow_id: &str, input: SomeFlow::StartInput, options: StartFlowOptions, ) -> SdkResult<String>

Starts a registered Flow with explicit lifecycle, retry, and initial persistence options.

Returns the server-assigned run ID. A missing request ID is replaced with a generated UUID.

Errors

Returns SdkError for invalid IDs, unregistered or mismatched Flow types, encoding failures, invalid option durations, reuse conflicts, and service failures.

pub fn invoke_rpc<Input: Value, Output: Value>( &self, flow_id: &str, rpc: Rpc<Input, Output>, input: Input, ) -> SdkResult<Output>

Invokes a registered RPC with typed input and decodes its typed output.

Errors

Returns SdkError::RpcLockConflict when locks cannot be acquired, WorkerInvocation for a handler failure, FlowNotActive for a terminal Flow, or a mapping/service error.

pub fn invoke_rpc_without_input<Output: Value>( &self, flow_id: &str, rpc: Rpc<(), Output>, ) -> SdkResult<Output>

Invokes a registered no-input RPC and decodes its typed output.

Returns the same errors as Self::invoke_rpc.

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

Reads one Attribute from the current run.

Returns Ok(None) when no value is stored.

pub fn get_attribute_map_instance<T: Value>( &self, flow_id: &str, attribute: &AttributeMap<T>, instance: &str, ) -> SdkResult<Option<T>>

Reads one Attribute-map instance from the current run.

Returns Ok(None) when the instance is absent.

pub fn set_attribute<T: Value>( &self, flow_id: &str, attribute: &Attribute<T>, value: T, ) -> SdkResult<()>

Writes one Attribute on an active Flow.

Errors

Returns SdkError::FlowNotActive, a value-mapping error, or a service failure.

pub fn set_attribute_map_instance<T: Value>( &self, flow_id: &str, attribute: &AttributeMap<T>, instance: &str, value: T, ) -> SdkResult<()>

Writes one Attribute-map instance on an active Flow.

Errors

Returns SdkError::FlowNotActive, a value-mapping error, or a service failure.

pub fn publish<T: Value>( &self, flow_id: &str, channel: &Channel<T>, value: T, ) -> SdkResult<()>

Publishes one typed message to a Channel on an active Flow.

pub fn publish_many<T: Value>( &self, flow_id: &str, channel: &Channel<T>, values: impl IntoIterator<Item = T>, ) -> SdkResult<()>

Publishes an ordered batch of typed messages to one Channel atomically.

pub fn publish_map<T: Value>( &self, flow_id: &str, channel: &ChannelMap<T>, instance: &str, values: impl IntoIterator<Item = T>, ) -> SdkResult<()>

Publishes an ordered batch to one Channel-map instance atomically.

pub fn write_stream<T: Value>( &self, flow_id: &str, stream: &Stream<T>, idempotency_key: &str, value: T, ) -> SdkResult<()>

Appends one typed best-effort Stream message with client idempotency.

The Flow instance need not exist or be active. Retained duplicate keys are successful first-write-wins no-ops.

Errors

Returns a definition error for an unregistered Stream, InvalidArgument for an empty ID or key containing #, a mapping error, or a FlowService failure.

pub fn read_stream<T: Value>( &self, flow_id: &str, stream: &Stream<T>, resume_token: &str, ) -> SdkResult<StreamMessage<T>>

Blocks for the next retained Stream message using the server default wait.

An empty token starts at the retained head. Pass the returned token unchanged to resume.

pub fn read_stream_with_timeout<T: Value>( &self, flow_id: &str, stream: &Stream<T>, resume_token: &str, timeout: Duration, ) -> SdkResult<StreamMessage<T>>

Blocks for the next retained Stream message with an explicit server wait.

Errors

Returns SdkError::LongPollTimeout when no message arrives, plus the same definition, duration, mapping, and service errors as Self::read_stream.

pub fn wait_for_flow(&self, flow_id: &str) -> SdkResult<FlowResult>

Blocks until a Flow closes and returns its terminal result.

Errors

Returns FlowNotFound for an unknown ID or a mapping/service error. Every terminal status is represented by FlowResult. This overload has no client-side timeout.

pub fn wait_for_flow_with_timeout( &self, flow_id: &str, timeout: Duration, ) -> SdkResult<FlowResult>

Blocks up to timeout and returns all output-bearing completions for a successful Flow.

Errors

Returns SdkError::LongPollTimeout when the timeout elapses while the Flow remains active; other errors match Self::wait_for_flow.

pub fn describe_flow(&self, flow_id: &str) -> SdkResult<FlowInfo>

Returns current identity, status, type, and start time for the latest run.

Errors

Returns SdkError::FlowNotFound for an unknown ID or a service/protocol error.

pub fn search_flows( &self, query: &str, page_size: i32, ) -> SdkResult<SearchFlowsPage>

Executes a server search query and returns its first page.

page_size must be non-negative; zero uses the server default. Indexed values are hydrated and decoded as serde_json::Value.

pub fn search_flows_page( &self, query: &str, page_size: i32, next_page_token: &str, ) -> SdkResult<SearchFlowsPage>

Continues a search with the opaque token returned by a previous page.

Keep query and page_size consistent across pages. An empty returned token marks the last page.

pub fn stop_flow( &self, flow_id: &str, options: StopFlowOptions, ) -> SdkResult<()>

Cancels, terminates, or fails an active Flow according to options.

Errors

Returns SdkError::FlowNotActive when no active run exists or another service error.

pub fn time_travel( &self, flow_id: &str, options: TimeTravelOptions, ) -> SdkResult<String>

Creates a new run by replaying an existing Flow from the selected historical point.

Returns the new server-assigned run ID.

Errors

Returns InvalidArgument for an unrepresentable time, FlowNotFound for an unknown ID, or another service error.

pub fn skip_timer( &self, flow_id: &str, step_execution: StepExecutionId, timer: TimerId, ) -> SdkResult<()>

Marks one timer in an active Step execution as satisfied immediately.

Errors

Returns InvalidArgument for an oversized index, FlowNotActive for a terminal Flow, or a service error when the Step execution or timer cannot be targeted.

pub fn wait_for_step_completion( &self, flow_id: &str, step_execution: StepExecutionId, timeout: Duration, ) -> SdkResult<()>

Blocks until one Step execution completes or timeout elapses.

Errors

Returns SdkError::LongPollTimeout on timeout, FlowNotActive when appropriate, or another service error. Successful completion returns () and does not decode Step output.

pub fn wait_for_attribute_equal<T: Value>( &self, flow_id: &str, attribute: &Attribute<T>, expected: T, timeout: Duration, ) -> SdkResult<()>

Blocks until a singleton Attribute in the current run equals expected.

String, bool, integer, and double values are supported. Object, bytes, and null values return SdkError::InvalidArgument before transport. A server-side expiry returns SdkError::LongPollTimeout.

pub fn wait_for_attribute_map_instance_equal<T: Value>( &self, flow_id: &str, attribute: &AttributeMap<T>, instance: &str, expected: T, timeout: Duration, ) -> SdkResult<()>

Blocks until one AttributeMap instance equals expected.

This targets the current run and otherwise has the same primitive-value, timeout, request-ID, and error behavior as wait_for_attribute_equal.

pub fn update_flow_config( &self, flow_id: &str, config: FlowConfig, ) -> SdkResult<()>

Replaces mutable runtime configuration fields on an active Flow.

Unset fields retain server-defined behavior.

pub fn trigger_continue_as_new(&self, flow_id: &str) -> SdkResult<()>

Requests that an active Flow roll its history into a successor run.

pub fn health_check(&self) -> SdkResult<()>

Verifies that Dex FlowService responds successfully.

Returns Ok(()) for a healthy service and a service-backed SdkError otherwise.