ZeroAlloc.Saga.Outbox 4.1.4

ZeroAlloc.Saga

Source-generated sagas for .NET: declare steps and their compensation on a partial class, and get a state machine with no reflection that runs under NativeAOT, on in-memory, EF Core, ZeroAlloc.ORM or Redis storage.

Why ZeroAlloc.Saga

• A workflow is one partial class. Steps, correlation keys and compensation are attributes. The generator emits the state machine, the event handlers and the command dispatch, and compensation runs in reverse automatically when a failure event arrives.
• Works under NativeAOT and trimming. CI publishes and runs AOT samples for the core, the outbox bridge, the ORM store and the resilience bridge. The EF Core store runs on JIT hosts only, blocked upstream.
• Compile-time diagnostics. 16 generator diagnostics catch authoring mistakes such as gaps in step order, missing correlation keys or a misshaped compensation method, three of them with code fixes.
• No double dispatch under retry. With the outbox bridge on the EF Core, ORM or Redis store, each step command is committed atomically with the saga state, so an optimistic-concurrency retry cannot send a command twice.

Install

dotnet add package ZeroAlloc.Saga
dotnet add package ZeroAlloc.Mediator.Generator

ZeroAlloc.Saga carries its own generator. Saga commands and events flow through ZeroAlloc.Mediator, whose generator you reference directly.

Quick start

using Microsoft.Extensions.DependencyInjection;
using ZeroAlloc.Mediator;
using ZeroAlloc.Saga;

var services = new ServiceCollection().AddLogging().AddTransient<Warehouse>().AddTransient<Payments>();
services.AddSaga().WithCheckoutSaga(); // generated for the [Saga] class
await using var provider = services.BuildServiceProvider();
var mediator = provider.GetRequiredService<IMediator>();

await mediator.Publish(new OrderPlaced(42, 9.95m), default); // step 1 sends ReserveStock
await mediator.Publish(new StockReserved(42), default);      // step 2 sends ChargeCard
await mediator.Publish(new PaymentDeclined(42), default);    // compensation sends ReleaseStock

public sealed record OrderPlaced(int OrderId, decimal Total) : INotification;
public sealed record StockReserved(int OrderId) : INotification;
public sealed record PaymentCharged(int OrderId) : INotification;
public sealed record PaymentDeclined(int OrderId) : INotification;

public readonly record struct ReserveStock(int OrderId) : IRequest;
public readonly record struct ReleaseStock(int OrderId) : IRequest;
public readonly record struct ChargeCard(int OrderId, decimal Total) : IRequest;
public readonly record struct ShipOrder(int OrderId) : IRequest;

[Saga]
public partial class CheckoutSaga
{
    public int OrderId { get; private set; }
    public decimal Total { get; private set; }

    [CorrelationKey] public int Key(OrderPlaced e) => e.OrderId;
    [CorrelationKey] public int Key(StockReserved e) => e.OrderId;
    [CorrelationKey] public int Key(PaymentCharged e) => e.OrderId;
    [CorrelationKey] public int Key(PaymentDeclined e) => e.OrderId;

    [Step(Order = 1, Compensate = nameof(Release))]
    public ReserveStock Reserve(OrderPlaced e) { (OrderId, Total) = (e.OrderId, e.Total); return new(OrderId); }

    [Step(Order = 2, CompensateOn = typeof(PaymentDeclined))]
    public ChargeCard Charge(StockReserved e) => new(OrderId, Total);

    [Step(Order = 3)]
    public ShipOrder Ship(PaymentCharged e) => new(OrderId);

    public ReleaseStock Release() => new(OrderId);
}

public sealed class Warehouse : IRequestHandler<ReserveStock, Unit>, IRequestHandler<ReleaseStock, Unit>, IRequestHandler<ShipOrder, Unit>
{
    public ValueTask<Unit> Handle(ReserveStock c, CancellationToken ct) => Log($"Reserved stock for {c.OrderId}");
    public ValueTask<Unit> Handle(ReleaseStock c, CancellationToken ct) => Log($"Released stock for {c.OrderId}");
    public ValueTask<Unit> Handle(ShipOrder c, CancellationToken ct) => Log($"Shipped {c.OrderId}");
    internal static ValueTask<Unit> Log(string what) { Console.WriteLine(what); return new(Unit.Value); }
}

public sealed class Payments : IRequestHandler<ChargeCard, Unit>
{
    public ValueTask<Unit> Handle(ChargeCard c, CancellationToken ct) => Warehouse.Log($"Charging {c.Total}");
}

It prints Reserved stock for 42, Charging 9.95 and Released stock for 42. A saga that reaches a terminal state is removed from the store automatically. Concepts explains the lifecycle and what the generator emits.

What you get

• Correlation by any key type, including strongly typed IDs and composite keys.
• Automatic compensation on a failure event, and manual compensation through ISagaManager.CompensateAsync.
• Optimistic concurrency with retry on conflict, each attempt in a fresh DI scope.
• In-memory storage by default; switch to a durable store with one fluent call.

Optional packages:

• ZeroAlloc.Saga.EfCore: durable store on your EF Core DbContext, with row-version concurrency.
• ZeroAlloc.Saga.Orm: durable store over ZeroAlloc.ORM, NativeAOT-ready.
• ZeroAlloc.Saga.Redis: durable store on Redis with WATCH/MULTI/EXEC concurrency.
• ZeroAlloc.Saga.Outbox: step commands dispatched through ZeroAlloc.Outbox, committed with the saga state.
• ZeroAlloc.Saga.Outbox.Orm: outbox rows in the ORM saga store's transaction.
• ZeroAlloc.Saga.Outbox.Redis: outbox rows in the Redis saga store's MULTI/EXEC.
• ZeroAlloc.Saga.Resilience: retry, timeout, circuit-breaker and rate-limit around step dispatch.

Performance

Saga state is persisted through generated Snapshot() and Restore() methods. Exact budgets, asserted by SagaStateAllocationTests:

There is no published head-to-head against another saga library yet. Details: docs/performance.md.

Learn more

• Documentation: docs/, starting with concepts, correlation and compensation
• Reference: packages and dependencies, diagnostics, samples, limitations and roadmap
• Upgrading: migrating to v4, release highlights, CHANGELOG
• Related: ZeroAlloc.Mediator, ZeroAlloc.Outbox, ZeroAlloc.Resilience, ZeroAlloc.EventSourcing
• Contributing: issues and pull requests are welcome on GitHub
• License: MIT, see LICENSE