Example app

Endless example application is a small API for managing imaginary bookings for passenger trips from some origin to some destination, as well as tracking positions and speeds of vehicles. It can be found in endless-example and can be run directly: sbt run.

API

It has a simple CRUD API for bookings and vehicles:

@@snip ExampleApp { #api }

Scaffolding

The application is assembled via calls to @scaladocdeployRepository (for bookings) and @scaladocdeployDurableEntity (for vehicles) (see @ref:runtime for more details)

Akka and Pekko runtimes essentially have the same API, so we'll use Pekko for the example:

@@snip PekkoApp { #main }

Algebras

You might have spotted the two algebra types in the snippet above:

Repository

@@snip BookingsAlg { #definition }

Here's the sequence of operations happening behind the scenes when retrieving an instance of entity algebra:

Entity

@@snip BookingAlg { #definition }

Implementations

Implementation of the repository algebra is trivial using Sharding instance (injected by deployRepository):

@@snip ShardedBookings { #definition }

Implementation of behavior algebra is done using the Entity typeclass instance (also injected by deployRepository):

@@snip BookingEntityBehavior { #definition }

Event handling

In this simple example, events essentially set fields in the state:

@@snip BookingEventApplier { #definition }

Protocol

Command and reply encoding/decoding on client and server side is implemented with a subclass of CommandProtocol, in this case ProtobufCommandProtocol as we'll be using protobuf. On the client side, we translate invocations into instances of OutgoingCommand and make use of the sendCommand helper function:

@@snip BookingCommandProtocol { #example-client }

On the server side, we decode instances of IncomingCommand and make use of handleCommand to trigger relevant entity logic and encode the reply:

@@snip BookingCommandProtocol { #example-server }

Here's an illustration of the chain of interactions taking place when placing a booking, both from the client and the server side:

Side-effects

We describe the availability process as well as entity passivation using Effector:

@@snip BookingSideEffect { #definition }

Testing

Unit testing for entity algebra implementation, event handling and effector benefits from to the parametric nature of F:

@@snip BookingEntityBehaviorSuite { #example }

@@snip BookingEventApplierSuite { #example }

@@snip BookingSideEffectSuite { #example }

Command protocol can be also be covered in isolation with synchronous round-trip tests:

@@snip BookingCommandProtocolSuite { #example }

Component and integration tests using Akka or Pekko testkits are also advisable and work as usual, see @githubPekkoExampleAppSuite.