Eventuate SAGA demo

This project demonstrates how to use Eventuate Tram Saga on a concrete use case.

It has been used at various talks given at DevoXX France, Bordeaux JUG, DevFest Lille, BreizhCamp, Paris JUG, Nantes JUG, Lyon JUG.

A similar example based on MicroProfile Long Runing Actions is available on GitHub.

It is made of 3 modules :

1. Holiday service: the edge service exposed to the outside. Orchestrates the SAGA and invokes specialized backend services such as trip, hotel and car. In this version, only trip is implemented. Feel free to download the code and to complete it with the 2 other services. This will be a good exercice!

2. Trip service: a backend service invoked by Holiday

3. Trip API messaging: defines the messages (commands and replies) handled by Trip.

Technical architecture

Comments:

1. Both services are implemented with Quarkus

2. They expose a REST API and uses CDI and JPA internally

3. They communicate with asynchronous messaging

4. Both services have their own MySQL database

5. CDC stands for Change Data Capture. It is an Eventuate component that implements the Transactional outbox pattern. Eventuate messages (commands, replies, events) are written in a message table before being published on a Kafka topic. The CDC acts as message relay and ensures transactional messaging and duplication detection

6. Kafka is used as message broker

7. Howl is a Kafka GUI enabling to easily browse topics, messages, consumer groups

8. Zookeeper supervises both Kafka and CDC.

In production, it is possible to run several CDC similar instances running in parallel (sharing the same EVENTUATELOCAL_CDC_LEADERSHIP_LOCK_PATH value), but only one is elected active by Zookeeper and able to read the message table. More information on Configuring the Eventuate CDC Service.

About the SAGA definition

SAGA offer a lightweight distributed transaction model on top of local ACID transactions.

The corner stone of the programming model is the SAGA definition. It is based on a specific DSL (Domain Specific Language) enabling to define steps. Each step is made of actions (local or remote) and optional compensation operations:

The execution of a SAGA is asynchronous. Its state is persisted in database and its execution can be suspended, for instance when waiting for a command reply. When resuming, it can be run by another thread. The log messages displayed by Holiday enables to understand how threading is managed behind the hood.

This model based on a DSL is called Orchestration. Eventuate offers an alternative based on domain events called Choreography. Orchestration is recommended for complex use cases.

Bridging synchronous and asynchronous execution

HolidayBookRequest is received in a synchronous way on a REST endpoint (see HolidayResource). In contrast, the execution of the SAGA is asynchronous.

For the demo, in order to display the complete response in Swagger-UI, it has been necessary to bridge the 2 modes of execution:

1. The answer to HolidayBookRequest is asynchronous using a CompetionStage<Response> response code. It is completed afterwards when the execution of the SAGA is finished

2. The end of a SAGA is notified by a HolidayBookSagaFinishedEvent domain event. This event is published by HolidayBookSaga (see onSagaCompletedSuccessfully and onSagaRolledBack methods)

3. This domain event is consumed by HolidayEventConsumer to complete the pending JAX-RS Response

4. SagaToCompletableFuture stores the association of SAGAs instance and pending CompletableFuture JAX-RS Responses.

Technical context

As of this date (Jan 2023), the following technical context has been used:

1. Java 17

2. Quarkus 2.13.3.Final

3. Eventuate Platform 2022.2.RELEASE

Ports in use

There are several TCP ports used by this demo:

1. Zookeeper: 2181

2. Kafka: 9092,29092

3. Kafka Howl: 9088

4. MySQL-Holiday: 3306

5. MySQL-Trip: 3308

6. cdc-holiday: 9086

7. cdc-trip: 9084

8. Quarkus-Trip: 9082

9. Quarkus-Holiday: 9080

How to build

Run mvn clean package in the main directory.

How to start the demo

Start the infrastrucure

Zookeeper, Kafka, Kafka Howl, PostgreSQLs and CDCs are run with docker compose.

To start them:

1. cd saga-infra

2. ./start-infra.sh: previous containers and volumes are pruned to start with a fresh situation.

After the infrastructure has been started, you can check both CDCs to ensure that they are connected to the database and Kafka:

1. cdc-holiday: http://localhost:9086/actuator/health

2. cdc-trip: http://localhost:9084/actuator/health

CDCs can be configured in 2 modes to read the message table:

• SQL polling mode offers a generic approach that can be used for all SQL databases, it is clearly not optimal in production

• by tailing the database server transaction log: only available for MySQL and PostgreSQL. It is highly recommended in production to improve performance and scalability.

Start Trip

1. cd trip

2. ./start-trip.sh

Start Holiday

1. cd holiday

2. ./start-holiday.sh

Understanding the demo

Before running the demo, it is important to understand the processing in place:

Comments:

1. Holiday acts as the edge service exposed to the outside. When receiving a HolidayBookResource, it starts a SAGA that orchestrates the processing

2. It invokes Trip which checks the departure (accepted value: Paris) and the destination (accepted values: London, Dublin, Budapest, Barcelona), determines the transport (BOAT, TRAIN, PLANE) and the time schedule

3. For the sake of simplicity, invoking Hotel and Car is not implemented

4. Holiday checks the total price that shouldn’t exceed 500.00

The request is rejected if:

• customer id is NOK

• departure or destination are NOK

• total price exceeds the maximum value.

It is accepted if all checks are OK.

Eventuate database

Eventuate needs some database tables to work:

PS6PY can be used to discover how they are accessed behind the scene. You can activate it on Holiday by setting application.properties:

quarkus.datasource.jdbc.driver=com.p6spy.engine.spy.P6SpyDriver

P6SPY is configured in src/main/ressources/spy.properties. SQL requests are written in spy.log.

To give you an insight, the following tables are used for a confirmed SAGA :

1. saga_instance: 1 insert, 7 updates, 6 selects

2. received_messages: 3 inserts

3. message: 3 inserts

Monitoring those 3 tables is highly critical to achieve good performance in production.

Warning: P6SPY does not work with Quarkus in prod mode.

How to run the demo

All the demo can be run from Holiday Swagger UI: http://localhost:9080/q/swagger-ui/

Kafka traffic can be checked from Kafka Howl: http://localhost:9088/topics

Trip Swagger UI can also be used to check the status of Trip entities: http://localhost:9082/q/swagger-ui/

Kafka topics

When the application is launched, several Kafka topics are created:

Comments:

• tripService is used by Trip to receive commands

• *-reply is used by Trip to send command responses

• Holiday is used to publish Holiday domain events.

Demo 1: accepted request

From Holiday Swagger UI:

1. Chose HolidayResource POST "Book a Holiday with LRA"

2. Select "Let’s go to London" from the examples

3. Try and execute it.

The response status should be ACCEPTED.

You can check the Kafka messages that have been exchanged between Holiday and Trip with Kafka Howl by digging in the Topics. In particular, you can check that Trip reply (HolidayBookSaga topic) header reply_outcome-type is set to SUCCESS.

Check the consistency of the Trip entity:

1. Get the trip_id value of the response in Holiday Swagger UI

2. Go to Trip Swagger UI and select "find by id"

3. The status should be ACCEPTED.

Demo 2: customer id NOK

From holiday Swagger UI:

1. Change the customer id value to 4

2. Execute it.

The request has been rejected by Holiday with a business error "Unknown customer".

Demo 3: destination NOK

From holiday Swagger UI:

1. Reset the customer id value to 42

2. Change the destination to "Londonx"

3. Execute it.

The request has been rejected by Trip with a business error "Rejected destination Londonx".

Check the consistency of the Trip entity:

1. Get the trip_id value of the response in Holiday Swagger UI

2. Go to Trip Swagger UI and select "find by id"

3. The status should be REJECTED

With Kafka Howl, you can check that Trip reply (HolidayBookSaga topic) header reply_outcome-type is set to FAILURE. This triggers a SAGA compensation.

Demo 4: max price exceeded

From holiday Swagger UI:

1. Reset the destination value to "London"

2. Change the value of people_count to 2

3. Execute it

The request has been rejected by Holiday with a business error "Max pricing exceeded".

Check the consistency of the Trip entity:

1. Get the trip_id value of the response in Holiday Swagger UI

2. Switch to Trip Swagger UI and select "find by id"

3. The status should be CANCELED.

Demo 5: timeout

From holiday Swagger UI:

1. Set the destination value to "Budapest"

2. This forces a timeout in Holiday servivce

3. The value of the timeout is configured with app.time.to.live.saga in application.properties

4. The status should be CANCELED.

Quarkus native mode

Building Holiday in native mode does not work yet. There is an error due to the use of java.util.Random.

Performance consideration

How long does it take to run a SAGA?

In this demo, the response time is measured for each request (see x-response-time HTTP header in the response). It includes the complete SAGA execution. On average, on my laptop it is around 190 msec for a successfull request.

The response time of a SAGA execution highly depends on the infrastructure and the CDC configuration. On my laptop, the best results have been achieved using MySQL in transaction log tailing.

This is the default configuration, 2 other docker compose files are available if you want to switch to PostgreSQL (see saga-infrastructure directory). Quarkus application.properties files are also provided in Trip and Holiday. BTW do not forget to also change your Maven dependency from quarkus-jdbc-mysql to quarkus-jdbc-postgresql to switch to PostgreSQL.

How does it compare with Long Running Actions?

Let’s wrap up our findings:

1. REST without LRA: 30 msec

2. REST with LRA: 120 msec

3. Eventuate SAGA with orchestration: 240 msec

These results have been measured in the following context:

1. it has been run on a laptop

2. all components running locally

3. without any concurrency and multi-threading

4. the business logic is very simple

5. no optimization for Kafka and Database

Warning: these results just provide an indication and should not be taken for granted. There are potentially numerous ways to fine tune these solutions in production.Do not forget to run your own benchmark before going in production