Quick and Dirty Command Handlers, Event Handlers, Wiring it Up

In my last post, I talked about a "quick and dirty" way to create a command bus in F#. In this post, we're going to look at a simple set of command handlers to plug into said bus and some event handlers.

Before I jump right in, let's define what we're looking for. I want to use NEventStore for my event bus (comes with some nice features that make getting up and running much faster). Feel free to plug in whatever event store you might feel like. Creating (an extremely basic) event store isn't too terribly hard, but I am not going to cover it in this post. So, without dragging this out too much more, let's create a function that wraps up the creation of NEventStore.

Serializer

NEventStore needs a serializer. It comes with a few baked in, but I have grown fond of FsPickler. It is really fast and convenient since we're using F#. Here's a quick little helper to create our serializer on demand.

Dispatcher

NEventStore also accepts a dispatcher (the thing that is given the events as they come in). Here is where we're going to accept (for now) our event handlers. If needed, as the documentation suggests, we could fire these events off onto a bus like NServiceBus or Mass Transit. All we're going to do (again, for now) is create a function that will return a dispatcher that passes each event to our event handlers. An event handler is just a function that takes a Guid (the entity's id) and a list (ResizeArray) of events.

Create the Event Store

And, finally, we need to create the event store. There is nothing fancy here, it is pretty much just like the example documentation, just using our serializer and dispatcher. It will also use SQL Server as the backing store along with storing the streams in memory.

So, now that we have an event stream, we can push it into our command handlers and extend our setup function from the last post. We're going to change our command handler function to take in bus. We can simply map the original functions and "apply" the event bus, and then pass the resulting functions into the original "createCommandRouter" function.

A simple little domain

Let's take a look at a silly example of a domain, a counter. The counter can be incremented and decremented and that's about it. Since this is all in F#, we'll use a record to define an entity's state and discriminated union to describe the commands and events. This is a pretty common theme if you go hunting around the internet and it has worked out very well for my projects. Our entities will consist of a state, an apply function, and a handle function. (Lev Gorodinski has a really good write-up on this approach and was the basis for my personal "Ah-ha!" moment.)

Now we just need to wire-up our command handler to use the apply and handle functions. Please keep in mind that this is a "Quick and Dirty" solution to get us going and exploring our domain and wiring things up. You will likely need to a function that the handler can call if it encounters and exception and will probably need to rework the domain to return multiple events from commands and then make the appropriate changes in the command handler to handle that. (Simple, really, but too much noise for this post. I will explore these things in a later post.)

Event handlers are just as simple. They can be used to respond to events from your domain and do things like update projections that feed the application. Our "q 'n d" event handler looks something like this:

The DomainStartup

Putting this together, we now get our new domain startup.

This post is already getting long so I will end it here. Have any feedback or questions, please leave them in the comments or hit me up on Twitter. I'd love to hear how you get started quickly on projects to feel productive without building too much cruft.

Quick and Dirty Command Bus with F#

When developing a new application that could benefit from the Domain Drive Design (DDD), Command Query Responsibility Segregation (CQRS), and Event Sourcing (ES) I like to start out with a "quick and dirty" stack, if you will. It should meet the needs of the application in the beginning with extensibility points baked in so that I can scale out in the areas that make sense. One of the hardest parts about this is worrying about how to serialize commands to command handlers in a way that can be scaled.

One of the interesting pieces of F# (which is not F# specific, of course) is the built-in use of agent-based programming. Using the built-in MailboxProcessor we can easily write a miniature command and event bus. Not having to worry about how to build this specific piece of infrastructure (to start) allows us to focus on building the application and then plug in new pieces as we need. For many applications this approach will probably be "good enough" and might solve our needs.

So, let's take a look at what we want from our buses. Let's ignore, for now, the fact that a command should only every be handled by one command handler. Our application is just starting out, it's small, and we can keep the pieces in our head. We aren't loading up assemblies in some dynamic nature so we can visibly look at a module and see what handlers are registered. (If you can't do this, it might be time to move up a level.) Since we're not going to explicitly determine that a command must only be handled by one handler, we can assume that the two buses (Event and Command, that is) can behave the same way. A "message" comes in and it gets handed off, in a serialized fashion, to the "listeners".

This post will cover the command bus.

Command Router Interface

Let's define a little interface for our command router (the bus).

This simple little thing allows us to create different buses as we need. Of course, to start, we'll just need something to allow us to send commands into the domain. Let's now define the look of our command. We probably want to know who sent in the command, the id of the entity we're targeting, and the command itself.

So here we have a discriminated union that describes who sent the command, a record that describes some "header data" that we might need, and then the "command." The "body" portion of the "Command" record is where we'll tuck away the actual command. (We're using obj instead of a generic to make our life a little easier later. Cheating, yeah.)

Create the darn thing

Let's put our IRouter interface to work. We're only going to have one instance of the bus but we might have multiple buses. We can put together a helper function that takes in our "handlers" and returns us an instance of the bus. A handler is just a function that takes a command and returns unit (void).

Now we can wire it up to our application. Since I am partial to Simple.Web and StructureMap, I'm going to show that here, but it should be fairly obvious how to do this in your preferred framework.

I'm punting for now and putting in some fake "createHandlerN" functions into a list and then passing it into the command router function. In my next post I'll cover what those look like and how to make this play nicely with a simple event bus using NEventStore. Until then, I'm always open for feedback on what I have presented and am interested in how you might have solved this sort of problem yourself! Overall, though, nothing difficult about this and it will help us break apart our applications very nicely.

Please Don't be Afraid of Command Query Responsibility Segregation (CQRS)

I know that I'm not the only person who has said this and I'm probably not going to be the last, but after discussing this very thing with a few people I think it is worth emphasizing. When I talk to other developers about what images the four words "Command Query Responsibility Separation" conjure, it is interesting. Often times I hear elaborate stories about event sourcing, eventual consistency, and a lot of crazy technology stacks.

It is a shame that this idea seems to be so prevalent, causing a lot of developer to discard it as overly complicated. If we look at the words that comprise the acronym, it seems silly that we attribute so much to it. In my mind, we have wrapped up so many ideas into this simple concept that it is almost like freaking out because somebody is attempting to use SOLID development practices. (Watch out for all of those crazy classes and interfaces!) At its core, CQRS is simple. Very simple. The idea is that we recognize that a call from an outside entity to mutate the state of our application and a call to get state information are two totally separate things. And, as such, should be modeled differently.

Real world pain

I worked on a project that interfaced with a COBOL "backend" for the government. One of the things that we had to face on that project was how the COBOL programmers viewed the world. When we needed to query anything or send in a "command" it would use, in their terms, the same screen. Basically, they had an old green screen AS-400 set of screens (over 200) that we just pushed data into and pulled it out of over a WSDL endpoint. It made it absolutely impossible for us to gain any context on the web side of the world because the same "screen" was used to ask for data and to mutate it. We also had to serialize a hundreds of empty fields back to the COBOL application with maybe one or two filled in just to get some data back. Needless to say this was a painful and error-prone process.

Once the web world had kind of taken over my team thought (foolishly) that we would start writing the logic on our side and deprecate the COBOL world. Unfortunately, development continued in the COBOL application. What we were able to do, though, was talk to the COBOL developers and get them to change the way we requested information. We found out that the "screens" we were sending back and forth did not, in fact, have to have identical fields. It was just how they had always done it when interfacing with the green screen.

After some discussion, we actually got a few of the new programs to utilize different fields for input and output. This even went so far as to breaking apart a few of the monolithic monsters that that gave us huge headaches and were pretty much impossible to test. (I'm talking QA testing, too. Unit/Integration tests were impossible.) This really helped speed up the development process and allowed a cleaner definition of what was required for input versus output. This was especially helpful for screens that returned collections. Before the change, we would have to send a request with (hundreds) of empty rows just so the COBOL program would have the correct data.

Oh, and this application is still being developed as of today. This isn't some horror story from the 90s.

CQRS versus the Command Pattern

Another thing to watch out for is mixing up ideas from the Command Pattern and CQRS. The commands in CQRS are not the same thing. Usually, in the command pattern, the command has an execute method on it that does the actual work. That is not how the commands work for CQRS. The commands should be built as Plain Old (Insert your development framework/language here) Objects. For us in the .NET world those are POCOs and, for Java devs, POJOs. (As was kindly pointed out in the comments: just a data structure.) They are just property bags that carry the intent of the user (a human or another system) to the domain.

Eventual Consistency

This is another thing that constantly gets tied to CQRS. Unfortunately, there is absolutely no reason that we have to have eventual consistency with CQRS. It is perfectly fine to inject a command handler into your web endpoint and pass in the command directly. We don't need a command bus to enjoy the magic of CQRS. And along with this, we also get:

Event Systems

And, for that matter, we don't have to have event systems in place to make use of CQRS. These are things that we can add to our system as we need to scale out and get a better feel for our domain. If these things are a requirement for your domain, obviously plan ahead and make extension points where you can plug these things in.

Why the confusion and over complication?

When I was able to make the shift over and try it out, plainly, without the overhead and complications I could see why. It is liberating. Once I broke everything apart and started practicing CQRS I could see how I could really empower my systems and make them even more decoupled by taking the next step. Adding in a command bus and event sourcing is a natural progression. Even so, we can implement a cheaper version of the two without a bunch of crazy overhead. This is made even more possible with (you guessed it!) F#. This will be the topic of my next post, so stay tuned!

Asynchronous Command Handlers, Object Identity, and CQRS

I have been working on a (closed-source, unfortunately) project in my spare time and have been using the Command Query Responsibility Separation (CQRS) pattern. In most places, it is pretty easy to utilize asynchronous command handlers, but there was one part that tripped me up a little bit. When a user creates a new aggregate root via, say, a web page, how do we handle the asynchronous nature of the command handler?

At one point, I thought about making these creation-type command handlers synchronous so the user could be warned if the creation has failed or if there were errors. I was not very happy with this because it meant that I couldn't just place the command on a bus and move on. It meant I cannot offload that work somewhere else and the user has to sit and wait for this thing to go on. Basically, an all around uncomfortable situation.

Why?

So, what made me care about this? Why is it important to think about? Well, it has some implications. First off, it makes one consider how an object's identity is created. If we have the domain create the id, then we have to sit around and wait for it to complete. (Hence, my dilemma.) Overall, this could work, but I was not satisfied with it. After all, my goal was to allow the web application to do as little processing as possible, other than serving up pages and communicating with the service bus.

Were do we go from here? I was a bit stumped and almost gave in to the idea that I would have to accept this band-aid fix as a permanent solution. Luckily, after some thought, and drawing some pictures, I realized I was looking at the problem from the wrong point of view. Shifting my thinking, the answer seemed pretty obvious and I wasn't sure why I didn't see it in the first place!

The First Step

The first step to my clarity was deciding that the domain did not need to be in charge of creating an identity. Instead, why can't we pass in, say a globally unique id (GUID) and tell the domain that we expect something to be created with this id? Now, we don't have to sit around and wait on some database to assign and id and filter it back to the user. So, as part of our command, we can create a new identity and pass it into the domain from the web server. Now, since the server has the targeted identity, we can forward the user to a "Success!" page with the new identity as a hidden field. We can either set a timer to forward the user to the read only model or provide a link on which the user can click.

But, what if it fails?

What if the creation fails? Well? Who cares? What does that actually mean in the domain? For me, in my current project, it didn't matter. We can display an "Oops! We screwed up!" page with a link back the creation page. We could go so far as to reload the creation page with the data passed in (since we have the command, after all). Even if the user cheats the system and tries to re-use an identity to create an aggregate to maybe cheat the system, we can detect it (the aggregate cannot be created when it has already been created!) and show the user an error page.

Wait, create what was already created?

Let's say a malicious user wants to try to trick the system into recreating an aggregate in hopes to gaining access to it. Well, we have to be careful here. In my solution, aggregates are made by newing up the target type, loading the event stream from the backing store, re-running the events, and then calling some method on the aggregate. This include "create" methods. The constructor doesn't actually put the object in a created state. So, instead, we have something like:

public abstract class Aggregate
{
    public void ReplayEvents(EventStream stream) { ... }
    protected void PlayEvent(Event target) { ... }
}

public class Foo : Aggregate
{
    private bool _created;

    public Foo()
    {
        // Just get the underlying code ready,
        // but don't set the state to created.
    }

    public void Create(FooCreateParams params)
    {
        // Validate the params and all that fun stuff
        // and, if all is well, fire a created event.
        // If this has already been created, throw an
        // exception or, maybe, fire an error event.

        if (_created) { /* Blow up! */ }

        PlayEvent(new CreatedEvent(params.Id)); // You get the gist.
    }

    private void PlayEvent(CreatedEvent target)
    {
        // React to the event here.
        _created = true;
    }
}

So, if the object has already been created, we don't want to mess with the state. Depending on your domain and the context of your application, you could either fail silently, fire an error event, or even throw an exception. No matter what you do, though, if a user somehow messes with the system (or you happen to have an identity clash) and tries to execute a Create on an already created object, we do not want to hint that the user actually hit upon an actual id.

Conclusion

With a little bit of thought, we are able to clear up a seemingly complex operation down to a pretty easy solution that allows us to keep our asynchronous operations. Now we have a pretty clean set of operations: User hits submit, we load the command on the bus with a new id, redirect the user to a "success" page with some way of referencing the new object, and then let the user move from there. On error, regardless of why, we let the user know an error happened, and provide them with some information to make a decision on how to move forward.