Wolverine skill

Wolverine Development

Next-generation .NET mediator and message bus for event-driven architectures. In-process command bus, async messaging with 15+ transports, durable inbox/outbox, sagas, HTTP endpoints, gRPC, and event sourcing with Marten.

Docs: https://wolverinefx.net | Source: https://github.com/JasperFx/wolverine

NuGet Packages (v6.x)

Package	Purpose
WolverineFx	Core — handlers, middleware, local queues, MediatR/MassTransit shims
WolverineFx.Http	HTTP endpoints (requires AddWolverineHttp())
WolverineFx.RabbitMQ	RabbitMQ transport
WolverineFx.Kafka	Kafka transport
WolverineFx.AmazonSqs	AWS SQS/SNS transport
WolverineFx.AzureServiceBus	Azure Service Bus transport
WolverineFx.Pubsub	GCP Pub/Sub transport
WolverineFx.Nats	NATS transport
WolverineFx.MQTT	MQTT transport (IoT)
WolverineFx.Pulsar	Apache Pulsar transport
WolverineFx.Redis	Redis transport
WolverineFx.SignalR	SignalR transport
WolverineFx.Grpc	gRPC integration
WolverineFx.HealthChecks	ASP.NET Core health checks (AddWolverine(), AddWolverineListeners())
WolverineFx.Marten	Marten integration — sagas, event sourcing, aggregates
WolverineFx.SqlServer	SQL Server persistence
WolverineFx.Postgresql	PostgreSQL persistence
WolverineFx.Sqlite	SQLite persistence
WolverineFx.MySql	MySQL persistence
WolverineFx.Oracle	Oracle persistence
WolverineFx.EntityFrameworkCore	EF Core integration
WolverineFx.CosmosDb	Azure CosmosDB persistence
WolverineFx.RavenDb	RavenDB persistence
WolverineFx.FluentValidation	FluentValidation middleware
WolverineFx.DataAnnotationsValidation	DataAnnotations validation
WolverineFx.MemoryPack	MemoryPack serialization
WolverineFx.MessagePack	MessagePack serialization
WolverineFx.Protobuf	Protocol Buffers serialization
WolverineFx.Newtonsoft	Newtonsoft.Json serialization
WolverineFx.RuntimeCompilation	Roslyn runtime compiler (Dynamic/Auto modes only)

When to Use

• Building event-driven architectures with durable messaging
• Implementing sagas / long-running workflows with persisted state
• Setting up messaging transports (15+ supported)
• Creating HTTP APIs with Wolverine.Http endpoint model
• Building event-sourced systems with Marten aggregates
• Migrating from MediatR or MassTransit
• Configuring transactional inbox/outbox for reliable message delivery
• Cross-service communication via gRPC

When Not to Use

• Pure CRUD apps without messaging needs
• Projects requiring only a mediator without persistence (consider MediatR)
• Non-.NET projects

---

Reference Sections

Section	File	Contents
Quickstart	quickstart.md	Minimal setup, handler conventions, message bus, CLI commands
Sagas	sagas.md	Stateful workflows, Saga base class, TimeoutMessage, persistence, lifecycle
Durable Messaging	durability.md	Inbox/outbox, stale recovery, message identity, storage management
RabbitMQ	transports-rabbitmq.md	Setup, listening, publishing, clusters, sharded queues, DLQ
Kafka	transports-kafka.md	Processing modes, offset commit, scaling, rebalancing, idempotency
HTTP Endpoints	http-endpoints.md	Verbs, parameters, responses, cascading, hybrid handlers, ProblemDetails
Error Handling	error-handling.md	Circuit breaker, failure rules, exception matching, Fault<T>, DLQ
Validation	validation.md	FluentValidation, DataAnnotations, gRPC validation, AOT
Testing	testing.md	TrackedSession, assertions, stubs, Alba integration
Code Gen / AOT	codegen.md	TypeLoadMode, pre-generation, Native AOT, runtime compilation
Marten / ES	marten.md	Aggregates, event sourcing, subscriptions, transactional outbox
gRPC	grpc.md	Code-first, proto-first, streaming, rich errors, transport
Health Checks	health-checks.md	Broker probes, ASP.NET integration, CLI checks, node leadership
+ Transports	additional-transports.md	AWS, Azure, GCP, NATS, MQTT, Pulsar, Redis, SignalR, TCP, SQL
Serialization	serialization.md	JSON, Newtonsoft, MessagePack, MemoryPack, Protobuf, AES encryption
Rate Limiting	batching-rate-limiting.md	Per-type/endpoint limits, token bucket, message batching
HTTP Advanced	http-advanced.md	API versioning, antiforgery, OpenAPI, file handling, caching, auth
Node Agents	node-agents.md	Leader election, agent families, heartbeat, cluster management
Interop/Shims	interop-shims.md	MediatR shim, MassTransit shim, CloudEvents
Observability	observability.md	OpenTelemetry, metrics, CritterWatch, causation tracking

---

Quick Reference

Minimal Setup

var builder = WebApplication.CreateBuilder(args);
builder.Host.UseWolverine(opts => opts.ApplicationAssembly = typeof(Program).Assembly);
var app = builder.Build();
return await app.RunJasperFxCommands(args);

Handler

public void Handle(MyCommand cmd) { ... }
public async Task HandleAsync(MyCommand cmd) { ... }
public static (Response, OutEvent) Handle(MyCommand cmd, IService svc) { ... }

Bus

await bus.SendAsync(msg); var resp = await bus.InvokeAsync<T>(req);
await bus.ScheduleAsync(msg, 5.Minutes());

HTTP

builder.Services.AddWolverineHttp(); app.MapWolverineEndpoints();
[WolverinePost("/api/x")] public static T Post(Cmd c, IDocumentSession s) { ... }

Saga

public class Order : Saga
{
    public string? Id { get; set; }
    public static Order Start(StartOrder m) => new() { Id = m.OrderId };
    public void Handle(CompleteOrder m) => MarkCompleted();
}

RabbitMQ

opts.UseRabbitMqUsingNamedConnection("rabbitmq").AutoProvision();
opts.ListenToRabbitQueue("q").UseDurableInbox();

Kafka

opts.UseKafka("localhost:9092");
opts.ListenToKafkaTopic("orders").UseDurableInbox();

Outbox

opts.PersistMessagesWithPostgresql(connStr);
opts.Policies.UseDurableOutboxOnAllSendingEndpoints();

Marten

builder.Services.AddMarten(opts=>...).IntegrateWithWolverine();
[AggregateHandler] public static OrderCreated Handle(CreateOrder cmd) => new(...);

gRPC

builder.Services.AddWolverineGrpc(); app.MapWolverineGrpcServices();

Testing

var bus = host.MessageBus();
var session = await host.TrackActivity().ExecuteAndWaitAsync(async () => { ... });
session.Sent.ShouldHaveMessageOfType<OrderCreated>();

Error Handling

opts.OnException<TimeoutException>().RetryTimes(3);
opts.OnException<DbException>().RetryTimes(2)
    .Then.ScheduleRetry(1.Seconds(), 5.Seconds(), 20.Seconds());

Health Checks

builder.Services.AddHealthChecks().AddWolverine().AddWolverineListeners();

Validation

opts.UseFluentValidation();
opts.UseDataAnnotationsValidation();

AOT

opts.CodeGeneration.TypeLoadMode = TypeLoadMode.Static;

CLI

dotnet run -- resources setup   dotnet run -- storage rebuild
dotnet run -- db-apply          dotnet run -- check-env
dotnet run -- codegen write

---

Common Pitfalls

Pitfall	Solution
InvokeAsync() inside saga handler on same saga	Use cascading messages (tuple returns)
Missing AddWolverineHttp()	Call before app.Build() — throws at startup
Concurrent HTTP requests at startup	WarmUpRoutes = RouteWarmup.Eager
Root-scoped IMessageBus in tests	host.MessageBus() extension method
Kafka ConfigureConsumer() replaces parent config	Not combinatorial — per-topic only
Kafka + Requeue policy	Use inline Retry — Requeue not supported
InboxStaleTime too low	Must exceed max processing time + retries
Hardcoded connection strings in tests	Use Servers class
Production without TypeLoadMode.Static	Pre-generate code: dotnet run -- codegen write

Source References

Concept	Location
Saga base class	src/Wolverine/Saga.cs:8
WolverineOptions	src/Wolverine/WolverineOptions.cs:97
MessageBus	src/Wolverine/Runtime/MessageBus.cs
NodeAgentController	src/Wolverine/Runtime/Agents/NodeAgentController.cs
HTTP endpoints	src/Http/Wolverine.Http/
gRPC	src/Wolverine.Grpc/
Marten integration	src/Persistence/Wolverine.Marten/
RabbitMQ transport	src/Transports/RabbitMQ/Wolverine.RabbitMQ/
Kafka transport	src/Transports/Kafka/Wolverine.Kafka/
Persistence (RDBMS)	src/Persistence/Wolverine.RDBMS/
Serialization	src/Extensions/
MediatR/MassTransit shims	src/Wolverine/Shims/

Architecture Notes

• Runtime code generation via JasperFx — handlers compiled to delegates at startup
• Partial classes organize WolverineOptions: Serialization, Encryption, Endpoints, Policies, Batching, RateLimiting, Faults, Forwarders, MessageTransformations
• ImHashMap for hot-path dictionary lookups — lock-free, allocation-free
• Member naming: public/internal = PascalCase, private/protected = camelCase with _ prefix
• Test conventions: host.MessageBus() (scoped), Servers.PostgresConnectionString (never hardcode)
• CI builds wolverine.slnx (full solution) — slim build insufficient for cross-project validation