Crate durable_workflow 

Durable Workflow Rust SDK

durable-workflow is the first-party Rust client and worker SDK for Durable Workflow. Rust applications can start and inspect workflows, run workflow and activity handlers, and exchange typed Avro values with PHP, Python, and Rust workers through one durable runtime.

Use the SDK with a self-hosted Durable Workflow Server or a managed Durable Workflow Cloud namespace. Your workers remain ordinary Rust processes and scale independently from the runtime.

Install

Rust 1.86 or newer is required.

cargo add durable-workflow

Applications using Tokio entry points should also enable the Tokio features they need:

cargo add tokio --features macros,rt-multi-thread

Run the example

examples/hello_world.rs is a complete typed workflow and activity example. It starts a workflow, runs two activities, demonstrates retry and failure handling, waits for completion, and prints the result.

Start a bootstrapped self-hosted Server, then run the example from this repository:

DURABLE_WORKFLOW_SERVER_URL=http://127.0.0.1:8080 \
DURABLE_WORKFLOW_TOKEN=dev-token \
cargo run --example hello_world

Pass the Server origin without a trailing /api. TASK_QUEUE changes the default rust-workers queue, and GREETING_NAME changes the example input.

For a provisioned Cloud namespace, use the exact runtime URL and the separate client and worker credentials shown in Cloud:

DURABLE_WORKFLOW_RUNTIME_URL=https://cloud.durable-workflow.com/api/runtime/v1/namespaces/your-namespace-id \
DURABLE_WORKFLOW_RUNTIME_NAMESPACE=your.namespace \
DURABLE_WORKFLOW_CLIENT_TOKEN=your-client-token \
DURABLE_WORKFLOW_WORKER_TOKEN=your-worker-token \
cargo run --example hello_world

The namespace runtime URL is already complete. Do not append another /api.

Core API

• Client starts, signals, queries, updates, cancels, terminates, describes, and awaits workflow executions.
• Worker registers workflow, activity, signal, query, and update handlers and long-polls task queues.
• WorkflowContext provides durable activities, timers, conditions, child workflows, side effects, version markers, parallel operations, selection, sagas, message streams, memo, search attributes, and continue-as-new.
• Typed registration and result helpers preserve Serde request and result types over the fixed Avro Value protocol.
• Activity options cover retries, start-to-close, schedule-to-start, schedule-to-close, heartbeat timeouts, cancellation, and heartbeats.

The SDK writes Avro payloads only. The fixed recursive Value schema preserves nulls, booleans, signed 64-bit integers, finite doubles, bytes, UTF-8 strings, lists, and string-keyed maps across official SDKs without customer-managed schemas or a registry.

Examples

Example	Demonstrates
hello_world.rs	Typed worker, workflow, activities, retries, and completion
activity_options.rs	Activity retry and timeout policies
condition_search_attributes.rs	Durable conditions and typed search attributes
continue_as_new.rs	Bounded histories and continue-as-new
parallel_saga.rs	Deterministic parallel work and saga compensation

Documentation

• Rust SDK landing page
• Generated API reference
• Rust SDK guide
• Self-hosted Server guide
• Cloud early access

Compatibility

The crate publishes its supported Server and worker-protocol ranges in [package.metadata.durable-workflow] in Cargo.toml. Runtime capability manifests, not matching package version strings, determine protocol compatibility. Stable releases follow semantic versioning.

Development

cargo fmt --all --check
cargo test --all-targets --all-features
cargo doc --all-features --no-deps
cargo package

Replay and codec defects require a minimal regression fixture. See CONTRIBUTING.md for the corpus rules.

License

Durable Workflow Rust SDK is released under the MIT License.

Macros

json

Construct a serde_json::Value from a JSON literal.

wait_condition

Create a durable condition wait whose predicate definition is fingerprinted from its inline Rust tokens.

Structs

ActivityCall

ActivityContext

ActivityFailure

A stable, machine-readable terminal activity failure.

ActivityHeartbeatResponse

ActivityOptions

Options recorded atomically on one deterministic schedule_activity command.

ActivityOptionsError

A machine-readable activity-options validation failure.

ActivityRetryPolicy

Durable server-side retry policy for one activity execution.

ActivityTask

ActivityTaskRejection

A worker-side activity settlement or heartbeat rejected by durable state.

CancelDurableOperationCall

Future returned by DurableOperationHandle::cancel.

ChildWorkflowAvroResult

Lossless successful child result for fixed Avro Value workflows.

ChildWorkflowCall

Future returned by WorkflowContext::start_child_workflow.

ChildWorkflowFailure

A stable, machine-readable child workflow failure delivered to its parent.

ChildWorkflowOptions

Options recorded with a child-workflow command.

ChildWorkflowResult

A successful child result together with its durable parent-child identity.

ChildWorkflowRetryPolicy

Durable retry policy for one child workflow invocation.

Client

ClientBuilder

ConditionWaitCall

Future returned by WorkflowContext::wait_condition.

ConditionWaitOptions

Stable identity and optional durable timeout for a condition wait.

ContinueAsNewOptions

Optional routing overrides for a continue-as-new transition.

ContinueAsNewOptionsError

A stable validation error raised before a continue-as-new command is emitted.

DurableOperationAwaitCall

Future returned by DurableOperationHandle::await_result.

DurableOperationCancelled

Typed result of explicitly awaiting a cancelled non-winning operation.

DurableOperationHandle

Stable reference to one member of a durable selection group.

HistoryEvent

MessageStream

MessageStreamMessage

ParallelCall

Future returned by WorkflowContext::parallel.

ParallelCompletion

One successful leaf retained when another parallel member failed.

ParallelFailure

A deterministic join failed after some siblings had already completed.

ParallelGroupError

Stable validation error returned before an invalid group emits commands.

ParallelGroupMetadata

Stable identity for one enclosing deterministic parallel group.

PayloadEnvelope

PollActivityTaskResponse

PollQueryTaskResponse

PollWorkflowTaskResponse

ProtocolFailure

A stable failure returned when a server rejects an SDK protocol version.

QueryContext

Immutable state supplied to a registered query handler.

QueryFailure

A stable, machine-readable workflow query or query-task settlement failure.

QuerySignal

One decoded signal in the committed workflow-history snapshot.

QueryTask

An ephemeral server-routed query task.

RegisterWorkerResponse

ReplayFailure

A stable, machine-readable failure raised when workflow code no longer reconstructs the durable command stream recorded in history.

Saga

Workflow-local deterministic saga compensation helper.

SagaCompensationFailure

A forward saga failure followed by a terminal compensation failure.

SearchAttributeUpdate

Validated typed workflow-side search-attribute mutation.

SelectCall

Future returned by WorkflowContext::select.

SelectionResult

The one winner committed for a durable selection group.

SignalCall

TimerCall

Future returned by WorkflowContext::sleep.

Uuid

A Universally Unique Identifier (UUID).

Worker

WorkerDeregistrationEnvelope

Result of gracefully removing a worker-plane registration.

WorkerHeartbeatObservation

WorkerRetryPolicy

Bounded retry policy for worker poll acquisition and worker heartbeats.

WorkflowCancellationRequested

Cooperative workflow cancellation observed at an author-controlled point.

WorkflowCommandOptions

Optional structured fields for a cancellation or termination request.

WorkflowCommandRejection

A stable rejection returned by instance- or selected-run lifecycle commands.

WorkflowCommandResult

The accepted, machine-readable result of a lifecycle command.

WorkflowContext

WorkflowDescription

WorkflowHandle

WorkflowHistoryBudget

Public history-budget information attached to the current workflow task.

WorkflowIdentity

The identity of one durable workflow execution.

WorkflowInstance

Typed local state owned by one deterministic workflow invocation.

WorkflowResultOptions

WorkflowStartOptions

Server-enforced timeout policy for a workflow start.

WorkflowStreamAppendItem

One item for direct or replay-safe append.

WorkflowStreamAppendResult

Durable acceptance and deduplication outcome for an append request.

WorkflowStreamDescription

Lifecycle and backlog metadata for one run-scoped Workflow Stream.

WorkflowStreamItem

One durable item at its stable zero-based offset.

WorkflowStreamPage

One bounded at-least-once subscription page.

WorkflowTask

WorkflowTerminalOutcome

A typed terminal workflow outcome with durable identity and failure metadata.

Enums

ActivityBackoff

Backoff intervals for one durable activity retry policy.

ActivityFailureKind

Stable terminal categories returned when an awaited activity does not succeed.

ActivityOptionsErrorKind

Stable validation categories for ActivityOptions.

AvroValue

Native adapter for the fixed language-neutral Avro Value schema.

ChildWorkflowFailureKind

Stable terminal categories returned when an awaited child does not succeed.

ConditionWaitOptionsError

Validation failure for a durable condition-wait definition.

ConditionWaitResult

Unambiguous terminal result of a durable condition wait.

Error

HandlerKind

The registered handler family reported by Error::HandlerType.

HandlerValueKind

Whether a typed handler failed to adapt its input or result.

ParallelAvroResult

Lossless fixed-Avro counterpart to ParallelResult.

ParallelOperation

A deferred durable leaf or nested group for WorkflowContext::parallel.

ParallelResult

One input-ordered result returned by WorkflowContext::parallel.

ParentClosePolicy

Server behavior when a parent closes while its child is still open.

SearchAttributeUpdateError

Validation failure for a typed workflow search-attribute update.

SearchAttributeValue

One public typed search-attribute value.

SelectionKey

Stable user-facing identity for one member of a durable selection group.

Value

Represents any valid JSON value.

WorkerPollOutcome

Stable classification for worker poll responses.

WorkflowCommandKind

The lifecycle command sent to a workflow execution.

WorkflowTerminalKind

Stable terminal categories returned by WorkflowHandle::result.

Constants

AVRO_VALUE_SCHEMA_FINGERPRINT

AVRO_VALUE_SCHEMA_FINGERPRINT_HEX

AVRO_VALUE_SCHEMA_JSON

Canonical Avro Value schema packaged with the crate and parsed by the runtime.

CONDITION_WAIT_MINIMUM_WORKER_PROTOCOL_VERSION

First additive worker protocol that defines external durable condition waits.

CONDITION_WAIT_OCCURRENCE_IDENTITY_CAPABILITY

Worker-registration capability for authored condition-wait occurrence identity.

CONDITION_WAIT_OCCURRENCE_IDENTITY_MINIMUM_WORKER_PROTOCOL_VERSION

First additive worker protocol that preserves authored condition-wait occurrences.

CONTROL_PLANE_VERSION

DEFAULT_CODEC

DURABLE_SELECTION_CAPABILITY

Worker-registration capability for persisted first-completion selection.

DURABLE_SELECTION_MINIMUM_WORKER_PROTOCOL_VERSION

First additive worker protocol that defines durable selection groups.

MEMO_UPSERTS_CAPABILITY

Worker-registration capability for portable memo upserts.

MEMO_UPSERT_MINIMUM_WORKER_PROTOCOL_VERSION

First additive worker protocol that defines portable memo upserts.

MESSAGE_STREAMS_CAPABILITY

Worker-registration capability for durable named input streams.

MESSAGE_STREAMS_MINIMUM_WORKER_PROTOCOL_VERSION

MESSAGE_STREAM_CURSOR_SCHEMA

MESSAGE_STREAM_MAX_BATCH

MESSAGE_STREAM_SCHEMA

MESSAGE_STREAM_SIGNAL

PORTABLE_WORKER_AFFINITY_MINIMUM_PROTOCOL_VERSION

First additive worker protocol that defines portable worker-affinity features.

QUERY_TASKS_CAPABILITY

Worker-registration capability for server-routed read-only queries.

QUERY_TASK_MINIMUM_WORKER_PROTOCOL_VERSION

First additive worker protocol that defines query-task transport.

SDK_VERSION

SEARCH_ATTRIBUTE_UPDATE_MINIMUM_WORKER_PROTOCOL_VERSION

First additive worker protocol that defines typed search-attribute upserts.

TYPED_SEARCH_ATTRIBUTES_CAPABILITY

Worker-registration capability for canonical typed search attributes.

TYPED_SEARCH_ATTRIBUTES_MINIMUM_WORKER_PROTOCOL_VERSION

First additive worker protocol that preserves declared search-attribute types.

WORKER_PROTOCOL_VERSION

WORKFLOW_UPDATES_CAPABILITY

Worker-registration capability for synchronous workflow updates.

Functions

decode_avro_value

decode_payload

encode_avro_value

encode_payload

portable_worker_affinity_capability_manifest

Truthful service-worker manifest for features this SDK currently refuses.

worker_protocol_supports_message_streams

Type Aliases

Result