DEV Community: Mattias Holmqvist

Implementing a Rock-Paper-Scissors game using Event Sourcing

Mattias Holmqvist — Mon, 08 Feb 2021 07:47:16 +0000

In this tutorial we will look at how we can design the game flow for a rock-paper-scissors game using Serialized APIs for Event Sourcing and CQRS.

Our favorite runtime environment for applications is usually Dropwizard but since many out there prefer Spring Boot I decided to use it instead for this article.
Our Java client works with any runtime environment or platform you use
on the JVM.

Configure the Serialized project

To develop our game we will use Serialized aggregates and projections. The aggregates will store the events for each game and the projections will provide a view of each game as well as a high score list of the top winners (in the case of multiple games being run).

If you have not yet signed up to Serialized you will need to [sign up for a free developer account (https://app.serialized.io). Once you've signed up and created your first project you will have an empty view of Aggregates, like this:

We now need to find out API keys which are available under Settings.

Copy the access key and secret access key to a safe location. We will need these to access Serialized APIs from our backend application.

Great job! We now have an empty Serialized project. We're now ready to start developing our game!

Setup and outline of the game

In this section we will describe the basic functionality of the game and the pieces that we need to implement to develop the whole game flow.

Game rules

The core of the game are the game rules. If you are interested in the history of the game you can read more about it on Wikipedia.

This is a brief summary of the game rules:

The game is played by two players.
A round consists of both players showing their hand (rock/paper/scissors).
Each round ends when both players have shown their hands and there is a winner.
If a round is tied (same hand is shown), the round will be run again.
Paper beats rock.
Rock beats scissors.
Scissors beats paper.
A game is best of 3 rounds - it is finished when one player has 2 round wins.

Game model

We will design our game using commands and events. The commands are actions that the game supports and the events are the Domain Events that are emitted as results from these commands.

Commands

Given our simple game rules there are only two actions we can perform:

StartGame will be sent when we decide to start a game with two players.
ShowHand will be sent whenever a player shows their hand.

Note: since the game ends automatically when the last hand is shown, and we have a winner, this is not modeled as a command, but rather as an event instead.

An interesting consequence of designing the game with commands and events is that we get a clear picture of how there is a discrepancy between the number of different commands and events.

Events

Below is a description of the events that our Game aggregate emits as a result for successfully processing commands:

GameStarted will be saved as a consequence of the start-game command.
RoundStarted will be saved together with the GameStarted for the first round and implicitly for upcoming rounds when both players have answered.
PlayerAnswered will be saved when a hand is shown by a player.
RoundTied will be saved when both players have shown hands, and they show the same sign.
RoundFinished will be saved when both players have shown hands
GameFinished will be saved when we have a winner (2 or more rounds won for a player).

Queries

We will also implement a number of queries to show the Projection support in Serialized. Projections help us calculate queryable models that are the result of a number of events that have been saved in the aggregates. The queries that we will support for the game are the following:

Game status - the current status of the game (including the rounds that have been played).
High score (wins per player in a list).
Total number of games.

Implementing the game

Let's dive in to the implementation of our game!

App configuration

If you are not familiar with our Java client, you can read more here about the basics.

First we must configure the Serialized client. In our AppConfig class we create an injectable bean for the aggregate client that we will use to store events into Serialized. We use a GameState class to manage the materialization of the state from any previously stored events and register the handler methods in this class for each event type that we designed in our modeling session, respectively.

@Configuration
public class AppConfig {

  @Autowired
  public AppConfig(Environment env) {
    this.env = env;
  }

  ...

  @Bean
  public AggregateClient<GameState> gameClient() {
    return AggregateClient.aggregateClient(GAME_AGGREGATE_TYPE, GameState.class, getConfig())
      .registerHandler(GameStarted.class, GameState::handleGameStarted)
      .registerHandler(PlayerWonRound.class, GameState::handlePlayerWonRound)
      .registerHandler(GameFinished.class, GameState::handleGameFinished)
      .registerHandler(PlayerAnswered.class, GameState::handlePlayerAnswered)
      .registerHandler(RoundStarted.class, GameState::handleRoundStarted)
      .registerHandler(RoundFinished.class, GameState::handleRoundFinished)
      .registerHandler(RoundTied.class, GameState::handleRoundTied)
      .build();
  }

  private SerializedClientConfig getConfig() {
    return SerializedClientConfig.serializedConfig()
      .accessKey(env.getProperty("SERIALIZED_ACCESS_KEY"))
      .secretAccessKey(env.getProperty("SERIALIZED_SECRET_ACCESS_KEY"))
      .build();
  }

}

The game logic

The GameState class contains the state for our Game aggregate. When a new command (ShowHand) is sent to the Game aggregate, we will first load an instance of GameState based on all previously stored events that was saved on the game.


/**
 * The transient state of a game, built up from events
 */
public class GameState {

  private final Set<Player> registeredPlayers = new LinkedHashSet<>();
  private final Set<PlayerHand> shownHands = new HashSet<>();
  private final Map<Player, Long> wins = new HashMap<>();

  private GameStatus gameStatus = GameStatus.NEW;

  public static GameState newGame() {
    return new GameState();
  }

  public GameState handleGameStarted(Event<GameStarted> event) {
    gameStatus = GameStatus.STARTED;
    registeredPlayers.addAll(event.data().players.stream().map(Player::fromString).collect(toSet()));
    return this;
  }

  public GameState handlePlayerWonRound(Event<PlayerWonRound> event) {
    Player winner = Player.fromString(event.data().winner);
    long numberOfWins = wins.getOrDefault(winner, 0L);
    wins.put(winner, numberOfWins + 1);
    return this;
  }

  public GameState handleRoundStarted(Event<RoundStarted> event) {
    return this;
  }

  public GameState handlePlayerAnswered(Event<PlayerAnswered> event) {
    Player player = Player.fromString(event.data().player);
    shownHands.add(new PlayerHand(player, event.data().answer));
    return this;
  }

  public GameState handleRoundTied(Event<RoundTied> event) {
    shownHands.clear();
    return this;
  }

  public GameState handleRoundFinished(Event<RoundFinished> event) {
    shownHands.clear();
    return this;
  }

  public GameState handleGameFinished(Event<GameFinished> event) {
    this.gameStatus = GameStatus.FINISHED;
    return this;
  }

  ...

}

We will use a single aggregate Game to implement the rules for the game and to emit the proper events for the correct situations. Games are a good showcase for Event Sourcing since they require strong consistency. The preserved history that we get out of the box is also useful to build fun side-features such as high score and statistics. By reacting to events we can also easily build notifications and reminders for players to act on.

The Game class is our aggregate root that contains the implementation of the game rules and logic.

public class Game {

  private final GameState gameState;

  ...

  public List<Event<?>> startGame(Player player1, Player player2) {
    if (player1.equals(player2)) {
      throw new IllegalArgumentException("Cannot play against yourself");
    }
    Set<Player> players = Stream.of(player1, player2).collect(toCollection(LinkedHashSet::new));
    return singletonList(gameStarted(players));
  }

  Player calculateWinner(PlayerHand hand1, PlayerHand hand2) {
    if (hand1.answer.equals(ROCK)) {
      return hand2.answer.equals(SCISSORS) ?
          hand1.player : hand2.player;
    } else if (hand1.answer.equals(PAPER)) {
      return hand2.answer.equals(ROCK) ?
          hand1.player : hand2.player;
    } else
      return hand2.answer.equals(PAPER) ?
          hand1.player : hand2.player;
  }

  Player calculateLoser(PlayerHand player1, PlayerHand player2) {
    return calculateWinner(player1, player2).equals(player1.player) ? player2.player : player1.player;
  }

}

Generating the high score leaderboard

The high score in our application is a Projection that is built up from all the GameFinished events that contain the id of the winner/loser for each game.

We can build this projection by simply telling Serialized to transform our events into a queryable high score projection.

In our AppConfig we add a projection client that is used to initialize our projection definition when our application starts.

@Configuration
public class AppConfig {

  ...

  @Bean
  public ProjectionClient projectionApiClient() {
    return ProjectionClient.projectionClient(getConfig()).build();
  }

  ...

}

We create a ProjectionInitializer service that will initialize all our projections (in this case the high score)

If the definition code is changed between app starts it will re-create the projection by re-reading all GameFinished events again.

@Service
public class ProjectionInitializer {

  private final ProjectionClient projectionClient;

  @Autowired
  public ProjectionInitializer(ProjectionClient projectionClient) {
    this.projectionClient = projectionClient;
  }

  public void createGameProjection() {
    projectionClient.createOrUpdate(
      singleProjection("games")
        .feed("game")
        .addHandler(GameStarted.class.getSimpleName(),
          merge().build(),
          set().with(targetSelector("status")).with(rawData("IN_PROGRESS")).build())
        .addHandler(RoundFinished.class.getSimpleName(),
          append()
            .with(targetSelector("rounds"))
            .build())
        .addHandler(GameFinished.class.getSimpleName(),
          merge().build(),
          set().with(targetSelector("status")).with(rawData("FINISHED")).build())
        .build());
  }

  public void createHighScoreProjection() {
    projectionClient.createOrUpdate(
      singleProjection("high-score")
        .feed("game")
        .withIdField("winner")
        .addHandler("GameFinished",
          inc().with(targetSelector("wins")).build(),
          set().with(targetSelector("playerName")).with(eventSelector("winner")).build(),
          setref().with(targetSelector("wins")).build())
        .build());
  }

  ...

}

For the games projection we append rounds to a rounds array and modify the status of the game when GameStarted and GameFinished event are received.

The high-score projection is slightly different. In this case we use the idField feature of Serialized to create projections that are identifiable using the playerId instead of the aggregateId (which is the gameId in this case). This makes the high-score projections queryable by playerId.

The application class

Our main application class is the entry point for our Spring Boot application. It will start the web container and also initialize/update our projection definitions during boot. Here's how it looks:

@Configuration
@EnableAutoConfiguration
@ComponentScan
public class GameApplication implements CommandLineRunner {

  private final ProjectionInitializer configurer;

  @Autowired
  public GameApplication(ProjectionInitializer configurer) {
    this.configurer = configurer;
  }

  @Override
  public void run(String... strings) {
    configurer.createHighScoreProjection();
    configurer.createGameProjection();
    configurer.totalStatsProjection();
  }

  public static void main(String[] args) {
    SpringApplication.run(GameApplication.class, args);
  }
}

Before starting the application you need to provide your Serialized API keys as system properties/environment variables to the Java process so that our AppConfig class can pick them up and initialize our client properly.

After starting the application, you can go to Projections in the Serialized console and you should be able to see the initialized projection definitions there.

Putting the pieces together

To expose the game logic to our client (Web/Mobile/other) we will create a @Controller that receives HTTP POST requests (Commands) from the client and executes our domain logic of the gameId provided in the request:


@Controller
public class GameCommandController {

  private final Logger logger = LoggerFactory.getLogger(getClass());
  private final AggregateClient<GameState> gameClient;

  @Autowired
  public GameCommandController(AggregateClient<GameState> gameClient) {
    this.gameClient = gameClient;
  }

  @RequestMapping(value = "/start-game", method = POST, consumes = "application/json")
  @ResponseStatus(value = HttpStatus.OK)
  public void startGame(@RequestBody StartGameCommand command) {
    Player player1 = Player.fromString(command.player1);
    Player player2 = Player.fromString(command.player2);
    GameState state = GameState.newGame();

    Game game = Game.fromState(state);
    gameClient.save(saveRequest().withAggregateId(command.gameId).withEvents(game.startGame(player1, player2)).build());
    logger.info("Game [{}] started with players [{}, {}]", command.gameId, command.player1, command.player2);
  }

  @RequestMapping(value = "/show-hand", method = POST, consumes = "application/json")
  @ResponseStatus(value = HttpStatus.OK)
  public void showHand(@RequestBody ShowHandCommand command) {
    // Load the aggregate state from all events, execute domain logic and store the result
    gameClient.update(command.gameId, gameState -> {
      Game game = Game.fromState(gameState);
      return game.showHand(Player.fromString(command.player), command.answer);
    });
    logger.info("Player [{}] answered [{}] in game [{}]", command.player, command.answer, command.gameId);
  }

}

To expose the projections we create a @Controller that receives HTTP calls from the client and queries our projections and returns the results:

@Controller
public class GameQueryController {

  private final ProjectionClient projectionClient;

  @Autowired
  public GameQueryController(ProjectionClient projectionClient) {
    this.projectionClient = projectionClient;
  }

  @RequestMapping(value = "/high-score", method = GET, produces = "application/json")
  @ResponseBody
  public HighScoreProjection highScore() {
    return HighScoreProjection.fromProjections(projectionClient.query(list("high-score").sort("-wins").build(HighScore.class)));
  }

  @RequestMapping(value = "/stats", method = GET, produces = "application/json")
  @ResponseBody
  public TotalGameStats gameStats() {
    ProjectionResponse<TotalGameStats> projection = projectionClient.query(aggregated("total-game-stats").build(TotalGameStats.class));
    return projection.data();
  }

  @RequestMapping(value = "/games/{gameId}", method = GET, produces = "application/json")
  @ResponseBody
  public GameProjection game(@PathVariable UUID gameId) {
    ProjectionResponse<GameProjection> game = projectionClient.query(single("games")
      .id(gameId)
      .build(GameProjection.class));
    return game.data();
  }

}

Testing the application

To test the application you can send HTTP POST requests to the endpoints /start-game and /show-hand.

An example request to start a new game can look like this:

curl -i http://localhost:8080/start-game \
  --header "Content-Type: application/json" \
  --data '
{
    "gameId" : "dfd2d7bb-8c67-4d4f-87c1-364d72dfd05d",
    "player1": "Lisa",
    "player2": "Bob"
}
'

To play a round we will send two show-hand requests. One for Lisa and one for Bob:

curl -i http://localhost:8080/show-hand \
  --header "Content-Type: application/json" \
  --data '
{
    "gameId" : "dfd2d7bb-8c67-4d4f-87c1-364d72dfd05d",
    "player": "Lisa",
    "answer" : "ROCK"
}
'

curl -i http://localhost:8080/show-hand \
  --header "Content-Type: application/json" \
  --data '
{
    "gameId" : "dfd2d7bb-8c67-4d4f-87c1-364d72dfd05d",
    "player": "Bob",
    "answer" : "PAPER"
}
'

Round results

Since our projection was already set up to show the results for each round we can now navigate to Projections/games/dfd2d7bb-8c67-4d4f-87c1-364d72dfd05d in the Serialized console and see the finished round.

To access this data we also have a query endpoint in the application:

curl -i http://localhost:8080/games/dfd2d7bb-8c67-4d4f-87c1-364d72dfd05d

Which calls the Serialized games projection for the given game id and returns the (already) calculated projection data:

{"players":["Bob","Lisa"],"status":"IN_PROGRESS","rounds":[{"winner":"Bob","loser":"Lisa"}]}

Showing the high-score

If we play one more identical round where Bob wins the round (and hence also the game), we can see the high-score projection being updated with his win of the game:

To access this data we also have a query endpoint in the application:

curl -i http://localhost:8080/high-score

{"highScores":[{"playerName":"Bob","wins":1}]}

This query shows the projection data from the high-score projection and uses the sort and limit feature of the Projection API to show the 10 players with the most number of wins. After running a few more games with more players the response can look like this:

{
  "highScores":
  [
    {"playerName":"Bob","wins":11},
    {"playerName":"Lisa","wins":6},
    {"playerName":"John","wins":5},
    {"playerName":"Dan","wins":4},
    {"playerName":"Anna","wins":1}
  ]
}

Summary

That wraps up the overview of this tutorial showing the basic techniques for Event Sourcing and CQRS using Serialized. Hope you find this tutorial useful and that it can inspire you to build your own application (or perhaps a game) using Serialized.

The complete sample code

Check out the complete sample code for this tutorial in our Github repository. Feel free to clone the project and modify it however you want. Have fun!

What are Domain Events?

Mattias Holmqvist — Sat, 07 Nov 2020 09:49:46 +0000

What is an Event?

An event in the context of software development is something that happens around us that we choose to put in to our system as something noteworthy. The most common scenarios include:

Storing events for analytics / BI purposes

Supporting communication between services by publishing application events
Use Event Sourcing to provide a single source of truth
Events are building blocks that have become popular for many use cases. Many technical products base their design on events as a core building block. Just like any other building block or definition it is important to recognize that all events are not equal. First let's look at the properties of events that are ubiquitous regardless of the use case or product involved.

Events are immutable

When something has happened in the world around us it is a fact. We cannot change history and bringing this realization into the design of our software is something that is very helpful for us when developing useful systems. We model the world in a way that resembles how we perceive the world around us. Things happen all the time and there is not much we can do about it. Our systems can help us record and remember the important things and this is why events are a great modeling construct.

An event can only occur once

An event can only happen once. If the same thing happens again later, it is still a different event since it by definition happened after the first occurrence. When you visit your friends house, and you ring the bell three times because they are slow to open the door, there are three different occurrences (events) of the door bell ringing.

Sometimes it can be practical to technically choose to aggregate multiple fine-grained events into a larger event for performance reasons or simply because it logically makes more sense in the application we are developing. Logically it is a good start to separate events and make them as explicit as possible.

Events have already happened

An event always describes something that happened as a fact. This implies that when we look at the event we see it as it happened in the past, and this is why we always write events in past tense. It is a good practice to be strict about this naming convention since it can be easy to confuse events (facts) with requests to a system (intention). Requests can be denied, and we (normally) don't store the history of requests other than for analytical purposes in our systems.

Technical implementation

At its core, an event is a collection of data. It does not hold any behavior or require any specific framework. To use events you need to be able to marshal/unmarshal the data from a serializable format so that they can be sent over the wire or stored to persistent storage. A good option at this point is JSON since it is easy to read, somewhat concise in its format and generally available for all languages. Many implementations also use serialized formats such as Protobuf.

Technically, it is a good practice to include a timestamp of when the event occurred in the event data as well as an unique identifier (UUID is a good choice) to be able to differentiate events from each other. An implementation of an event using JSON could look something like this:

{
  "eventId" : "e4f57d96-994e-4172-a3a6-9820709c87cc",
  "eventType" : "door-bell-rung",
  "timestamp" : "1593168851560",
  "data" : {
    "field1" : "Data here",
    "field2" : "More data"
  }
}

What are Domain Events?

Domain Events are an important concept within Domain-Driven Design. The concept of Domain Events was however not included in Eric Evans' great book about Domain-Driven Design when it was first written, but added as an appendix later, which explains how this focus around events is different from how we used to design systems.

Domain Events are part of your Domain Model

Domain Events are part of your Domain Model, so to define them properly we must put ourselves into the correct context. In Domain-Driven Design we create a model that is valid within a Bounded Context. The context is our solution to a particular problem that we are addressing, so it can be a subsystem or a Microservice or a monolithic application. The core principle of the Domain Model is the same - it is only valid within this context.

Questions to ask while defining your domain events:

Does our stakeholders/business care about it?
Is it a decision made by our system or another system?
Does it encapsulate the why behind the change?

Aggregates create your Domain Events

A Domain Event is an event that is spawned from this model that is a result of a decision within the domain. Within the model our Aggregates have the role of maintaining business rules and this is where we implement decision points in our model, so the Aggregates are also responsible for creating the Domain Events.

This picture illustrates how Domain Events are part of our Domain Model. They are not being sent from other systems and they are not something that the user sends to our system when performing an action. In our terminology, we call these messages commands which describes how they encapsulate the will to make our system perform a task.

Technical implementation

Domain events add little to the generic implementation of other types of events. It is useful to include the originating aggregateId, from where the event was spawned and include the aggregateType and eventType to help consumers of the event to interpret it. They should be serializable just like any other type of event, and you should not include deep references to objects in the code representation of your Domain Events.

{
  "aggregateType" : "payment",
  "aggregateId" : "1d0d12cd-ac5e-470a-8479-b5a871472445",
  "eventType" : "payment-successfully-completed",
  "eventId" : "e4f57d96-994e-4172-a3a6-9820709c87cc",
  "timestamp" : "1593168851560",
  "data" : {
    "customerId" : "ec930ec6-063f-41e2-9ecb-581cf5e2ad06",
    "amountPaid" : 334
  }
}

When is an event not a Domain Event?

To qualify as a Domain Event the event should have a deeper meaning and importance to our business. Everything that happen around us can be described as events, but that does not mean that we need to implement everything that happens in our software.

Examples of things that happen that might not be suitable to model as Domain Events:

Something technical (a ButtonClicked, ExceptionThrown etc) happened that we want to record or handle, but it is not described in the ubiquitous language of our domain.
Something that happened outside of our bounded context. This could a Domain Event in another system or a different bounded context.
Requests to your system. These we define as Commands rather than events, since they can be rejected by our system.

Integrating using Domain Events

You can use Domain Events to integrate services with each other. They are a very useful way to publish information about what happened in different parts of your system and let other parts react, aggregate or perform calculations based on them. There are however some things to consider before going all in using Domain Events as an integration mechanism.

Domain Events are contextual
Remember the Domain Events are really part of the Domain Model from the context where they are spawned. That is where they have their true meaning and publishing events widely to other systems may introduce unwanted coupling between these systems. Since the Domain Events primarily have the role of storing the truth of your applications history.

In a larger system, such as for example an e-commerce system that handles both customer registration, orders, shipping and payments it can be tricky to use Domain Events from one of these contexts in the other contexts. The meaning of the event may not make sense in other contexts. The word order will likely show in all of these contexts but the meaning and importance of the word is different. This is where the knowledge of Context Mapping in Domain-Driven Design is so important ot understand that the Domain Events are part of the Domain Model.

How to get started?

Getting started with Domain Events does not have to be a big change to your system architecture. If you already are designing applications using DDD you can start by also saving events together with your current application state in a part of your application.

When you start adding Domain Events to the mix of your application you might get interested in Event Sourcing, where Domain Events are the central piece of information. Programming with events as the basic building block can take some time to get used to, but the learning is often worth the time, and you will likely notice less friction when serving the needs of the business people with data. You don't have to use Event Sourcing to start using Domain Events in your software. Domain Events can be a useful addition to a more classical DDD-style architecture where they provide an extra dimension of time to certain parts of the application where this is particularly important.

How are Domain Events and Event Sourcing related?

Event Sourcing is an architectural pattern that is applied within a Bounded Context to provide the single source of truth. There are different interpretations of Event Sourcing, but we tend to keep it quite simple:

Event Sourcing is when you use Domain Events to store the state of an Aggregate within a Bounded Context.

This basically means replacing your relational data model (or other data store) with an ever-growing log of Domain Events, which is called an event store. This is the core of Event Sourcing. So to use Event Sourcing you definitely need to understand Domain Events.

For full disclosure, there are few other interpretations of the pattern, but we still think combining Event Sourcing with Domain-Driven Design and Bounded Contexts is the simplest and clearest view on what this pattern is. Mixing in other technical aspects such as pub/sub tends to blur the picture too much.

The transition to Event Sourcing can be a tricky change to make, but there are some big wins that come with it and this transition does not have to be a big-bang. Since Event Sourcing is a pattern that is to be applied within an application/service and not as a system-wide architectural pattern we recommend getting started with a single microservice or application. If your company is new to these ideas it could be wise to let a single team start experimenting with these technologies and ideas.

Common mistakes and pitfalls

Getting started with Domain Events can feel awkward and there are a few things to remember in order to stay on track with your modeling, so your Domain Events bring true value to your software design.

Trying to model everything

The Domain Model should be useful for the problem we're trying to solve. The model is there to enforce the business rules that we have and preferably our architecture should provide a simple enough integration support for us to be able to connect the application with other systems to make it a useful whole.

A common trap that developers fall down into is to try to model everything related to the problem at hand. This is where the distinction of Domain Events and other events can come handy since many times the other events that happen (technical or peripheral) can be regarded as logging events that we can store for analytical purposes only. Often, it is evident what should be a Domain Event when we try to create these technical events from our Aggregate. It becomes quite clear that they do not belong there.

Not breaking out of the CRUD mindset

One of the most common mistakes when starting with Domain Events and with DDD in general is to not go the whole way and figure our what is actually going on in the domain. It is easy to fall into the trap of naming all events SomethingCreated, SomethingUpdated and SomethingDeleted. While not a problem in itself it does not make use of the powerful thing we get by adding the context and meaning to the actual change that the Domain Event represent. You lose the intent of the event and reading the event log later will not provide that much value.

Next steps

To start using Domain Events as a primary building block for your application and use them to their full extent, I recommend learning more about Event Sourcing and then trying out Serialized as a way to get started without any installation of software or management of infrastructure.