EventFlow

This repository uses git lfs, install it if you want to build the code.

EventFlow is a basic CQRS+ES framework designed to be easy to use.

Have a look at our getting started guide, the dos and don'ts and the FAQ.

Features

• CQRS+ES framework
• Async/await first: Every part of EventFlow is written using async/await.
• Highly configurable and extendable
• Easy to use
• No use of threads or background workers making it "web friendly"
• Cancellation: All methods that does IO work or might delay execution (due to retries), takes a CancellationToken argument to allow you to cancel the operation

Examples

• Simple: Shows the key concepts of EventFlow in a few lines of code
• Shipping: To get a more complete example of how EventFlow could be used, have a look at the shipping example found here in the code base. The example is based on the shipping example from the book "Domain-Driven Design - Tackling Complexity in the Heart of Software" by Eric Evans. Its in-progress, but should provide inspiration on how to use EventFlow on a larger scale. If you have ideas and/or comments, create a pull request or an issue

Overview

Here is a list of the EventFlow concepts. Use the links to navigate to the documentation.

• Aggregates: Domains object that guarantees the consistency of changes being made within each aggregate
• Command bus and commands: Entry point for all command/operation execution.
• Event store: Storage of the event stream for aggregates. Currently there is support for these storage types.
• In-memory - only for test
• Files - only for test
• Microsoft SQL Server
• EventStore - only for test (for now) home page
• Read models: Denormalized representation of aggregate events optimized for reading fast. Currently there is support for these read model storage types.
  • Elasticsearch
  • In-memory - only for test
  • Microsoft SQL Server
• Snapshots: Instead of reading the entire event stream every single time, a snapshot can be created every so often that contains the aggregate state. EventFlow supports upgrading existing snapshots, which is useful for long-lived aggregates. Snapshots in EventFlow are opt-in and EventFlow has support for
  • In-memory - only for test
  • Microsoft SQL Server
• Queries: Value objects that represent a query without specifying how its executed, that is let to a query handler
• Jobs: Perform scheduled tasks at a later time, e.g. publish a command. EventFlow provides support for these job schedulers
  • Hangfire - home page
• Event upgrade: As events committed to the event store is never changed, EventFlow uses the concept of event upgraders to deprecate events and replace them with new during aggregate load.
• Event publishing: Sometimes you want other applications or services to consume and act on domains. For this EventFlow supports event publishing.
• RabbitMQ
• Metadata: Additional information for each aggregate event, e.g. the IP of the user behind the event being emitted. EventFlow ships with several providers ready to use used.
• Value objects: Data containing classes used to validate and hold domain data, e.g. a username or e-mail.
• Customize: Almost every single part of EventFlow can be swapped with a custom implementation through the embedded IoC container.

Simple example

Here's an example on how to use the in-memory event store (default) and a in-memory read model store.

using (var resolver = EventFlowOptions.New
    .AddEvents(typeof (TestAggregate).Assembly)
    .AddCommandHandlers(typeof (TestAggregate).Assembly)
    .UseInMemoryReadStoreFor<TestAggregate, TestReadModel>()
    .CreateResolver())
{
  var commandBus = resolver.Resolve<ICommandBus>();
  var eventStore = resolver.Resolve<IEventStore>();
  var readModelStore = resolver.Resolve<IInMemoryReadModelStore<
    TestAggregate,
    TestReadModel>>();
  var id = TestId.New;

  // Publish a command
  await commandBus.PublishAsync(new PingCommand(id));

  // Load aggregate
  var testAggregate = await eventStore.LoadAggregateAsync<TestAggregate>(id);

  // Get read model from in-memory read store
  var testReadModel = await readModelStore.GetAsync(id);
}

Note: .ConfigureAwait(false) and use of CancellationToken is omitted in the above example to ease reading.

State of EventFlow

EventFlow is still under development, especially the parts regarding how read models are re-populated.

EventFlow is currently used in production environments and performs very well, but it need to mature before key APIs are stable.

EventFlow is greatly opinionated, but its possible to create new implementations for almost every part of EventFlow by registering a different implementation of an interface.

Useful articles related to EventFlow and DDD

Many of the technical design decisions in EventFlow is based on articles. This section lists some of them. If you have a link with a relevant article, please share it by creating an issue with the link.

• Domain-Driven Design

• Domain-Driven Design Reference by Eric Evans

• General CQRS+ES

• CQRS Journey by Microsoft published by Microsoft
• An In-Depth Look At CQRS by Mike Mogosanu
• CQRS, Task Based UIs, Event Sourcing agh! by Greg Young
• Busting some CQRS myths by Jimmy Bogard
• CQRS applied by Gabriel Schenker

• Eventual consistency

• How To Ensure Idempotency In An Eventual Consistent DDD/CQRS Application by Mike Mogosanu

• Why not to implement "unit of work" in DDD

• Unit Of Work is the new Singleton by Mike Mogosanu
• The Unit of Work and Transactions In Domain Driven Design by Mike Mogosanu

How to contribute

EventFlow still needs a lot of love and if you want to help out there are several areas that you could help out with.

• Features: If you have a great idea for EventFlow, create a pull request. It might be a finished idea or just some basic concepts showing the feature outline
• Pull request feedback: Typically there are several pull requests marked with the in progress and feedback is always welcome. Please note that the quality of the code here might not be "production ready", especially if the pull request is marked with the prof of concept label
• Documentation: Good documentation is very important for any library and is also very hard to do properly, so if spot a spelling error, think up a good idea for a guide or just have some comments, then please create either a pull request or an issue
• Information sharing: Working with CQRS+ES and DDD is hard, so if you come across articles that might be relevant for EventFlow, or even better, can point to specfic EventFlow functionality that might be done better, then please create an issue or ask in the Gitter chat
• Expand the shipping example: If you have ideas on how to expand the shipping example found in the code base, the please create a pull request or create an issue
  • Give a good understanding of how to use EventFlow
  • Give a better understanding of how API changes in EventFlow affect existing applications
  • Provide a platform for DDD discussions

Integration tests

EvenFlow has several tests that verify that its able to use the systems it integrates with correctly.

• Elasticsearch: Elasticsearch is automatically downloaded and run during the Elasticsearch integration tests from your TEMP directory. Requires Java to be installed and the JAVA_HOME environment variable set
• EventStore: EventStore is automatically downloaded and run during the EventStore integration tests from your TEMP directory
• MSSQL: Microsoft SQL Server is required to be running
• RabbitMQ: Set an environment variable named RABBITMQ_URL with the URL for the RabbitMQ instance you would like to use.

There's a Vagrant box with both Elasticsearch and RabbitMQ you can use here.

Alternatively you can skip the NUnit tests marked with the integration category.

Thanks

• JetBrains: OSS licenses
• iconmonstr: Free icons for EventFlow
• JC008: License for Navicat Essentials for SQLite

License

The MIT License (MIT)

Copyright (c) 2015-2016 Rasmus Mikkelsen
Copyright (c) 2015-2016 eBay Software Foundation
https://github.com/rasmus/EventFlow

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.