README.md

Rust examples

Purpose

Runnable Rust examples for Dex Flows, Steps, and application patterns.

This application mirrors the examples shared by the Java, Python, and TypeScript applications. It intentionally depends on the published dex-sdk = "=1.31.0" crate without a repository path override.

RPC and mutation calls can return SdkError::FlowNotActiveOrNotFound when the Flow is missing or the operation requires an active execution that has ended. A query-only RPC can still read a retained terminal Flow when it has no locks, transactionality, durable effects, or Server-forced Update routing. At that confirmed read boundary, handle the error as missing or unavailable without a lifecycle probe, a short WaitForFlow timeout, or historical Step-output decoding. RPC success alone does not prove that the Flow is active.

Layout

src/
├── products/       # real-world business scenarios
├── patterns/       # design patterns
├── primitives/     # one minimal example per Dex primitive
├── server/         # Axum HTTP router
└── workflow_patterns/  # Workflow Patterns WCP-1 to WCP-43, one file per group

HTTP routes use category prefixes:

• /products/<kebab>/... — e.g. /products/job-post/create
• /patterns/<kebab>/... — e.g. /patterns/polling/start
• /primitives/<kebab>/... — e.g. /primitives/channel/approve

Run

Rust 1.97 or newer is required. Start Dex, then run the Worker and HTTP server:

cd examples/rust
dexcli dev
cargo run --locked

The examples share namespace-level slots by index type: keyword1, text1, int1, and numbered later slots such as keyword2. Use a fresh local store and a new port after changing an example's index schema.

Application searches must constrain FlowType and parenthesize caller filters. The sample search endpoints enforce their Flow type.

The pull Worker connects to 127.0.0.1:8801 and needs only an outbound connection to the Dex Server. The application serves HTTP on 127.0.0.1:8080 and stores large payload blobs under /tmp/dex-rust-examples-blobs. Override these with DEX_SERVER_ADDRESS, DEX_EXAMPLES_HTTP_ADDRESS, and DEX_BLOB_CACHE_DIR.

Worker routing is automatic. Clients do not configure Worker targets.

Products

Every shared product example has a distinct Rust Flow and implementation file.

Java/Python/TypeScript example	Rust Flow	Demonstrated SDK features
Money transfer	MoneyTransferFlow	Debit/credit saga, Execute retry, and compensation
Order processing	OrderProcessingFlow	Charge, seller Channel + reminder Timer, ship retry, refund
Microservice orchestration	OrchestrationFlow	Parallel Steps, Attribute swap RPC, Channel-or-timer wait
Engagement	EngagementFlow	Indexed status, decision RPCs, reminders, external notification
Subscription	SubscriptionFlow	Billing timers, concurrent control Step, update/cancel RPCs
User onboarding process	UserOnboardingFlow	Email verification and two ordered tasks with durable reminders
Job posting	JobPostingFlow	Locked, versioned RPC updates feeding independent FIFO LinkedIn and Indeed Channel consumers
Deal DSL	DealDSLFlow	Durable state-machine interpreter with keyed condition waits and one-action checkpoints

Patterns

Every shared design-pattern Flow is independently registered; multi-Flow patterns remain split so their orchestration boundaries are visible.

Java/Python/TypeScript pattern	Rust Flow	Demonstrated SDK features
Cron schedule	CronScheduleFlow	Fixed-interval durable timer loop
Drain internal Channel	DrainInternalChannelFlow	Internal publication, one-at-a-time drain, sentinel completion
Draining External Channel Publishing	DrainingExternalChannelFlow	RPC publication, one-at-a-time drain, conditional completion
Interruptible execution	InterruptibleFlow	Graceful interrupt handling
Manual recovery	ManualRecoveryFlow	Exhausted retry recovery and manual Channel decision
Static parallel Steps	StaticParallelStepsFlow	A fixed set of concurrent Step types
Dynamic parallel Steps	DynamicParallelStepsFlow	A runtime-sized set of one Step type
Await parallel Steps	AwaitParallelStepsFlow	Join every worker's result
First-win parallel Steps	FirstWinParallelStepsFlow	Keep the first result and cancel siblings
Basic SubFlow fan-out	BasicParentFlow	Wait for half of the SubFlows and cancel the remaining IDs
Long-lived SubFlow parent	AdvancedLongLiveParentFlow	Bounded workers, request Channel, stop Attribute, and SubFlow loop
Short-lived SubFlow parent	AdvancedShortLiveParentFlow	Locked active count and atomic completion when the Channel is empty
Partitioning and back pressure	SubmitRequestFlow	Stable parent partitioning and durable retries after admission rejection
Polling	PollingFlow	One long-running Execute loop with heartbeats, a progress Stream, and an engine-enforced maximum wait
Failure recovery	FailureRecoveryFlow	Retry exhaustion and compensation Step
Reminders	ReminderFlow	Reminder loop, accept/opt-out Channels, global timeout
Inactiveness Tracker Timer	InactivenessTrackerFlow	Activity resets a timer; expiry processes inactiveness
Entity Store	UserProfileFlow	Attribute Store projection and profile RPCs
Timeout handling	FlowGracefulTimeout	Task-versus-timeout race and forced completion/failure
Wait for Step completion	WaitForStepCompletionFlow	Client::wait_for_step_completion target followed by background work

Workflow Patterns

src/workflow_patterns implements the control-flow patterns of the Workflow Patterns Initiative (WCP-1 to WCP-43) as 36 Flows, grouped by pattern category. The shared mapping names every Flow, Step, Channel, Attribute, and RPC, and states what each test asserts. The Flows have no HTTP routes; tests/workflow_patterns.rs drives them through the Client.

The Java retrying-Worker example and Python basic/resource-control/AI-agent examples are language-specific. The Go Deal DSL browser UI and PostgreSQL catalog remain in its separate dex-deal-dsl binary.

Verify

make fmt-check
make clippy
make test
./run-integration-tests.sh

The catalog integration test constructs every Flow, checks the exact 8 + 23 mapping and the 36 Workflow Patterns Flows, rejects duplicate names, validates all definitions in one Registry, and ensures the manifest uses the published crate rather than a local path.

The integration script starts the current checkout's dexcli dev, then starts and verifies Money Transfer, Engagement, Microservice, Subscription, Deal DSL, and Failure Recovery Flows through the published Rust SDK. It then runs the Workflow Patterns tests.

All tests use server-zd and pull Workers. DEX_INTEG_ENGINE=zd remains accepted. Set DEX_SERVER_ZD_BINARY to reuse a built dex-server-zd.

The Go examples support ./run-e2e-tests.sh --keep-running to leave Dex running after E2E tests for manual HTTP exploration.