Rust SDK
The Orcher Rust SDK is the orcher-sdk crate. Workflows are async functions marked #[workflow], tasks are async functions marked #[task], and a Worker built in the same binary finds and runs all of them without manual registration. A Client starts workflows, sends them events and reads their results.
- Attribute macros:
#[workflow],#[task],#[tasks],#[actor]and#[operations]generate the serialization and registration code. - Typed task references:
#[task]generates a constant named after the function, soctx.execute_task(charge_payment, input)fails to compile if the task is misspelled or renamed. Input and output types are checked when the task runs, not at compile time. - Registration at startup: every
#[workflow],#[task]and#[actor]linked into the binary is registered with the worker when it is built. - One
Resulttype: workflows and tasks returnorcher_sdk::Result, which the prelude exports. Don't importanyhow::Resultalongside it: the worker relies on the SDK's error type to tell a workflow that is waiting from one that has failed.
Installation
1[dependencies]2orcher-sdk = "0.17.0"3tokio = { version = "1", features = ["full"] }4serde = { version = "1", features = ["derive"] }The SDK is built on Tokio and needs a Tokio runtime. A worker spends most of its time waiting on long polls, so the single-threaded runtime, #[tokio::main(flavor = "current_thread")], is enough for most workers; run CPU-heavy task code with tokio::task::spawn_blocking.
Feature Flags
| Feature | Description | Default |
|---|---|---|
full | Enables auto-register, derive and testing | Yes |
auto-register | The #[workflow], #[task], #[tasks], #[actor] and #[operations] macros, and registration of what they define when a worker is built | Yes |
derive | #[derive(Payload)] | Yes |
testing | orcher_sdk::testing: run workflows in memory with mocked tasks | Yes |
compression | gzip helpers on orcher_sdk::payload::Payload. Client and worker gzip (with_gzip_compression()) work without it | No |
Turning off default features removes the macros, so keep auto-register unless you register handlers yourself.
Quick Start
1. Define Tasks
Tasks do the work that touches the outside world: API calls, database writes, file I/O. A task takes a TaskContext and exactly one input, and is retried under its retry policy when it fails.
1use orcher_sdk::prelude::*;23#[derive(Serialize, Deserialize)]4struct PaymentResult {5 charge_id: String,6 amount_cents: u64,7 status: String,8}910#[task(retry = 3)]11async fn charge_payment(_ctx: TaskContext, amount_cents: u64) -> Result<PaymentResult> {12 // Call your payment provider here. `retry = 3` allows 3 attempts in all.13 let charge_id = format!("ch_{amount_cents}");14 Ok(PaymentResult {15 charge_id,16 amount_cents,17 status: "succeeded".to_string(),18 })19}2021#[task]22async fn reserve_inventory(_ctx: TaskContext, order_id: String) -> Result<String> {23 // Call your inventory service here.24 Ok(format!("res_{order_id}"))25}2. Define a Workflow
A workflow orchestrates tasks. The engine journals each step's result, so after a crash or restart the workflow is replayed from its journal and completed steps are not run again.
1use orcher_sdk::prelude::*;23#[derive(Serialize, Deserialize)]4struct OrderInput {5 order_id: String,6 amount_cents: u64,7}89#[derive(Serialize, Deserialize)]10struct OrderOutput {11 order_id: String,12 charge_id: String,13 reservation_id: String,14 status: String,15}1617#[workflow(name = "process_order")]18async fn process_order(ctx: WorkflowContext, input: OrderInput) -> Result<OrderOutput> {19 let payment: PaymentResult = ctx.execute_task(charge_payment, input.amount_cents).await?;20 let reservation_id: String = ctx21 .execute_task(reserve_inventory, input.order_id.clone())22 .await?;2324 Ok(OrderOutput {25 order_id: input.order_id,26 charge_id: payment.charge_id,27 reservation_id,28 status: "completed".to_string(),29 })30}3. Run a Worker
The worker polls one task queue in one namespace and runs every workflow and task linked into the binary.
1// A current-thread runtime suits a worker's I/O-bound gRPC work.2#[tokio::main(flavor = "current_thread")]3async fn main() -> Result<()> {4 let worker = Worker::builder()5 .server_url("http://localhost:50051")6 .namespace("default")7 .task_queue("orders")8 .build()9 .await?;1011 // Runs every #[workflow] and #[task] in the binary until shut down.12 worker.run().await13}4. Start Workflows (Client)
1use orcher_sdk::client::StartWorkflowOptions;2use orcher_sdk::prelude::*;34#[derive(Serialize, Deserialize)]5struct OrderInput {6 order_id: String,7 amount_cents: u64,8}910#[derive(Serialize, Deserialize)]11struct OrderOutput {12 order_id: String,13 charge_id: String,14 reservation_id: String,15 status: String,16}1718#[tokio::main]19async fn main() -> Result<()> {20 let client = Client::connect("http://localhost:50051").await?;2122 let handle = client23 .start_workflow_with_options(24 "process_order",25 OrderInput {26 order_id: "ord_123".to_string(),27 amount_cents: 9999,28 },29 StartWorkflowOptions::new("orders").with_workflow_id("order-ord_123"),30 )31 .await?;3233 let result: OrderOutput = handle.result().await?;34 println!("Order {} completed: {}", result.order_id, result.status);3536 Ok(())37}Next Steps
- Workflows: the workflow context, timers, child workflows, events, determinism
- Tasks: task attributes, retries, non-retryable errors, heartbeats, cancellation
- Client: connecting with an API key and TLS, starting workflows, duplicate starts
- Worker: configuration, namespaces, graceful shutdown
- Sessions: running a series of tasks on one worker
- Actors: keyed actors with durable state
- Testing: running workflows in memory with mocked tasks
- Patterns: sagas, parallel tasks, fan-out/fan-in, approvals