jasperfx / wolverine

Supercharged .NET server side development!

Wolverine

Wolverine is a Next Generation .NET Mediator and Message Bus. Check out the documentation website at https://wolverine.netlify.app.

Support Plans

While Wolverine is open source, JasperFx Software offers paid support and consulting contracts for Wolverine.

Help us keep working on this project 💚

Become a Sponsor on GitHub

Working with the Code

To work with the code, just open the wolverine.sln file in the root of the repository and go. If you want to run integration tests though, you'll want Docker installed locally and to start the matching testing services with:

docker compose up -d

There's a separate README in the Azure Service Bus tests as those require an actual cloud set up (sorry, but blame Microsoft for not having a local Docker based emulator ala Localstack).

Contributor's Guide

For contributors, there's a light naming style Jeremy refuses to let go of that he's used for gulp 20+ years:

1. All public or internal members should be Pascal cased
2. All private or protected members should be Camel cased
3. Use _ as a prefix for private fields

The build is scripted out with Bullseye in the /build folder. To run the build file locally, use build with Windows or ./build.sh on OSX or Linux.

Documentation

All the documentation content is in the /docs folder. The documentation is built and published with Vitepress and uses Markdown Snippets for code samples. To run the documentation locally, you'll need a recent version of Node.js installed. To start the documentation website, first run:

npm install

Then start the actual website with:

npm run docs

To update the code sample snippets, use:

npm run mdsnippets

History

This is a little sad, but Wolverine started as a project named "Jasper" way, way back in 2015 as an intended reboot of an even older project named FubuMVC / FubuTransportation that was a combination web api framework and asynchronous message bus. What is now Wolverine was meant to build upon what we thought was the positive aspects of fubu's programming model but do so with a much more efficient runtime. Wolverine was largely rebooted, revamped, and renamed in 2022 with the intention of being combined with Marten into the "critter stack" for highly productive and highly performant server side development in .NET.

wolverine's Issues

Azure Service Bus Support

Also see JasperFx/jasper#520 for older context

DurabilityAgent Improvements

Epic spanning the work to close #10, #16, #26, #29, and #30

Recovering incoming messages in DurabilityAgent needs to consider paused listeners

Rewrite it just a little bit to query by endpoint? Make sure it's not pulling down incoming envelopes to listeners that are paused

Clean up IEnvelopePersistence API

Make it much more clear which methods require an active session. Maybe split incoming vs outgoing persistence? Use IReadOnlyList everywhere. Maybe bring in CancellationToken? Deal with any TODO in the code too.

Opt in for native Rabbit MQ delayed delivery

cc @AlexZeitler

If a user has https://github.com/rabbitmq/rabbitmq-delayed-message-exchange installed, use an "opt in" mode to utilize native Rabbit MQ scheduled send.

Today scheduled send with Rabbit MQ falls back into Wolverine's persistent scheduled messages

Introduce a higher speed serializer option

Do some research. Should do before 1.0 to verify the abstraction

Endpoint Configuration Policies

Need the ability to specify properties of various endpoints more easily

Tasks

• Rabbit MQ conventional routing needs an allow/deny list filter. Chain configuration for listener/sender using expression somehow
• Policies.UseDurableInboxForAllListeners()
• Policies.UseDurableOutboxForAllSenders()
• chain configuration for Rabbit MQ listeners
• chain configuration for Rabbit MQ senders
• Policies.LocalQueues(configure)
• Policies.UseSeparateLocalQueueForEachMessageType(configure)
• New way of registering endpoint policies

Advanced Pulsar Usage

Really just making sure that ConsumerOptions and ProducerOptions are both exposed and usable from PulsarEndpoint. Might try to make the subscription name be configurable too, but use the service name as the default.

Replace project icon and website in Directory.Build.props

Just got Jasper stuff in there now

Delete Endpoint.Parse(uri)

It was a hokey way of making it easy to load all settings from configuration by using Uri, but that just doesn't really fly now.

Reconsider this.

Optimized usage for AOT and Serverless

Not exactly sure what this entails yet. Thinking that it means some codegen ahead of time.

Re-evaluate in memory job scheduling

There's a unique InMemoryScheduledJobProcessor for each lightweight, local queue + the JasperRuntime. The diagnostics are useless.

Might be worth just improving the diagnostics on IJasperRuntime to show you everything that's outstanding.

Eliminate usage of Console.WriteLine in the codebase where it should be ILogger

Go hunt down and find old usages of Console.Writeline() where it should just be logging. RabbitMqTransport is a known offender.

Move messages that are unknown transports in the RecoverOutgoingMessages to the dead letter queue

Add support for Marten multi-tenancy to the Marten middleware

Might require some work on the Marten side of things. I think I'd want an ISessionFactory<T> where the T could be Jasper's IExecutionContext

Idempotent checking on messages received and outgoing messages

Use the inbox & outbox

Add causation & correlation tracking to the Marten session within Jasper handlers

Low hanging fruit. Just copy from the Envelope within the IMessageContext

Eliminate handler discovery and usage of abstract or interface types

Instead introduce new conventions for middleware.

Eliminate "durable" from any meaning on Uris

FubuTransportation left over. Just adds confusion.

Add error handling information to the command line "Describe" diagnostics

Might be cool on each handler to see what the error handling policies are

New Wolverine ASP.Net Core Endpoint Model because why not?

To be clear, this will not be any kind of full blown, alternative AspNetCore framework because that way lies madness, heartbreak, and failure

Goal: Mechanism to utilize Jasper's execution pipeline within Minimal API HTTP endpoints without having to manually delegate through to ICommandBus.

Signature

Use the Endpoint suffix nomenclature for discovery. Either use fubu-style naming conventions on the method names, or
override with [HttpPost("route")] style attributes. So:

public class SomethingEndpoint
{
    public Task<Output> post_something(Input request, Service service, Service2 service2)
    {

    }

    // OR

    [HttpPost("/something")]
    public Task<Output> Post(Input request, Service service, Service2 service2)
    {

    }
}

Notes:

• Still support method injection
• The base class generated around this will handle registration with Minimal API? Or one generated class to make it all faster.
• Gotta figure out how to expose metadata about the endpoints through to AspNetCore. Stuff like Open API configuration
  or [Authorize] attributes
• How to designate outgoing messages versus the HTTP response??? Could there be a base class just to add outgoing messages
  ala Saga.MarkCompleted()?
• Start making some of the other middleware HTTP aware? Thinking about making Marten being able to move the correlation id
  from the HTTP request to the session. Also ability to move the correlation id from HttpContext to the Jasper IExecutionContext?
  maybe that gets done with OTEL machinery???
• Do the code generation well, and this could be a good Azure Functions / AWS Lambda serverless strategy by cutting out a lot of cold start issues
• Support it on Saga as well? Why not?
• Also want a more efficient way to delegate through to ICommandBus. Something where you get an IInvoker<T> or IQuery<TRequest, TResponse> behind the scenes?

Special Services

These services should be resolved to the main Jasper method automatically:

1. HttpContext
2. ClaimsPrincipal
3. HttpRequest
4. HttpResponse
5. CancellationToken -- but this should come from the HTTP request

Streamline persistence library names

Wolverine.Persistence.SqlServer --> Wolverine.SqlServer et al. Clean up the docs as well

Reevaluate CircuitWatcher

What do do when the sender is latched and it's not durable? Throw at the point of sending? Move the Envelope.QuickSendAsync() logic into ISendingAgent? The variability is there.

Sample Middleware with Fluent Validation

Build a sample project, put it into the documentation. I don't think it's worth distributing a Nuget for that.

Put Alba specs on new outbox approaches

• With Marten
• With EF Core

Enforce the convention that the first argument is always the message type in handlers

I changed the docs, but there might still be really old support for other positions in the code

Improve the quick start sample

cc @AlexZeitler

• Improve the description of cascading messages. Do something w/ ItemCreated
• Link to the handler discovery, but add more description
• Probably more, so just review. That was written years ago.

Wire Compatibility with NServiceBus

Using either Rabbit MQ or Azure Service Bus, you should be able to interchange messages with an app using NServiceBus

Back pressure on durable & buffered listeners

Turn off the listeners if messages get backed up

Options for routing rules based on message data

Today all the routing is done based on message type. Analyze if there's any value in doing this by choosing the message route based on the data of the message body itself.

Publish event messages for meaningful actions in Wolverine

Publishing messages will allow users to easily register handlers for big events. Thinking:

• circuit tripped off
• circuit resumed
• endpoint paused
• endpoint restarted
• endpoint failed?
• endpoint too deep?

All of these are available for the tracker too? The observable path is beneficial too maybe.

Add observable support to the durability agent?

Like the async daemon in Marten. Publish events and metrics. Might make testing better.

Default Endpoint Names

For Rabbit MQ queues, it should be the queue name. Or exchange name
For SQS, the queue name
and so on

This will help a bit w/ diagnostics and logging

Metrics collection

Way more analysis necessary. At first thought, collect:

• Standing count of outgoing messages in inbox/outbox -- observable gauge
• Count of queue depth. Sampled observable gauge
• Aggregate "effective time" from sent to successfully processed. Histogram?
• Aggregate average of sent messages -- counter
• Number of messages handled by endpoint. Success & failure. Retries? -- counter with tags
• Queue length -- observable gauge

Add something like Marten's OptimizeArtifactWorkflow() for Jasper

See https://martendb.io/configuration/optimized_artifact_workflow.html. Or really, just make this automatic.

Saga improvements

See SagaFramePolicy. Use a custom exception with more context. Similar validation to what we did for projections in Marten

Improved Middleware Strategy

The big goal is to make the creation and usage of middleware easier.

Test cases

• Instance methods on middleware is scoped
• Static methods
• Synchronous "before"
• Asynchronous "before"
• Synchronous "after"
• Asynchronous "after"
• No filter
• User-defined filter
• Inferred filter by message applicability
• Use multiple middleware on one handler
• Add middleware by attribute too!
• Can use services
• Use objects built by middleware
• Dispose middleware objects that are created
• Filter model?

Circuit Breaker on local queues

If buffered, try to keep in memory. If durable, send to persistence as owned by zero. Latch either way.

Rabbit Mq should build a non durable, exclusive, auto delete queue for responses to the local node

Rework ITrackedSession usage

• Evaluate usage
• When asking for the "single XYZ of anything", and there's more than one or none, throw a better exception with the full history

Re-evaluate the IMessageContext interface

There's a lot of stuff on that thing that's not relevant to users

AWS SQS & SNS Support

Not sure if that'll require a separate library or not yet. Hoping that LocalStack is viable

Bring back request/reply mechanics

Inline RequestAndWait(CancellationToken) : Task,

Don't want to do that, but probably necessary for some users.

Acknowledgement workflow with callbacks

Need more context here. This is going to be used to standardize the workflow we built as custom code for a client to do acknowledgements about success or failure of an outgoing message, but with some mechanism to pass back contextual information about the original message.

Add SendAndAwait() and Request() specs to SendingCompliance

It could turn up issues with Envelope mapping for different transports

Frame chain is being re-arranged

Using .NET 6 and Wolverine 0.8.2 I get an exception when invoking commands of different types in parallel.
A gist reproducing the issue can be found here:
https://gist.github.com/gztamas/50997c72c61b9ed7809156bdb76c7be1

According to the gitter discussion with @jeremydmiller it might be an issue of insufficient/bad locking.

Verify de-duplication in Inbox and Outbox

Just based on message ids

Backfill Xml API comments on all configuration API methods

Look at the listener / subscriber configuration elements

Flesh out ISendMyself options for cascading messages?

Might decide not to do this at all, but it was handy once upon a time.

Enforce back pressure limitations in the RecoverIncomingMessages and RecoverOutgoingMessages actions

There's some TODOs. When the BoundedCapacity gets full on the worker queue, slow it down