Tag Archives: Jasper

Jasper Command Line App Support you Wish Your Framework Already Had

Jasper is a new messaging and command runner framework targeting Netstandard2 my shop has been building as a replacement for part of the old FubuMVC framework. I wrote about the general vision and rationale here.

Earlier today I made a v0.7.0 release of Jasper and its related extensions. The pace of development has kicked back up because we’re getting ready to start doing load and chaos testing with our QA folks later this week and we’re already transitioning some smaller, low volume systems to Jasper. The highlights this time are:

  • A lot of optimization for the “cold start” time, especially if you’re using Jasper in combination with ASP.Net Core. I collapsed the ASP.Net Core support back to the core library, so this post is already obsolete.
  • The integration with ASP.Net Core is a lot tighter. For example, Jasper is now using the ASP.Net Core logging under its covers, the ASP.Net Core IHostedService, and just generally plays nicer when used in combination with ASP.Net Core applications.
  • Jasper now has some support for stateful sagas, but only with Marten-backed persistence. I’ll blog about this one soon, and there will be other saga persistence options coming fairly soon. Sql Server backed persistence at a bare minimum.
  • Finer grained control over how certain message types are published
  • Mild improvements to the Marten integration. Again, Jasper isn’t hard coupled to Marten and Postgresql, but it’s just been easy to prove out concepts with Marten first.
  • More command line usages that I’m showing in the rest of this post;)

Command Line Integration

First off, let’s say that you have a simple Jasper application that listens for incoming messages at a designated port configured with this class:

public class SubscriberApp : JasperRegistry
{
    public SubscriberApp()
    {
        // Listen for incoming messages via the
        // built in, socket transport in a 
        // fire and forget way at port 2222
        Transports.LightweightListenerAt(2222);
    }
}

To run your Jasper application as a console application, you can use the Jasper.CommandLine library as a quick helper that also adds some diagnostic commands you may find helpful during both development and deployment time. Using your SubscriberApp class above, you can bootstrap your application in a console application like this:

class Program
{
    static int Main(string[] args)
    {
        return JasperAgent.Run(args);
    }
}

Once that’s done, you can immediately run your application from the command line with dotnet run, which would give you some output like this:

Running service 'SubscriberApp'
Application Assembly: Subscriber, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
Hosting environment: Production
Content root path: [the IHostedEnvironment.ContentRootPath value]
Hosted Service: Jasper.Messaging.MessagingActivator
Hosted Service: Jasper.Messaging.NodeRegistration
Listening for loopback messages
Listening for messages at [url]/messages
Listening for messages at [url]/messages/durable

Active sending agent to loopback://replies/
Active sending agent to loopback://retries/
Handles messages:
            [Message Type]: [Handler Type and Handler Method Name]

Now listening on: [listener Uri]
Application started. Press Ctrl+C to shut down.

Other than a little bit of contextual information, it’s about what you would get with the ASP.Net Core command line support. If you’re not familiar with the dotnet cli, you can pass command line arguments to your Program.Main() ​method by using double dashes to separate arguments that apply to dotnet run from the arguments that get passed into your main method. Using the Oakton library for parsing Linux style command arguments and flags, your Jasper application can also respond to other commands and optional flags.

Knowing all that, this:

dotnet run -- -v

or

dotnet run -- --verbose

will run your application with console and debug loggers, and set the minimum log level in the ASP.Net Core logging to “Debug.”

Alternatively, you can also override the log level by:

dotnet run -- --log-level Information

or

dotnet run -- -l Trace

where the value is one of the values in the LogLevel enumeration.

To override the environment your application is running under, you can use this flag:

dotnet run -- --environment Development

or use the “-e” short version of that.

So what, what else do you got?

You can run a Jasper application, but there’s actually quite a bit more. If you type dotnet run -- ?, you can see the other available commands:

 

Screen Shot 2018-04-11 at 3.53.09 PM

The “export-json-schema” and “generate-message-types” commands are from an extension library that allows you to export JSON schema documents for the known message types or generate C# classes with the necessary Jasper message type identity from JSON schema documents. The command line support is extensible, allowing you to add prepackaged commands from addon Nugets or even be exposed from your own application. I’m going to leave that to a later post or *gasp*, updated documentation.

Preview the Generated Code

If you read my earlier post on Jasper’s Roslyn-Powered “Special Sauce,” you know that Jasper internally generates and compiles glue code to handle messages or HTTP requests. To help troubleshoot applications or just to understand the interplay between message handlers and any configured middleware, you can use this command to either list out the generated code or export it to a file:

dotnet run -- code -f export.cs

 

Check out the IoC Container Configuration

As a long time IoC tool author and user, I’m painfully aware that people run into issues with service registrations being incorrect or using erroneous lifecycles. To help ease those issues, Jasper allows you to see the service registrations of your entire application with this command:

dotnet run -- services

This is just displaying the output of the Lamar WhatDoIHave() report, similar to StructureMap’s WhatDoIHave() functionality.

Validate the System

As part of deployment or maybe even local development, you can choose to just start up the application, run all the registered environment checks, and verify that all the known message handlers and HTTP routes can be successfully compiled — with oodles of ugly red textual output if any check along the way fails. That’s done with dotnet run -- validate.

 

Manage Subscriptions

It’s admittedly kind of boring and I’m running out of time before I need to head home, but there is a dotnet run -- subscriptions command that you can use to manage message subscriptions at deployment or build time that’s documented here.

 

Next up:

I’ll get a decent, business facing example of Jasper’s stateful saga support.

 

Integrating Jasper into ASP.Net Core

Continuing a blog series on Jasper functionality:

  1. Jasper’s Configuration Story 
  2. Jasper’s Extension Model
  3. Integrating Marten into Jasper Applications
  4. Durable Messaging in Jasper 
  5. Integrating Jasper into ASP.Net Core (this one)
  6. Jasper’s HTTP Transport
  7. Jasper’s “Outbox” Support within ASP.Net Core Applications

There will be some need for completely headless services written with Jasper that rely strictly on TCP connections or yet to come queueing transports, but I expect that most of the systems at work where we’ll use Jasper will be within ASP.Net Core applications.

Moreover, as a nasty lesson learned from my hubristic attempts at creating a freestanding development ecosystem with FubuMVC, Jasper is meant to be merely a good citizen within the greater server side ASP.Net Core ecosystem. In regards to this blog post, that means using as much of the standard Hosting model as possible. For example, Jasper supports the IHostedService model from ASP.Net Core out of the box for long running background services or startup and shutdown actions.

As of Jasper 0.6, I pulled the HTTP support and ASP.Net Core integration into a separate Jasper.Http Nuget. This might feel like the tail wagging the dog, but I really only did this to optimize the core Jasper testing suite because bootstrapping ASP.Net Core on every integration test was slowing the automated build down too much. If I can find a way to optimize or at least parallelize much more of the bootstrapping with the messaging, I will consider merging things back together again later.

When Jasper is integrated into an ASP.Net Core system, it:

  • Adds more service registrations to the application
  • Bootstraps the JasperRuntime object and places that within the container so that the Jasper transports will be cleanly shut down when the IWebHost is disposed
  • Replaces the built in DI container with Lamar (Jasper only works with Lamar at this point)
  • Jasper also sneaks in some ASP.Net Core middleware to add its own routes into the application, which I’ll show off in the next post about Jasper’s HTTP messaging transport

All of this is documented in the Jasper Getting Started page and in the specific documentation for ASP.Net Core integration.

Longer term, I might try to move Jasper closer to the existing ASP.Net Core bootstrapping mechanisms.

Bootstrapping ASP.Net Core the Idiomatic Jasper Way

The first option is really about adding HTTP support to an idiomatic Jasper application. In this case, you just use the JasperHttpRegistry from the Jasper.Http library as the base class for your application definition like so:

public class AppWithMiddleware : JasperHttpRegistry
{
    public AppWithMiddleware()
    {
        // Do the normal stuff you do to configure
        // service registrations, configuration, and
        // messaging support

        Http.Configure(app =>
        {
            app.UseMiddleware<CustomMiddleware>();

            // Explicitly control the order in which the Jasper
            // middleware is placed within the ASP.Net Core
            // pipeline. 
            app.AddJasper();

            // Just to show how you can configure ASP.Net Core
            // middleware that runs after Jasper's RequestDelegate,
            // but do note that Jasper has its own default "not found"
            // behavior
            app.Run(c =>
            {
                c.Response.StatusCode = 404;

                return c.Response.WriteAsync("Not found");
            });
        });
    }
}

A couple things to note:

  • The Http property in the class shown above is just the IWebHostBuilder interface you’re already used to if you use ASP.Net Core today
  • If the call to IApplicationBuilder.AddJasper() is omitted, Jasper will add its own middleware to the very end of the pipeline
  • The HTTP bootstrapping in the idiomatic model is somewhat parallelized with the messaging support bootstrapping
  • I’d argue that this usage makes the ASP.Net Core StartUp conventional configuration model unnecessary, but you’re perfectly able to continue using that if you want.

I hope to do more optimizations to the cold startup time in the future for the idiomatic Jasper approach that would make this option be more attractive. Right now, the biggest reason to use this approach over the following is to be able to use Jasper’s console application harness and Storyteller integration.

 

Adding Jasper to an Existing ASP.Net Core System

You can also add Jasper to an existing ASP.Net Core system using its idiomatic bootstrapping approach. In this case, you still start with the JasperHttpRegistry base class from the Jasper.Http library, but you mostly use this to configure the messaging support:

public class SimpleJasperBusApp : JasperHttpRegistry
{
    public SimpleJasperBusApp()
    {
        // Enable the HTTP messaging transport
        Http.Transport.EnableListening(true);
        
        // Listen for TCP messages at port 2222
        Transports.LightweightListenerAt(2222);
    }
}

Then, to add the Jasper support to your ASP.Net Core application, you would add these calls:

var builder = new WebHostBuilder();
builder
    .UseKestrel()
    .UseUrls("http://localhost:3003")
    .UseStartup<Startup>()
    
    // This *has* to be the last call 
    // to your IWebHostBuilder
    .UseJasper<SimpleJasperBusApp>();


theHost = builder.Build();

theHost.Start();

I hate this from a usability perspective, but for right now, the call to UseJasper() has to be added after any other IStartUp registration including the UseStartup<T>() method. You still have the same ability to explicitly control the order of the Jasper middleware within your ASP.Net Core middleware pipeline.

 

 

 

Jasper v0.6: Better outbox usage, Lamar, ASP.Net Core integration changes

I’ve been a little distracted with the Lamar/BlueMilk work and Marten bug-fixing, but Jasper is still rolling along and about to get into production at work (a super early prototype is running in a low volume system now). I just pushed Jasper 0.6 to Nuget with some new improvements. The documentation has been updated and reflects the new changes described below.

Big changes:

  • Jasper uses Lamar for all IoC usage. I’m still very confident that the Jasper + Lamar (was “BlueMilk”) combination will lead to a very effective combination of flexibility and performance in the runtime pipeline. Lamar natively supports all the ASP.Net Core DI abstractions, so if you don’t care about any of its advanced features you don’t even need to care that it exists.
  • I broke the ASP.Net Core integration out into its own library, Jasper.Http. SeeAdding Jasper to an ASP.Net Core Application in the docs for the details.

    We’ve gone back and forth on whether Jasper is going to be modular or an easier to work with single library, but this one came down to the ASP.Net Core bootstrapping being somewhat expensive and making the main Jasper test suite be unnecessarily slow, so out it goes. I don’t think you’re going to notice the hit if all you do is bootstrap a single application in a test suite, but you sure do if you’re developing on Jasper itself and bootstrap and tear down 100+ applications during the integration tests;-)

  • The “outbox pattern” support was extended to cascading messages. This was an overdue improvement over its FubuMVC/FubuTransportation/RhinoServiceBus ancestors. I’ll have a blog post about this next week after every one is back from the MVP Summit.
  • IServiceBus was renamed to IMessageContext. This one will make a lot more sense with some documentation or a blog post on the outbox pattern work.
  • (Hopefully) Easier messaging support configuration. I tried hard to simplify the API underneath

Next Up…

Jasper is getting put into a production application at work within the month, and we’re doing some significant proof of concept work around using Consul for service discovery with Jasper applications and building out Octopus deployment steps for the dynamic subscriptions. Next week I’ll get back to blogging about Jasper’s integration with ASP.Net Core applications, the new HTTP transport option, and Jasper’s support for the “outbox” pattern.

Renaming BlueMilk to Lamar

BlueMilk was the early working name of a successor project to StructureMap that was originally ripped out of the new Jasper framework project. 

Most of the feedback on the name “BlueMilk” wasn’t positive. I wasn’t terribly attached to the name, so I’m officially renaming “BlueMilk” to “Lamar.” The first Nuget (v0.8) is published with the very latest work. I might be able to throw an OSS Friday sometime this week at finishing the remaining StructureMap features inside of Lamar and publishing some documentation, but we’ll see.

First, what the heck is Lamar? For most of you, it’s my intended successor to the venerable, well liked (by at least some people), and unfortunately slowpoke StructureMap library. It’s also the runtime code generation and compilation subsystem I pulled out of Jasper so folks could use that independently of Jasper.

For the moment, you can find way more information about Lamar under the “BlueMilk” tag on my blog.

What’s with the new name?

Other than Marten, most of my OSS efforts the past 2-3 years have really been working toward the Jasper framework we’re brewing up at work as a successor to FubuMVC. “Jasper” itself is just named after my ancestral hometown (Jasper, MO), and most of the other projects on the JasperFx organization are named after either other little towns around Jasper (Oakton, Alba) or local landmarks (Baseline). Fitting into that theme, Lamar is the next town up highway 71 and I’ve got plenty of family roots there as well.

Other notes that may only interest me:

  • Mirabeau B. Lamar was the 2nd president of the Republic of Texas, a hero of the TX revolution, and worlds of things in Texas are named after him. I didn’t know this until researching this post, but Lamar, MO is apparently named after him as well.
  • My wife is *this* close to completing a master’s program at Lamar University and I’m super proud of her
  • Lamar the town is the birthplace of Harry S. Truman
  • It was raided during the Civil War by Quantrill’s Raiders (think Jesse James)
  • Wyatt Earp was their first constable
  • I’m biased, but the Barton County Fair in Lamar may be the best small town fair in the entire state
  • If you’re a Modern Family friend, the Cameron character is supposedly from this area

BlueMilk is Ready for Early Adopters

This was renamed “Lamar” because the feedback on the name was, um, not good:)

 

EDIT 2/14/2018: And this already brought out a bug if you have a type that would need a closed generic type as an argument to its constructor. 0.7.1 will follow very shortly on Nuget.

 

BlueMilk is the name of a new OSS Inversion of Control tool I’m building specifically for usage in Jasper applications, but also as a higher performant replacement for StructureMap in Netstandard 2.0 applications going forward. To read more about what is genuinely unique about its internals and approach, see Jasper’s Roslyn-Powered “Special Sauce.”

I’m declaring BlueMilk 0.7 on Nuget right now as ready for enterprising, early adopter types to try out either on its own or within an ASP.Net Core application. At this point it’s passing all the ASP.Net Core compliance tests with a couple exceptions that I can’t possibly imagine being important in many cases (like the order in which created objects are disposed and a really strange way they order objects in a list when there’s mixed open and closed generic type registrations). It’s also supporting quite a few StructureMap features that I missed while trying to work with the built in DI container.

As I said in the introductory post, you can use BlueMilk as either a drop in replacement for the built in ASP.Net Core DI tool or as a faster subset of StructureMap for a much more richer feature set.

Current Feature Set

In most cases, the BlueMilk feature and API is identical to StructureMap’s and I’ll have to send you to the StructureMap documentation for more explanation.

Caveats

  • I’m wrestling with the 1st usage, warm up time just due to how long it takes Roslyn to bootstrap itself on its very first usage. What I’ve come up with so far is to have the dynamic classes for services registered as singletons or scoped be built on the initial startup, but allowing any other resolvers be built lazily the first time they are actually used. This is an ongoing struggle.
  • The lifecycle scoping is different than idiomatic StructureMap. I opted to give up and just use the ASP.Net team’s new definition for what “transient” and “scoped” means.
  • There is a dependency for the moment on a library called Baseline, that’s just my junk drawer of convenience extension methods (leftovers from FubuCore for anyone that used to follow FubuMVC). Before BlueMilk hits 1.0, I’ll internalize those extension methods somehow and eliminate that dependency

Using within ASP.Net Core Applications

You’ll want to pull down the BlueMilk.Microsoft.DependencyInjection package to get the ASP.Net Core bootstrapping shim — and blame the ASP.Net team for the fugly naming convention.

In code, plugging in BlueMilk is done through the UseBlueMilk() extension method as shown below:

var builder = new WebHostBuilder();
builder
    .UseBlueMilk()
    .UseUrls("http://localhost:5002")
    .UseKestrel()
    .UseStartup();

Pretty standard ASP.Net Core stuff. Using their magical conventions on the Startup class, you can do specific BlueMilk registrations using a ConfigureContainer(ServiceRegistry) method as shown below:

public class Startup
{
    public void ConfigureContainer(ServiceRegistry services)
    {
        // BlueMilk supports the ASP.Net Core DI
        // abstractions for registering services
        services.AddLogging();

        // And also supports quite a few of the old 
        // StructureMap features like type scanning
        services.Scan(x =>
        {
            x.AssemblyContainingType<SomeMarkerType>();
            x.WithDefaultConventions();
        });

     }

 // Other stuff we don't care about here
}

Durable Messaging in Jasper

My colleague Mike Schenk had quite a bit of input and contributions to this work. This continues a series of blog posts just trying to build up to the integration of durable messaging with ASP.Net Core:

  1. Jasper’s Configuration Story 
  2. Jasper’s Extension Model
  3. Integrating Marten into Jasper Applications
  4. Durable Messaging in Jasper (this one)
  5. Integrating Jasper into ASP.Net Core Applications
  6. Jasper’s HTTP Transport
  7. Jasper’s “Outbox” Support within ASP.Net Core Applications

 

Right now (0.5.0), Jasper offers two built in message transports using either raw TCP socket connections or HTTP with custom ASP.Net Core middleware. Either transport can be used in one of two ways:

  1. Fire and Forget” — Fast, but not backed by any kind of durable message storage, so there’s no guaranteed delivery.
  2. Store and Forward” — Slower, but make damn sure that any message sent is successfully received by the downstream service even in the face of system failures.

Somewhere down the line we’ll support more transport options like RabbitMQ or Azure Service Bus, but for right now, one of the primary design goals of Jasper is to be able to effectively do reliable messaging with the infrastructure you already have. In this case, the “store” part of durable messaging is going to be the primary, backing database of the application. Our proposed architecture at work would then look something like this:

Slide1

So potentially, we have multiple running instances (“nodes”) of each service behind some kind of load balancer (F5 in our shop), with each service having its own dedicated database.

For the moment, we’ve been concentrating on using Postgresql through Marten to prove out the durable messaging concept inside of Jasper, with Sql Server backing to follow shortly. To opt into that persistence, add the MartenBackedExtension extension from the Jasper.Marten library like this:

public class PostgresBackedApp : JasperRegistry
{
    publicPostgresBackedApp()
    {
        Settings.ConfigureMarten(_ =>
        {
            _.Connection("some connection string");
        });

        // Listen for messages durably at port 2301
        Transports.DurableListenerAt(2301);

        // This opts into Marten/Postgresql backed
        // message persistence with the retry and
        // message recovery agents
        Include<MartenBackedPersistence>();
     }
}

What this does is add some new database tables to your Marten configuration and directs Jasper to use Marten to persist incoming and outgoing messages before they are successfully processed or sent. If you end up looking through the code, it uses custom storage operations in Marten for better performance than the out of the box Marten document storage.

Before talking about all the ways that Jasper tries to make the durable messaging as reliable as possible by backstopping error conditions, let’s talk about what actually happens when you publish a message.

What Happens when You Send a Message?

When you send a message through the IServiceBus interface  or through cascading messages, Jasper doesn’t just stop and send the actual message. If you’re publishing a message that is routed by a durable channel, calling this code:

public async Task SendPing(IServiceBus bus)
{
    // Publish a message
    await bus.Send(new PingMessage());
}

will result in an internal workflow shown in this somewhat simplified sequence diagram of the internals:

Handling a Message w_ Unit of Work Middleware

The very first thing that happens is that each outgoing copy of the message is persisted to the durable storage, which is Postgresql in this post. Next, Jasper batches outgoing messages in a similar way to the debounce operator in Rx by outgoing Uri. If you’re using either the built in TCP or HTTP transports, the next step is to send a batch of messages to the receiving application. The receiving application in turn first persists the incoming messages in its persistence, and sends back an acknowledgement to the original sending application. Once the acknowledgement is received, the sending application will delete the outgoing messages just sent successfully from its message persistence and go on its merry way.

That’s the “store and forward” happy path. Now let’s talk about all the myriad ways things could go wrong and what Jasper tries to do to ensure that your messages get to where they are supposed to go.

Network Hiccups

How’s that for a scientific term? Sending message batches will occasionally fail due to the normal litany of temporary network issues. If an outgoing message batch fails, all the messages get their “sent attempts” count incremented in storage and they are added back into the local, outgoing sending agent queue to be tried again.

Circuit Breaker

Jasper’s sending agents implement a form of the Circuit Breaker pattern where a certain number of consecutive failures (it’s configurable) to send a message batch to any destination will cause Jasper to latch that sending agent. When the sending agent is latched, Jasper will not make any attempts to send messages to that destination. Instead, all outgoing messages to that destination will simply be persisted to the backing message persistence without any node ownership. The key point here is that Jasper won’t keep trying to send messages just to get runtime exceptions and it won’t allow the memory usage of your system to blow up from all the backed up, outgoing messages being in an in memory sending queue.

When the destination is known to be in a failure condition, Jasper will continue to poll the destination with a lightweight ping message just to ascertain if the destination is back up yet. When a successful ping is acknowledged by the destination, Jasper will unlatch the sending agent and begin sending outgoing messages.

Resiliency and Node Failover

If you are using the Marten/Postgresql backed message persistence, your application has a constantly running message persistence agent (it’s actually called SchedulingAgent) that is polling for persisted messages that are either owned by no specific node or persisted messages that are owned by an inactive node.

To detect whether a node is active, we rely on each node holding a session level advisory lock in the underlying Postgresql database as long as it’s really active. Periodically, Jasper will run a query to move any messages owned by an inactive node to “any node” ownership where any running node can recover both the outgoing and incoming messages. This query detects inactive nodes simply by the absence of an active advisory lock for the node identity in the database.

The message persistence agent also polls for the existence of any persisted incoming or outgoing messages that are not owned by any node. If it detects either, it will assign some of these messages to itself and pull outgoing messages into its local sending queues and incoming messages into its local worker queues to be processed. The message polling and fetching was designed to try to enable the recovery work to be spread across the running nodes. This process also uses Postgresql advisory locks as a distributed lock to prevent multiple running nodes from double dipping into the same persisted messages.

The end result of all that verbiage is:

  • If the receiving application is completely down, Jasper will be able to recover the outgoing messages and send them later when the receiving application is back up
  • If a node fails before it can send or process all the messages in flight, another node will be able to recover those persisted messages and process them
  • If your entire application goes down or is shut down, it will pick up the outstanding, persisted work of incoming and outgoing messages when any node is restarted
  • By using the advisory locks in the backing database, we got around having to have any kind of distributed lock mechanism (we were considering Consul) or leader election for the message recovery process, making our architecture here a lot simpler than it could have been otherwise.

 

More Work for the Future

The single biggest thing Jasper needs is early adopters and usage in real applications to know how what it already has for resiliency is working out. Beyond that though, I know we want at least a little more work in the built in transports for:

  1. Backpressure — We might need some kind of mechanism to allow the receiving applications let the senders know, “hey, I’m super busy here, could you stop sending me so many messages for a little bit” and slow down the sending.
  2. Work Stealing — We might say that its easier to implement back pressure between the listening agent and worker queues within the receiving application. In that case, if the listener sees there are too many outstanding messages waiting to be processed in the local worker queues, it would just persist the incoming messages for any other node to pick up when it can. We think this might be a cheap way to implement some form of work stealing.
  3. Diagnostics — We actually do have a working diagnostic package that adds a small website application to expose information about the running application. It could definitely use some additional work to expose metrics on the active message persistence.
  4. Sql Server backed message persistence — probably the next thing we need with Jasper at work

 

Other Related Stuff I Didn’t Get Into

  • We do have a dead letter queue mechanism where messages that just can’t be processed are shoved over to the side in the message persistence. All configurable of course
  • All the message recovery and batching thresholds are configurable. If you’re an advanced Jasper user, you could use those knobs to fine tune batch sizes and failure thresholds
  • It is possible to tell Jasper that a message expires at a certain time to prevent sending messages that are just too old

 

Integrating Marten into Jasper Applications

Continuing a new blog series on Jasper:

  1. Jasper’s Configuration Story 
  2. Jasper’s Extension Model
  3. Integrating Marten into Jasper Applications  (this one)
  4. Durable Messaging in Jasper
  5. Integrating Jasper into ASP.Net Core Applications
  6. Jasper’s HTTP Transport
  7. Jasper’s “Outbox” Support within ASP.Net Core Applications

 

Using Marten from Jasper Applications

Time to combine two of my biggest passions (time sinks) and show you how easy it is to integrate Marten into Jasper applications. If you already have a Jasper application, start by adding a reference to the Jasper.Marten Nuget. Using Jasper’s extension model, the Jasper.Marten library will automatically add IoC registrations for the Marten:

  1. IDocumentStore as a singleton
  2. IQuerySession as scoped
  3. IDocumentSession as scoped

At a bare minimum, you’ll at least need to tell Jasper & Marten what the connection string is to the underlying Postgresql database something like this sample:

public class AppWithMarten : JasperRegistry
{
    public AppWithMarten()
    {
        // StoreOptions is a Marten object that fulfills the same
        // role as JasperRegistry
        Settings.Alter<StoreOptions>((config, marten) =>
        {
            // At the simplest, you would just need to tell Marten
            // the connection string to the application database
            marten.Connection(config.GetConnectionString("marten"));
        });
    }
}

In this case, we’re taking advantage of Jasper’s strong typed configuration model to configure the Marten StoreOptions object that completely configures a Marten DocumentStore in the underlying IoC container like this from the Jasper.Marten code:

// Just uses the ASP.Net Core DI registrations
registry.Services.AddSingleton<IDocumentStore>(x =>
{
    var storeOptions = x.GetService<StoreOptions>();
    var documentStore = new DocumentStore(storeOptions);
    return documentStore;
});

And for the basics, that’s all there is to it. For right now, the IDocumentSession service is resolved by calling IDocumentStore.OpenSession(), but it’s likely users will want to be able to opt for either lightweight sessions or configure different transactional levels. I don’t know what that’s going to look like yet, but it’s definitely something we’ve thought about for the future.

 

 

 

Jasper’s Extension Model

Continuing a new blog series on Jasper:

  1. Jasper’s Configuration Story 
  2. Jasper’s Extension Model (this one)
  3. Integrating Marten into Jasper Applications
  4. Durable Messaging in Jasper
  5. Integrating Jasper into ASP.Net Core Applications
  6. Jasper’s HTTP Transport
  7. Jasper’s “Outbox” Support within ASP.Net Core Applications

 

 

The starting point of any Jasper application is the JasperRegistry class that defines the configuration sources, various settings, and service registrations, similar in many respects to the IWebHostBuilder and Startup types you may be familiar with in ASP.Net Core applications (or the FubuRegistry for any old FubuMVC hands). A sample one is shown below:

public class SubscriberApp : JasperRegistry
{
    public SubscriberApp()
    {
        Subscribe.At("http://loadbalancer/messages");
        Subscribe.ToAllMessages();

        Transports.LightweightListenerAt(22222);
    }
}

If everything you can possibly change or configure is done by the internal DSL exposed by the JasperRegistry class, it’s only natural then that the extension model is just this:

public interface IJasperExtension
{
    void Configure(JasperRegistry registry);
}

As a sample, here’s an available extension from the Jasper.Marten library that lets you opt into using Marten-backed message persistence that will be featured in a blog post later in this series:

/// <summary>
/// Opts into using Marten as the backing message store
/// </summary>
public class MartenBackedPersistence : IJasperExtension
{
    public void Configure(JasperRegistry registry)
    {
        // Override an OOTB service in Jasper
        registry.Services.AddSingleton<IPersistence, MartenBackedMessagePersistence>();

        // Jasper works *with* ASP.Net Core, even without a web server,
        // so you can use their IHostedService model for long running tasks
        registry.Services.AddSingleton<IHostedService, SchedulingAgent>();

        // Customizes the Marten integration a little bit with
        // some custom schema objects this extension needs
        registry.Settings.ConfigureMarten(options =>
        {
            options.Storage.Add<PostgresqlEnvelopeStorage>();
        });
    }
}

To apply and use these extensions, you have two options. First, you can say that the exposed extension has to be explicitly added by the application developers in their JasperRegistry with syntax like this:

public class ItemSender : JasperRegistry
{
    public ItemSender()
    {
        Include<MartenBackedPersistence>();
        // and a bunch of other stuff that isn't germane here
    }
}

The other option is to make an extension be auto-discovered and applied whenever the containing assembly is part of the application. To do this, add an assembly level attribute to your extension library that references the extension type you want auto-loaded. Here’s an example from the Jasper.Consul extension library:

// This is a slight change from [FubuModule] in FubuMVC
// Telling Jasper what the extension type is just saves the
// type scanning discovery. Got that idea from a conversation
// w/ one of the ASP.Net team members
[assembly:JasperModule(typeof(ConsulExtension))]

namespace Jasper.Consul.Internal
{
    public class ConsulExtension : IJasperExtension
    {
        public void Configure(JasperRegistry registry)
        {
            registry.Services.For<IUriLookup>().Add<ConsulUriLookup>();
            registry.Services.For<IConsulGateway>().Add<ConsulGateway>();
        }
    }
}

When to use either model? I’m a big fan of the “it should just work” model and the auto-discovery in many places, but plenty of other folks will prefer the explicit Include<Extension>() call in their JasperRegistry to make the code be more self-documenting.

In either case, there’s a little bit of trickery going on behind the scenes to order both the service registrations and any changes to “Settings” objects to create a precedence order like this:

  1. Application specific declarations in the JasperRegistry class — regardless of the ordering of where the Include() statements wind up
  2. Extension declarations
  3. Core framework defaults

 

A Little History about the Ideas Here

When Chad Myers and I started talking through the ideas that later became FubuMVC, one of our goals was to maximize our ability to apply customer-specific extensions and customizations to the on premises model application we were building at the time. We knew that many a software shop had crashed and burned in that situation if they resorted to using customer specific forks of their core product. We envisioned a web framework that would pretty well let you add or change almost anything in customer extensions without forcing any kind of fork to the core application. The Open-Closed Principle taken to an extreme, if you will. Using FubuMVC extensions (we originally called them “Bottles”), you could add all new routes, change IoC service registrations, swap out views, and even inject content into existing views in the core application with a model where you just drop the extension assembly into the bin path of the application and go.

I want to say that it’s one of the cleverest things I’ve ever successfully completed, and it definitely added some value (not so much in the app it was meant for because they ditched the on premises model shortly after and succeeded without the crazy extensibility;)) All that said though, Jasper is meant for a different world where we might not be quite so eager to build large applications and I’m much more gun shy about complexity in my OSS projects than 10 years younger me was, so the extensibility will not be quite so big a part of Jasper’s core identity and philosophy as it was in the FubuMVC days.

 

Jasper’s Configuration Story

A couple dozen times I’ve sat around a table at some kind of software conference swapping software horror stories with other developers, all of us trying to one up each other. The winning story usually ends up being some kind of twisted usage of stored procedures to build dynamic websites or something just as berserk. Just behind misuse of sprocs is stories of naive teams that hard coded some kind of value like a database connection string, a file path, or an email address that should really be in some kind of external configuration source. If you’re going to use Jasper to build applications, this post is all about how to avoid being the subject of one of those horror stories by using .Net configuration with Jasper.

This is meant to be the start of a series of related blog posts on Jasper that lead up to how we intend to support durable messaging within an ASP.Net Core application without forcing you to use distributed transactions. Not promising when they’ll be done, but I’m planning:

  1. Jasper’s Configuration Story (this one)
  2. Jasper’s Extension Model
  3. Integrating Marten into Jasper Applications
  4. Durable Messaging in Jasper
  5. Integrating Jasper into ASP.Net Core Applications
  6. Jasper’s HTTP Transport
  7. Jasper’s “Outbox” Support within ASP.Net Core Applications

I think this will be the longest post by far.

When I published my blog post introducing Jasper a couple weeks ago, I used this sample code to show a minimal Jasper application that would listen for incoming messages at port 2601:

    class Program
    {
        static int Main(string[] args)
        {
            return JasperAgent.Run(args, _ =>
            {
                _.Logging.UseConsoleLogging = true;

                _.Transports.LightweightListenerAt(2601);
            });
        }
    }

I wrote that sample purposely to be as simple as possible, but that led to the obvious question about how to pull the port number from configuration from folks reading the code sample. As of now, Jasper gives you a couple options. The first option is to use our integration with the configuration support from ASP.Net Core.

First though, I’m going to move the application bootstrapping code above into a JasperRegistry class (think Startup classes in ASP.Net Core applications) like this:

public class PongerApp : JasperRegistry
{
    public PongerApp()
    {
        Logging.UseConsoleLogging = true;
        Transports.LightweightListenerAt(2601);
    }
}

and then that application would be bootstrapped with code like this:

class Program
{
    static int Main(string[] args)
    {
        return JasperAgent.Run(args);
    }
}

Great, now let’s pull the port number from configuration, in this case from environment variables:

public class PongerApp : JasperRegistry
{
    public PongerApp()
    {
        // Declare what configuration sources we want
        Configuration
            .AddEnvironmentVariables()
            .AddJsonFile("ponger.settings.json");

        // Use the final product of the configuration root data
        // to configure the application
        Settings.WithConfig(root =>
        {
            var port = root.GetValue("INCOMING_PORT");
            Transports.LightweightListenerAt(port);
        });
    }
}

A couple quick things to note:

  1. JasperRegistry.Configuration is a ConfigurationBuilder object from ASP.Net Core
  2. The root argument to the nested closure in Settings.WithConfig() is the IConfigurationRoot object compiled from the JasperRegistry.Configuration object.

It’s admittedly a little cumbersome with the nested closure in the call to Settings.WithConfig(), but doing it that way helps Jasper order operations for you so that all additions to the ConfigurationBuilder are calculated once before you execute the nested closure. In the FubuMVC days I called the “Mongolian BBQ” approach where you declare the ingredients you want and let’s the framework figure out how to do things in order for you just like the cook at a Mongolian BBQ restaurant.

This is maybe the simplest conceptual way to add external configuration, but there are a couple other options in Jasper.

Uri Aliases

We’ve been using this code to direct Jasper to listen for messages at a certain port with its built in TCP transport in its “fire and forget” mode:

public class PongerApp : JasperRegistry
{
    public PongerApp()
    {
        Transports.LightweightListenerAt(2601);
    }
}

That code is just syntactical sugar for this code that instead supplies a meaningful Uri:

public class PongerApp : JasperRegistry
{
    public PongerApp()
    {
        Transports.ListenForMessagesFrom("tcp://localhost:2601");
    }
}

Now, let’s move the Uri for where and how the application should listen for incoming messages to an application json configuration file like this one:

{
    "incoming": "tcp://localhost:2601"
}

Finally, we can use Jasper’s concept of Uri aliases to configure the application like this:

public class PongerApp : JasperRegistry
{
    public PongerApp()
    {
        Configuration
            .AddJsonFile("ponger.settings.json");
        
        Transports.ListenForMessagesFrom("config://incoming");
    }
}

At runtime, Jasper will translate the Uri “config://incoming” to “the Uri string in the configuration with the key ‘incoming.'” There’s a couple other things to note about Uri aliases:

  • The aliasing strategies are pluggable, but the “config” option is the only one that comes out of the box. We also have an option to use Consul’s key/value storage in the Jasper.Consul extension.
  • The aliases are valid in any place where you use a Uri to send or route messages

Strong Typed Configuration

I’m a big fan of strong typed configuration going back to the “Settings” model in FubuMVC, and it’s even part of ASP.Net Core proper with their Options model. With quite a bit of help from my colleague Mark Wuthrich, Jasper brings the old Settings model forward with some lessons learned type improvements.

Using Jasper’s strong typed configuration, you can do this instead:

public class PongerSettings
{
    public Uri Incoming { get; set; }
}

public class PongerApp : JasperRegistry
{
    public PongerApp()
    {
        Configuration
            .AddJsonFile("ponger.settings.json");

        Settings.With(settings =>
        {
            Transports.ListenForMessagesFrom(settings.Incoming);
        });
    }
}

where the “ponger.settings.json” file would look something like:

{ "incoming": "tcp://localhost:2601" }

I like the Settings model personally because of the traceability between configuration elements and the places in the code that consumes those elements. I wouldn’t bother with the Settings model in this simple of an application, but it might make sense in a bigger application. Do note that the Settings objects are part of the underlying IoC registrations and are available to be injected into any kind of message or HTTP handler class in your application code.

It’s Just Code, Do Whatever You Want

Don’t like any of the options that Jasper provides out of the box? No worries, the JasperRegistry configuration is an example of an “internal DSL,” meaning that it’s fair game to use any kind of .Net code you want like maybe this:

public class PongerApp : JasperRegistry
{
    public PongerApp()
    {
        // Programmatically find the incoming Uri any way you want
        // with your own code
        string uri = Environment.GetEnvironmentVariable("PONGER_INCOMING_URI");
        Transports.ListenForMessagesFrom(uri);
    }
}

Introducing BlueMilk: StructureMap’s Replacement & Jasper’s Special Sauce

BlueMilk is the codename for a new project that’s an outgrowth from our new Jasper framework. Specifically, BlueMilk is extracting the runtime code generation and compilation “Special Sauce” support code that’s in Jasper now into a stand alone library. Building upon the runtime code generation, the logical next step was to make BlueMilk into the intended successor to the venerable StructureMap project as a fast, minimal IoC container on its own, but also supports inlining the service activation code into Jasper’s message and HTTP request handlers.

I think these are the key points for BlueMilk:

  1. Support the essential functionality and configuration API of StructureMap to be an offramp for folks invested in StructureMap that want to move to a faster option in their Netstandard2 applications
  2. Align much closer with the ASP.Net team’s DI compliance behavior. In some cases like object lifecycles, this is a breaking change with StructureMap’s traditional behavior and I don’t entirely agree with their choices, but .Net is their world and all us scrappy community OSS authors are just living in it.
  3. Easy integration into ASP.Net Core applications by directly supporting their abstractions (IServiceCollection, IServiceProvider, ServiceDescriptor, IServiceScope, etc.) out of the box.
  4. Trade in some of the runtime flexibility that StructureMap had in favor of better performance (and fewer ways for users to get themselves in a tangle)
  5. Expose the runtime code generation and compilation model (originally built for Marten, but we took it out later) in a separate library because a few folks have expressed some interest in having just that without using Jasper

There’s a preliminary Nuget up this morning (0.1.0) that supports some of StructureMap’s behavior and all of the ASP.Net Core compliance. You can use a container like this:

// Idiomatic StructureMap
var container = new Container(_ =>
{
    _.For<IWidget>().Use<AWidget>().Named("A");
    
    // StructureMap's old type scanning
    _.Scan(s =>
    {
        s.TheCallingAssembly();
        s.WithDefaultConventions();
    });
});

var widget = container.GetInstance<IWidget>();

// ASP.Net Core DI compatible
IServiceProvider container2 = new Container(_ =>
{
    _.AddTransient<IWidget, AWidget>();
    _.AddSingleton(new MoneyWidget());
});

var widget2 = container.GetService<IWidget>();

 

My Thoughts on Project Scope

I only started working on BlueMilk by itself over the holidays, so it’s not like anything is truly set in concrete, but this list is what I think the scope would be. My philosophy here is to jettison many of the features in StructureMap that cause internal complexity, performance issues, or generate loads of user questions and edge case bugs.

Core Functionality

  1. All ASP.Net Core DI compliance — lifecycle management (note that it’s different than StructureMap’s lifecycle definitions), object disposal, basic service resolution, open generic support, dealing with enumerable types
  2. StructureMap’s basic support for service location
  3. Nested Containers (scoped container)
  4. Type Scanning from StructureMap
  5. Service resolution by name
  6. Lazy & Func<T> resolution
  7. WhatDoIHave() and other diagnostics — no IoC or any other kind of framework author should release a tool without something like this for the sake of their own sanity
  8. Auto-find missing registrations — one of my biggest gripes about the built in container

Later

  1. Inline dependencies
  2. AutoFactory support — I think this could work out very well with the code generation model
  3. Construction Policies
  4. Some of StructureMap’s attribute configuration

Leaving Behind unless someone else really wants to build *and* help support it

  • Interception — Maybe. I’m not super excited about supporting it
  • Child containers and profiles. Utter nightmare to support. Edge case hell. Crazy amount of complexity internally. The only way we use them in work is for per-test isolation, and we can live without them in that case
  • Changing configuration at runtime (Container.Configure()).
  • Passing arguments at runtime. One of the biggest sources of heartburn for me supporting StructureMap. I think the better autofactory support in BlueMilk could be a far better alternative anyway.

Why do this?

One of my fervent goals with Jasper from the very beginning was to maximize performance to the point where its throughput was barely distinguishable from laboriously writing highly optimized bespoke code by hand. I wanted users to have all the productivity benefits of a good framework that takes care of common infrastructure needs without sacrificing performance. I know that some folks will disagree, but I still think there’s ample reasons to use an IoC container to handle quite a bit of the object composition, service activation, object scoping, and service cleanup.

If you allow that assumption of IoC usage, that left me with a couple options and thoughts:

  • I think it’s hugely disadvantageous to .Net frameworks to have to support multiple IoC containers. My experience is that basically every single framework abstraction I have ever seen for an IoC container has been problematic. If you are going to support multiple IoC containers in your application framework, my experience from FubuMVC and from watching the unfolding consternation over ASP.Net Core’s DI compliance is to restrict your framework from making all but a handful of assumptions about IoC container behavior.
  • I could just use my own StructureMap container because I understand it front to back and it fits the way that I personally work and all the .Net developers in my shop know it. The only problem there is that StructureMap has fallen behind in terms of performance. I think I have a decent handle on what it would take to reverse that with a potential 5.0, but I’m just not up for doing the work, I’m exhausted keeping up with user questions, and I really want to get out of supporting StructureMap.
  • I tried a couple times to just use the new built-in ASP.Net Core DI tool, but it’s extremely limited and I was getting frustrated with how many things were missing and how much more hand holding it took to be usable compared to StructureMap.

If you saw my Jasper’s Special Sauce post last week, you know that we are already using the service registration information to opt into inlining all the object construction and disposal directly into the generated message handlers whenever possible. The code that did that was effectively the beginning of a real IoC container, so it wasn’t that big of a jump to pulling all of that code into its own library and building it into the IoC tool that I wanted a theoretical StructureMap 5.0 to be.