Guides

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.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
use serde::Deserialize;
4
5
#[derive(Deserialize)]
6
struct ApprovalData {
7
approved: bool,
8
approver: String,
9
reason: String,
10
}
11
12
#[task]
13
pub async fn process_order(_ctx: TaskContext, order_id: String) -> Result<()> {
14
// ...
15
}
16
17
#[workflow]
18
pub async fn order_approval(
19
ctx: WorkflowContext,
20
order_id: String,
21
) -> Result<OrderResult> {
22
ctx.set_state("status", &"pending_approval")?;
23
24
// Suspend until an external caller sends the "approve" event
25
let approval: ApprovalData = ctx
26
.wait_for_event("approve")
27
.await?;
28
29
if approval.approved {
30
ctx.set_state("status", &"approved")?;
31
ctx.execute_task(process_order, order_id.clone()).await?;
32
33
Ok(OrderResult {
34
status: "completed".to_string(),
35
approver: Some(approval.approver),
36
})
37
} else {
38
ctx.set_state("status", &"rejected")?;
39
40
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.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
#[tokio::main]
5
async fn main() -> Result<()> {
6
let client = OrcherClient::connect("http://localhost:50051").await?;
7
8
// Start the approval workflow
9
let handle = client
10
.start_workflow("order_approval", "order_123".to_string())
11
.await?;
12
13
println!("Workflow started: {}", handle.workflow_id());
14
15
// 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?;
21
22
// Wait for workflow to complete
23
let result = handle.result::<OrderResult>().await?;
24
println!("Workflow completed: {:?}", result);
25
26
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.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
use std::time::Duration;
4
5
#[task]
6
pub async fn process_order(_ctx: TaskContext, order_id: String) -> Result<()> { /* ... */ }
7
8
#[workflow]
9
pub async fn order_with_timeout(
10
ctx: WorkflowContext,
11
order_id: String,
12
) -> Result<OrderResult> {
13
// Wait up to 1 hour for approval
14
let approval: Option<ApprovalData> = ctx
15
.wait_for_event_with_timeout("approve", Duration::from_secs(3600))
16
.await?;
17
18
match approval {
19
Some(data) if data.approved => {
20
ctx.execute_task(process_order, order_id).await?;
21
22
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 escalate
35
ctx.set_state("status", &"auto_approved")?;
36
ctx.execute_task(process_order, order_id).await?;
37
38
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.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
#[task]
5
pub async fn process_order(_ctx: TaskContext, order_id: String) -> Result<()> { /* ... */ }
6
7
#[workflow]
8
pub async fn multi_step_approval(
9
ctx: WorkflowContext,
10
order_id: String,
11
) -> Result<OrderResult> {
12
// Step 1: Wait for manager approval
13
ctx.set_state("status", &"pending_manager")?;
14
let manager_approval: ApprovalData = ctx
15
.wait_for_event("manager_approve")
16
.await?;
17
18
if !manager_approval.approved {
19
return Ok(OrderResult { status: "rejected_by_manager".into(), approver: None });
20
}
21
22
// Step 2: Wait for finance approval
23
ctx.set_state("status", &"pending_finance")?;
24
let finance_approval: ApprovalData = ctx
25
.wait_for_event("finance_approve")
26
.await?;
27
28
if !finance_approval.approved {
29
return Ok(OrderResult { status: "rejected_by_finance".into(), approver: None });
30
}
31
32
// Step 3: Both approved — process order
33
ctx.set_state("status", &"approved")?;
34
ctx.execute_task(process_order, order_id).await?;
35
36
Ok(OrderResult {
37
status: "completed".to_string(),
38
approver: Some("manager+finance".to_string()),
39
})
40
}

Next Steps