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 on pull Workers with other options using server defaults.

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.

Always selects pull Workers, overriding any server-configured push target. Returns the server-assigned run ID. A missing request ID is replaced with a generated UUID. When the options contain an initial value for a hard-delete Attribute, the Client first requests the Server protocol version once and reuses the result for later calls.

Errors

Returns SdkError for invalid IDs, unregistered or mismatched Flow types, encoding failures, invalid option durations, reuse conflicts, and service failures. Returns SdkError::InvalidArgument for an invalid initial hard-delete Attribute value or a definition that does not match the registered one. Returns SdkError::Service when an initial hard-delete Attribute targets a Server older than protocol version 3.

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.

A non-transactional RPC without Attribute locks starts from a backend query. A retained terminal execution can serve it when the handler returns no durable effects. Locks, transactional execution, returned effects, or server policy can require an active execution.

Errors

Returns SdkError::RpcLockConflict when locks cannot be acquired, WorkerInvocation for a handler failure, FlowNotActiveOrNotFound when the target is missing or the selected path cannot use its closed execution, or a mapping/service error.

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

Invokes a registered RPC with typed input and additive runtime map-instance selections.

Errors

Returns a local definition error for an unregistered or wrong-kind selection. Invalid map instance names and all errors documented by Self::invoke_rpc are also returned.

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 invoke_rpc_without_input_with_options<Output: Value>( &self, flow_id: &str, rpc: Rpc<(), Output>, options: RpcInvokeOptions, ) -> SdkResult<Output>

Invokes a registered no-input RPC with additive runtime map-instance selections.

Errors

Returns the same errors as Self::invoke_rpc_with_options.

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

Appends one typed best-effort Stream message with source metadata.

The Flow instance need not exist or be active. Every call appends a message, including calls that repeat the same source. A source may contain #.

Errors

Returns a definition error for an unregistered Stream, InvalidArgument for an empty Flow ID or source, 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 list_stream_messages<T: Value>( &self, flow_id: &str, stream: &Stream<T>, page_size: i32, before_page_token: &str, ) -> SdkResult<StreamMessagesPage<T>>

Returns one newest-first page of retained Stream messages without waiting for writes.

An empty before_page_token starts at the retained tail. Pass StreamMessagesPage::next_page_token unchanged to read the next, older page. Stream trimming may remove messages between pages.

Errors

Returns InvalidArgument when flow_id is empty or page_size is not positive. Returns a definition error for an unregistered Stream, a mapping error for an incompatible retained value, or a FlowService error when the request fails.

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 search_flows_with_options( &self, query: &str, page_size: i32, next_page_token: &str, options: SearchFlowsOptions, ) -> SdkResult<SearchFlowsPage>

Searches with explicit inclusion options; retain query and options across pages. An empty token starts pagination.

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

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

Errors

Returns SdkError::FlowNotActiveOrNotFound 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, FlowNotActiveOrNotFound 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, options: WaitForStepCompletionOptions, ) -> SdkResult<()>

Blocks until one Step execution completes or its request budget expires.

The server derives a stable Request ID from the Step execution when none is supplied.

Errors

Returns SdkError::RequestTimeout when a positive request timeout expires, FlowNotActiveOrNotFound when appropriate, or another service error. Successful completion returns () and does not decode Step output.

pub fn wait_for_attribute_match<T: Value>( &self, flow_id: &str, attribute: &Attribute<T>, attribute_match: AttributeMatch<T>, options: WaitForAttributeOptions, ) -> SdkResult<T>

Blocks until a singleton Attribute in the current run satisfies attribute_match.

Returns the current value observed by the successful wait. The server derives a stable Request ID from the condition when none is supplied. String and Boolean Attributes support equality matches. Integer and floating-point Attributes support every match. A positive request-timeout expiry returns SdkError::RequestTimeout. A hard-delete Attribute, defined with Attribute::hard_delete_on_null, returns SdkError::InvalidArgument before the Client contacts Dex.

pub fn wait_for_attribute_map_instance_match<T: Value>( &self, flow_id: &str, attribute: &AttributeMap<T>, instance: &str, attribute_match: AttributeMatch<T>, options: WaitForAttributeOptions, ) -> SdkResult<T>

Blocks until one AttributeMap instance satisfies attribute_match.

This targets the current run and otherwise has the same match, request-timeout and handler-generation, request-ID, return-value, and error behavior as Self::wait_for_attribute_match. A hard-delete AttributeMap, defined with AttributeMap::hard_delete_on_null, returns SdkError::InvalidArgument before the Client contacts Dex.

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

Replaces mutable runtime configuration fields on an active Flow.

Leaves the Worker target unset, preserving the active Flow target. Other unset fields also retain the active Flow setting.

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.