Receiving Events
Waiting for Events
Use wait_for_event() inside a workflow to suspend execution until an external caller delivers an event with the matching name. The workflow is released from the server while waiting — it consumes no resources until the event arrives.
1use orcher::prelude::*;2use anyhow::Result;3use serde::Deserialize;45#[derive(Deserialize)]6struct ApprovalData {7 approved: bool,8 approver: String,9 reason: String,10}1112#[task]13pub async fn process_order(_ctx: TaskContext, order_id: String) -> Result<()> {14 // ...15}1617#[workflow]18pub async fn order_approval(19 ctx: WorkflowContext,20 order_id: String,21) -> Result<OrderResult> {22 ctx.set_state("status", &"pending_approval")?;2324 // Suspend until an external caller sends the "approve" event25 let approval: ApprovalData = ctx26 .wait_for_event("approve")27 .await?;2829 if approval.approved {30 ctx.set_state("status", &"approved")?;31 ctx.execute_task(process_order, order_id.clone()).await?;3233 Ok(OrderResult {34 status: "completed".to_string(),35 approver: Some(approval.approver),36 })37 } else {38 ctx.set_state("status", &"rejected")?;3940 Ok(OrderResult {41 status: "rejected".to_string(),42 approver: None,43 })44 }45}Sending Events from Client
External systems send events using the workflow handle's send_event() method. The event is delivered to the workflow's journal as an EventReceived entry. If the workflow is currently waiting for that event name, it resumes immediately.
1use orcher::prelude::*;2use anyhow::Result;34#[tokio::main]5async fn main() -> Result<()> {6 let client = OrcherClient::connect("http://localhost:50051").await?;78 // Start the approval workflow9 let handle = client10 .start_workflow("order_approval", "order_123".to_string())11 .await?;1213 println!("Workflow started: {}", handle.workflow_id());1415 // Later: Send approval event (e.g., from a REST API handler)16 handle.send_event("approve", ApprovalData {17 approved: true,18 approver: "manager@company.com".to_string(),19 reason: "Approved by manager".to_string(),20 }).await?;2122 // Wait for workflow to complete23 let result = handle.result::<OrderResult>().await?;24 println!("Workflow completed: {:?}", result);2526 Ok(())27}Events with Timeout
Use wait_for_event_with_timeout() to set a deadline on how long the workflow waits. If the event doesn't arrive before the timeout, the method returns None (Rust/TS) or raises a TimeoutError (Python), letting you implement fallback behavior like auto-approval or escalation.
1use orcher::prelude::*;2use anyhow::Result;3use std::time::Duration;45#[task]6pub async fn process_order(_ctx: TaskContext, order_id: String) -> Result<()> { /* ... */ }78#[workflow]9pub async fn order_with_timeout(10 ctx: WorkflowContext,11 order_id: String,12) -> Result<OrderResult> {13 // Wait up to 1 hour for approval14 let approval: Option<ApprovalData> = ctx15 .wait_for_event_with_timeout("approve", Duration::from_secs(3600))16 .await?;1718 match approval {19 Some(data) if data.approved => {20 ctx.execute_task(process_order, order_id).await?;2122 Ok(OrderResult {23 status: "completed".to_string(),24 approver: Some(data.approver),25 })26 }27 Some(data) => {28 Ok(OrderResult {29 status: "rejected".to_string(),30 approver: None,31 })32 }33 None => {34 // Timeout — auto-approve or escalate35 ctx.set_state("status", &"auto_approved")?;36 ctx.execute_task(process_order, order_id).await?;3738 Ok(OrderResult {39 status: "auto_approved".to_string(),40 approver: Some("system".to_string()),41 })42 }43 }44}Multiple Events
Workflows can wait for multiple events in sequence to implement multi-step approval chains, staged gates, or phased processing. Each wait_for_event() call suspends independently — the workflow only proceeds when the specific named event arrives.
1use orcher::prelude::*;2use anyhow::Result;34#[task]5pub async fn process_order(_ctx: TaskContext, order_id: String) -> Result<()> { /* ... */ }67#[workflow]8pub async fn multi_step_approval(9 ctx: WorkflowContext,10 order_id: String,11) -> Result<OrderResult> {12 // Step 1: Wait for manager approval13 ctx.set_state("status", &"pending_manager")?;14 let manager_approval: ApprovalData = ctx15 .wait_for_event("manager_approve")16 .await?;1718 if !manager_approval.approved {19 return Ok(OrderResult { status: "rejected_by_manager".into(), approver: None });20 }2122 // Step 2: Wait for finance approval23 ctx.set_state("status", &"pending_finance")?;24 let finance_approval: ApprovalData = ctx25 .wait_for_event("finance_approve")26 .await?;2728 if !finance_approval.approved {29 return Ok(OrderResult { status: "rejected_by_finance".into(), approver: None });30 }3132 // Step 3: Both approved — process order33 ctx.set_state("status", &"approved")?;34 ctx.execute_task(process_order, order_id).await?;3536 Ok(OrderResult {37 status: "completed".to_string(),38 approver: Some("manager+finance".to_string()),39 })40}