devlyon / mixter

CQRS and Event Sourcing Koans

Mixter

Mixter is a project to discover CQRS/Event sourcing through koans in multiple languages.

At this point the koans have been ported to 5 languages: C#, Java 8, Scala, PHP and Javascript.

Starting

1. Checkout master branch
2. Execute ./run script
3. You will have to make tests pass green, then to go to next test, execute ./next

See few slides on http://devlyon.fr/mixter, it explains the main steps and goals for each.

You can view one solution for each language with a small Web API on branches [lang]-solution.

Feedback is required

Feel free to use issues in this repo to give your feedback, to propose some improvements, to ask for other languages...and even better to submit pull requests.

Explanations of some implementation details

We have done some choices that we consider implementation details, but that can hurt some people. So we try to explain them here.

About events publication mecanism in CQRS/ES, there are two main well known options :

1. use an AggregateRoot base class that accumulate uncommitted events that are picked by Repository on Save of the aggregate.

2. use DomainEvents.Raise(event) static call from AggregateRoot protected Apply method

We chose a third way that consists of passing an IEventPublisher (with Publish method) to each aggregate method to raise events. There is no more need to call Repository.Save and it avoids static method call.

We use a DecisionProjection concept to keep track of "transient state" of aggregates.

We thought this "transient state" as a special projection (like Read model ones) to take further decision in the aggregate, that's why we call it DecisionProjection. We kept this class private inside the aggregate.

Commands and command handlers are not shown here for now, for simplicity, it has been left implicit through method of aggregates.

Perhaps something to introduce in further version.

Any questions ?

You can contact us through GitHub or on Twitter : @clem_bouillier, @florentpellet, @jeanhelou, @ouarzy.

Add new languages

If you want to fork with your preferred language, you only need to follow some rules.

The KoanCli script is based on a naming convention in commit message.

• Failing tests should contain [Test KO]
• Resolving tests should contain [Test OK]

Currently the KoanCli script isn't dynamic and tests number must be static to know the correspondence between a test and a step. Here number of tests per step:

• Step 1, delete command: 4 tests
• Step 2, timeline messages: 1 tests
• Step 3, subscription aggregate: 4 tests
• Step 4, aggregates interaction: 4 tests
• Step 5, command handler: 2 tests

Changelog

V2

• Create KoanCli: no git knowledge required. You simply call run script to starting, and next to jump at next step. (#3)
• Remove reply message (#7)
• Rename publish to quack (#16)
• Fix several bug specific at languages (#15, #5, #4)
• Make PHP version work with PHP 7.2 (#36)

V1 (obsolete)

First version, use during a Mix-IT workshop 2015 : http://www.mix-it.fr/session/1041/agilite-par-le-code-grace-a-cqrs-et-eventsourcing

mixter's Issues

Remove reply message, associated events and commands

It adds quite a bit of complexity to the exercise without much additional insight in the design.

• Java
• Javascript
• C#
• PHP

This is a "master" issue to be updated for each language merged and closed once all languages have been updated.

Make C# work without visual studio.and with mono

Xunit VS runner is tied to csproj for now
Need xunit console runner
use paket? (/!\ is it ok for everyone to use console too much...)

KoanCli not works on git 1.7

The command to list the branches isn't the same as in the recent versions

Add Python implementation

I'd like to help with this, so this is partly a reminder for myself.

JS : split aggregate files

In domain, each file contains all informations on an aggregate.
Separate this file by a comment or other files, could facilitate understanding

[php/v2] Typo after cloning the project

after initializing the project I got a

PHP Fatal error:  Class 'Tests\Domain\Messages\MessagePublished' not found in /.../mixter/tests/Domain/Messages/MessageTest.php on line 92

the event should be name MessageQuacked

Fix case issues on js dependency

On Linux and case sensistive file systems in general, the case of the js dependencies can cause issues

Missplaced files for the csharp part at step-2

When checking out csharp-wrokshop-step-2
a. New files at Mixter.Infrastructure.Tests are expected here Mixter.Infrastructure.Tests/Infrastructure
After correcting this:
b. all test are passing (no leading failing test)

Branches suck

It's probably much better using a simple directory view in one single branch.

Use another vocabulatory than Publish/Republish

Could be something like Quack, or Meow or Whinny, as a reminder of Tweet ;)

• JS
• C#
• Java
• PHP

Add PHP7 compatibility

At the moment, if you choose PHP, you can't use PHP7 because of the outdated dependencies.

PHP Fatal error:  Cannot use PhpParser\Node\Scalar\String as String because 'String' is a special class name in vendor/classpreloader/classpreloader/src/Parser/DirVisitor.php on line 8

Add Scala version

Propose these koans in Scala

[Scala] Tests in NotifyFollowerOfFolloweeMessageSpec are always green

Too generic parameters in withFixtures

Improve instructions slide

• Users should not change the tests or the infrastructure code. the solution is necessarily in the core code
• Users can look at the Identity context implementation to get a feeling of how to do the implementation
• Improve introduction to explain the business and what the code of the workshop is all about.

Fix missing @Test on java-test-1.1

MessageTest#whenAMessageIsDeletedByItsAuthorThenItShouldSendMessageDeletedEvent

Java annotations : Add comments

Java annotations are liked, but participants would have more comments to explain concepts directly in the code.

We can also add link to the article in the source, and reuse the same content

[php/v2] missing an event in the initialization of the event publisher

In the step 1 - 2
https://github.com/DevLyon/mixter/blob/php/v2/tests/Domain/Messages/MessageTest.php#L109

there is an event missing

    $messageId = MessageId::generate();
    $messageQuacked = new MessageQuacked($messageId, 'Hello', $authorId);
    $messageDeleted = new MessageDeleted($messageId, $authorId);
    $message = new Message(array($messageQuacked, $messageDeleted));

Errors running ./run

Hi guys,

I've been trying to go through the exercise but didn't manage to even start it.

I was expecting some kind of template code to start the exercise. Apparently, the only effect that running the script has is the attached output.

I'm not sure if I'm missing something or something is not working as it should in the script.

Thanks in advance.
Carlos.

:run output.txt

Update README

• include a description of the business of mixter
• include an link to the evenstorming result (image ?)

[Scala] Typo on [Core][NotifyFollowerOfFolloweeMessage]

The commit 70f346b fix typo of test in a commit [Test OK]

`koans` CLI

Introduce a command to help people navigate the koans.

The command should at least allow to :

• check out the starting point for a language
• move to the next test for the current language
• skip a section and move to the next step

The command should be available in the master branch

Republished instead of requacked on Java version

A rename is missed
https://github.com/DevLyon/mixter/blob/java/v2.1/domain/src/test/java/mixter/domain/core/message/MessageTest.java

Add F# version

Make the koans available in F#.

Some questions to answer :

• do we use the same concepts (EventPublisher) ?

Create a less guided version

Several participants indicated that this was too guided to understand the concepts.
We can make a version 3 which gives no source, but only tests.

We can consider automatically switch to V2 at the end of the v3, to bring it to a "real" application.

We can also proposed a quiz at every step, to check knowledge

Normalize the exercise across languages

Currently there are minor variations across the 4 languages.

including

• no class needs to be created in js, only the implementation. there is little insight to be gained in implementing an event.
• ???

Thank you!

We have just done the workshop with a colleague and it was really great! Steps are very well partitioned and all the transitions are smooth! Thank you very much!

[Scala] Test 4 Step 4 : Test is not constistent

Actually, in case of a requake, the test named "notify followers when a followee requacks a message" (https://github.com/DevLyon/mixter/blob/scala/v2.1/domain/src/test/scala/mixter/domain/subscription/handlers/NotifyFollowerOfFolloweeMessageSpec.scala#L31), ask us to notify followers of the author message instead of followers of the requacker message

Potential fix (https://github.com/DevLyon/mixter/blob/scala/v2.1/domain/src/test/scala/mixter/domain/subscription/handlers/NotifyFollowerOfFolloweeMessageSpec.scala#L35) :

--- followerRepository.saveFollower(AuthorId, AFollowerId)
+++ followerRepository.saveFollower(RequackerId, AFollowerId)

Add warning when running ./run in other branch than master

Warn : "are you sure you want to reinit everything? All your work will be lost..."

Test DSL in C# too complex

For beginners testers, the DSL complicated rather than simplified. It should be deleted

DecisionProjectionBase on Java version

Add test to check if event is managed by projection.
Currently, an exception of NullPointer type is raised.

Add dotnet core version

Based on classic dotnet version.

C# visual studio not run xunit test

A packet misses to execute automatically in Visual Studio