Saga Patterns Skill

When to Use This Skill

Use this skill when:

• Saga Patterns tasks - Working on distributed transaction patterns using orchestration and choreography

• Planning or design - Need guidance on Saga Patterns approaches

• Best practices - Want to follow established patterns and standards

Overview

Design distributed transaction patterns using orchestration and choreography for microservices.

MANDATORY: Documentation-First Approach

Before designing sagas:

• Invoke docs-management skill for saga patterns

• Verify patterns via MCP servers (perplexity, context7)

• Base guidance on established microservices patterns

Saga Fundamentals

Why Sagas?

PROBLEM: Distributed transactions across services are complex. Traditional 2PC (Two-Phase Commit) doesn't scale.

SOLUTION: Saga = Sequence of local transactions Each step has a compensating action Eventual consistency instead of ACID

┌─────────┐ ┌─────────┐ ┌─────────┐ │ Step 1 │───►│ Step 2 │───►│ Step 3 │ │ Tx + Cx │ │ Tx + Cx │ │ Tx + Cx │ └─────────┘ └─────────┘ └─────────┘ │ │ │ ▼ ▼ ▼ Local Local Local Transaction Transaction Transaction

Tx = Forward Transaction Cx = Compensating Transaction

Saga Coordination Styles

Choreography (Event-Driven)

Choreography Pattern:

Services communicate through events. No central coordinator. Each service knows what to do next.

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Order │ │ Payment │ │ Inventory │ │ Service │ │ Service │ │ Service │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ OrderCreated │ │ │─────────────────►│ │ │ │ PaymentProcessed │ │ │─────────────────►│ │ │ │ InventoryReserved │◄─────────────────┼──────────────────│ │ OrderConfirmed │ │

Characteristics: ✓ Loose coupling ✓ Simple services ✗ Hard to track ✗ Cyclic dependencies risk

Orchestration (Coordinator-Driven)

Orchestration Pattern:

Central orchestrator coordinates the saga. Services expose commands. Orchestrator manages state.

            ┌─────────────────┐
            │   Orchestrator  │
            │  (Saga Manager) │
            └────────┬────────┘
                     │
    ┌────────────────┼────────────────┐
    │                │                │
    ▼                ▼                ▼

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Order │ │ Payment │ │ Inventory │ │ Service │ │ Service │ │ Service │ └─────────────┘ └─────────────┘ └─────────────┘

Characteristics: ✓ Clear flow visibility ✓ Easier debugging ✗ Single point of failure ✗ Coupling to orchestrator

Choreography Implementation

Event-Driven Flow

// Order Service - Starts Saga public class OrderService { private readonly IEventPublisher _events;

public async Task CreateOrderAsync(CreateOrderCommand cmd)
{
    var order = new Order(cmd.CustomerId, cmd.Items);
    await _repository.SaveAsync(order);

    // Publish event to start saga
    await _events.PublishAsync(new OrderCreated
    {
        OrderId = order.Id,
        CustomerId = cmd.CustomerId,
        TotalAmount = order.TotalAmount
    });
}

// Handle compensation
public async Task HandleAsync(PaymentFailed @event)
{
    var order = await _repository.GetAsync(@event.OrderId);
    order.Cancel("Payment failed");
    await _repository.SaveAsync(order);

    await _events.PublishAsync(new OrderCancelled
    {
        OrderId = @event.OrderId,
        Reason = "Payment failed"
    });
}

}

// Payment Service - Reacts to OrderCreated public class PaymentService { public async Task HandleAsync(OrderCreated @event) { try { var payment = await ProcessPaymentAsync(@event.OrderId, @event.TotalAmount);

        await _events.PublishAsync(new PaymentProcessed
        {
            OrderId = @event.OrderId,
            PaymentId = payment.Id
        });
    }
    catch (PaymentException ex)
    {
        await _events.PublishAsync(new PaymentFailed
        {
            OrderId = @event.OrderId,
            Reason = ex.Message
        });
    }
}

}

// Inventory Service - Reacts to PaymentProcessed public class InventoryService { public async Task HandleAsync(PaymentProcessed @event) { try { await ReserveInventoryAsync(@event.OrderId);

        await _events.PublishAsync(new InventoryReserved
        {
            OrderId = @event.OrderId
        });
    }
    catch (InsufficientInventoryException)
    {
        // Trigger compensation
        await _events.PublishAsync(new InventoryReservationFailed
        {
            OrderId = @event.OrderId
        });
    }
}

// Compensating action
public async Task HandleAsync(OrderCancelled @event)
{
    await ReleaseInventoryAsync(@event.OrderId);
}

}

Orchestration Implementation

Saga Orchestrator

// Saga State Machine public class OrderSaga : Saga<OrderSagaData>, IAmStartedBy<OrderCreated>, IHandle<PaymentProcessed>, IHandle<PaymentFailed>, IHandle<InventoryReserved>, IHandle<InventoryReservationFailed> { protected override void ConfigureHowToFindSaga(SagaPropertyMapper<OrderSagaData> mapper) { mapper.MapSaga(s => s.OrderId) .ToMessage<OrderCreated>(m => m.OrderId) .ToMessage<PaymentProcessed>(m => m.OrderId) .ToMessage<PaymentFailed>(m => m.OrderId) .ToMessage<InventoryReserved>(m => m.OrderId) .ToMessage<InventoryReservationFailed>(m => m.OrderId); }

public async Task Handle(OrderCreated message, IMessageHandlerContext context)
{
    Data.OrderId = message.OrderId;
    Data.CustomerId = message.CustomerId;
    Data.TotalAmount = message.TotalAmount;
    Data.Status = SagaStatus.Started;

    // Request payment
    await context.Send(new ProcessPaymentCommand
    {
        OrderId = message.OrderId,
        Amount = message.TotalAmount
    });
}

public async Task Handle(PaymentProcessed message, IMessageHandlerContext context)
{
    Data.PaymentId = message.PaymentId;
    Data.Status = SagaStatus.PaymentCompleted;

    // Request inventory reservation
    await context.Send(new ReserveInventoryCommand
    {
        OrderId = message.OrderId
    });
}

public async Task Handle(PaymentFailed message, IMessageHandlerContext context)
{
    Data.Status = SagaStatus.Failed;

    // Compensate: Cancel order
    await context.Send(new CancelOrderCommand
    {
        OrderId = message.OrderId,
        Reason = "Payment failed"
    });

    MarkAsComplete();
}

public async Task Handle(InventoryReserved message, IMessageHandlerContext context)
{
    Data.Status = SagaStatus.Completed;

    // Complete the saga
    await context.Publish(new OrderCompleted
    {
        OrderId = Data.OrderId
    });

    MarkAsComplete();
}

public async Task Handle(InventoryReservationFailed message, IMessageHandlerContext context)
{
    Data.Status = SagaStatus.Failed;

    // Compensate: Refund payment
    await context.Send(new RefundPaymentCommand
    {
        OrderId = Data.OrderId,
        PaymentId = Data.PaymentId
    });

    // Compensate: Cancel order
    await context.Send(new CancelOrderCommand
    {
        OrderId = Data.OrderId,
        Reason = "Inventory unavailable"
    });

    MarkAsComplete();
}

}

public class OrderSagaData : ContainSagaData { public Guid OrderId { get; set; } public Guid CustomerId { get; set; } public decimal TotalAmount { get; set; } public Guid? PaymentId { get; set; } public SagaStatus Status { get; set; } }

Compensating Transactions

Compensation Design

Compensation Principles:

1. SEMANTIC UNDO Not always exact reverse Example: Cancel order vs. un-create order

2. IDEMPOTENT Can be called multiple times safely Same result regardless of retries

3. NEVER FAIL Compensation must succeed eventually Use retries with backoff

4. ORDERED Compensate in reverse order Last step first, first step last

Compensation Flow: Step 1 ─► Step 2 ─► Step 3 ─► FAILURE │ │ │ │ │ │ │ ▼ │ │ └───► Compensate 3 │ │ │ │ └───────────────► Compensate 2 │ │ └─────────────────────────► Compensate 1

Compensation Examples

// Forward Transaction and Compensation Pairs public class ReservationService { // Forward: Reserve inventory public async Task<ReservationId> ReserveAsync(OrderId orderId, List<Item> items) { var reservation = new Reservation(orderId, items); foreach (var item in items) { await _inventory.DecrementAsync(item.ProductId, item.Quantity); } await _repository.SaveAsync(reservation); return reservation.Id; }

// Compensating: Release reservation
public async Task ReleaseAsync(ReservationId reservationId)
{
    var reservation = await _repository.GetAsync(reservationId);
    if (reservation.Status == ReservationStatus.Released)
        return; // Idempotent

    foreach (var item in reservation.Items)
    {
        await _inventory.IncrementAsync(item.ProductId, item.Quantity);
    }

    reservation.Release();
    await _repository.SaveAsync(reservation);
}

}

Error Handling

Retry Strategies

Retry Patterns:

1. IMMEDIATE RETRY For transient failures Network glitches, timeouts

2. EXPONENTIAL BACKOFF Increasing delays 1s → 2s → 4s → 8s

3. CIRCUIT BREAKER Stop retrying after threshold Allow recovery time

4. DEAD LETTER QUEUE Capture failed messages Manual intervention

Timeout Handling

// Saga with Timeout public class OrderSaga : Saga<OrderSagaData> { public async Task Handle(OrderCreated message, IMessageHandlerContext context) { // Set timeout for payment await RequestTimeout<PaymentTimeout>( context, TimeSpan.FromMinutes(30));

    await context.Send(new ProcessPaymentCommand { ... });
}

public async Task Timeout(PaymentTimeout timeout, IMessageHandlerContext context)
{
    if (Data.Status == SagaStatus.AwaitingPayment)
    {
        // Payment didn't complete in time
        await context.Send(new CancelOrderCommand
        {
            OrderId = Data.OrderId,
            Reason = "Payment timeout"
        });

        Data.Status = SagaStatus.TimedOut;
        MarkAsComplete();
    }
}

}

Saga Design Template

Saga Design: [Process Name]

Overview

[What this saga accomplishes]

Trigger

[What event starts this saga]

Steps

Flow Diagram

[ASCII saga flow diagram]

Failure Scenarios

Failure Point
What Failed
Compensation Chain

After Step 1
[Description]
Compensate 1

After Step 2
[Description]
Compensate 2 → 1

Timeout Handling

- Step 1 timeout: [What happens]

- Step 2 timeout: [What happens]

Idempotency

- [How duplicates are handled]

Monitoring

- [What to monitor]

- [Alerting thresholds]

Choosing Choreography vs Orchestration

Factor
Choreography
Orchestration

Coupling
Loose
Tighter

Visibility
Distributed
Centralized

Complexity
In events
In orchestrator

Debugging
Harder
Easier

Team structure
Independent teams
Central team

Failure handling
Distributed
Centralized

Best for
Simple flows
Complex flows

Workflow

When designing sagas:

- Identify Boundaries: Which services participate?

- Define Steps: Forward actions in order

- Design Compensations: Reverse actions for each step

- Choose Style: Choreography or orchestration?

- Handle Failures: Timeouts, retries, dead letters

- Ensure Idempotency: All actions repeatable safely

- Plan Monitoring: Track saga state and failures

- Test Failure Paths: Verify compensations work

User-Facing Interface

When invoked directly by the user, this skill designs a saga pattern for distributed transactions.

Execution Workflow

- Parse Arguments - Extract transaction description, style preference (orchestration/choreography/recommend), and participating services list. If no transaction provided, ask the user.

- Research Context - Use MCP servers to understand saga patterns for similar transactions.

- Analyze Transaction - Identify participating services, define forward transaction steps, design compensating actions, plan error handling.

- Recommend Style - If style not specified, evaluate choreography vs orchestration based on flow complexity, team structure, debugging needs, and coupling tolerance.

- Design Saga - Create step definitions, compensations, state machine (orchestration) or event flow (choreography), and failure scenarios.

- Generate Output - Produce saga design document with flow diagrams, step detail table, C# implementation examples, error handling strategy, and monitoring recommendations.

References

For detailed guidance:

Last Updated: 2025-12-26