Struct TaskHubGrpcClient 

pub struct TaskHubGrpcClient { /* private fields */ }

Client for managing orchestrations via a gRPC connection to a sidecar.

Implementations

impl TaskHubGrpcClient

pub async fn new(host_address: &str) -> Result<Self>

Create a new client connected to the given host address.

The default address is http://localhost:4001.

Errors

Returns DurableTaskError::InvalidAddress if host_address is not a valid URI, or DurableTaskError::ConnectionFailed / DurableTaskError::GrpcError if the underlying transport cannot be established.

pub async fn with_options( host_address: &str, options: ClientOptions, ) -> Result<Self>

Create a new client connected to the given host address with custom options.

Errors

Returns DurableTaskError::InvalidAddress if host_address is not a valid URI, DurableTaskError::Other if TLS options are inconsistent (e.g. only one of client_cert_pem / client_key_pem is set, or skip_verify is requested), or DurableTaskError::ConnectionFailed / DurableTaskError::GrpcError if the underlying transport cannot be established.

pub fn from_channel(channel: Channel) -> Self

Create a client from an existing tonic Channel.

pub fn from_channel_with_options( channel: Channel, options: ClientOptions, ) -> Self

Create a client from an existing tonic Channel with custom options.

pub fn close(self)

Close the client, releasing the underlying gRPC channel.

The channel is also released when the client is dropped. This method provides an explicit, named alternative.

pub async fn schedule_new_orchestration( &mut self, orchestrator_name: &str, input: Option<String>, instance_id: Option<String>, start_at: Option<DateTime<Utc>>, ) -> Result<String>

Schedule a new orchestration instance and return its instance ID.

Errors

Returns DurableTaskError::Other if orchestrator_name or instance_id is empty, exceeds the configured identifier length, or contains control characters. Returns DurableTaskError::GrpcError if the sidecar RPC fails.

pub async fn get_orchestration_state( &mut self, instance_id: &str, fetch_payloads: bool, ) -> Result<Option<OrchestrationState>>

Get the current state of an orchestration.

Errors

Returns DurableTaskError::Other if instance_id is invalid, or DurableTaskError::GrpcError if the sidecar RPC fails. The successful result is Ok(None) if the instance does not exist.

pub async fn wait_for_orchestration_start( &mut self, instance_id: &str, fetch_payloads: bool, timeout: Option<Duration>, ) -> Result<Option<OrchestrationState>>

Wait for an orchestration to start running.

Errors

Returns DurableTaskError::Other if instance_id is invalid, DurableTaskError::Timeout if timeout elapses before the instance starts, or DurableTaskError::GrpcError if the sidecar RPC fails.

pub async fn wait_for_orchestration_completion( &mut self, instance_id: &str, fetch_payloads: bool, timeout: Option<Duration>, ) -> Result<Option<OrchestrationState>>

Wait for an orchestration to reach a terminal state.

Errors

Returns DurableTaskError::Other if instance_id is invalid, DurableTaskError::Timeout if timeout elapses before completion, or DurableTaskError::GrpcError if the sidecar RPC fails.

pub async fn raise_orchestration_event( &mut self, instance_id: &str, event_name: &str, data: Option<String>, ) -> Result<()>

Raise an event to an orchestration instance.

Errors

Returns DurableTaskError::Other if instance_id or event_name is invalid, or DurableTaskError::GrpcError if the sidecar RPC fails.

pub async fn terminate_orchestration( &mut self, instance_id: &str, output: Option<String>, recursive: bool, ) -> Result<()>

Terminate a running orchestration.

Errors

Returns DurableTaskError::Other if instance_id is invalid, or DurableTaskError::GrpcError if the sidecar RPC fails.

pub async fn suspend_orchestration( &mut self, instance_id: &str, reason: Option<String>, ) -> Result<()>

Suspend a running orchestration.

Errors

Returns DurableTaskError::Other if instance_id is invalid, or DurableTaskError::GrpcError if the sidecar RPC fails.

pub async fn resume_orchestration( &mut self, instance_id: &str, reason: Option<String>, ) -> Result<()>

Resume a suspended orchestration.

Errors

Returns DurableTaskError::Other if instance_id is invalid, or DurableTaskError::GrpcError if the sidecar RPC fails.

pub async fn purge_orchestration( &mut self, instance_id: &str, recursive: bool, ) -> Result<i32>

Purge an orchestration’s history and state by instance ID.

Returns the number of deleted instances.

Errors

Returns DurableTaskError::Other if instance_id is invalid, or DurableTaskError::GrpcError if the sidecar RPC fails.

pub async fn purge_orchestrations_by_filter( &mut self, filter: PurgeInstanceFilter, recursive: bool, ) -> Result<i32>

Purge orchestrations matching the given filter criteria.

Returns the number of deleted instances.

Examples

use dapr_durabletask::api::{OrchestrationStatus, PurgeInstanceFilter};

let filter = PurgeInstanceFilter::new()
    .with_created_time_from(chrono::Utc::now() - chrono::Duration::hours(24))
    .with_runtime_status([OrchestrationStatus::Completed, OrchestrationStatus::Failed]);

let deleted = client.purge_orchestrations_by_filter(filter, false).await.unwrap();
println!("Deleted {deleted} orchestrations");

Errors

Returns DurableTaskError::GrpcError if the sidecar RPC fails.