Guides

Best Practices


1. Keep Workflows Simple

Workflows should be thin orchestration layers that coordinate tasks. Put complex business logic, calculations, and external interactions inside tasks, not in the workflow itself. This keeps your workflow deterministic and makes individual pieces easier to test and reuse.

Good: Simple orchestration logic

1
#[workflow(name = "process_order", version = "1.0.0")]
2
pub async fn process_order(ctx: WorkflowContext, order_id: String) -> Result<String> {
3
ctx.execute_task(validate, order_id.clone()).await?;
4
ctx.execute_task(charge, order_id.clone()).await?;
5
ctx.execute_task(fulfill, order_id).await?;
6
Ok("Done".to_string())
7
}

Bad: Complex business logic in workflow

1
#[workflow(name = "complex_order", version = "1.0.0")]
2
pub async fn complex_order(ctx: WorkflowContext, order_id: String) -> Result<String> {
3
// Don't put complex calculations in workflows — they must be deterministic
4
// and this logic is harder to test in isolation
5
let tax = calculate_complex_tax(&order_id)?;
6
let discount = apply_promotional_rules(&order_id)?;
7
// ... more complex logic
8
Ok("Done".to_string())
9
}

2. Use Descriptive Names

Task and workflow names appear in logs, dashboards, and the execution history. Clear names make debugging and monitoring significantly easier. Choose names that describe the action being performed, not generic labels.

1
// Good: Clear intent — you know exactly what each step does
2
ctx.execute_task(charge_credit_card, payment_info).await?;
3
ctx.execute_task(send_confirmation_email, email_data).await?;
4
5
// Bad: Vague names — impossible to debug from logs
6
ctx.execute_task(task1, data).await?;
7
ctx.execute_task(process, info).await?;

3. Handle Errors Explicitly

Don't let errors silently propagate. If a step fails, decide whether to retry, compensate, or fail the workflow. Explicit error handling makes your workflow's behavior predictable and makes failures easier to diagnose.

1
let result = ctx.execute_task(risky_operation, data).await;
2
3
match result {
4
Ok(value) => {
5
// Handle success
6
}
7
Err(e) => {
8
// Run compensation or retry logic
9
ctx.execute_task(rollback, data).await?;
10
}
11
}

4. Use Timeouts

Always set timeouts on wait_for_event calls. Without a timeout, a workflow waiting for an event that never arrives will remain suspended forever. Timeouts give you a way to handle the "no response" case — sending a reminder, escalating, or failing gracefully.

Durable sleeps are also useful for implementing retry delays, rate limiting, and scheduled actions.

1
use std::time::Duration;
2
3
// Set reasonable timeouts for external events
4
ctx.wait_for_event_with_timeout("approval", Duration::from_secs(86400)).await?;
5
6
// Use sleep for durable delays
7
ctx.sleep(Duration::from_secs(3600)).await?;

5. Make Tasks Idempotent

Idempotent means "safe to execute more than once with the same effect." While Orcher's journaling prevents duplicate execution during normal replay, tasks can be retried due to transient failures (network timeouts, worker crashes). If a task makes an external API call, use idempotency keys to ensure the external system doesn't process the request twice.

1
#[task(name = "charge_card", retry = 3)]
2
pub async fn charge_card(_ctx: TaskContext, input: PaymentInput) -> Result<ChargeResult> {
3
// Use idempotency keys for external APIs
4
stripe::Charge::create(&stripe_client, ChargeParams {
5
idempotency_key: Some(format!("charge_{}", input.order_id)),
6
amount: input.amount,
7
// ...
8
}).await?;
9
}

Next Steps