Saga Pattern in Practice — Designing Compensating Transactions for Microservice Distributed Systems (Choreography vs Orchestration)

[Traditional Distributed Transaction — 2PC]
BEGIN DISTRIBUTED TX
  Order Service.insert()     ← lock
  Inventory Service.update() ← lock
  Payment Service.charge()   ← lock
COMMIT (or ROLLBACK)  ← all at once
 
[Saga Pattern]
Order Service.insert()     → commit → publish event
Inventory Service.update() → commit → publish event
Payment Service.charge()   → commit  (on failure: run compensating events in reverse)

// @EventHandler is a custom decorator representing message broker subscriptions.
// It can be implemented with NestJS's @nestjs/event-emitter or a Kafka consumer wrapper.
 
// 1. Order Service — creates order and publishes event via Outbox pattern
class OrderService {
  constructor(
    private readonly orderRepo: OrderRepository,
    private readonly db: DataSource,
  ) {}
 
  async createOrder(dto: CreateOrderDto): Promise<void> {
    // Handle DB commit and event insertion in the same transaction (Outbox pattern)
    await this.db.transaction(async (em) => {
      const order = await em.save(Order, {
        ...dto,
        status: OrderStatus.PENDING,
      });
 
      await em.save(OutboxEvent, {
        aggregateId: order.id,
        type: 'ORDER_CREATED',
        payload: JSON.stringify({ orderId: order.id, items: dto.items }),
        processedAt: null,
      });
    });
  }
 
  // Compensation on receiving failure event: cancel order
  @EventHandler('INVENTORY_RESERVATION_FAILED')
  async handleReservationFailed(event: ReservationFailedEvent): Promise<void> {
    await this.db.transaction(async (em) => {
      await em.update(Order, event.orderId, { status: OrderStatus.CANCELLED });
 
      await em.save(OutboxEvent, {
        aggregateId: event.orderId,
        type: 'ORDER_CANCELLED',
        payload: JSON.stringify({ orderId: event.orderId, reason: event.reason }),
        processedAt: null,
      });
    });
  }
}
 
// 2. Inventory Service — subscribes to OrderCreated and attempts stock reservation
class InventoryService {
  constructor(private readonly db: DataSource) {}
 
  @EventHandler('ORDER_CREATED')
  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
    // Idempotency guarantee: skip if this event has already been processed
    const alreadyProcessed = await this.db.getRepository(InboxEvent)
      .existsBy({ eventId: event.eventId });
    if (alreadyProcessed) return;
 
    const available = await this.checkStock(event.items);
 
    if (!available) {
      // Bundle inbox record and failure event in the same transaction
      await this.db.transaction(async (em) => {
        await em.save(InboxEvent, { eventId: event.eventId });
        await em.save(OutboxEvent, {
          aggregateId: event.orderId,
          type: 'INVENTORY_RESERVATION_FAILED',
          payload: JSON.stringify({ orderId: event.orderId, reason: 'OUT_OF_STOCK' }),
          processedAt: null,
        });
      });
      return;
    }
 
    // reserveStock, inbox record, and success event must be bundled in a single transaction.
    // If the process dies after reserveStock but before the inbox record, a retry could double-deduct inventory.
    await this.db.transaction(async (em) => {
      await this.reserveStock(em, event.items);
      await em.save(InboxEvent, { eventId: event.eventId });
      await em.save(OutboxEvent, {
        aggregateId: event.orderId,
        type: 'INVENTORY_RESERVED',
        payload: JSON.stringify({ orderId: event.orderId }),
        processedAt: null,
      });
    });
  }
}

[Order Service]
    │ publishes ORDER_CREATED
    ▼
[Inventory Service] ──── out of stock ───► publishes INVENTORY_RESERVATION_FAILED
    │ success                                              │
    │ publishes INVENTORY_RESERVED          [Order Service] ◄──────────────┘
    ▼                                           publishes ORDER_CANCELLED
[Payment Service]
    │ publishes PAYMENT_PROCESSED
    ▼
[Order Service] → confirm order

// Saga state type definitions
type SagaStep = 'RESERVE_INVENTORY' | 'PROCESS_PAYMENT' | 'CONFIRM_ORDER';
type SagaStatus = 'RUNNING' | 'COMPLETED' | 'COMPENSATING' | 'FAILED';
 
interface SagaState {
  id: string;
  orderId: string;
  currentStep: SagaStep;
  completedSteps: SagaStep[]; // cumulatively stored in DB; referenced in reverse during compensation
  status: SagaStatus;
}
 
class OrderSagaOrchestrator {
  constructor(
    private readonly sagaRepo: SagaRepository,
    private readonly inventoryClient: InventoryClient,
    private readonly paymentClient: PaymentClient,
    private readonly orderClient: OrderClient,
  ) {}
 
  async execute(orderId: string): Promise<void> {
    const saga = await this.sagaRepo.create({
      orderId,
      currentStep: 'RESERVE_INVENTORY',
      completedSteps: [],
      status: 'RUNNING',
    });
 
    try {
      // Step 1: Reserve inventory
      await this.inventoryClient.reserve(orderId);
      // recordStep adds the given step to the completedSteps array and persists it to DB.
      // Even after an orchestrator restart, we can tell which steps completed for compensation.
      await this.sagaRepo.recordStep(saga.id, 'RESERVE_INVENTORY');
 
      // Step 2: Process payment
      await this.paymentClient.process(orderId);
      await this.sagaRepo.recordStep(saga.id, 'PROCESS_PAYMENT');
 
      // Step 3: Confirm order
      await this.orderClient.confirm(orderId);
      await this.sagaRepo.markCompleted(saga.id);
 
    } catch (error) {
      await this.sagaRepo.updateStatus(saga.id, 'COMPENSATING');
      // Re-fetch the latest completedSteps via findById to use for compensation
      await this.compensate(await this.sagaRepo.findById(saga.id));
    }
  }
 
  private async compensate(saga: SagaState): Promise<void> {
    // Run compensation in reverse order only for completed steps
    const compensations: Partial<Record<SagaStep, () => Promise<void>>> = {
      PROCESS_PAYMENT: () => this.paymentClient.refund(saga.orderId),
      RESERVE_INVENTORY: () => this.inventoryClient.release(saga.orderId),
      // CONFIRM_ORDER has no compensation — if we reached this step, everything succeeded
    };
 
    const stepsToCompensate = [...saga.completedSteps].reverse();
 
    for (const step of stepsToCompensate) {
      const compensation = compensations[step];
      if (compensation) {
        try {
          await compensation();
        } catch (err) {
          // On compensation failure: move to Dead Letter Queue or notify for manual intervention
          await this.notifyManualIntervention(saga.id, step, err);
        }
      }
    }
 
    await this.sagaRepo.markFailed(saga.id);
  }
}

[OrderSagaOrchestrator]
    │
    ├──► inventoryClient.reserve(orderId)  ✓ → completedSteps: ['RESERVE_INVENTORY']
    │
    ├──► paymentClient.process(orderId)    ✗ failed!
    │
    │    [Begin compensation — reverse order]
    ├──► inventoryClient.release(orderId)  (compensates RESERVE_INVENTORY)
    │
    └──► sagaRepo.markFailed(sagaId)

import { proxyActivities, ApplicationFailure } from '@temporalio/workflow';
import type * as activities from './activities';
 
const { reserveInventory, processPayment, cancelReservation, refundPayment } =
  proxyActivities<typeof activities>({
    startToCloseTimeout: '30s',
    retry: {
      maximumAttempts: 3,
      nonRetryableErrorTypes: ['InsufficientStockError', 'InvalidPaymentError'],
    },
  });
 
// Temporal durably manages this workflow's state via event sourcing
export async function orderSagaWorkflow(orderId: string): Promise<void> {
  let inventoryReserved = false;
  let paymentProcessed = false;
 
  try {
    await reserveInventory(orderId);
    inventoryReserved = true;
 
    await processPayment(orderId);
    paymentProcessed = true;
 
  } catch (err) {
    // Compensation — in reverse order, continuing even if individual compensations fail
    if (paymentProcessed) {
      await refundPayment(orderId).catch(() => {
        // Handle refund failure separately, e.g., send a notification
      });
    }
    if (inventoryReserved) {
      await cancelReservation(orderId);
    }
 
    throw ApplicationFailure.create({ message: `Order saga failed: ${orderId}` });
  }
}