Express yourself with

a finite-state machine in Scala

Michał Tomański

michaltomanski

Problem(s)

Problem(s)

• is not a trivial sequence of steps (e.g. shopping checkout)

• has many steps (e.g. user registration)

How to model a process that:

Finite-state machine

Model of a (potentially complex) process in which we can distinguish steps

Finite-state machine

• States
• Data
• Transitions
• Triggers

Case study

Express Ticket Machine

• Stationary (at the railway station)
• Show the soonest train connections
• Pick one
• Reserve a seat on that connection
• Pay
• Print the ticket
• Cancel reservation if timeout

For people who are in a hurry

®

Tools

Actor

• Receives a message
• Do logic related to this message
• Update his internal state
• Reply

FSM

Is an actor

FSM

States

class TicketMachine(...) 
    extends FSM[TicketMachineState, TicketMachineData]

FSM

Data

class TicketMachine(...) 
    extends FSM[TicketMachineState, TicketMachineData]

FSM

Initial values

FSM

Transitions

FSM

State timeouts

val reservationTimeout = 20.seconds
  
when(WaitingForPayment, reservationTimeout) {
  case Event(PaymentSuccessful(paymentId), data) =>
    goto(PrintingOutTickets)
  case Event(StateTimeout, data: DataWithSelectedConnection) =>
    goto(FetchingSoonestConnections) using data.resetAfterTimeout()
}

FSM

onTransition {
  case Idle -> FetchingSoonestConnections =>
    nextStateData match {
      case DataWithOrigin(id, origin) => {
        connectionActor ! FetchSoonestConnections(origin)
      }
    }
...

Transition actions

FSM

Transition actions

FSM

Initializing

FSM

Unhandled

Demo time

Awesome, but can it be any better?

Next Level - make it persistent

Persistent Actor

• Persist every valid event
• Do your business logic after it's persisted
• When it crashes, all the events are read from the journal
• We got our state back!

Persistent FSM

Is a persistent actor

trait PersistentFSM[S <: FSMState, D, E] 
  extends PersistentActor with PersistentFSMBase[S, D, E]
  with ActorLogging

class TicketMachine(...) 
  extends PersistentFSM[TicketMachineState, 
    TicketMachineData, TicketMachineEvent]

Persistent FSM

State identifiers

trait PersistentFSM[S <: FSMState, D, E] 

sealed trait TicketMachineState extends FSMState

case object Idle extends TicketMachineState {
  override def identifier: String = "Idle"
}

Persistent FSM

Applying events

Persistent FSM

Storage plugin config

akka {
  persistence.journal.plugin = "akka.persistence.journal.leveldb"
  
  persistence.journal.leveldb.dir = "leveldb/journal"
}

Demo time

Persistent FSM

Storage

What is really persisted?

• Every event that is applied
• The state identifier of the states we are going to 

Persistent FSM

Recovery

What happens during recovery?

• events are read from journal one by one
• applyEvent is run on each domain event
• state is set to the state corresponding to its identifier
• after the entire journal is read, the transition handlers from last state to last state is performed
• Going from WaitingForPayment to WaitingForPayment
• onRecoveryCompleted handler is fired

Persistent FSM

What can go wrong?

Persisting an event might fail because of:

• Pre-persisting failure (e.g. serialization error)
  - ​onPersistRejected is called
   
• Persisting failure (e.g. db not available)
  - onPersistFailure is called and actor is stopped
  - backoff strategy can be configured
  - journal plugin decides when to give up and issue error

Persistent FSM

What can go wrong?

Recovering might fail

• onRecoveryFailure will be called
  and actor will be stopped

Persistent FSM

What can go wrong?

• Persisting events can take some time
• All incoming events are stashed 
• Posion pill is handled by akka itself, not minding events waiting in the stash

actor ! PersistThisPlx("Important string")
actor ! PoisonPill
// might not be a good idea

Persistent FSM

What can go wrong?

• Events during recovery have /deadLetters as sender() 
• if you really need to have the original sender, store its actorpath

Persistent FSM

Evolution

Two kinds of evolutions might cause us problems:

• Events schema evolution
• FSM logic evolution

Persistent FSM

Evolution

Events schema evolution

class MyEventAdapter extends EventAdapter {
  override def manifest(event: Any): String =
    "" // when no manifest needed, return ""
 
  override def toJournal(event: Any): Any =
    event // identity
 
  override def fromJournal(event: Any, manifest: String): EventSeq = {
    val upcastedEvent = doSomeLogic(event)
    EventSeq.single(upcastedEvent)
  }
}

Persistent FSM

Evolution

FSM logic evolution

Manipulating transition logic may lead to incorrect behavior during recovery. e.g.

• run our state machine through steps 1, 2 and 3
• shut it down
• remove transition between state 2 and 3
• restart everything
• ...aaand we have all events correctly replayed and ended up in state 3, although it should be now impossible

Ok, is it better now with Persistent FSM?

Pros:

• Persistence
• A good start for Event Sourcing / CQRS

Cons:

• Schema changes (not so painful)
• Logic changes (a bit more painful)

Persistent FSM

Awesome, but...

Express yourself with

a finite-state machine in Scala

Michał Tomański

@michaltomanski

github.com/michaltomanski/fsm-demo

slides.com/michaltomanski/fsm