Wolverine: Transactional Messaging with RabbitMQ or Kafka, Inbox, Outbox, and Durable Local Queues

Sat, 02 May 2026 00:00:00 +0000

When we build microservices, the hard part is usually not publishing a message. The hard part is making database writes and message delivery behave correctly when failures happen between them. If a service stores data in PostgreSQL, publishes an integration event to RabbitMQ or Kafka, and also needs to update another store like MongoDB, we need a reliable way to keep those steps consistent without using a distributed transaction.

In this post, I want to show a practical way to solve that problem with Wolverine. The sample uses a small e-commerce system with two microservices, Catalogs and Orders, and demonstrates three important patterns together while keeping the broker selectable through configuration:

transactional outbox for publishing integration events after the database commit
durable inbox for idempotent downstream message consumption
durable local processing for internal work that should run after commit in a separate transaction

The sample is based on my Wolverine transactional messaging structure and uses a two-service e-commerce scenario with Catalog and Order. In the local blog sample, I kept the same architectural boundaries so the article stays practical: shared contracts, separate service projects, an Aspire AppHost, focused integration tests, and a transport switch between RabbitMQ and Kafka.

The Problem We Want to Solve

Assume Catalogs receives a request to create a product.

That request needs to do three things:

Store the product in PostgreSQL.
Publish ProductCreatedV1 so Orders can import that product through RabbitMQ or Kafka.
Update a MongoDB read model for query scenarios.

These three steps do not belong to one physical transaction:

PostgreSQL write uses one database transaction.
RabbitMQ or Kafka publish is external broker communication.
MongoDB projection should happen in a different persistence boundary.

If we do these steps manually in sequence, failures create inconsistent state very quickly:

product saved in PostgreSQL but event not published
event published but local transaction rolled back
product saved and event published but MongoDB projection failed
downstream service receives duplicate messages and writes duplicate records

This is exactly where Wolverine helps.

What Wolverine Gives Us

Wolverine is not only a message bus. It also gives us durable messaging primitives that fit very well with transactional application code.

For this scenario, the important capabilities are:

durable outgoing messages for outbox behavior
durable incoming messages for inbox behavior
durable local queues for internal post-commit processing
EF Core integration so message persistence can participate in the same PostgreSQL transaction as the write model

That means we can persist application data and outgoing work together, commit once, and let Wolverine flush the durable work only after the transaction succeeds.

Sample Scenario

The sample uses two microservices in an e-commerce domain:

Catalogs: write-side service for creating products
Orders: downstream consumer that imports product data from integration events

The flow is:

Catalogs receives POST /api/v1/catalogs/products.
Catalogs stores the product in PostgreSQL.
In the same transaction, Catalogs queues ProductCreatedV1 for the configured broker.
In the same transaction, Catalogs also queues an internal durable command named ProjectProductReadModel.
After commit, Wolverine dispatches both durable messages.
The local durable handler projects the product into MongoDB.
Orders consumes ProductCreatedV1 through a durable inbox and stores its own imported product record in PostgreSQL.

This gives us one transactional write boundary in Catalogs, one separate local processing boundary for MongoDB, and one separate consumer boundary in Orders.

Here is the sample API entry point that starts the flow:

// Thin endpoint — delegates to MediatR handler
internal static class CreateProductEndpoint
{
    internal static RouteHandlerBuilder MapCreateProductEndpoint(this IEndpointRouteBuilder endpoints)
        => endpoints.MapPost("/products", Handle).WithName("CreateProduct");

    private static async Task<CreatedAtRoute<CreateProductResponse>> Handle(
        [FromBody] CreateProductRequest request,
        IMediator mediator,
        CancellationToken cancellationToken)
    {
        var result = await mediator.Send(new CreateProductCommand(
            request.Name, request.Price, request.Stock,
            request.Category, request.Description), cancellationToken);

        return TypedResults.CreatedAtRoute(result, "CreateProduct", new { id = result.Id });
    }
}

The endpoint has one job: parse the HTTP request, build a command, send it through MediatR, and return the response.

Why Durable Local Processing Matters

This is the part many teams miss.

Sometimes we only think about external messaging, but internal asynchronous work can be just as important. In this sample, MongoDB projection is not an external integration event. It is internal application work, but it still should not run inside the same request transaction.

Why?

MongoDB is a different persistence technology.
We do not want the HTTP request to fail because a secondary projection store is temporarily unavailable.
We want the write model in PostgreSQL to stay the source of truth.
We still want reliable eventual consistency for the read model.

So instead of writing to MongoDB inline, Catalogs sends a durable local command after the PostgreSQL transaction is committed. That gives us a clean separation:

PostgreSQL write model is committed first.
MongoDB projection runs later in its own handler and its own persistence boundary.
If projection fails, Wolverine can retry it without losing the original business write.

This is what I mean by internal message processing in a transactional way. It is not one distributed transaction across PostgreSQL and MongoDB. It is a reliable post-commit workflow with durable local messaging.

Solution Structure

The sample keeps the structure close to a real microservice solution instead of putting everything in one demo project.

Main parts of the local sample:

src/Aspire/ECommerce.AppHost: Aspire orchestration entry point for catalogs-api, orders-api, PostgreSQL, MongoDB, and either RabbitMQ or Kafka depending on configuration
src/Services/Catalog/Catalog: write-side product logic and internal read-model projection flow
src/Services/Catalog/Catalog.Api: HTTP endpoints for creating products and reading write/read models
src/Services/Order/Order: downstream import logic with inbox-style duplicate protection
src/Services/Order/Order.Api: HTTP endpoints for importing and querying products in the order service
src/Shared/Contracts: MessageEnvelope<T>, ProductCreatedV1, and ProjectProductReadModel
src/BuildingBlocks/BuildingBlocks.Integration.Wolverine: shared Wolverine configuration with MediatR bridge for internal command dispatch
tests/Shared/Tests.Shared: shared end-to-end flow helper used by service tests
tests/Services/Catalog/Catalog.Tests: integration test for create + project flow
tests/Services/Order/Order.Tests: integration test for idempotent import behavior

This structure matters because the article is not only about Wolverine APIs. It is also about where to place contracts, handlers, persistence, and feature slices in a maintainable solution.

Each feature follows a consistent pattern with three files:

Command/Query (CreateProductCommand.cs): defines the request as a MediatR IRequest<TResponse> record
Handler (CreateProductHandler.cs): implements IRequestHandler<TRequest, TResponse> with the business logic
Endpoint (CreateProductEndpoint.cs): thin HTTP layer that injects IMediator and calls mediator.Send(command)

This keeps endpoints focused on HTTP concerns (routing, binding, status codes) while all business logic lives in MediatR handlers that are auto-discovered and testable in isolation.

The shared contracts are intentionally small and explicit:

public sealed record MessageEnvelope<TMessage>(
    Guid MessageId,
    Guid CorrelationId,
    DateTime OccurredAtUtc,
    TMessage Message)
{
    public static MessageEnvelope<TMessage> Create<TMessage>(
        TMessage message,
        Guid? correlationId = null,
        Guid? messageId = null,
        DateTime? occurredAtUtc = null)
        where TMessage : IMessage => new(
            messageId ?? Guid.NewGuid(),
            correlationId ?? Guid.NewGuid(),
            occurredAtUtc ?? DateTime.UtcNow,
            message);
}

public sealed record ProductCreatedV1(
    Guid Id,
    string Name,
    string Category,
    string Description,
    decimal Price,
    DateTime CreatedAtUtc)
    : IIntegrationEvent;

public sealed record ProjectProductReadModel(
    Guid ProductId,
    string Name,
    string Category,
    string Description,
    decimal Price)
    : IInternalCommand, IRequest;

System Architecture

The diagram below shows the full architecture with both services, the message broker, and both persistence stores:

flowchart TD classDef client fill:#a855f7,stroke:#7e22ce,color:#fff,font-size:14px classDef service fill:#06b6d4,stroke:#0891b2,color:#fff,font-size:14px classDef db fill:#f59e0b,stroke:#d97706,color:#fff,font-size:14px classDef broker fill:#10b981,stroke:#059669,color:#fff,font-size:14px classDef handler fill:#8b5cf6,stroke:#6d28d9,color:#fff,font-size:14px subgraph Client["🖥️ Client"] C1["HTTP Client"] end C1 --> EP1 subgraph Catalog["📦 Catalog Service"] direction TB EP1["POST /products"] H1["CreateProductHandler"] EB1["IEventBus \n📡 Publish"] DB1["PostgreSQL \nProducts + Outbox"] Outbox["📤 Bus Outbox \n📬 Drain & Deliver"] ICB1["IInternalCommandBus \n⚙️ Enqueue"] PH["ProjectReadModelHandler \n⚙️ Project"] MDB["MongoDB \nReadModels"] EP1 --> H1 H1 --> EB1 H1 --> DB1 H1 --> ICB1 DB1 -.-> Outbox Outbox --> B1 ICB1 --> PH PH --> MDB end subgraph Broker["📨 Message Broker"] B1{{"RabbitMQ / Kafka"}} end B1 --> C1C subgraph Order["📦 Order Service"] direction TB C1C["ProductCreatedConsumer \n🧩 Handler"] NH["NotificationHandler \n🧩 Handler"] DB2["PostgreSQL \nImportedProducts"] C1C --> NH NH --> DB2 end class C1 client class EP1,C1C service class H1,PH,NH handler class EB1,ICB1 service class DB1,DB2,Outbox,MDB db class B1 broker

Message Flow End to End

Let’s walk through the full request flow.

1. Catalogs receives product creation request

Catalogs exposes an endpoint like:

`1`	`POST /api/v1/catalogs/products`

The request creates a product in the write model.

In the sample, that endpoint delegates to a MediatR command through the thin CreateProductEndpoint: it receives the HTTP request, sends a CreateProductCommand through IMediator, and returns a CreatedAtRoute response. The handler then orchestrates the write model, integration event, and internal projection command.

2. MediatR handler orchestrates the write transaction

The actual business logic lives in the CreateProductHandler, which MediatR invokes when the endpoint sends a CreateProductCommand:

internal sealed class CreateProductHandler(
    CatalogsDbContext dbContext,
    IEventBus eventBus,
    IInternalCommandBus internalCommandBus)
    : IRequestHandler<CreateProductCommand, CreateProductResponse>
{
    public async Task<CreateProductResponse> Handle(CreateProductCommand request, CancellationToken cancellationToken)
    {
        var product = Product.Create(request.Name, request.Price, request.Stock);
        dbContext.Products.Add(product);

        var integrationEvent = MessageEnvelope.Create(new ProductCreatedV1(
            product.Id, product.Name, request.Category ?? string.Empty,
            request.Description ?? string.Empty, product.Price, product.CreatedAtUtc));

        await eventBus.PublishAsync(integrationEvent, cancellationToken);
        await dbContext.SaveChangesAsync(cancellationToken);

        await internalCommandBus.EnqueueAsync(new ProjectProductReadModel(
            product.Id, product.Name, request.Category ?? string.Empty,
            request.Description ?? string.Empty, product.Price), cancellationToken);

        return new CreateProductResponse(product.Id, product.Name, product.Price, product.Stock);
    }
}

The important point is not the exact syntax. The important point is the behavior:

product write is persisted in PostgreSQL
outgoing broker event is persisted durably
local projection command is persisted durably
commit happens once
Wolverine dispatches durable work only after commit succeeds

That is the outbox story. The handler brings the write model, integration event, and internal command into one persistence boundary.

The handler follows the same responsibilities in one MediatR pipeline:

persist the write model in PostgreSQL
publish the integration event through IEventBus (Wolverine outbox)
enqueue internal projection work through IInternalCommandBus (MediatR bridge)
SaveChangesAsync triggers the transactional outbox — Wolverine flushes durable messages only after commit

External Integration Event with RabbitMQ or Kafka

After commit, Wolverine publishes MessageEnvelope<ProductCreatedV1> to the configured broker.

In this sample, both APIs default to rabbitmq, but you can switch to kafka with configuration only. The application code does not need to change because the Wolverine transport wiring is selected in startup based on the configured transport.

If you run the APIs directly, set this in both API projects:

{
    "Messaging": {
        "Transport": "rabbitmq"
    }
}

Change the value to kafka to switch brokers.

If you run through Aspire, the AppHost reads Messaging__Transport, provisions only the selected broker container, and forwards the same value to both services.

1
2

$env:Messaging__Transport = "kafka"
dotnet run --project src/Aspire/ECommerce.AppHost/ECommerce.AppHost.csproj

Use rabbitmq instead of kafka to switch back.

Why wrap the event in a message envelope?

Because in real systems we usually need metadata such as:

message id
correlation id
causation id
message type
creation time
tracing or tenant information

A reusable MessageEnvelope<T> keeps transport-level and observability metadata consistent across services.

The sample envelope and event contracts look like this:

public sealed record MessageEnvelope<TMessage>(
    Guid MessageId,
    Guid CorrelationId,
    DateTime OccurredAtUtc,
    TMessage Message);

public sealed record ProductCreatedV1(
    Guid Id,
    string Name,
    string Category,
    string Description,
    decimal Price,
    DateTime CreatedAtUtc);

In this sample, Orders subscribes to the same event and imports the product into its own database.

That means Catalogs does not know anything about Orders internals. It only publishes an integration event.

Durable Inbox in Orders

On the consumer side, Orders uses Wolverine durable inbox semantics backed by PostgreSQL.

This solves a common problem in broker-based systems: duplicate delivery.

RabbitMQ and Kafka both require idempotent consumers. Consumers can crash after partially processing a message. Network failures can make delivery uncertain. Without inbox protection, the same event may create duplicate rows or duplicate side effects.

With a durable inbox:

incoming messages are tracked durably
processing can be retried safely
duplicate deliveries can be ignored or handled idempotently
the consumer can recover after crashes without losing message state

In the sample, Orders consumes ProductCreatedV1 and writes an imported product record to its own PostgreSQL database. That is a classic microservice integration pattern: each service owns its own data and builds its own local view from events.

The consumer follows a thin bridge pattern: a Wolverine handler receives the message from the transport and delegates to a MediatR notification handler for the actual business logic.

// Thin Wolverine bridge consumer — only delegates to MediatR
public sealed class ProductCreatedConsumer(IMediator mediator)
{
    public async Task Consume(MessageEnvelope<ProductCreatedV1> envelope)
        => await mediator.Publish(new ProductCreatedNotification(envelope));
}

The notification and its handler carry the actual business logic:

public sealed record ProductCreatedNotification(
    MessageEnvelope<ProductCreatedV1> Envelope) : INotification;

public sealed class ProductCreatedNotificationHandler(
    OrdersDbContext dbContext)
    : INotificationHandler<ProductCreatedNotification>
{
    public async Task Handle(
        ProductCreatedNotification notification,
        CancellationToken cancellationToken)
    {
        var message = notification.Envelope.Message;

        var existing = await dbContext.ImportedProducts
            .FirstOrDefaultAsync(x => x.Id == message.Id, cancellationToken);

        if (existing is null)
        {
            dbContext.ImportedProducts.Add(new ImportedProduct
            {
                Id = message.Id,
                Name = message.Name,
                Price = message.Price,
                Stock = message.Stock
            });
        }
        else
        {
            existing.Name = message.Name;
            existing.Price = message.Price;
            existing.Stock = message.Stock;
        }

        await dbContext.SaveChangesAsync(cancellationToken);
    }
}

This separation keeps the transport consumer minimal and testable. The Wolverine handler only does transport-specific work (deserialization, envelope extraction), and all business logic lives in the MediatR notification handler. Unit tests can test the handler directly without bootstrapping Wolverine.

On the Orders side, the endpoint that receives external integration events follows the same thin pattern — it publishes through IEventBus and returns immediately:

internal static class ReceiveProductCreatedEndpoint
{
    internal static RouteHandlerBuilder MapReceiveProductCreatedEndpoint(this IEndpointRouteBuilder endpoints)
        => endpoints.MapPost("/products/receive", Handle);

    private static async Task<Accepted> Handle(
        [FromBody] MessageEnvelope<ProductCreatedV1> envelope,
        IEventBus eventBus,
        CancellationToken cancellationToken)
    {
        await eventBus.PublishAsync(envelope, cancellationToken);
        return TypedResults.Accepted();
    }
}

Internal Durable Command for MongoDB Projection

Now back to the internal processor scenario.

After Catalogs commits the product in PostgreSQL, it also dispatches a durable local command:

public sealed record ProjectProductReadModel(
    Guid ProductId,
    string Name,
    string Category,
    string Description,
    decimal Price)
    : IInternalCommand, IRequest;

A local MediatR handler processes that command and upserts a MongoDB read model.

ProjectProductReadModel implements both IInternalCommand (for the IInternalCommandBus interface constraint) and IRequest (for MediatR dispatch):

And the handler implements IRequestHandler<ProjectProductReadModel>:

public class ProjectProductReadModelHandler(
    IProductReadRepository repository)
    : IRequestHandler<ProjectProductReadModel>
{
    public async Task Handle(
        ProjectProductReadModel command,
        CancellationToken cancellationToken)
    {
        var product = await repository.GetProductByIdAsync(
            command.ProductId, cancellationToken);

        await repository.UpsertProductAsync(new ProductReadModel
        {
            Id = product.Id,
            Name = product.Name,
            Price = product.Price,
            Stock = product.Stock
        }, cancellationToken);
    }
}

This handler runs outside the original HTTP request transaction.

That gives us several benefits:

MongoDB projection is retriable
request latency stays lower
PostgreSQL remains the transactional source of truth
projection failures do not corrupt the write transaction

To register the MediatR handlers, the module configuration uses AddMediatR instead of Wolverine’s ScanHandlers:

1
2
3

// CatalogModule.cs — MediatR replaces Wolverine handler discovery
builder.Services.AddMediatR(cfg =>
    cfg.RegisterServicesFromAssembly(typeof(CatalogsMetadata).Assembly));

The same applies to Orders, where MediatR is registered alongside Wolverine ScanHandlers for the thin transport consumer. Module prefixes for exchange/queue naming are shared via constants in MessagingConstants:

// MessagingConstants.cs — shared prefix constants
public static class ModulePrefixes
{
    public const string Catalog = "catalog";
    public const string Order = "order";
}

Using constants avoids hardcoded strings and makes the convention explicit across services:

// CatalogModule.cs — publisher: auto-derives "catalog" from assembly
builder.AddTransactionalWolverine(transport, cfg =>
    cfg.ScanIntegrationEvents(typeof(CatalogModule).Assembly));

// OrderModule.cs — consumer: references shared constant
builder.AddTransactionalWolverine(transport, cfg =>
    cfg.ListenToIntegrationEvents(
        MessagingConstants.ModulePrefixes.Catalog,
        typeof(ProductCreatedV1).Assembly));

This is a very useful pattern when one service needs to persist data in multiple stores but should only treat one of them as the primary transactional boundary.

In this sample, Wolverine is used exclusively as the transport layer for RabbitMQ or Kafka, while the local command dispatch is handled by MediatR. The WolverineInternalCommandBus bridges the two by accepting an internal command through Wolverine’s durable queue and forwarding it to MediatR:

internal sealed class WolverineInternalCommandBus(IMediator mediator) : IInternalCommandBus
{
    public async Task EnqueueAsync<TCommand>(TCommand command, CancellationToken cancellationToken = default)
        where TCommand : IInternalCommand
    {
        await mediator.Send(command, cancellationToken);
    }
}

This separation keeps Wolverine focused on reliable transport with transactional outbox/inbox while MediatR handles the in-process command dispatch with its pipeline behaviours, request/response semantics, and notification broadcasting.

The simplified sample implementation of that projection flow is:

public async Task ProjectReadModelAsync(ProjectProductReadModel command, CancellationToken cancellationToken = default)
{
    var product = await _writeStore.FindAsync(command.ProductId, cancellationToken)
        ?? throw new InvalidOperationException($"Product '{command.ProductId}' not found.");

    await _readStore.UpsertAsync(new ProductReadModel
    {
        Id = product.Id,
        Name = product.Name,
        Price = product.Price,
        Stock = product.Stock,
        SyncedAt = DateTime.UtcNow
    }, cancellationToken);
}

In the actual implementation, this method is encapsulated in the MediatR handler discussed above, so projection runs after commit with retries through Wolverine’s durable local queue.

Integration Tests

The sample includes focused integration tests so the transport switch is not only documented, but also verified.

The tests verify the business flow works with both supported transport values using TestContainers:

Catalog flow test — creates a product and verifies both the PostgreSQL write model and the MongoDB read model:

[Fact]
public async Task CreateAndProjectProduct_ShouldSucceed()
{
    var response = await Factory.CreateClient().PostAsJsonAsync(
        "/api/v1/catalogs/products",
        new CreateProductRequestDto("Test Product", 29.99m, 10, "corr-001"));

    response.EnsureSuccessStatusCode();

    await Task.Delay(500); // wait for async projection

    await ExecuteCatalogDbContextAsync(async dbContext =>
    {
        var product = await dbContext.Products.SingleAsync(x => x.Name == "Test Product");
        Assert.Equal(29.99m, product.Price);
    });

    await ExecuteMongoDbContextAsync(async mongo =>
    {
        var readModel = await mongo.ProductReadModels
            .Find(x => x.Name == "Test Product")
            .FirstOrDefaultAsync();
        Assert.NotNull(readModel);
    });
}

Order import tests — insert on first delivery, update on duplicate, and verify error handling for faulty payloads:

[Fact]
public async Task ConsumeProductCreated_ShouldInsert_WhenMissing()
{
    var envelope = MessageEnvelope.Create(new ProductCreatedV1(
        Guid.NewGuid(), "New Product", 19.99m, 5));

    var response = await Client.PostAsJsonAsync(
        "/api/v1/orders/products/receive", envelope);
    response.EnsureSuccessStatusCode();

    await Task.Delay(500);

    await ExecuteDbContextAsync(async db =>
    {
        var imported = await db.ImportedProducts
            .SingleAsync(x => x.Id == envelope.Message.Id);
        Assert.Equal("New Product", imported.Name);
    });
}

These tests make the article more concrete because they verify the most important outcomes:

the product is written and projected across PostgreSQL and MongoDB
duplicate messages update existing records idempotently
faulty payloads are rejected and moved to Wolverine’s error queue

There are also transport configuration tests that validate normalization and rejection of unsupported values. All integration tests use TestContainers with real PostgreSQL, MongoDB, and RabbitMQ or Kafka instances.

Conclusion

Transactional messaging is really about failure handling, not only message publishing. When one request needs to update a write model, publish an integration event, and trigger internal asynchronous work, Wolverine gives a clean way to model those steps with outbox, inbox, and durable local processing.

This sample shows how Wolverine can model transactional outbox, durable inbox, and durable local processing in a way that fits real microservice boundaries. RabbitMQ and Kafka stay interchangeable through configuration, the APIs are wired for both transports, and the tests keep the switching behavior covered.

You can find the sample code in this repository:

https://github.com/meysamhadeli/blog-samples/tree/main/wolverine-transactional-messaging-aspire

Wolverine on dotnetuniversity