Reference

Patterns


Patterns that come up often, written against the Rust SDK. Each one is complete code that compiles against orcher-sdk 0.7.

One rule runs through all of them: a step that hasn't finished yet returns the suspension error, and it must reach the worker unchanged. Handle the specific errors you mean to handle and return the rest (Handling Failures).


Saga (Compensation)

When a business operation spans several services, undo the steps that succeeded if a later one fails. The SDK's Saga keeps the list of compensations and runs them in reverse order:

1
use orcher_sdk::prelude::*;
2
use orcher_sdk::workflow::Saga;
3
4
#[derive(Clone, Serialize, Deserialize)]
5
pub struct Trip {
6
pub trip_id: String,
7
pub amount_cents: u64,
8
}
9
10
#[derive(Serialize, Deserialize)]
11
pub struct Booking {
12
pub flight: String,
13
pub hotel: String,
14
pub payment: String,
15
}
16
17
#[task(retry = 3)]
18
pub async fn reserve_flight(_ctx: TaskContext, trip: Trip) -> Result<String> {
19
Ok(format!("fl_{}", trip.trip_id))
20
}
21
22
#[task(retry = 10)]
23
pub async fn cancel_flight(_ctx: TaskContext, trip: Trip) -> Result<bool> {
24
// Cancel by trip id; safe to repeat.
25
Ok(!trip.trip_id.is_empty())
26
}
27
28
#[task(retry = 3)]
29
pub async fn reserve_hotel(_ctx: TaskContext, trip: Trip) -> Result<String> {
30
Ok(format!("ht_{}", trip.trip_id))
31
}
32
33
#[task(retry = 10)]
34
pub async fn cancel_hotel(_ctx: TaskContext, trip: Trip) -> Result<bool> {
35
Ok(!trip.trip_id.is_empty())
36
}
37
38
#[task(retry = 3, non_retryable_errors = ["CardDeclined"])]
39
pub async fn charge_trip(_ctx: TaskContext, trip: Trip) -> Result<String> {
40
Ok(format!("ch_{}", trip.trip_id))
41
}
42
43
#[workflow]
44
pub async fn book_trip(ctx: WorkflowContext, trip: Trip) -> Result<Booking> {
45
let mut saga = Saga::new();
46
47
// Each step runs its task; once it succeeds, its compensation is
48
// registered with the same input.
49
let flight: String = saga
50
.add_step(&ctx, reserve_flight, trip.clone())
51
.with_compensation(cancel_flight)
52
.execute()
53
.await?;
54
let hotel: String = saga
55
.add_step(&ctx, reserve_hotel, trip.clone())
56
.with_compensation(cancel_hotel)
57
.execute()
58
.await?;
59
60
// If the charge fails for good, cancel_hotel and then cancel_flight run
61
// before the error is returned.
62
let payment: String = saga
63
.add_step(&ctx, charge_trip, trip)
64
.execute()
65
.await?;
66
67
saga.commit();
68
Ok(Booking {
69
flight,
70
hotel,
71
payment,
72
})
73
}
  • add_step(&ctx, task, input).with_compensation(task).execute() runs the task and, once it succeeds, registers the compensation with the same input. If the task fails, the compensations registered so far run, last first, and the task's error is returned.
  • execute_without_compensation() runs a step with nothing to undo; its failure doesn't trigger compensation.
  • saga.add_compensation(task, input) registers a compensation for a step you ran yourself, and saga.compensate(&ctx) runs them on demand.
  • A failing compensation doesn't stop the others. Give compensations generous retries and make them safe to repeat.
  • Saga passes the suspension through, so it never compensates a step that is merely still running. It is in orcher_sdk::workflow.

Parallel Tasks

1
#[task(retry = 3)]
2
pub async fn resize_image(_ctx: TaskContext, url: String) -> Result<String> {
3
Ok(format!("{url}?w=640"))
4
}
5
6
#[workflow]
7
pub async fn resize_all(ctx: WorkflowContext, urls: Vec<String>) -> Result<Vec<String>> {
8
// Build every call first, then await them together, so all the tasks are
9
// scheduled in the same activation and run in parallel.
10
let calls = urls
11
.into_iter()
12
.map(|url| ctx.execute_task::<_, _, String>(resize_image, url));
13
14
// `join_all` polls every call. `try_join_all` would stop at the first
15
// call still running and schedule the rest one activation at a time.
16
futures::future::join_all(calls)
17
.await
18
.into_iter()
19
.collect()
20
}

All the tasks are scheduled in one activation and run on whichever workers are free. Collecting the Vec<Result<_>> into a Result<Vec<_>> returns the first error, which is the suspension while any task is still running.


Fan-Out / Fan-In with Child Workflows

For work that is itself a multi-step workflow, or too large for one workflow's history, start a child per unit of work:

1
#[derive(Serialize, Deserialize)]
2
pub struct Chunk {
3
pub index: usize,
4
pub rows: Vec<u64>,
5
}
6
7
#[workflow]
8
pub async fn sum_chunk(_ctx: WorkflowContext, chunk: Chunk) -> Result<u64> {
9
Ok(chunk.rows.iter().sum())
10
}
11
12
#[workflow]
13
pub async fn sum_all(ctx: WorkflowContext, rows: Vec<u64>) -> Result<u64> {
14
// Fan out: start one child per chunk without waiting.
15
let mut children = Vec::new();
16
for (index, rows) in rows.chunks(1_000).enumerate() {
17
let options = ChildWorkflowOptions::new()
18
.workflow_id(format!("{}-chunk-{index}", ctx.workflow_id()));
19
let child = ctx
20
.start_child_workflow_with_options(
21
"sum_chunk",
22
Chunk {
23
index,
24
rows: rows.to_vec(),
25
},
26
options,
27
)
28
.await?;
29
children.push(child);
30
}
31
32
// Fan in: wait for each result.
33
let mut total = 0;
34
for child in children {
35
let partial: u64 = child.result().await?;
36
total += partial;
37
}
38
Ok(total)
39
}

start_child_workflow_with_options returns a handle without waiting, so all the children start before the parent waits on any of them. Each child has its own history, which keeps the parent's small. Ids derived from the parent's id are unique per parent and the same on replay.


Human-in-the-Loop

Wait for a person, with a deadline:

1
#[derive(Serialize, Deserialize)]
2
pub struct Decision {
3
pub approved: bool,
4
pub reviewer: String,
5
}
6
7
#[task]
8
pub async fn request_review(_ctx: TaskContext, document_id: String) -> Result<()> {
9
// Notify reviewers here, with a link that sends the "decision" event.
10
let _ = document_id;
11
Ok(())
12
}
13
14
#[task]
15
pub async fn publish(_ctx: TaskContext, document_id: String) -> Result<String> {
16
Ok(format!("published {document_id}"))
17
}
18
19
#[workflow]
20
pub async fn review_document(ctx: WorkflowContext, document_id: String) -> Result<String> {
21
let _: () = ctx.execute_task(request_review, document_id.clone()).await?;
22
23
let decision: Option<Decision> = ctx
24
.wait_for_event_with_timeout("decision", std::time::Duration::from_secs(3 * 24 * 60 * 60))
25
.await?;
26
27
match decision {
28
Some(d) if d.approved => ctx.execute_task(publish, document_id).await,
29
Some(d) => Ok(format!("rejected by {}", d.reviewer)),
30
None => Ok("no decision within three days".to_string()),
31
}
32
}

A client delivers the decision with handle.send_event("decision", ...) (Client). The deadline is a durable timer, so the workflow can wait for days without holding a worker.


Partial Failures in a Batch

Record the items that fail and carry on with the rest:

1
use orcher_sdk::error::WorkflowError;
2
3
#[derive(Serialize, Deserialize)]
4
pub struct BatchResult {
5
pub succeeded: usize,
6
pub failed: Vec<String>,
7
}
8
9
#[task(retry = 3)]
10
pub async fn import_record(_ctx: TaskContext, record_id: String) -> Result<()> {
11
// Import one record here.
12
let _ = record_id;
13
Ok(())
14
}
15
16
#[workflow]
17
pub async fn import_all(ctx: WorkflowContext, record_ids: Vec<String>) -> Result<BatchResult> {
18
let mut result = BatchResult {
19
succeeded: 0,
20
failed: Vec::new(),
21
};
22
for record_id in record_ids {
23
let outcome: Result<()> = ctx.execute_task(import_record, record_id.clone()).await;
24
match outcome {
25
Ok(()) => result.succeeded += 1,
26
// Only a task that failed for good counts as a failed record.
27
Err(Error::Workflow(WorkflowError::TaskFailed { .. })) => result.failed.push(record_id),
28
// Anything else, the suspension signal included, ends this
29
// activation: pass it on.
30
Err(other) => return Err(other),
31
}
32
ctx.set_state("progress", &result.succeeded)?;
33
}
34
Ok(result)
35
}

Only WorkflowError::TaskFailed is counted as a failed item. A catch-all Err(_) arm would count every item whose task is still running as failed.


State Machine

1
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
2
pub enum OrderState {
3
Created,
4
Paid,
5
Shipped,
6
Delivered,
7
Cancelled,
8
}
9
10
#[task(retry = 3)]
11
pub async fn take_payment(_ctx: TaskContext, order_id: String) -> Result<bool> {
12
Ok(!order_id.is_empty())
13
}
14
15
#[task(retry = 3)]
16
pub async fn ship(_ctx: TaskContext, order_id: String) -> Result<String> {
17
Ok(format!("trk_{order_id}"))
18
}
19
20
#[workflow]
21
pub async fn order_lifecycle(ctx: WorkflowContext, order_id: String) -> Result<OrderState> {
22
let mut state = OrderState::Created;
23
loop {
24
ctx.set_state("state", &state)?;
25
state = match state {
26
OrderState::Created => {
27
let paid: bool = ctx.execute_task(take_payment, order_id.clone()).await?;
28
if paid {
29
OrderState::Paid
30
} else {
31
OrderState::Cancelled
32
}
33
}
34
OrderState::Paid => {
35
let _tracking: String = ctx.execute_task(ship, order_id.clone()).await?;
36
OrderState::Shipped
37
}
38
OrderState::Shipped => {
39
let _: serde_json::Value = ctx.wait_for_event("delivered").await?;
40
OrderState::Delivered
41
}
42
OrderState::Delivered | OrderState::Cancelled => return Ok(state),
43
};
44
}
45
}

Expose the current state with a query handler that reads ctx.get_state("state") (Queries).


Long-Running Loops

A workflow that loops for weeks, polling or processing a stream, grows its history with every step, and replay reads all of it. Restart it with a fresh history every so many iterations, passing on the state it needs, with ctx.restart_fresh_with (Workflows).


Sharing Expensive Clients

Create HTTP clients, connection pools and SDK clients once per worker process, not once per task attempt:

1
use std::sync::OnceLock;
2
3
/// Stands in for an HTTP or database client that is costly to create.
4
pub struct PartnerClient {
5
base_url: String,
6
}
7
8
fn partner() -> &'static PartnerClient {
9
static CLIENT: OnceLock<PartnerClient> = OnceLock::new();
10
CLIENT.get_or_init(|| PartnerClient {
11
base_url: std::env::var("PARTNER_URL").unwrap_or_else(|_| "https://partner.example.com".to_string()),
12
})
13
}
14
15
#[task(retry = 3)]
16
pub async fn notify_partner(_ctx: TaskContext, order_id: String) -> Result<String> {
17
// Built once per worker process and reused by every task attempt.
18
let client = partner();
19
Ok(format!("{}/orders/{order_id}", client.base_url))
20
}

Passing Large Data by Reference

Each payload is limited to 8 MiB by default, and every activation of a workflow carries the payloads it has received. Write large results to object storage or a database and pass a reference:

1
#[derive(Serialize, Deserialize)]
2
pub struct ExportRef {
3
/// Where the task wrote its output, for example an object-store key.
4
pub location: String,
5
pub rows: u64,
6
}
7
8
#[task(timeout = 1800)]
9
pub async fn export_table(_ctx: TaskContext, table: String) -> Result<ExportRef> {
10
// Write the rows to object storage here and return where they are,
11
// not the rows themselves.
12
Ok(ExportRef {
13
location: format!("exports/{table}.parquet"),
14
rows: 1_000_000,
15
})
16
}

One Task per Item, or Batches

One task per item retries each item on its own and shows each one's outcome, at the cost of a journal entry and a scheduling round trip per item. A task per batch has less overhead, but retries the whole batch when one item fails and must keep its input and result within the payload limit. Choose by how independent the items are, and measure with your own workload.


Next Steps

  • Workflows: the workflow context
  • Tasks: retries and idempotency
  • Testing: testing these workflows with mocked tasks