Getting Started

Saga Pattern with Compensating Transactions


When a multi-service transaction fails partway through, you need to undo the steps that already succeeded. The saga pattern tracks each completed step and runs compensating actions in reverse order on failure. Orcher journals every step, so even if the process crashes during compensation, it resumes exactly where it left off — no manual cleanup required.

How it works

A saga has a shape: every forward step pushes one compensation onto a stack, and a failure pops the whole stack in reverse. You can see it in the example's widening catch blocks — the further the trip booking gets, the more there is to undo.

The Compensation Stack
Forward step
If it fails, undo
book_flight
→
nothing — first step
book_hotel
→
↺ cancel_flight
book_car
→
↺ cancel_hotel → cancel_flight
Each completed step adds one compensation; failure pops them newest-first.

Example: booking a trip with rollback

1
import {
2
Workflow,
3
Tasks,
4
Task,
5
WorkflowContext,
6
createTaskRefs,
7
} from '@orcher/sdk';
8
9
@Tasks()
10
class TravelTasks {
11
@Task()
12
async bookFlight(details: FlightDetails): Promise<Booking> {
13
return await flightApi.book(details);
14
}
15
16
@Task()
17
async bookHotel(details: HotelDetails): Promise<Booking> {
18
return await hotelApi.book(details);
19
}
20
21
@Task()
22
async bookCar(details: CarDetails): Promise<Booking> {
23
return await carApi.book(details);
24
}
25
26
@Task()
27
async cancelFlight(bookingId: string): Promise<void> {
28
await flightApi.cancel(bookingId);
29
}
30
31
@Task()
32
async cancelHotel(bookingId: string): Promise<void> {
33
await hotelApi.cancel(bookingId);
34
}
35
}
36
37
const tasks = createTaskRefs(TravelTasks);
38
39
@Workflow({ name: 'book_trip', version: '1.0.0' })
40
class BookTrip {
41
async run(ctx: WorkflowContext, input: TripBooking): Promise<BookingResult> {
42
// Step 1: Book flight
43
const flight = await ctx.executeTask(tasks.bookFlight, input.flight);
44
45
// Step 2: Book hotel (compensate flight on failure)
46
let hotel: Booking;
47
try {
48
hotel = await ctx.executeTask(tasks.bookHotel, input.hotel);
49
} catch (error) {
50
await ctx.executeTask(tasks.cancelFlight, flight.id);
51
throw error;
52
}
53
54
// Step 3: Book car (compensate hotel + flight on failure)
55
let car: Booking;
56
try {
57
car = await ctx.executeTask(tasks.bookCar, input.car);
58
} catch (error) {
59
await ctx.executeTask(tasks.cancelHotel, hotel.id);
60
await ctx.executeTask(tasks.cancelFlight, flight.id);
61
throw error;
62
}
63
64
return { flightId: flight.id, hotelId: hotel.id, carId: car.id };
65
}
66
}

Compensation actions execute in reverse order of the forward steps. Because Orcher journals each task result, compensation is durable too — a rollback interrupted by a crash resumes instead of restarting:

Crash Mid-Rollback
✗
book_carFails — rollback begins
✓
cancel_hotelCompensation completed — journaled
✗
worker diesRollback half-finished
↻
replaycancel_hotel skipped — its result is in the journal
✓
cancel_flightRollback completes — hotel is never double-cancelled
Compensation is code like any other — journaled, replayed, and finished.

Design notes

  • A compensation is a countermeasure, not an inverse. cancel_flight may incur a fee, land on a waitlist, or trigger a voucher — the system returns to a consistent state, not necessarily the original one. Name compensations after what they really do.
  • Order forward steps by how much you'd hate to undo them. Put the cheapest-to-compensate steps first and the most painful (or non-compensatable) step last — ideally the last step needs no compensation at all because nothing comes after it that can fail.
  • Compensations can fail too. Each cancel_* is a journaled task with retries; if one exhausts them, the workflow fails with the rollback exactly half-done — and the journal records precisely which compensations completed, turning a 3 a.m. mystery into a worklist.
  • The try/catch ladder doesn't scale forever. Three steps read fine; at six, track completed steps in a list and compensate in a reverse loop — or push each phase into a child workflow that owns its own compensation.

Next Steps