Reference

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, so ctx.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 Result type: workflows and tasks return orcher_sdk::Result, which the prelude exports. Don't import anyhow::Result alongside 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]
2
orcher-sdk = "0.17.0"
3
tokio = { version = "1", features = ["full"] }
4
serde = { 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

FeatureDescriptionDefault
fullEnables auto-register, derive and testingYes
auto-registerThe #[workflow], #[task], #[tasks], #[actor] and #[operations] macros, and registration of what they define when a worker is builtYes
derive#[derive(Payload)]Yes
testingorcher_sdk::testing: run workflows in memory with mocked tasksYes
compressiongzip helpers on orcher_sdk::payload::Payload. Client and worker gzip (with_gzip_compression()) work without itNo

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.

1
use orcher_sdk::prelude::*;
2
3
#[derive(Serialize, Deserialize)]
4
struct PaymentResult {
5
charge_id: String,
6
amount_cents: u64,
7
status: String,
8
}
9
10
#[task(retry = 3)]
11
async 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
}
20
21
#[task]
22
async 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.

1
use orcher_sdk::prelude::*;
2
3
#[derive(Serialize, Deserialize)]
4
struct OrderInput {
5
order_id: String,
6
amount_cents: u64,
7
}
8
9
#[derive(Serialize, Deserialize)]
10
struct OrderOutput {
11
order_id: String,
12
charge_id: String,
13
reservation_id: String,
14
status: String,
15
}
16
17
#[workflow(name = "process_order")]
18
async 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 = ctx
21
.execute_task(reserve_inventory, input.order_id.clone())
22
.await?;
23
24
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")]
3
async 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?;
10
11
// Runs every #[workflow] and #[task] in the binary until shut down.
12
worker.run().await
13
}

4. Start Workflows (Client)

1
use orcher_sdk::client::StartWorkflowOptions;
2
use orcher_sdk::prelude::*;
3
4
#[derive(Serialize, Deserialize)]
5
struct OrderInput {
6
order_id: String,
7
amount_cents: u64,
8
}
9
10
#[derive(Serialize, Deserialize)]
11
struct OrderOutput {
12
order_id: String,
13
charge_id: String,
14
reservation_id: String,
15
status: String,
16
}
17
18
#[tokio::main]
19
async fn main() -> Result<()> {
20
let client = Client::connect("http://localhost:50051").await?;
21
22
let handle = client
23
.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?;
32
33
let result: OrderOutput = handle.result().await?;
34
println!("Order {} completed: {}", result.order_id, result.status);
35
36
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