Replay Safety Rules
To ensure correct replay behavior, workflows must be deterministic — the same inputs must always produce the same control flow. Any operation that could return a different result on replay must be wrapped in a journaled step.
Safe Operations (Deterministic)
These operations are safe inside workflow code because they produce the same result on every replay. Pure computation, conditional logic on deterministic data, and journaled SDK calls (execute_task, sleep) are all replay-safe.
1use orcher::prelude::*;2use anyhow::Result;34#[task]5pub async fn process_order(_ctx: TaskContext, total: f64) -> Result<String> {6 // ...7}89#[task]10pub async fn apply_vip_discount(_ctx: TaskContext, total: f64) -> Result<()> {11 // ...12}1314#[workflow]15pub async fn safe_workflow(16 ctx: WorkflowContext,17 input: OrderInput,18) -> Result<String> {19 // SAFE: Pure computation (same result every time)20 let total = input.quantity as f64 * input.price;2122 // SAFE: Task execution (journaled — result cached on replay)23 let result: String = ctx24 .execute_task(process_order, total)25 .await?;2627 // SAFE: Sleep (journaled — timer recorded in journal)28 ctx.sleep(Duration::from_secs(60)).await?;2930 // SAFE: Conditional on deterministic data31 if total > 1000.0 {32 ctx.execute_task(apply_vip_discount, total).await?;33 }3435 Ok(result)36}Unsafe Operations (Non-Deterministic)
These operations break replay because they can return different results each time. Direct API calls, reading the current time, generating random values, and accessing environment variables must always be wrapped inside a journaled task — never called directly in workflow code.
1use orcher::prelude::*;2use anyhow::Result;34#[task]5pub async fn get_current_time(_ctx: TaskContext) -> Result<u64> {6 Ok(SystemTime::now().duration_since(UNIX_EPOCH)?.as_secs())7}89#[task]10pub async fn fetch_api_data(_ctx: TaskContext, url: String) -> Result<ApiResponse> {11 let resp = reqwest::get(&url).await?.json().await?;12 Ok(resp)13}1415#[workflow]16pub async fn example_workflow(ctx: WorkflowContext, input: OrderInput) -> Result<String> {17 // UNSAFE: Current time differs on replay18 // let now = SystemTime::now();1920 // UNSAFE: Random values differ on replay21 // let random_id = rand::thread_rng().gen::<u32>();2223 // UNSAFE: Direct API call (not journaled — will re-execute on replay)24 // let response = reqwest::get("https://api.example.com").await?;2526 // CORRECT: Wrap non-deterministic operations in tasks27 let current_time: u64 = ctx.execute_task(get_current_time, ()).await?;28 let api_data: ApiResponse = ctx.execute_task(fetch_api_data, url).await?;2930 // Or use ctx.execute() for inline journaled closures31 let timestamp: u64 = ctx.execute("get_timestamp", || async {32 Ok(SystemTime::now().duration_since(UNIX_EPOCH)?.as_secs())33 }).await?;3435 Ok("result".to_string())36}Rule of Thumb: Any operation that could produce different results on replay must be wrapped in ctx.execute() or ctx.execute_task().
Viewing the Journal
Since the journal is stored in standard PostgreSQL tables, you can query it directly using SQL. This is useful for debugging workflow executions, auditing step results, and understanding the timeline of events.
SQL Query
You can query the journal directly from PostgreSQL:
1-- View all journal entries for a workflow execution2SELECT3 event_id,4 event_type,5 timestamp,6 payload7FROM workflow_execution_journal8WHERE9 workflow_id = 'order-processing-abc123'10 AND execution_id = 'exec_xyz789'11ORDER BY event_id ASC;1213-- View only step completions14SELECT15 event_id,16 payload->>'step_name' AS step_name,17 payload->'result' AS result,18 timestamp19FROM workflow_execution_journal20WHERE21 workflow_id = 'order-processing-abc123'22 AND event_type = 'StepCompleted'23ORDER BY event_id;2425-- View step-level idempotency cache26SELECT27 step_name,28 step_type,29 status,30 result,31 execution_attempt,32 duration_ms,33 created_at34FROM execution_log35WHERE workflow_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'::uuid36ORDER BY created_at;3738-- View workflow timeline with step durations39SELECT40 event_id,41 event_type,42 timestamp,43 timestamp - LAG(timestamp) OVER (ORDER BY event_id) AS duration44FROM workflow_execution_journal45WHERE workflow_id = 'order-processing-abc123'46ORDER BY event_id;Practical Examples
Example 1: API Call with Automatic Idempotency
1use orcher::prelude::*;2use anyhow::Result;34/// Task: Charge credit card via Stripe5#[task(retry = 3)]6pub async fn charge_card(7 _ctx: TaskContext,8 input: PaymentInput,9) -> Result<ChargeResult> {10 let charge = stripe::Charge::create(11 &stripe_client,12 ChargeParams {13 amount: input.amount,14 currency: "usd",15 source: input.card_token,16 idempotency_key: Some(format!("order_{}", input.order_id)),17 }18 ).await?;1920 Ok(ChargeResult {21 charge_id: charge.id,22 amount: charge.amount,23 })24}2526/// Workflow: Process payment27#[workflow]28pub async fn process_payment(29 ctx: WorkflowContext,30 input: PaymentInput,31) -> Result<PaymentResult> {32 // Once its result is journaled, replay never runs this again33 // Even if workflow crashes and replays multiple times34 let charge: ChargeResult = ctx35 .execute_task(charge_card, input)36 .await?;3738 Ok(PaymentResult {39 charge_id: charge.charge_id,40 success: true,41 })42}