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:
1use orcher_sdk::prelude::*;2use orcher_sdk::workflow::Saga;34#[derive(Clone, Serialize, Deserialize)]5pub struct Trip {6 pub trip_id: String,7 pub amount_cents: u64,8}910#[derive(Serialize, Deserialize)]11pub struct Booking {12 pub flight: String,13 pub hotel: String,14 pub payment: String,15}1617#[task(retry = 3)]18pub async fn reserve_flight(_ctx: TaskContext, trip: Trip) -> Result<String> {19 Ok(format!("fl_{}", trip.trip_id))20}2122#[task(retry = 10)]23pub 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}2728#[task(retry = 3)]29pub async fn reserve_hotel(_ctx: TaskContext, trip: Trip) -> Result<String> {30 Ok(format!("ht_{}", trip.trip_id))31}3233#[task(retry = 10)]34pub async fn cancel_hotel(_ctx: TaskContext, trip: Trip) -> Result<bool> {35 Ok(!trip.trip_id.is_empty())36}3738#[task(retry = 3, non_retryable_errors = ["CardDeclined"])]39pub async fn charge_trip(_ctx: TaskContext, trip: Trip) -> Result<String> {40 Ok(format!("ch_{}", trip.trip_id))41}4243#[workflow]44pub async fn book_trip(ctx: WorkflowContext, trip: Trip) -> Result<Booking> {45 let mut saga = Saga::new();4647 // Each step runs its task; once it succeeds, its compensation is48 // registered with the same input.49 let flight: String = saga50 .add_step(&ctx, reserve_flight, trip.clone())51 .with_compensation(cancel_flight)52 .execute()53 .await?;54 let hotel: String = saga55 .add_step(&ctx, reserve_hotel, trip.clone())56 .with_compensation(cancel_hotel)57 .execute()58 .await?;5960 // If the charge fails for good, cancel_hotel and then cancel_flight run61 // before the error is returned.62 let payment: String = saga63 .add_step(&ctx, charge_trip, trip)64 .execute()65 .await?;6667 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, andsaga.compensate(&ctx)runs them on demand.- A failing compensation doesn't stop the others. Give compensations generous retries and make them safe to repeat.
Sagapasses the suspension through, so it never compensates a step that is merely still running. It is inorcher_sdk::workflow.
Parallel Tasks
1#[task(retry = 3)]2pub async fn resize_image(_ctx: TaskContext, url: String) -> Result<String> {3 Ok(format!("{url}?w=640"))4}56#[workflow]7pub 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 are9 // scheduled in the same activation and run in parallel.10 let calls = urls11 .into_iter()12 .map(|url| ctx.execute_task::<_, _, String>(resize_image, url));1314 // `join_all` polls every call. `try_join_all` would stop at the first15 // call still running and schedule the rest one activation at a time.16 futures::future::join_all(calls)17 .await18 .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)]2pub struct Chunk {3 pub index: usize,4 pub rows: Vec<u64>,5}67#[workflow]8pub async fn sum_chunk(_ctx: WorkflowContext, chunk: Chunk) -> Result<u64> {9 Ok(chunk.rows.iter().sum())10}1112#[workflow]13pub 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 = ctx20 .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 }3132 // 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)]2pub struct Decision {3 pub approved: bool,4 pub reviewer: String,5}67#[task]8pub 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}1314#[task]15pub async fn publish(_ctx: TaskContext, document_id: String) -> Result<String> {16 Ok(format!("published {document_id}"))17}1819#[workflow]20pub async fn review_document(ctx: WorkflowContext, document_id: String) -> Result<String> {21 let _: () = ctx.execute_task(request_review, document_id.clone()).await?;2223 let decision: Option<Decision> = ctx24 .wait_for_event_with_timeout("decision", std::time::Duration::from_secs(3 * 24 * 60 * 60))25 .await?;2627 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:
1use orcher_sdk::error::WorkflowError;23#[derive(Serialize, Deserialize)]4pub struct BatchResult {5 pub succeeded: usize,6 pub failed: Vec<String>,7}89#[task(retry = 3)]10pub async fn import_record(_ctx: TaskContext, record_id: String) -> Result<()> {11 // Import one record here.12 let _ = record_id;13 Ok(())14}1516#[workflow]17pub 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 this29 // 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)]2pub enum OrderState {3 Created,4 Paid,5 Shipped,6 Delivered,7 Cancelled,8}910#[task(retry = 3)]11pub async fn take_payment(_ctx: TaskContext, order_id: String) -> Result<bool> {12 Ok(!order_id.is_empty())13}1415#[task(retry = 3)]16pub async fn ship(_ctx: TaskContext, order_id: String) -> Result<String> {17 Ok(format!("trk_{order_id}"))18}1920#[workflow]21pub 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::Paid30 } else {31 OrderState::Cancelled32 }33 }34 OrderState::Paid => {35 let _tracking: String = ctx.execute_task(ship, order_id.clone()).await?;36 OrderState::Shipped37 }38 OrderState::Shipped => {39 let _: serde_json::Value = ctx.wait_for_event("delivered").await?;40 OrderState::Delivered41 }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:
1use std::sync::OnceLock;23/// Stands in for an HTTP or database client that is costly to create.4pub struct PartnerClient {5 base_url: String,6}78fn 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}1415#[task(retry = 3)]16pub 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)]2pub struct ExportRef {3 /// Where the task wrote its output, for example an object-store key.4 pub location: String,5 pub rows: u64,6}78#[task(timeout = 1800)]9pub 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.