Guides

Retry & Compensation


Automatic Retry

When a task fails due to a transient error — such as a network timeout, a temporary service outage, or a rate limit — Orcher can automatically retry it according to a configurable retry policy. You specify the maximum number of attempts, the delay bounds (initial and max interval), and a backoff coefficient that grows the delay exponentially (set it to 1.0 for fixed-interval retries). Inside the task, you can use ctx.attempt() to check which attempt you're on and ctx.is_retry() / ctx.isRetry() to detect whether this is a retry execution.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
// Simple retry with exponential backoff
5
#[task(
6
name = "fetch_data",
7
retry = 5 // Retry up to 5 times
8
)]
9
pub async fn fetch_data(
10
ctx: TaskContext,
11
url: String,
12
) -> Result<ApiResponse> {
13
if ctx.is_retry() {
14
tracing::warn!("Retrying fetch (attempt {})", ctx.attempt());
15
}
16
17
let response = reqwest::get(&url)
18
.await
19
.context("Failed to fetch data")?;
20
21
if response.status().is_server_error() {
22
// 5xx errors will trigger retry
23
return Err(anyhow::anyhow!("Server error: {}", response.status()));
24
}
25
26
let data = response.json().await?;
27
Ok(data)
28
}
29
30
// Advanced retry policy
31
#[task(
32
name = "critical_operation",
33
retry_policy(
34
max_attempts = 5,
35
initial_interval = 1, // 1 second
36
max_interval = 60, // Cap at 60 seconds
37
backoff_coefficient = 2.0 // Double each time (1.0 = fixed intervals)
38
)
39
)]
40
pub async fn critical_operation(
41
_ctx: TaskContext,
42
input: OperationInput,
43
) -> Result<OperationResult> {
44
// Retry delays: 1s, 2s, 4s, 8s, 16s
45
external_service::call(input).await
46
}

Retry Backoff

Orcher computes the delay between retry attempts with exponential backoff: each delay is the previous one multiplied by backoff_coefficient, starting from initial_interval and capped at max_interval. A coefficient of 2.0 doubles the delay each time; a coefficient of 1.0 keeps the interval fixed. Exponential backoff (coefficient > 1.0) is recommended for most external service calls, while a fixed interval (coefficient = 1.0) works well for predictable transient failures.

Exponential
backoff_coefficient = 2.0 · recommended
1 · immediate
2 · 1s
3 · 2s
4 · 4s
5 · 8s
6 · 16s (capped)
Fixed
backoff_coefficient = 1.0 · constant gap
1 · immediate
2 · initial_interval
3 · initial_interval
4 · initial_interval
5 · initial_interval

Delay before each attempt. Exponential multiplies by backoff_coefficient up to max_interval; a coefficient of 1.0 holds a constant gap. There is no separate linear mode.


Compensation (Saga Pattern)

The Saga pattern provides a way to maintain data consistency across multiple steps without distributed transactions. Each forward step is paired with a compensation action that undoes its effect. When a later step fails, you run the compensations for the completed steps in reverse order — your own logic, made durable by Orcher. Done consistently, this keeps the system from being stuck partially committed: either every step succeeds, or the completed ones are undone.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
#[workflow(name = "booking_saga", version = "1.0.0")]
5
pub async fn booking_saga(
6
ctx: WorkflowContext,
7
input: BookingInput,
8
) -> Result<BookingResult> {
9
// Step 1: Book hotel
10
let hotel_booking = match ctx
11
.execute_task(book_hotel, input.hotel.clone())
12
.await
13
{
14
Ok(booking) => booking,
15
Err(e) => {
16
// First step failed, no compensation needed
17
return Err(anyhow::anyhow!("Hotel booking failed: {}", e));
18
}
19
};
20
21
// Step 2: Book flight
22
let flight_booking = match ctx
23
.execute_task(book_flight, input.flight.clone())
24
.await
25
{
26
Ok(booking) => booking,
27
Err(e) => {
28
// Compensate: Cancel hotel
29
tracing::error!("Flight booking failed, canceling hotel");
30
let _ = ctx
31
.execute_task(cancel_hotel, hotel_booking.id)
32
.await;
33
34
return Err(anyhow::anyhow!("Flight booking failed: {}", e));
35
}
36
};
37
38
// Step 3: Book car rental
39
let car_booking = match ctx
40
.execute_task(book_car, input.car.clone())
41
.await
42
{
43
Ok(booking) => booking,
44
Err(e) => {
45
// Compensate: Cancel flight and hotel (reverse order)
46
tracing::error!("Car booking failed, canceling flight and hotel");
47
48
let _ = ctx
49
.execute_task(cancel_flight, flight_booking.id)
50
.await;
51
52
let _ = ctx
53
.execute_task(cancel_hotel, hotel_booking.id)
54
.await;
55
56
return Err(anyhow::anyhow!("Car booking failed: {}", e));
57
}
58
};
59
60
Ok(BookingResult {
61
hotel: hotel_booking,
62
flight: flight_booking,
63
car: car_booking,
64
status: "completed".to_string(),
65
})
66
}

Saga Visualization

The following diagrams illustrate how a saga executes forward steps and triggers compensations on failure. When a step fails, all previously completed steps are compensated in reverse order to maintain data consistency.

Successful saga
Book Hotel → success
Book Flight → success
Book Car → success
All bookings confirmed
Failed saga · with compensation
Book Hotel → success
Book Flight → success
Book Car → failure
compensation · reverse order
Cancel Flight → done
Cancel Hotel → done
All bookings rolled back

Next Steps