Struct WorkflowClient 

pub struct WorkflowClient<B> { /* private fields */ }

A client for submitting and controlling workflow instances.

Unlike CheckpointingRunner, the client does not execute tasks — it only creates initial snapshots and stores lifecycle signals. A PooledWorker (or CheckpointingRunner::resume) picks up and executes the work.

Example

use sayiir_runtime::WorkflowClient;
use sayiir_runtime::persistence::InMemoryBackend;
use sayiir_core::workflow::ConflictPolicy;

let backend = InMemoryBackend::new();
let client = WorkflowClient::new(backend)
    .with_conflict_policy(ConflictPolicy::UseExisting);

Implementations

impl<B> WorkflowClient<B>

pub fn new(backend: B) -> Self

Create a new client wrapping the given backend.

The default conflict policy is ConflictPolicy::Fail.

pub fn from_shared(backend: Arc<B>) -> Self

Create a client from a shared backend reference.

Useful when the same backend is shared with a runner or worker.

pub fn with_conflict_policy(self, policy: ConflictPolicy) -> Self

Set the conflict policy for duplicate instance IDs.

pub fn backend(&self) -> &Arc<B>

Get a reference to the backend.

impl<B> WorkflowClient<B>

where B: SnapshotStore + SignalStore,

pub async fn submit<C, Input, M>( &self, workflow: &Workflow<C, Input, M>, instance_id: impl Into<String>, input: Input, ) -> Result<(WorkflowStatus, Option<Bytes>), RuntimeError>

where Input: Send + 'static, M: Send + Sync + 'static, C: Codec + EnvelopeCodec + EncodeValue<Input> + 'static,

Submit a workflow for execution.

Creates an initial snapshot in the backend so that a PooledWorker can pick it up. Does not execute any tasks.

Returns (WorkflowStatus, Option<Bytes>):

• (InProgress, None) when a fresh snapshot was created.
• (status, output) when the conflict policy returns an existing instance.

Errors

Returns RuntimeError::InstanceAlreadyExists when the policy is Fail and the instance already exists, or propagates backend I/O errors.

pub async fn cancel( &self, instance_id: &str, reason: Option<String>, cancelled_by: Option<String>, ) -> Result<(), RuntimeError>

Request cancellation of a workflow instance.

Stores a cancel signal in the backend. The worker picks it up at the next task boundary.

Errors

Returns an error if the signal cannot be stored.

pub async fn pause( &self, instance_id: &str, reason: Option<String>, paused_by: Option<String>, ) -> Result<(), RuntimeError>

Request pausing of a workflow instance.

Stores a pause signal in the backend. The worker picks it up at the next task boundary.

Errors

Returns an error if the signal cannot be stored.

pub async fn unpause(&self, instance_id: &str) -> Result<(), RuntimeError>

Unpause a paused workflow instance.

Errors

Returns an error if the workflow is not found or not paused.

pub async fn send_event( &self, instance_id: &str, signal_name: &str, payload: Bytes, ) -> Result<(), RuntimeError>

Send an external event (signal) to a workflow instance.

The payload is buffered in FIFO order per (instance_id, signal_name).

Errors

Returns an error if the event cannot be stored.

pub async fn status( &self, instance_id: &str, ) -> Result<WorkflowStatus, RuntimeError>

Get the current status of a workflow instance.

Errors

Returns an error if the snapshot cannot be loaded.

impl<B> WorkflowClient<B>

where B: SnapshotStore + SignalStore + TaskResultStore,

pub async fn get_task_result( &self, instance_id: &str, task_id: &str, ) -> Result<Option<Bytes>, RuntimeError>

Get a single task result from a workflow instance.

Returns Ok(Some(bytes)) if the task has completed, Ok(None) if the task was never executed. For completed/failed workflows, the result is recovered from the backend’s history or cache.

Errors

Returns an error if the snapshot cannot be loaded.

pub async fn get_task_result_of<T: TaskIdentifier>( &self, instance_id: &str, ) -> Result<Option<Bytes>, RuntimeError>

Type-safe variant of get_task_result that derives the task_id from a TaskIdentifier implementor (e.g. a #[task]-generated struct).

let result = client.get_task_result_of::<ValidateOrderTask>("order-42").await?;

Errors

Returns an error if the snapshot cannot be loaded.