Microsoft .NET Architecting Applications for the Enterprise, Second Edition (2014)

---

Track everything, and rebuild as appropriate

As a design pattern, event sourcing formalizes an approach to data-driven systems that consists of tracking all data operations sequentially in an append-only store. The log of events becomes the primary data source. Any workable representation of data is built (and rebuilt) from the log of events.

Subsequently, event sourcing is a resource for architects and developers because it allows you to track everything that happens around the system and remains flexible enough to let architects extrapolate context and content for the application logic to process. Last but not least, context and content can be rebuilt any time using different business rules without touching the log of events. And the log of events can—with a quick change—start tracking new events.

Today’s line-of-business applications

The real world is full of enterprise, line-of-business systems that in one way or another perform audit trails and track every single event around their data entities. Think, for example, of banking applications that don’t simply tell you the balance of the account; instead, they list decades of transactions, and the tracked operations are used to replay the state of the account at any given date. Think also of accounting applications that must track all possible changes to invoices (change of date, address, credit note) to the point that printing an invoice can result only from replaying all events that affected the invoice over time.

You can also think of betting applications that, from a list of events, can extract pending bets and easily enable what-if scenarios to make predictions and generate statistics. A few years ago in Italy, a football match was decided by a harshly criticized penalty goal. Probably to gain more visibility, a betting agency decided to pay bets as if the penalty were never awarded. More recently, during World Cup 2014 Uruguay beat Italy. However, some controversial decisions of the referee inspired the same betting agency to also pay bets made on the draw. Rather than because of inspiration, we “bet” they made that decision on the wings of some what-if software simulation.

Event sourcing as a pattern was formalized only a few years ago. All such aforementioned applications existed for decades; some even were written in COBOL or Visual Basic 6. This is to say that event sourcing—in spite of the rather hyped-up name—is not heralding any new concept in software. For decades, each team worked out a solution for the same problem the best they possibly could. Finally, someone formalized it as a pattern.

As explained in Chapter 4, “Writing software of quality,” patterns are not the law and are still subject to interpretation, adaptation, and refactoring. Event sourcing as a pattern goes hand in hand with storing events and replaying events to build up some state. This is just the mainstream approach; your way of dealing with these things might be a bit different and still equally effective.

When event sourcing is appropriate

Using events as the primary data source might not be ideal for all systems. Let’s briefly think over the I-Buy-Stuff online store. Is it really crucial for all stakeholders to know about products added to and deleted from the shopping cart? Or what the most-viewed products are? Is it crucial to track the gold status of a customer and the entire history of that customer, such as when the status was first acquired, when it was lost, and maybe when it was re-acquired?

The answers are not obvious. They fall into the classic “It depends” category. So let’s review suitable scenarios for event sourcing.

Suitable scenarios

The most compelling scenario for an event-sourcing implementation is when the business demands that the intent and purpose of data operations be captured. For example, if you are requested to display the activity of a user within a system—say, all travel-related bookings she made, modified, or canceled and all changes she made to her personal record (address, preferences, or credit card data)—then it is key that you track any operation and save it within the context of an event, such as user-modified-home-address event.

Other suitable scenarios for event sourcing exist too. One is when you need to perform some work on top of recorded events. You might want to be able to replay events to restore the (partial) state of the system, undo actions or roll back to specific points. More generally, event sourcing works well in all situations in which you need to decouple the storage of raw data from materialized models and aggregates built on top of that and strictly follow the business requirements.

As a pleasant side effect, event sourcing also might save you from the burden of controlling conflicting updates to data. All you do in this case is let each concurrent client just record an event and then replay events to build the resulting state of the involved aggregate.

Finally, you might want to use event sourcing when the domain itself is inherently event-based. In this case, storing events comes as a natural feature of the domain and requires minimal implementation effort. This is precisely the case of our first example.

Less-than-ideal scenarios

Event sourcing requires ad hoc software architecture and tools, and it needs architects and developers to do things they don’t usually do. In a nutshell, you need a good reason to take the event sourcing route. Our general rule is that you don’t need event sourcing unless your scenario matches one of the scenarios in the preceding paragraphs. More in detail, we’d also say the following:

You don’t need event sourcing if a classic CRUD system can do the job well.

You don’t need event sourcing if audit trails, rollback, and replay actions are not strictly required.

Interestingly, event sourcing is also often associated with the idea of eventual consistency and, subsequently, many suggest that event sourcing is not ideal for scenarios where you need real-time updates to the views. Based on our experience, we would say, “It actually depends.”

Eventual consistency stems from the latency between recording the event and processing it. If synchronous processing of events is arranged, or if latency is kept to a bare minimum, you can happily have event sourcing in the context of real-time systems. Or at least this is what we’ve done on a couple of projects.

In the end, the key determining factor we recommend for deciding whether to use event sourcing is whether or not tracking events is relevant in the business domain.

Event sourcing and real-time systems

A real-time system is simply a system that must provide a valid response to a request within an agreed-upon amount of time. Failure is not an option for such a system. Failing to provide a usable response in the given interval might have significant repercussions on the business. For this reason, real-time systems are critical systems.

However, a real-time system is not necessarily a system that must provide a usable response instantaneously or in just a few milliseconds. If real-time meant just two or three milliseconds of tolerance, probably no implementation would be suitable. Any system constrained to return a response within a fixed amount of time is real-time regardless of the length of the interval.

Dino successfully applied event sourcing in a couple of systems that can easily be labeled as real-time. One is the infrastructure for generating live scores of professional tennis tournaments. Every single event for a given match is saved, and the score and statistics are calculated in the background. The calculated score, as well as up-to-date statistics and overlays, are offloaded to a distinct database for live-score clients to consume. We’ll see a demo version of a live-score system later in the chapter.

Another example is the software used for monitoring room of wind-power plants. In this case, data captured by hardware sensors flows continually into the system and is just logged. Next, data is processed and grouped in data clumps that are logically more relevant and served to presentation clients.

Event sourcing with replay

There’s little value in using event sourcing within the I-Buy-Stuff online store, at least given the limited set of requirements we assumed in past chapters. We could have just forced the demo to use event sourcing with the excuse that all we want, ultimately, is to give a practical demo of how to store and replay events. We decided, instead, to change examples—precisely pursuing the point that event sourcing is a resource and not a must, even for the demos of a book.

Likewise, we don’t want to lead you to the wrong assumption: that e-commerce and online stores is not a domain where event sourcing can be successfully applied. It all depends on the bounded contexts you have and their requirements. If it is crucial for all stakeholders to know about the products a given user viewed or temporarily added to a shopping cart, event sourcing becomes the ideal way to implement that part of the system.

Once you determine that tracking events is useful for your application, implementing event sourcing follows the guidelines discussed next.

A live-scoring system

The first example we’ll present is a live-scoring system for a water polo game. A live-scoring system generally consists of two distinct stacks: one that collects events taking place in the context of the game, and one that presents the current state of the game to clients such as web browsers and mobile apps.

This is quite a good example of an application that is naturally based on events. Using event sourcing here is straightforward and, given the relatively small number of events, using replay to rebuild the state of relevant aggregates is a no-brainer.

Overall layout of the system

Figure 13-1 presents the overall layout of the WaterpoloScoring sample system. It is based on an ASP.NET MVC application that referees (or, more likely, assistant referees or scorekeepers) use to tally goals. In a more realistic version, the system will also track players’ fouls and penalties as well as shots that scored or missed.

FIGURE 13-1 An overview of the WaterpoloScoring system.

The system consists of two main components: scoring and live-score modules. In the example, however, both components are managed as distinct screens within the same ASP.NET MVC application. In the end, the live-score view just invokes a Web API front end fed by snapshots created on top of recorded events.

Functional requirements

The scoring screen must provide the following functions:

Start a match

End a match

Start a period

End a period

Score a goal for either team

The ability to undo any of the previous actions

Each action generates an event that is saved to the event store. Each action also generates an event that indicates the need to refresh the snapshot database. The snapshot database contains the current state of the match in a format that is suited for live score applications—team names, current score, current period, whether the ball is in play, and a partial score for past periods.

FIGURE 13-2 A mockup for the scoring page of the sample application.

Implementation of the system

The water polo scoring system receives a bunch of UI messages when a button is clicked. Each button click is essentially the notification for a relevant match event, such as start, end, period, or goal. The request generated with the click is dispatched to the application layer and processed. The request is then redirected to the home page.

public ActionResult Action(String id)
{
// We use a dispatcher here only because all buttons belong to
// the same HTML form; subsequently, the same action is requested
// regardless of the clicked button. We use this code here to
// disambiguate.

var action = MakeSenseOfWhatTheUserDid(Request);
_service.Dispatch(id, action);
return RedirectToAction(“index”, new {id = id});
}

The home page just reads back the current state of the match and refreshes the user interface accordingly:

public ActionResult Index(String id)
{
var model = _service.GetCurrentState(id);
return View(model);
}

The current state of the ongoing match is read, all events are replayed, and all of them are applied to a freshly created instance of the related aggregate. Let’s find out more details.

The command bus

A scoring system is not rocket science; the most complex part is implementing the scoring rules. For a water polo match, scoring rules are trivial—you just sum up scored goals and that’s it. However, a scoring system is hardly limited to just calculating the score. Often, you might want to generate statistics or overlays to be displayed by live clients such as mobile applications, HTML pages, or even Flash video clips displayed on LED walls.

You can easily implement the workflow behind each scoring event with plain, transaction script code. However, in this case, having a command bus and events doesn’t really add a lot more complexity and keeps extensibility high. Once you have a command bus, everything comes together easily. For the command bus, we use the same component we discussed in Chapter 10, “Introducing CQRS.” Here’s the source code:

public class Bus
{
private static readonly Dictionary<Type, Type> SagaStarters =
new Dictionary<Type, Type>();
private static readonly Dictionary<string, object> SagaInstances =
new Dictionary<string, object>();
private static readonly EventRepository EventStore = new EventRepository();

public static void RegisterSaga<TStartMessage, TSaga>()
{
SagaStarters.Add(typeof(TStartMessage), typeof(TSaga));
}
public static void Send<T>(T message) where T : Message
{
// Check if the message can start one of the registered sagas
if (SagaStarters.ContainsKey(typeof(T)))
{
// Start the saga, creating a new instance of the type
var typeOfSaga = SagaStarters[typeof(T)];
var instance = (IStartWithMessage<T>)Activator.CreateInstance(typeOfSaga);
instance.Handle(message);

// At this point the saga has been given an ID;
// let’s persist the instance to a (memory) dictionary for later use.
SagaInstances[instance.SagaId] = instance;
}

// Check if the message can be handled by one of the existing sagas.
if (message.SagaId == null)
return;

if (SagaInstances.ContainsKey(message.SagaId))
{
// Check compatibility between saga and message: can the saga handle THIS message?
var sagaType = SagaInstances[message.SagaId].GetType();
if (!typeof(ICanHandleMessage<T>).IsAssignableFrom(sagaType))
return;

var saga = (ICanHandleMessage<T>) SagaInstances[message.SagaId];
saga.Handle(message);
}

// Publish and persist the event
if (message is DomainEvent)
{
// Persist the event
EventStore.Save(message as DomainEvent);

// Invoke all registered sagas and give each
// a chance to handle the event.
foreach (var sagaEntry in SagaInstances)
{
var sagaType = sagaEntry.Value.GetType();
if (!typeof(ICanHandleMessage<T>).IsAssignableFrom(sagaType))
return;

// Give other sagas interested in the event a chance to handle it.
// Current saga already had its chance to handle the event.
var handler = (ICanHandleMessage<T>) sagaEntry.Value;
if (sagaEntry.Key != message.SagaId)
handler.Handle(message);
}
}
}
}

As you might have noticed, the list of saga instances is not stored in a permanent form of storage; instead, saga instances are kept in memory. This means that, while debugging the application, you won’t be able to deliver messages to an existing saga; that works only within the same session.

The bus is the core of the scoring module; it receives messages from the application layer following the user’s activity in the browser.

Supported events and commands

The user interface of the scoring application is shown in Figure 13-3. The page contains six buttons for the key events: match started, match ended, period started, period ended, goal scored by home, and goal scored by visitors. In addition, the user interface contains two more buttons: one to undo last action, and one to clear the event store for debugging purposes.

FIGURE 13-3 The home page of the sample application.

The click on the Zap button doesn’t push any message to the bus; the action is handled directly within the application layer. Clicking on the Undo button pushes a command to the bus that the related saga handles. Clicking on any other buttons in the user interface pushes a plain event to the bus. The event is recorded by the bus and then published to registered sagas.

Right after each button click, the page collects the current state of the match and passes that to the view. The view looks at the state of the match and its score, and it enables or disables buttons as appropriate. The following code shows the implementation of the saga:

public class MatchSaga : SagaBase<MatchData>,
IStartWithMessage<MatchStartedEvent>,
ICanHandleMessage<MatchEndedEvent>,
ICanHandleMessage<PeriodStartedEvent>,
ICanHandleMessage<PeriodEndedEvent>,
ICanHandleMessage<GoalScoredEvent>,
ICanHandleMessage<MatchInfoChangedEvent>,
ICanHandleMessage<UndoLastActionCommand>
{
private readonly EventRepository _repo = new EventRepository();
public void Handle(MatchStartedEvent message)
{
// Set the ID of the saga
SagaId = message.MatchId;

// Signal that match information has changed
NotifyMatchInfoChanged(message.MatchId);
}

public void Handle(UndoLastActionCommand message)
{
_repo.UndoLastAction(message.MatchId);

// Signal that match information has changed
NotifyMatchInfoChanged(message.MatchId);
}

public void Handle(MatchEndedEvent message)
{
// Signal that match information has changed
NotifyMatchInfoChanged(message.MatchId);
}

public void Handle(PeriodStartedEvent message)
{
// Signal that match information has changed
NotifyMatchInfoChanged(message.MatchId);
}

public void Handle(PeriodEndedEvent message)
{
// Signal that match information has changed
NotifyMatchInfoChanged(message.MatchId);
}

public void Handle(GoalScoredEvent message)
{
// Signal that match information has changed
NotifyMatchInfoChanged(message.MatchId);
}

public void Handle(MatchInfoChangedEvent message)
{
SnapshotHelper.Update(message.MatchId);
}

private static void NotifyMatchInfoChanged(string matchId)
{
var theEvent = new MatchInfoChangedEvent(matchId);
Bus.Send(theEvent);
}
}

The saga starts when the MatchStartedEvent is pushed to the bus. The saga ID coincides with the unique ID of the match:

// This message pushed to the bus starts the saga
var domainEvent = new MatchStartedEvent(matchId);
Bus.Send(domainEvent);

As you can see from the source code, most messages are plain notifications and don’t require much more than just persistence. That’s why we coded them as events. For example, here’s how the application layer generates a notification that a goal has been scored:

// TeamId is an enum type defined in the domain model for the command stack
var command = new GoalScoredEvent(matchId, TeamId.Home);
Bus.Send(command);

In addition to plain persistence, the saga method for these events fires another event—the MatchInfoChanged event. The MatchInfoChanged event causes the saga to trigger the process that updates the snapshot database for live-score clients.

Undoing the last action

When the user clicks the Undo button in the user interface, a command is pushed to the bus instead. The Undo button sends a message through which the user actually tells the system to do something: delete the last recorded action as if it never happened.

var command = new UndoLastActionCommand(matchId);
Bus.Send(command);

The command is handled by the saga placing a call to the API that wraps up the event store. In general, the event store is append-only; in this case, we remove the last stored item because the undo functionality for the domain just means that the last action should be treated as if it never happened. However, nothing really prevents you from implementing the undo through a logical deletion. Some advanced scoring systems do exactly that to audit the activity of referees and collect usability information.

public void Handle(UndoLastActionCommand message)
{
_repo.UndoLastAction(message.MatchId);

// Signal that match information has changed
NotifyMatchInfoChanged(message.MatchId);
}

The UndoLastAction method uses the storage API (either a classic SQL Server or a NoSQL document database) to retrieve the last event object and delete it. In our example, we use RavenDB for the event store. Here’s the code we use:

public void UndoLastAction(String id)
{
var lastEvent = (from e in GetEventStream(id) select e).LastOrDefault();
if (lastEvent != null)
{
DocumentSession.Delete(lastEvent);
DocumentSession.SaveChanges();
}
}

The GetEventStream method is a helper method exposed by the event store application interface to retrieve the entire list of events for a given aggregate. Let’s find out more about the event store.

Persisting events

The event store is just a persistent store where you save information about events. In general, an event is a data-transfer object (DTO)—a plain collection of properties. In light of this, an event can be easily persisted as a record of a SQL Server database table or to a NoSQL data store. (SeeChapter 14, “The persistence layer,“ for more information about alternative data stores and polyglot persistence.)

When it comes to event stores, there are two main issues related to relational stores. One issue is the inherent cost of licenses for most popular relational stores. This might or might not be a problem, depending on the context, the business, the costs of software, the financial strength of customers, and so forth. The other issue is more technical: not all events have the same structure and set of properties. How would you go about modeling a table schema for all possible events of an application?

You can probably create a fixed schema of columns that accommodates known events. What if a new event is added or an event’s description changes? Another approach entails having a relational table made of a few columns—such as aggregate ID, type of event, and a JSON-serialized dictionary with property values that characterize the event.

Yet another approach is not using a relational store and resorting to a document database such as RavenDB. This is what we did in our example. The following code shows what it takes to persist an event in a RavenDB store:

public class EventRepository
{
private IDocumentSession DocumentSession { get; set; }

public EventRepository()
{
DocumentSession = RavenDbConfig.Instance.OpenSession();
}

public void Save(DomainEvent domainEvent)
{
var eventWrapper = new EventWrapper(domainEvent);
DocumentSession.Store(eventWrapper);
DocumentSession.SaveChanges();
return;
}
...
}

You first initialize RavenDB in global.asax at the startup of the application and then use the created engine instance to open a session. Through the interface of the session, you then save and delete objects. Note that you might want to wrap events into a container class—the EventWrapperclass of our example—so that all stored objects look to be of the same type regardless of the actual type:

public class EventWrapper
{
public EventWrapper(DomainEvent theEvent)
{
TheEvent = theEvent;
}
public DomainEvent TheEvent { get; private set; }
}

Another solution that is gaining momentum is the NEventStore project. (See http://neventstore.org.) NEventStore is a persistence library specifically designed to address event-sourcing issues. It offers a unified API to persist events that intelligently hides different storage mechanisms.

Replaying events

In addition to saving events, the other key function one expects out of an event store is returning the full or partial stream of events. This function is necessary to rebuild the state of an aggregate out of recorded events. In RavenDB, getting the stream of events is as easy as in the following code:

public IEnumerable<EventWrapper> GetEventStream(String id)
{
return DocumentSession
.Query<EventWrapper>()
.Where(t => t.MatchId == id)
.OrderBy(t => t.Timestamp).ToList();
}

Replaying events consists of looping through the stream of events and applying them to a fresh instance of the related aggregate. In our example, we have a small domain model centered on the Match aggregate. The Match class has a method for nearly any significant change of state: start, end, new period, end of period, goal, and more.

Materializing an instance of Match consistent with tracked events requires the following pseudo-code.