Saga Pattern

The saga for an order has four forward steps, each a local transaction in its own service: create order (status pending), reserve inventory, charge payment, ship. If every step succeeds the order is confirmed. If a step fails — payment declined at step 3 — the saga does not roll back; nothing can, the earlier steps are committed. Instead it runs the compensating actions of the completed steps in reverse: release inventory, then cancel order. The order ends in cancelled, the stock is available again, and no card was charged.

A compensation is a semantic undo, not a database rollback. Releasing a reservation is a new write that restores availability; it does not erase the fact that a reservation existed, and it may run after other customers already saw the stock as taken. The distinction matters for the things that cannot be undone: a card can be refunded (a new transaction that a customer sees on their statement), a shipment can be cancelled until the carrier picks it up, but an email that said "your order is confirmed" cannot be unsent — it can only be followed by another email. Steps with no meaningful undo go last, after every step that can fail; this is the single most important ordering rule in saga design. Ship after charge, notify after ship.

A saga is a state machine whose state is persisted after every transition. That is what makes it survive crashes: an orchestrator that dies after reserving inventory restarts, reads state = inventory_reserved, and continues with the payment step rather than starting over. Every transition is triggered by a reply or an event and moves to exactly one next state; a step that times out is a transition too (payment_pending → compensating after 60 s), because a saga that waits forever for a reply is a locked resource with extra steps. The states also define what the user sees: pending on the order page, "we are confirming your payment" — an honest intermediate state, not a fake confirmed that might later flip.

Every step and every compensation must be idempotent, because the driver will retry them after any crash or timeout, and a retry may arrive after the original finally succeeded. Reserve with the order id as the reservation key; charge with an idempotency key derived from the saga id; release a reservation by id so releasing twice is a no-op. The state machine plus idempotent steps is the whole recovery story: replay from the persisted state, re-issue the current step, ignore duplicate replies. This is the same discipline as Workflow State Graph in agent systems — explicit states, explicit transitions, persisted between steps.

Two ways to drive the machine. Orchestration: one component (the order saga orchestrator, often inside the order service) holds the state and sends commands — ReserveInventory, ChargePayment — waiting for replies. The flow is in one place, readable as the code above, and the orchestrator knows every saga's current state. Choreography: no central driver; each service reacts to events — inventory listens for OrderCreated and emits StockReserved, payment listens for StockReserved and emits PaymentCaptured or PaymentFailed, inventory listens for PaymentFailed and releases. The flow is emergent: it exists only as the sum of subscriptions, and the state of one saga is scattered across services.

Choreography is attractive for two or three steps with obvious events and no compensation; it is Event-Driven Architecture doing what it does well. It degrades as steps and failure paths multiply: nobody can answer "where is order 91 right now?" without a trace, adding a step means editing subscriptions in several services, and a missing compensation subscription — inventory never listened for PaymentFailed — fails silently until an order ships unpaid. Orchestration costs a component that must be highly available and adds a small hub of coupling, but makes the flow explicit, testable and observable. For anything with compensation, prefer orchestration.

Every step has a timeout and the timeout is a transition. Payment providers answer in 2 s or in 40 s; a saga must decide when "no reply" becomes "failed", and what it does then — compensating a charge that may have succeeded requires querying the provider by idempotency key first, then refunding if it did. Timeouts are also how the saga bounds its pending window: an order can sit in payment_pending for a minute, not for a day, and the state machine has a path out of every non-terminal state, including a path that escalates to a human queue when automation cannot decide.

Design the pending states as product features, not as embarrassments. "Order received — confirming payment" with a spinner that resolves within seconds is what every large retailer shows, because it is the truthful representation of a saga in progress. Faking confirmed and silently flipping to cancelled five seconds later is the dishonest version, and it is what teams build when they try to hide the saga from the UI. The read side of this — how the order page learns that the state changed — is a CQRS concern.