Setting Up Your Project

To get started you will need to configure your project as a cross-project so sbt can compile to all three targets.

Adding Dependencies

Add JitPack to your resolvers and pull in cats-actors using the %%% triple-percent operator, which selects the right artifact for each platform automatically:

resolvers += "jitpack" at "https://jitpack.io"

libraryDependencies += "com.github.suprnation.cats-actors" %%% "cats-actors" % "2.1.0"

Then declare a cross-project in your build.sbt:

import org.portablescala.sbtplatformdeps.PlatformDepsPlugin.autoImport._
import scala.scalanative.build._

ThisBuild / scalaVersion := "2.13.18"

lazy val myProject = crossProject(JVMPlatform, JSPlatform, NativePlatform)
  .crossType(CrossType.Full)
  .settings(
    libraryDependencies ++= Seq(
      "com.github.suprnation.cats-actors" %%% "cats-actors" % "2.1.0"
    )
  )
  .nativeSettings(
    nativeConfig ~= {
      _.withLTO(LTO.none)
        .withMode(Mode.releaseFull)
        .withGC(GC.immix)
    }
  )

With CrossType.Full you get separate jvm/, js/, and native/ source trees alongside the shared one. Everything in shared/ compiles everywhere. Platform-specific code lives in its own tree, and the build wires it in automatically.

From there, running on any platform is just a target name:

sbt "myProjectJVM/run"      # JVM
sbt "myProjectJS/run"       # Node.js
sbt "myProjectNative/run"   # Scala Native binary

Note: to view and run all code samples discussed in this blog post, clone the GitHub repository.

Racing JVM Against Native

The actor ring benchmark is a classic. Popularised by Erlang, it has been used to compare actor systems for decades. Create a ring of N actors, inject a single token, and let it travel totalHops times around the ring. Each relay is one message send. Measure the total time. Same code, two platforms, see what happens.

The full code lives in sample7 in the repository, but let’s walk through it.

The Ring Actor

Each actor in the ring does exactly one thing: if the token still has hops remaining, pass it to the next actor. When the count hits zero, signal that the relay is done.

final case class RingToken(remaining: Long)

final class RingNode(
    index: Int,
    ringSize: Int,
    slots: Ref[IO, Option[Vector[ActorRef[IO, RingToken]]]],
    done: Deferred[IO, Unit]
) extends Actor[IO, RingToken] {

  override def receive: Receive[IO, RingToken] = {
    case RingToken(0L) =>
      done.complete(()).void
    case RingToken(r) if r > 0L =>
      for {
        vecOpt <- slots.get
        vec    <- vecOpt match {
          case Some(v) => IO.pure(v)
          case None    => IO.raiseError(new IllegalStateException("ring not wired"))
        }
        next = vec((index + 1) % ringSize)
        _    <- next ! RingToken(r - 1L)
      } yield ()
    case _ => IO.unit
  }
}

Breaking Down the RingNode

1. The token: RingToken carries a single field, remaining, counting down from totalHops to zero. That is all that ever travels on the wire.

2. The ring topology: The vector of actor refs is stored in a Ref because all nodes are spawned before any of them know about the others. The harness wires them up in a second pass by calling slots.set(Some(refs)).

3. The completion signal: done is a Deferred[IO, Unit], a one-shot, semantically blocking signal. When the last hop arrives, done.complete(()) fires and unblocks the harness that is waiting on done.get. No polling, no shared mutable variable.

4. The send: next ! RingToken(r - 1L) is the fire-and-forget send, pure functional IO, the same whether this code runs on the JVM or compiles to a native binary.

Wiring and Firing

The benchmark harness spawns the ring, wires it, fires the first token, and waits:

private def runOnce(system: ActorSystem[IO], runId: String, cfg: Config): IO[FiniteDuration] = {
  val n    = cfg.ringSize
  val hops = cfg.totalHops

  for {
    done     <- Deferred[IO, Unit]
    slots    <- Ref[IO].of[Option[Vector[ActorRef[IO, RingToken]]]](None)
    refsList <- (0 until n).toList.traverse(i =>
      system.actorOf(new RingNode(i, n, slots, done), s"ring-$runId-$i")
    )
    refs = refsList.toVector
    _    <- slots.set(Some(refs))
    t0   <- Clock[IO].monotonic
    _    <- refs(0) ! RingToken(hops)
    _    <- done.get
    t1   <- Clock[IO].monotonic
  } yield t1 - t0
}

Run it yourself:

# JVM
sbt "sample7JVM/run"

# Scala Native (compile first, then run the binary directly)
sbt "sample7Native/nativeLink"
./sample7/native/target/scala-2.13/native/com.suprnation.Sample7

You can tune things via environment variables (SAMPLE7_RING_SIZE, SAMPLE7_TOTAL_HOPS, SAMPLE7_WARMUP_RUNS, SAMPLE7_MEASURED_RUNS) or pass them as CLI flags. The same benchmark also runs on Node.js via sample7JS/run — useful for a quick sanity check, though the browser target is where Scala.js really comes into its own, as you will see in the next section.

Sample Output :log:

Here is what the Native binary prints for ring size 64 with 1M hops:

=== Sample 7: actor ring (token relay) ===
Startup (entry → actor system ready): 0.21 ms
Ring size: 64, total hops: 1000000
Warmup: 1, measured: 3

[warmup 1] elapsed: 11.612 s
[run 1] elapsed: 11.498 s
[run 2] elapsed: 11.541 s
[run 3] elapsed: 11.573 s

Median elapsed: 11.541 s
Stddev elapsed: 0.033 s
CV (consistency): 0.3%  (lower = steadier)
Median throughput: 86696.41 messages/s
Median latency: 11541.000 ns per hop

0.21ms startup, 0.3% CV. Now run the same config on the JVM and the startup jumps to 127ms, CV climbs to 6.6%, but throughput reaches 111k msg/s and keeps climbing with ring size. Two different trade-offs, same actor code.

The Numbers

Results from a sweep across ring sizes of 32, 64, 128, and 256 with 1M total hops:

Native starts up in under 6ms across every ring size while the JVM costs over 120ms at startup. After warmup the JVM pulls ahead on throughput, reaching over 250k messages per second at ring size 128, because the JVM’s just-in-time compiler observes the hot loop at runtime and generates optimised machine code for it, something a statically compiled binary cannot do. Native compiles once ahead of time and runs at a fixed speed, which is why its throughput is steady but does not accelerate with load. The consistency column reflects exactly this: Native’s stddev stays flat and low throughout while the JVM varies more between runs. If you need a process that starts instantly and runs predictably, Native is the right choice. If you need maximum sustained throughput on a long-running service, the JVM takes it. Same actor code, both options open.

Eight Monkeys in the Browser

OK now we are having fun.

Meet Kong, Bonzo, Coco, Mango, Peaches, Bandit, Zippy, and Bubbles. Eight monkey actors spawned into an arena. Each round, every living monkey picks a random target and throws a banana at them. The target has a 25% chance to dodge. Take enough hits and you are out. Last monkey standing wins.

Every banana throw is a real actor message send using the ! operator. The monkeys are making decisions, updating their own state, and communicating asynchronously, exactly as you would write production actor code. And on Scala.js, every event feeds a live React UI running right here in the page.

Go ahead, watch the battle unfold. :point_down:

Not a single line of JavaScript was written. Those are Scala actors, compiled to JS via Scala.js, rendering a React UI through the Slinky bindings. The full code is in sample8 in the repository.

The MonkeyActor

Each monkey holds its own state in a Ref[IO, MonkeyState] and receives three kinds of messages:

sealed trait ArenaMessage
final case class Tick(round: Int)                              extends ArenaMessage
final case class IncomingBanana(fromId: Int, fromName: String) extends ArenaMessage
final case class ThrowResult(targetId: Int, hit: Boolean)      extends ArenaMessage

On a Tick, a monkey picks a target and throws:

case Tick(_) =>
  for {
    me <- state.get
    _  <- if (me.health <= 0 || me.bananas <= 0) IO.unit else throwBanana(me)
  } yield ()

throwBanana finds a living target, decrements the banana count, and sends an IncomingBanana to the target actor:

private def throwBanana(me: MonkeyState): IO[Unit] =
  for {
    targets <- allStates.traverse(_.get).map(_.filter(s => s.health > 0 && s.id != id))
    _ <- if (targets.isEmpty) IO.unit else {
      val target = targets(rng.nextInt(targets.size))
      for {
        _       <- state.update(s => s.copy(bananas = s.bananas - 1, throws = s.throws + 1))
        _       <- PlatformInterop.appendVisualLog(s"🍌 $name throws at ${target.name}!")
        _       <- PlatformInterop.onBananaThrown(id, target.id)
        monkeys <- registry.get
        _       <- monkeys(target.id) ! IncomingBanana(id, name)
      } yield ()
    }
  } yield ()

On the receiving end the target rolls the dice (25% dodge chance, otherwise take the hit):

private def receiveBanana(me: MonkeyState, fromId: Int, fromName: String): IO[Unit] = {
  val dodged = rng.nextInt(100) < 25
  for {
    monkeys <- registry.get
    _ <- if (dodged) {
      PlatformInterop.appendVisualLog(s"💨 ${me.name} dodges!") *>
      (monkeys(fromId) ! ThrowResult(id, hit = false))
    } else {
      for {
        updated <- state.updateAndGet(s => s.copy(health = s.health - 1))
        _       <- PlatformInterop.appendVisualLog(s"💥 ${me.name} hit! HP: ${updated.health}")
        _       <- monkeys(fromId) ! ThrowResult(id, hit = true)
        _       <- if (updated.health <= 0)
                     PlatformInterop.appendVisualLog(s"☠️  ${me.name} is out!") *>
                     PlatformInterop.onMonkeyEliminated(id)
                   else IO.unit
      } yield ()
    }
  } yield ()
}

Notice the thrower always gets a ThrowResult back. Actors closing the loop, idiomatic actor design.

One Trait, Three Platforms

Here is the clever part. The shared actor code never touches any platform-specific API. Instead it calls through a single trait:

trait PlatformInteropApi {
  def appendVisualLog(line: String): IO[Unit]
  def onBananaThrown(fromId: Int, toId: Int): IO[Unit]
  def onMonkeyEliminated(id: Int): IO[Unit]
  def onScoreUpdate(scores: List[(Int, String, Int, Int)]): IO[Unit]
  def checkRestart: IO[Boolean]
  def resetArena(): IO[Unit]
}

On JVM and Native it is minimal, just print to the console and move on:

// JVM and Native
object PlatformInterop extends PlatformInteropApi {
  override def appendVisualLog(line: String): IO[Unit]         = IO.println(line)
  override def onBananaThrown(fromId: Int, toId: Int): IO[Unit] = IO.unit
  override def onMonkeyEliminated(id: Int): IO[Unit]           = IO.unit
  // ...
}

On Scala.js, every call feeds the live React arena above:

// JS (browser)
object PlatformInterop extends PlatformInteropApi {
  override def appendVisualLog(line: String): IO[Unit]         = IO(ReactShowcase.append(line))
  override def onBananaThrown(fromId: Int, toId: Int): IO[Unit] = IO(ReactShowcase.addProjectile(fromId, toId))
  override def onMonkeyEliminated(id: Int): IO[Unit]           = IO(ReactShowcase.eliminateMonkey(id))
  override def checkRestart: IO[Boolean]                       = IO(ReactShowcase.consumeRestart())
  // ...
}

ReactShowcase manages state through an AtomicReference and runs a 50ms paint loop that re-renders the SVG arena. Click restart and the shared actor code picks it up automatically, same functional IO loop across all three platforms.

Running Locally

cd sample8
sbt "starterJS/fastLinkJS"
npm install && npm run dev
# open http://localhost:5173

Conclusion :tada:

The same actor. The same receive. The same !. Running on a JVM, compiled to a native binary, or animating a banana war in your browser. That is Cats-Actors now.

A huge thank you to Rémi Lavolée and Nick Childers for making this possible.

Check out the Cats-Actors repository and clone the cats-actor-sample repository, pick a platform, and get hacking.

As always, stay safe, keep hacking!

Meet Alice and Bob

Alice and Bob are best friends and tech enthusiasts who often lend and borrow money from each other. Today, Alice needs to send some money to Bob to settle a shared expense. To handle this transaction, they decide to use the latest release of Cats-Actors, excited to explore its new typed actors feature.

Typed actors ensure type-checked message passing at compile time, reducing runtime errors. Alice and Bob will create wallet actors to manage their balances and use a transaction actor to coordinate the money transfer from Alice’s wallet to Bob’s.

Setting Up Your Project

To begin working with typed actors in Cats-Actors, you’ll need to set up your Scala project to include the necessary dependencies and explore the framework’s resources.

Adding Dependencies

First, ensure your Scala project is configured to fetch dependencies from JitPack, a popular repository for GitHub-hosted projects. Add the following lines to your build.sbt file:

   resolvers += "JitPack" at "https://jitpack.io"

   libraryDependencies += "com.github.suprnation" % "cats-actors_2.13" % "2.0.0-RC1"

In the above snippet, "2.0.0-RC1" should be replaced with the latest version of Cats-Actors available on JitPack. These dependencies enable you to utilize Cats-Actors in your Scala application.

Visit the Cats-Actors GitHub repository to explore comprehensive documentation, examples, and community contributions related to the framework.

Note to view and run all code samples discussed in this blog post, clone the GitHub repository.

The WalletActor: Managing Alice and Bob’s Wallets :bank:

The WalletActor is responsible for managing commands related to wallet operations, including retrieving balances, depositing funds, and withdrawing funds. It ensures robustness by strictly typing its receive operations to handle only Command messages, thereby preventing runtime errors. Let’s delve into how it works.

package com.suprnation.samples

import cats.effect.{ExitCode, IO, IOApp, Ref}
import cats.implicits._
import com.suprnation.actor.Actor.{Actor, Receive}
import com.suprnation.actor.ActorRef.ActorRef
import com.suprnation.actor._

object WalletActor {
  sealed trait Command
  case class GetBalance(replyTo: ActorRef[IO, Balance]) extends Command
  case class Deposit(amount: BigDecimal, replyTo: Option[ActorRef[IO, Response]]) extends Command
  case class Withdraw(amount: BigDecimal, replyTo: Option[ActorRef[IO, Response]]) extends Command

  sealed trait Response
  case class TransactionFailed(reason: String) extends Response
  case class Balance(amount: BigDecimal) extends Response

  def create(walletId: String): IO[Actor[IO, Command]] =
    for {
      balance <- Ref[IO].of(BigDecimal.decimal(0.0))
    } yield new Actor[IO, Command] {
      override def receive: Receive[IO, Command] = {
        case Deposit(amount, replyTo) =>
          balance.update(_ + amount) >>
            balance.get.flatMap(newBalance =>
              IO.println(
                s"[${context.self.path.name}] Deposited $amount to $walletId. New balance: $newBalance"
              ) >>
                replyTo.fold(IO.unit)(_ ! Balance(newBalance))
            )

        case Withdraw(amount, replyTo) =>
          balance.get.flatMap { currentBalance =>
            if (currentBalance >= amount) {
              balance.update(_ - amount) >>
                balance.get.flatMap(newBalance =>
                  IO.println(
                    s"[${context.self.path.name}] Withdrew $amount from $walletId. New balance: $newBalance"
                  ) >>
                    replyTo.fold(IO.unit)(_ ! Balance(newBalance))
                )
            } else replyTo.fold(IO.unit)(_ ! TransactionFailed(s"Insufficient funds in $walletId"))
          }

        case GetBalance(replyTo) =>
          for {
            currentBalance <- balance.get
            _ <- replyTo ! Balance(currentBalance)
          } yield ()
      }
    }
}

Breaking Down the WalletActor

The WalletActor handles three main commands:

1. GetBalance: This command is used to query the current balance of the wallet. It takes an ActorRef that will receive the balance as a response.

    case class GetBalance(replyTo: ActorRef[IO, Balance]) extends Command
   

2. Deposit: This command adds a specified amount to the wallet’s balance. It also optionally takes an ActorRef to send a response indicating the new balance.

    case class Deposit(amount: BigDecimal, replyTo: Option[ActorRef[IO, Response]]) extends Command
   

3. Withdraw: This command deducts a specified amount from the wallet’s balance if there are sufficient funds. It can also take an ActorRef for response purposes.

    case class Withdraw(amount: BigDecimal, replyTo: Option[ActorRef[IO, Response]]) extends Command
   

Responses include the current balance and a transaction failure message if something goes wrong:

• TransactionFailed: Indicates a failed transaction with a reason.
• Balance: Represents the current balance of the wallet.

The create method initializes the WalletActor with a starting balance of 0. Its receive method is strictly typed to handle only Command messages, ensuring type safety and minimizing runtime errors.

The TransactionActor: Coordinating the Transfer :money_mouth_face:

With Alice and Bob’s wallets all set, it’s time to master the art of money transfer. The TransactionActor takes on the pivotal role of seamlessly managing transactions between them.

Before we dive into the code, let’s explore the intricate workings of the transaction state machine.

The Transaction State Machine 🤖

The TransactionActor takes charge of orchestrating the flow of a transaction between two wallets. The process involves the following states:

1. PreStart: Initialization phase where the actor sends a withdrawal request to the source wallet.
2. awaitWithdraw: Waits for confirmation of the withdrawal from the source wallet.
3. awaitDeposit: Waits for confirmation of the deposit to the destination wallet.
4. Transaction Complete: Indicates that the transaction was successful and the actor can be stopped.
5. Transaction Failed: Indicates that the transaction failed, either during withdrawal or deposit, and the actor can be stopped.

Here’s a state machine diagram to visualize this flow:

Implementing the TransactionActor

With the state machine as our guide, let’s roll up our sleeves and bring the TransactionActor to life!

object TransactionActor {
  sealed trait Response
  case class TransactionSuccess(transactionId: String) extends Response
  case class TransactionFailed(reason: String) extends Response

  def create(
      transactionId: String,
      parent: ActorRef[IO, Response],
      fromWallet: ActorRef[IO, WalletActor.Command],
      toWallet: ActorRef[IO, WalletActor.Command],
      amount: BigDecimal
  ): Actor[IO, Nothing] = new Actor[IO, Nothing] {

    override def preStart: IO[Unit] = for {
      _ <- IO.println(
        s"~~~ [Tx: $transactionId] => Sending withdraw request to [${fromWallet.path.name}].  Awaiting confirmation.  ~~~"
      )
      _ <- fromWallet ! WalletActor.Withdraw(amount, context.self.widenRequest.some)
      _ <- context.become(awaitWithdraw)
    } yield ()

    def awaitWithdraw: Receive[IO, WalletActor.Response] = {
      case WalletActor.Balance(_) =>
        for {
          _ <- IO.println(
            s"~~~ [Tx: $transactionId] => Withdraw from [${fromWallet.path.name}] confirmed.  Depositing to [${toWallet.path.name}]. ~~~"
          )
          _ <- toWallet ! WalletActor.Deposit(amount, context.self.widenRequest.some)
          _ <- context.become(awaitDeposit)
        } yield ()

      case WalletActor.TransactionFailed(reason) =>
        parent ! TransactionFailed(s"Withdraw from source wallet failed: $reason")
        context.stop(context.self)
    }

    def awaitDeposit: Receive[IO, WalletActor.Response] = {
      case WalletActor.Balance(_) =>
        for {
          _ <- IO.println(
            s"~~~ [Tx: $transactionId] => Deposit to [${toWallet.path.name}] confirmed.  Killing actor - transaction complete! ~~~"
          )
          _ <- parent ! TransactionSuccess(transactionId)
          _ <- context.stop(context.self)
        } yield ()

      case WalletActor.TransactionFailed(reason) =>
        parent ! TransactionFailed(s"Deposit to destination wallet failed: $reason")
        context.stop(context.self)
    }
  }
}

Lights, Camera, Action! :clapper:

It’s showtime for our main application! Here, we’ll orchestrate the entire ensemble: setting up the actor system, casting wallet actors for Alice and Bob, and kickstart a thrilling transaction between them. Plus, we’ve got a backstage reporter actor to capture all the action and reactions!

object Main extends IOApp {
  def run(args: List[String]): IO[ExitCode] =
    ActorSystem[IO]("actor-system").use { system =>
      for {
        auditor <- system.actorOf(new Actor[IO, Any] {
          override def receive: Receive[IO, Any] = { case response =>
            val sender: String = context.sender.map(_.path.name).getOrElse("N/A")
            IO.println(s"[From: $sender] => $response")
          }
        }, "reporter")

        alice <- system.actorOf(WalletActor.create("alice"), "alice-actor")
        _ <- alice ! Deposit(100, auditor.some)

        bob <- system.actorOf(WalletActor.create("bob"), "bob-actor")

        // The transaction actor does not receive any messages, it coordinates flow between two actors.
        _ <- system.actorOf[Nothing](
          TransactionActor.create("alice->bob::1", auditor, alice, bob, BigDecimal(100)), "tx-coordinator"
        )

        // Retrieve the new balances
        _ <- alice ! GetBalance(auditor)
        _ <- bob ! GetBalance(auditor)

      } yield ExitCode.Success
    }
}

The Workflow: Step by Step :rocket:

1. Initialization: The ActorSystem is set up, and a reporter actor is created to log actions and results.
2. Creating Wallets: Wallet actors for Alice and Bob are created, and an initial deposit is made to Alice.
3. Transaction Coordination: A TransactionActor is created to manage the transfer of 100 units from Alice’s wallet to Bob’s. The coordinator sends a withdrawal request to Alice’s wallet and, upon confirmation, sends a deposit request to Bob’s wallet.
4. Logging Results: The reporter actor logs the balance of each wallet after the transaction is complete.

Sample Output and Logs Explanation :log:

Below is a snapshot of what you might see when running the application, along with detailed explanations for each log entry:

[alice-actor] Deposited 100 to alice. New balance: 100.0
[From: alice-actor] => Balance(100.0)
[alice-actor] Withdrew 100 from alice. New balance: 0.0
~~~ [Tx: alice->bob::1] => Withdraw from [alice-actor] confirmed.  Depositing to [bob-actor]. ~~~
[From: alice-actor] => Balance(0.0)
[From: bob-actor] => Balance(0.0)
[bob-actor] Deposited 100 to bob. New balance: 100.0
~~~ [Tx: alice->bob::1] => Deposit to [bob-actor] confirmed.  Killing actor - transaction complete! ~~~

• ~~~ [Tx: alice->bob::1] => Sending withdraw request to [alice-actor]. Awaiting confirmation. ~~~: The transaction actor initiates the withdrawal from Alice’s wallet.
• [alice-actor] Deposited 100 to alice. New balance: 100.0: Alice’s wallet receives a deposit of 100 units.
• [From: alice-actor] => Balance(100.0): The reporter logs the balance of Alice’s wallet.
• [alice-actor] Withdrew 100 from alice. New balance: 0.0: Alice’s wallet processes the withdrawal.
• ~~~ [Tx: alice->bob::1] => Withdraw from [alice-actor] confirmed. Depositing to [bob-actor]. ~~~: The transaction actor confirms the withdrawal and starts the deposit to Bob’s wallet.
• [From: alice-actor] => Balance(0.0): The reporter logs the updated balance of Alice’s wallet.
• [From: bob-actor] => Balance(0.0): The reporter logs the initial balance of Bob’s wallet.
• [bob-actor] Deposited 100 to bob. New balance: 100.0: Bob’s wallet receives the deposit.
• ~~~ [Tx: alice->bob::1] => Deposit to [bob-actor] confirmed. Killing actor - transaction complete! ~~~: The transaction actor confirms the deposit and completes the transaction.

Conclusion :tada:

With the release of Cats-Actors 2.0.0-RC1, typed actors bring a new level of safety and clarity to actor-based programming in Scala. This example demonstrated a classic Alice-to-Bob transaction, showcasing the simplicity and effectiveness of typed actors. Whether you’re building simple applications or complex distributed systems, typed actors can help you write more reliable and maintainable code.

Try it out for yourself, and explore the possibilities that typed actors open up in your projects! :rocket:

As always, stay safe, keep hacking!

Imagine you’re working at ACME Inc., where your task is to create a logic circuit verifier to ensure the reliability of their motherboards. These motherboards will be used in a mission to launch cats into space, and no one wants these feline astronauts to be at risk. You’ve been tasked with developing a logic circuit simulator that accounts for the internal delays of digital circuits, ensuring that all signals stabilize on each clock tick. We certainly don’t want a motherboard with AND gates still transitioning when it’s time to read the values. So, gear up, and let’s embark on this Cats-Actors adventure to build a robust logic circuit simulator and ensure those kittens have a safe sendoff!

Setting Up Your Project

To get started with Cats-Actors, you need to set up your Scala project with the necessary dependencies. Add the following to your build.sbt file:

resolvers += "JitPack" at "https://jitpack.io"

libraryDependencies += "com.github.suprnation" % "cats-actors_2.13" % "1.0.1"

For a complete listing of all code samples and to clone the project, visit the GitHub repository.

Understanding the Actor Model

Before we dive into building our logic circuit simulator, let’s take a moment to understand the actor model. Imagine actors as independent workers in a factory. Each worker has their own tasks and responsibilities, and they communicate with each other by passing messages. This setup ensures that no one is stepping on anyone else’s toes, making it easier to build systems that are both concurrent and fault-tolerant.

In the Cats-Actors framework, these actors get an extra boost from functional programming principles. This means our actors will use immutable data and pure functions, making our system more predictable and easier to maintain.

So, what can actors do in this model?

1. Send Messages: Just like sending a text, actors communicate by sending messages to each other. Each actor has a mailbox where it receives these messages.
2. Create Actors: Need more hands on deck? Actors can create new actors to help with tasks.
3. Change Behavior: Actors can switch up their behavior based on the messages they get, allowing them to adapt to different situations.

By combining the actor model with functional programming, we get the best of both worlds. This synergy helps us build systems that are robust, scalable, and easy to maintain.

Building Our Logic Circuit Simulator

In this section, we’ll start building the core components of our logic circuit simulator using Cats-Actors. Our goal is to construct various logic gates and combine them to simulate complex circuits. Let’s break down the components and build them step by step.

First, we’ll start by creating the Wire actor, which will transport signals. After that, we’ll create basic logic gates like AND, OR, and an alternative OR gate using De Morgan’s laws. We’ll then combine these gates into more complex components such as Half Adders and Full Adders, and finally, we’ll build Demultiplexers.

Ready? Let’s dive in.

1. Creating the Wire Actor

The Wire actor is responsible for transporting signals, which can be either true (high voltage) or false (low voltage). It allows component actors to subscribe to state changes and notifies them whenever its state changes.

Here’s the code for the Wire actor:

def wire(_currentState: Boolean): IO[Actor[IO]] = {
      for {
        associationsRef <- Ref[IO].of(Map.empty[ActorRef[IO], String])
        currentStateRef <- Ref[IO].of(_currentState)
      } yield new Actor[IO] {
        override def receive: Receive[IO] = {
          case AddComponent(name: String, b: ActorRef[IO]) =>
            for {
              _ <- associationsRef.update(_ + (b -> name))
              currentState <- currentStateRef.get
              _ <- b ! StateChange(name, currentState)
            } yield ()

          case GetValue => currentStateRef.get

          case s: Boolean =>
            currentStateRef.get.map(_ != s).ifM(
              for {
                currentState <- currentStateRef.updateAndGet(_ => s)
                associations <- associationsRef.get
                _ <- associations.toList.parTraverse_ { 
                  case (ref: ActorRef[IO], name: String) =>
                     ref ! StateChange(name, currentState)
                }
              } yield (),
              IO.unit
         )
     }
   }
}

In this code, the Wire actor maintains its current state (currentState) and a map of associations where each entry maps a subscribing actor to a wire name. When it receives an AddComponent message, it adds the subscribing actor to its associations and sends the current state to the subscriber. When it receives a boolean value, it updates its state and notifies all subscribed components if the state has changed. Broadcasting state changes to all associations is done in parallel using parTraverse_.

2. Creating the Basic Logic Gates

Now, let’s move on to creating the logic gates. We’ll start with the NOT gate (Inverter). The Inverter actor will take an input and output the inverted result after a delay.

Here’s the code for the Inverter actor:

def inverter(input: ActorRef[IO], output: ActorRef[IO]): Actor[IO] = new Actor[IO] {
  override def preStart: IO[Unit] = {
    input ! AddComponent("in", self)
  }

  override val receive: Actor.Receive[IO] = {
    case StateChange(_, s: Boolean) =>
      (IO.sleep(inverterDelay) >> (output ! (!s))).start
  }
}

The inverter actor registers itself with the input wire, receiving updates under the name “in”. When it receives a state change, it waits for the inverter delay before sending the inverted signal to the output. This process is run in the background using start, allowing the actor to continue processing other messages.

Next, we’ll create the AND gate. The And actor will take two inputs and output the result of their AND operation.

Here’s the code for the And actor:

def and(input0: ActorRef[IO], input1: ActorRef[IO], output: ActorRef[IO]): IO[Actor[IO]] = {
  for {
    in0 <- Ref[IO].of[Option[Boolean]](None)
    in1 <- Ref[IO].of[Option[Boolean]](None)
  } yield new Actor[IO] {
    override def preStart: IO[Unit] = {
      (input0 ! AddComponent("in0", self), 
       input1 ! AddComponent("in1", self)).parTupled.void
    }

    override val receive: Actor.Receive[IO] = {
      case StateChange("in0", b: Boolean) => in0.set(b.some) >> sendMessage.start
      case StateChange("in1", b: Boolean) => in1.set(b.some) >> sendMessage.start
    }

    private val sendMessage: IO[Unit] =
      (in0.get, in1.get).flatMapN {
        case (Some(first), Some(second)) =>
          IO.sleep(andDelay) >> (output ! (first && second))
        case _ => IO.unit
      }
  }
}

The AND actor listens for state changes from its two input wires. When either input changes, it checks if both inputs are true and sends the result to the output wire after a specified delay (andDelay). Note how the state changes are run in the background using start.

Similarly, we can create the OR actor, which outputs true if at least one input is true.

def or(input0: ActorRef[IO], input1: ActorRef[IO], output: ActorRef[IO]): IO[Actor[IO]] = {
  for {
    in0 <- Ref[IO].of[Option[Boolean]](None)
    in1 <- Ref[IO].of[Option[Boolean]](None)
  } yield new Actor[IO] {
    override def preStart: IO[Unit] = {
      (input0 ! AddComponent("in0", self), 
      input1 ! AddComponent("in1", self)).parTupled.void
    }

    override val receive: Actor.Receive[IO] = {
      case StateChange("in0", b: Boolean) => in0.set(b.some) >> sendMessage.start
      case StateChange("in1", b: Boolean) => in1.set(b.some) >> sendMessage.start
    }

    private def sendMessage: IO[Unit] = {
      (in0.get, in1.get).flatMapN {
        case (Some(first), Some(second)) =>
          IO.sleep(orDelay) >> (output ! (first || second))
        case _ => IO.unit
      }
    }
  }
}

The Or actor’s logic is very similar to the And actor’s logic. It registers with the input wires, listens for state changes, and sends the result to the output wire after the specified delay.

We can notice many commonalities between the And and Or actors. To eliminate redundancy, we can create a higher-order actor called reducer, which takes a reduction function and a delay as parameters. This actor will generalize the logic for creating gates with two inputs and one output.

Here’s the code for the reducer:

def reducer(reduceFn: (Boolean, Boolean) => Boolean, delay: Duration)
            (input0: ActorRef[IO],input1: ActorRef[IO], 
            output: ActorRef[IO]
): IO[Actor[IO]] = {
  for {
    in0 <- Ref[IO].of[Option[Boolean]](None)
    in1 <- Ref[IO].of[Option[Boolean]](None)
  } yield new Actor[IO] {
    override def preStart: IO[Unit] =
      (input0 ! AddComponent("in0", self), 
      input1 ! AddComponent("in1", self)).parTupled.void

    override val receive: Actor.Receive[IO] = {
      case StateChange("in0", b: Boolean) => in0.set(b.some) >> sendMessage.start
      case StateChange("in1", b: Boolean) => in1.set(b.some) >> sendMessage.start
    }

    private def sendMessage: IO[Unit] = {
      (in0.get, in1.get).flatMapN {
        case (Some(first), Some(second)) =>
          IO.sleep(delay) >> (output ! reduceFn(first, second))
        case _ => IO.unit
      }
    }
  }
}

Using this higher-order function, we can rewrite the AND and OR gates as follows:

val and = reducer(_ && _, andDelay)(_, _, _)
val or = reducer(_ || _, orDelay)(_, _, _)

This approach keeps the logic for the AND and OR gates intact while reducing redundancy.

Next, let’s create an alternative implementation of the OR gate using De Morgan’s laws, which, given the timings, will be more efficient. Chip manufacturers often specialize in certain gates to reduce production costs and make those gates super efficient. Other gates can be formed using De Morgan’s laws or truth table deductions. According to De Morgan’s laws:

By using this transformation, we can create the OrAlt actor:

def orAlt(input0: ActorRef[IO], input1: ActorRef[IO], output: ActorRef[IO]): Actor[IO] =
  new Actor[IO] {
    override val preStart: IO[Unit] = for {
      notInput0 <- context.actorOf(PropsF[IO](wire(false)), "notInput0")
      notInput1 <- context.actorOf(PropsF[IO](wire(false)), "notInput1")
      notOutput0 <- context.actorOf(PropsF[IO](wire(false)), "notOutput0")

      _ <- context.actorOf(Props[IO](inverter(input0, notInput0)), "A")
      _ <- context.actorOf(Props[IO](inverter(input1, notInput1)), "B")
      _ <- context.actorOf(PropsF[IO](and(notInput0, notInput1, notOutput0)), "notAB")
      _ <- context.actorOf(Props[IO](inverter(notOutput0, output)), "notNotAB")
    } yield ()
  }

In the OrAlt actor, we first invert both inputs, then AND these inverted inputs, and finally invert the result. This approach leverages the efficiency of De Morgan’s laws to potentially reduce the overall computation time, especially in complex circuits.

Note how we are now dealing at a higher level of abstraction – we focus on the logical connections between components rather than the internal workings of the actors. A typical approach in the typelevel community is using FS2 and managing these wirings manually. Achieving the same level of abstraction with FS2 can be more challenging. This isn’t to say FS2 is inferior, but Cats-Actors can simplify dynamic graph constructions and modifications at runtime, particularly when handling dynamic stream graphs.

By using De Morgan’s transformation, we can optimize the OR gate, which typically has a delay of 10ms. In this alternative implementation, we use a NOT gate on each input, an AND gate to combine these negated inputs, and another NOT gate on top of everything. Given that all these components run in parallel, we would have a total delay of only 3ms from the input perturbations, significantly improving efficiency.

3. Creating More Complex Components

Now that we have created basic logic gates, let’s move on to combining these gates into more complex components. We’ll start with the Half Adder. A Half Adder is a digital circuit that performs addition of two binary digits. It has two inputs, a and b, and two outputs, s (sum) and c (carry). The sum output is the XOR of the inputs, and the carry output is the AND of the inputs.

Here’s the code for the Half Adder:

def halfAdder(a: ActorRef[IO], b: ActorRef[IO], s: ActorRef[IO], c: ActorRef[IO]): Actor[IO] = {
  new Actor[IO] {
    override val preStart: IO[Unit] = for {
      d <- context.actorOf(PropsF[IO](wire(false)), "d")
      e <- context.actorOf(PropsF[IO](wire(false)), "e")
      _ <- context.actorOf(PropsF[IO](or(a, b, d)), "Or")
      _ <- context.actorOf(PropsF[IO](and(a, b, c)), "And")
      _ <- context.actorOf(Props[IO](inverter(c, e)), "Inverter")
      _ <- context.actorOf(PropsF[IO](and(d, e, s)), "And2")
    } yield ()
  }
}

The Half Adder actor uses our previously defined gates to create the sum and carry outputs. It uses an OR gate, an AND gate, and an inverter to achieve this.

Next, let’s create the Full Adder, which adds three binary digits (two significant bits and a carry bit). The Full Adder outputs a sum and a carry. We’ll use two Half Adders and an OR gate to construct the Full Adder:

def fullAdder(a: ActorRef[IO], b: ActorRef[IO], cin: ActorRef[IO], sum: ActorRef[IO], cout: ActorRef[IO]): Actor[IO] = new Actor[IO] {
    override val preStart: IO[Unit] = for {
        s <- context.actorOf(PropsF[IO](wire(false)))
        c1 <- context.actorOf(PropsF[IO](wire(false)))
        c2 <- context.actorOf(PropsF[IO](wire(false)))
        _ <- context.actorOf(Props[IO](halfAdder(a, cin, s, c1)), "HalfAdder1")
        _ <- context.actorOf(Props[IO](halfAdder(b, s, sum, c2)), "HalfAdder2")
        _ <- context.actorOf(PropsF[IO](or(c1, c2, cout)), "OrGate")
    } yield ()
}

By leveraging the Half Adder, the Full Adder actor becomes simpler and more modular. This demonstrates the power of building higher-order components from simpler ones, enhancing our digital circuit simulation capabilities.

Next, let’s build a 2-to-1 Demultiplexer (Demux2), which directs an input signal to one of the two output lines based on a control signal. Here’s the code for Demux2:

def demux2(in: ActorRef[IO], c: ActorRef[IO], out1: ActorRef[IO], out0: ActorRef[IO]): Actor[IO] = new Actor[IO] {
    override val preStart: IO[Unit] = for {
        notC <- context.actorOf(PropsF[IO](wire(false)), "not")
        _ <- context.actorOf(Props[IO](inverter(c, notC)), "InverterA")
        _ <- context.actorOf(PropsF[IO](and(in, notC, out1)), "AndGateA")
        _ <- context.actorOf(PropsF[IO](and(in, c, out0)), "AndGateB")
    } yield ()
}

Finally, let’s create a General Demultiplexer (Demux), which can handle multiple control signals and direct the input signal to one of the output lines. The Demux actor uses recursion to handle multiple control signals, dynamically creating a demux of any size by wiring Demux2 actors together. This approach illustrates the flexibility and power of combining actors and functional programming in Cats-Actors. Here’s the code for Demux:

def demux(in: ActorRef[IO], c: List[ActorRef[IO]], out: List[ActorRef[IO]]): Actor[IO] = new Actor[IO] {
    override val preStart: IO[Unit] = c match {
        case c_n :: Nil =>
            context.actorOf(Props[IO](demux2(in, c_n, out.head, out(1)))).void

        case c_n :: c_rest =>
            for {
                out1 <- context.actorOf(PropsF[IO](wire(false)))
                out0 <- context.actorOf(PropsF[IO](wire(false)))
                _ <- context.actorOf(Props[IO](demux2(in, c_n, out1, out0)))
                _ <- context.actorOf(Props[IO](demux(out1, c_rest, out.take(out.size / 2))))
                _ <- context.actorOf(Props[IO](demux(out0, c_rest, out.drop(out.size / 2))))
            } yield ()

        case Nil => IO.unit
    }
}

Note how we can create a demux of any size by recursively wiring Demux2 actors. This exemplifies the power of Cats-Actors, allowing us to use actors and functional programming in unison, and even employ recursion to create dynamic structures.

One key advantage of Cats-Actors is its ability to create dynamic stream graphs without needing to manage the intricate details of wiring these streams manually. Cats-Actors is particularly beneficial when dealing with dynamic graphs of streams that need to be constructed or modified at runtime. This approach simplifies the development of dynamic, evolving systems, making it an excellent choice for complex and adaptable applications.

Putting It All Together

Now, let’s put all our components together and create a Logic Circuit Simulator. This main application will set up a simulation board to test a demultiplexer with two control inputs and four outputs.

Here’s the complete code for the Logic Circuit Simulator:

object LogicCircuitSimulator extends IOApp {
  override def run(args: List[String]): IO[ExitCode] = {
    ActorSystem[IO]("De-multiplexer Board Simulator").use(system =>
      for {
        in1 <- system.actorOf(PropsF(wire(false)), "in1")
        c1 <- system.actorOf(PropsF(wire(false)), "c1")
        c2 <- system.actorOf(PropsF(wire(false)), "c2")
        out1 <- system.actorOf(PropsF(wire(false)), "out1")
        out2 <- system.actorOf(PropsF(wire(false)), "out2")
        out3 <- system.actorOf(PropsF(wire(false)), "out3")
        out4 <- system.actorOf(PropsF(wire(false)), "out4")

        allActors = List(in1, c1, c2, out1, out2, out3, out4)
        printTruthTable =
          for {
            outputs <- allActors.parTraverse(_ ?[Boolean] GetValue)
            result = allActors.zip(outputs).map {
              case (actor, value) => s"${actor.path.name}::$value"
            }.mkString("\t")
            _ <- IO.println(result)
          } yield ()

        _ <- system.actorOf(Props(demux(in1, List(c2, c1), List(out4, out3, out2, out1))))

        _ <- in1 ! true
        _ <- printTruthTable.delayBy(1 second)

        _ <- c1 ! true
        _ <- printTruthTable.delayBy(1 second)

        _ <- c1 ! false
        _ <- c2 ! true
        _ <- printTruthTable.delayBy(1 second)

        _ <- c1 ! true
        _ <- printTruthTable.delayBy(1 second)

        _ <- in1 ! false
        _ <- printTruthTable.delayBy(1 second)
      } yield ()
    ).as(ExitCode.Success)
  }
}

In the main application, we first set up the board simulator to test a demultiplexer with two control inputs and four outputs. We create all the necessary wires for the input, control, and output signals. Notice how elegant it is to query all actors to retrieve their values in parallel using allActors.parTraverse(_ ?[Boolean] GetValue).

We then create the demultiplexer, which routes the input signal based on the control signals. For instance, when we set in1 to true, we expect out4 to be true. Similarly, we can change the control signals c1 and c2 and observe the expected outputs. This dynamic manipulation and observation of the circuit’s state showcase how state changes propagate through the circuit and how the outputs change accordingly.

By printing the truth table, the program shows the state of all wires at each step, demonstrating the robustness and efficiency of our logic circuit simulator built with Cats-Actors. This powerful approach allows us to dynamically create and modify our circuit, demonstrating the harmony between functional programming and the actor model in Cats-Actors.

Conclusion

In this tutorial, we’ve explored the synergy between the actor model and functional programming by building a robust logic circuit simulator using Cats-Actors. We’ve created basic components like wires and logic gates, and combined them into more complex structures such as half adders, full adders, and demultiplexers. Through this process, we’ve demonstrated how Cats-Actors enables us to build dynamic, reliable systems with ease.

The power of Cats-Actors lies in its ability to manage concurrency and state in a highly predictable and maintainable manner. By leveraging functional programming principles, we’ve shown how to create a system that is both scalable and fault-tolerant. This approach simplifies the development of complex, evolving systems, making it an excellent choice for various applications.

If you’re interested in learning more or contributing to the project, check out the Cats-Actors GitHub repository. This repository contains comprehensive documentation and additional examples to help you get started with building your own actor-based systems.

As always, stay safe, keep hacking!

Number Guessing Game

The example we will use throughout this post is a number guessing game. When the program starts it will ask the user for his/her name and on input the program will generate a random number between 1 and 5 and ask the user to guess the number. If the user guesses the number correctly, the program will inform the user of his/her unique mind-reading abilities (incidentally, the user’s superpowers will work 20% of the time!), otherwise, the program will notify the telekinetic failure. Finally, once the game round is complete, the program will ask the user the choose between having another go or exiting. The complete source code is listed below:

def main(args: Array[String]): Unit = {
  println("What is your name?")
  val name: String = readLine()
  println(s"Hello $name welcome to the game!")
  var exec: Boolean = true
  while (exec) {
    val num: Int = scala.util.Random.nextInt(5) + 1
    println(s"Dear $name, please guess a number from 1 to 5")
    val guess: Int = readLine().toInt
    if (guess == num) println(s"You guessed right, $name!")
    else println(s"You guessed wrong, $name the number was $num")
    println(s"Do you want to continue $name?")
    readLine() match {
      case "y" => exec = true
      case "n" => exec = false
    }
  }
}

So what’s “wrong” with such a program? To understand what we can improve, let us first detour and explain the three functional programming principles.

Functional Programming Properties

Functional programs have three main properties:

1. Total - Functions always return an output for every input.
2. Deterministic - Functions return the same output for the same input.
3. Pure - The only purpose of providing a function input is to compute the output.

In contrast, procedural programs are:

1. Partial - Procedures do not return values for some inputs (for example, they throw exceptions).
2. Non-Deterministic - Procedures return different outputs for the same input.
3. Impure - Procedures perform side-effects which mutate data or interact with the external world.

Let’s have a look at some examples to see how these principles apply.

Example 1: Print line to system output

def println(s: String): Unit = ???

The method println above is:

• Total - it is defined for all inputs - the output is always unit
• Deterministic - all inputs yield the same output - unit
• Impure - under the hood println invokes some system calls to push things to the screen - this is not part of the computation.

Example 2: Parse integer

def parseInt(s: String): Int = ??? 

The method parseInt above is:

• Partial - not all strings are valid numbers, e.g. the input “hello world” would throw an exception
• Deterministic - all inputs will give the same result or error
• Pure - There are no side-effects or interactions apart from the conversion from a string to an integer.

Example 3: Generate a random number

def randomInt(): Int = ???

The method randomInt above is:

• Total - for every input we get an output
• Non-Deterministic - by definition the return of a random function is non-deterministic
• Impure - random numbers are generated by observing outside data that is not predictable or generated using pseudo-random streams, both of which are external to the computation.

Having understood the properties of functional programs, we will now iterate over the source problem and convert it into an equivalent program that is more principled (i.e. follows more functional programming properties).

Number Guessing Game - First Iteration

In the first iteration of the program, we will directly address two partial functions. The first partial function that we are going to address is

val guess: Int = readLine().toInt

readLine().toInt is a partial function since it is not defined for all inputs (some inputs will throw an exception). One way to implement the total equivalent is to swap the return type from Int to Option[Int] to capture cases in which the input would throw an exception. You can think of Option[Int] as a more honest type since it explicitly encodes those values which yield no result.

def parseNumber(str: String): Option[Int] = Try(str.toInt).toOption

The second partial function we will address in this section is

readLine() match {
  case "y" => exec = true
  case "n" => exec = false
}

This function is not total since it is only defined for two inputs, “y” and “n”, in all other cases, a MatchError is thrown. We can convert this to a total function as follows:

var continue: Boolean = false
while(continue) {
  continue = false
  readLine() match {
    case "y" => exec = true
    case "n" => exec = false
    case _ => continue = true
  }
}

The complete code after these two conversions is

def main(args: Array[String]): Unit = {
  println("What is your name?")
  val name: String = readLine()
  println(s"Hello $name welcome to the game!")
  var exec: Boolean = true
  while (exec) {
    val num: Int = scala.util.Random.nextInt(5) + 1
    println(s"Dear $name, please guess a number from 1 to 5")
    val guessOpt: Option[Int] = parseNumber(readLine())
    guessOpt match {
      case None =>
        println("Not a number!")
      case Some(guess) =>
        if (guess == num) println(s"You guessed right, $name!")
        else println(s"You guessed wrong, $name the number was $num")
        println(s"Do you want to continue $name?")
        var continue: Boolean = false
        while(continue) {
          continue = false
          readLine() match {
            case "y" => exec = true
            case "n" => exec = false
            case _ => continue = true
          }
        }
    }
  }
}

Number Guessing Game - Second Iteration

The initial iteration of the program is already more principled than our original problem, and, in most cases, we would stop here. For the sake of this exercise, however, we will address three more procedures: println, readLine and Random.nextInt. How to convert such functions into pure functions has perplex the FP community for years. Fortunately, the solution was simple and elegant; let’s welcome the IO monad. Let’s start this section by creating the IO monad from scratch.

The IO Monad

You can think of the IO monad as a “container” that contains a description of a computation. The computation itself might not be functional (in the functional programming sense), but the description itself is. The basic definition of the IO Monad is as follows:

case class IO[A](unsafeRun: () => A) {}

You can see that the value of type A is deferred (the return of a function) by placing it into an IO[A] box, and only when the unsafeRun method is called, the value of type A is returned. Let’s have a look at an example.

object IOSample {
  def main(args: Array[String]): Unit = {
    val program: IO[Unit] = IO(() => println("Hello World"))
    println(program)
  }
}

Running the program above will result in the following output:

IO(com.suprnation.IOSample$$$Lambda$15/0x0000000801162c40@5b464ce8)

As you can see, nothing happens - program is just a description that has an embedded println computation. So the above description is total, deterministic and pure, and is one value from the infinite IO[Unit] set.

To run this description, we need to invoke the unsafeRun method as follows:

object IOSample {
  def main(args: Array[String]): Unit = {
    val program: IO[Unit] = IO(() => println("Hello World"))
    program.unsafeRun()
  }
}

At this point the program transitions from pure to impure (as in not following the FP properties) and “Hello World” is printed to the console.

Transforming IO; map and flatMap

To compose IO, we will need two main methods: map and flatMap defined as follows:

case class IO[A](unsafeRun: () => A) { self =>
    def map[B](fn: A => B): IO[B] = IO(() => fn(self.unsafeRun()))
    def flatMap[B](fn: A => IO[B]): IO[B] = IO(() => fn(self.unsafeRun()).unsafeRun())
}

Visually if we think of IO as a box with a value inside, we can think of map as a function that swaps the value of the box by passing it through the function fn and flatMap as swapping the box based on the current value. As an example let’s say we want to increment the value val three = IO(() => 3).

We can achieve this by using the map function as follows:

val three = IO(() => 3)
three.map(v => v + 1)

What if we want to return true when the value inside the box is even and false otherwise? In this case, we want to swap the box entirely, and hence we would use a flatMap as follows:

val three = IO(() => 3)
three.flatMap(v => if (v % 2 == 0) IO(() => true) else IO(() => false))

Before we go further, let’s define two helper methods on the IO companion object - point and unit - to help us package pure values in an IO box.

object IO {
    def point[A](a: A): IO[A] = IO(() => a)
    def unit: IO[Unit] = IO.point(())
}

Using these helper methods, we can simplify the example above as follows:

val three = IO.point(3)
three.map(v => v + 1)
three.flatMap(v => if (v % 2 == 0) IO.point(true) else IO.point(false))

For comprehension

Before we transform the original program, let’s do one final example of adding two IO[Int] together. Given the following program

object IOArithmetic {
  def main(args: Array[String]): Unit = {
    val number1: IO[Int] = IO.point(1)
    val number2: IO[Int] = IO.point(2)
  }
}

we cannot simply add the two numbers using number1 + number2 but we need to use a combination of flatMap and map to sequence the computation. The solution to this problem is as follows:

object IOArithmetic {
  def main(args: Array[String]): Unit = {
    val number1: IO[Int] = IO.point(1)
    val number2: IO[Int] = IO.point(2)

    number1.flatMap(n1 => {
      number2.map(n2 => {
        n1 + n2
      })
    })
  }
}

The use of flatMap and map to sequence computations is so common that Scala has some special syntactic sugar called for comprehensions. Thus, the above can be re-written as follows:

for {
  n1 <- number1
  n2 <- number2
} yield n1 + n2

Moving forward, we will prefer this style rather than explicitly writing flatMap and map but remember that both are equivalent and it is just syntactic sugar :cake:.

Final Conversion

Armed with the IO Monad, let’s crank up the function knob and finalise the conversion. We will start by wrapping up the println, readLine and Random.nextInt within IO as follows:

def putStrLn(message: String): IO[Unit] = IO(() => println(message))
def getStrLn: IO[String] = IO(() => readLine())
def randomNumber(upper: Int): IO[Int] = IO(() => scala.util.Random.nextInt(upper))

Next, we will convert the original program using flatMap and map. The conversion is reasonably mechanical but to illustrate our conversion strategy, let’s transform the first three lines of the procedural program.

println("What is your name?")
val name: String = readLine()
println(s"Hello $name welcome to the game!")

These three lines can be written using a for-comprehension as follows:

for {
   _    <- putStrLn("What is your name?")
   name <- getStrLn
   _    <- putStrLn(s"Hello $name welcome to the game!")
} yield ()

In a sense, this program is reminiscent of the procedural counterpart, but there is one key difference - this program is just a description. We will need to call unsafeRun to execute this description which will unwrap the descriptions and perform the underlying computations. At this point our program violates the functional properties defined above and crosses the pure to impure boundary.

val program = for {
   _    <- putStrLn("What is your name?")
   name <- getStrLn
   _    <- putStrLn(s"Hello $name welcome to the game!")
} yield ()
program.unsafeRun()

The transformed number guessing game is as follows:

def main(args: Array[String]): Unit = {
    def checkContinue(name: String): IO[Boolean] = for {
      _ <- putStrLn(s"Do you want to continue $name?")
      input <- getStrLn
      cont <-  input.toLowerCase() match {
          case "y" => IO.point(true)
          case "n" => IO.point(false)
          case _ => checkContinue(name)
        }
    } yield cont

    def gameLoop(name: String): IO[Unit] = for {
      num <- randomNumber(5).map(_ + 1)
      _   <- putStrLn(s"Dear $name, please guess a number from 1 to 5")
      input   <- getStrLn
      _       <- parseNumber(input) match {
          case None => putStrLn("Not a number!")
          case Some(guess) =>
            if (guess == num) putStrLn(s"You guessed right, $name!")
            else putStrLn(s"You guessed wrong, $name the number was $num")
        }
      cont <- checkContinue(name)
      _    <- if (cont) gameLoop(name) else IO.unit
    } yield ()

    val program: IO[Unit] = for {
      _     <- putStrLn("What is your name?")
      name  <- getStrLn
      _     <- putStrLn(s"Hello $name welcome to the game!")
      _     <- gameLoop(name)
    } yield ()

    program.unsafeRun()
}

Note that loops in functional programs are transformed into tail-recursive functions. Note also that even though our functions are tail-recursive, our IO implementation is not, and this program will lead to stack overflow issues. Multiple libraries implement a stack safe IO; we opted for simplicity to showcase how functional concepts relate. If you are going to use IO in production, I strongly recommend using Cats Effect or ZIO.

Conclusion

This post transformed a procedural program into a functional program abiding to the three functional principles. The final transformation is still not the end of the road to functional-town; we could expand this example further to categorise different types of IO (tag-less final), but we will leave that for another post. For now, the take-home message is this:

Think of functional programming as a tool in your toolbox. You can always adjust the level of purity in your codebase to fit your comfort level. What’s important is that whatever you do, try to be more principled.

As always, stay safe, keep hacking.

Managing the fleet - GKE Upgrades

One thing I’m really proud of at Suprnation is the fact that for the past three years we had very few crashes. Even more impressive is the fact that our systems auto-recovered from such crashes. Such an outcome is the result of an earlier decision to go reactive - see the reactive manifesto - and the “let it crash” philosophy ingrained throughout our system.

Reactive Systems are typically composed of smaller components which cooperate together to achieve a common goal. Deploying these small components is challenging; how do we isolate, schedule, configure and supervise these components? This is where Kubernetes comes in; it addresses all of these issues. Specifically we use Google Kubernetes Engine, the hosted Kubernetes engine offered by Google.

When using Kubernetes, systems administrators can focus on managing the fleet rather than manage individual components. One challenging aspect of managing a fleet is upgrades. On one hand upgrades give us access to the latest features, but on the other hand they disrupt our business. So what goes on during an upgrade? Well let’s visualise the upgrade sequence.

Node by node, each node is drained, a new VM is created and GKE will wait for the VM to start running. Once running, GKE will register the node with the master and become ready. Once ready, the workload is resumed. During this period - disruption period - your business might (and probably will) experience disruptions.

Can we do better? One feature which is coming up in the next release for GKE is surge-upgrades. If we look at the previous disruption period we can see that certain things can be moved out. Specifically, an extra VM - called a surge VM - can be created before draining the node. By creating an extra VM in this manner we can see that the disruption period shortens and is equal to the time it requires Kubernetes to reschedule your workload from node-to-node. Visually this looks as follows

Surge upgrades will really help us reduce disruptions faced by our clients but this is not a silver bullet. There is only so much magic Google can do in order to make sure that our applications are reliable. There are things which we can ourselves in order to protect ourselves against disruptions. So what are disruptions?

Workload Disruptions

Let’s create a simple application and deploy this on a cluster in order to understand better what workload disruptions are.

const http = require('http');
const os = require('os');

var handler = function(request, response) {
  console.log("Received request from " + request.connection.remoteAddress);
  response.writeHead(200);
  response.end("Hit " + os.hostname() + "\n");
};

http.createServer(handler).listen(8080);

As you can see from the code at the top we are creating a simple server which responds to a client request. We package this application, deploy it on a three-node cluster and expose it via a service by using the following commands

> kubectl run platform --labels="app=platform" --image=platform:v1 --port=8080
> kubectl expose deployment platform --type=LoadBalancer --port=8080 --name platform-http

Visually, this is what we have achieved

So what’s happening here? The client will hit the HTTP endpoint and the service will forward the request to one of the available pods to get serviced. If no pods are available the client will fail to connect.

So let’s run an upgrade scenario. As we mentioned previously, during an upgrade a node is taken down and all pods running on that node are evicted. What this means is that our application will start throwing errors since the pod is evicted but requests are still hitting the endpoint. Of course Kubernetes reschedules the pod and the situation recovers but there is this inevitable period where our application will surely serve errors if hit. Visually this scenario looks as follows

Replicas

So what can we do to mitigate this situation? One obvious thing to do here is to increase the number of replicas that we have. Let’s update the deployment to scale up to 3 replicas.

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  labels:
    app: platform
  name: platform
spec:
  replicas: 3
  selector:
    matchLabels:
      app: platform
  template:
    spec:
      containers:
      - image: platform:v1
        name: platform
        ports:
        - containerPort: 8080
          protocol: TCP

Alternatively we can use the command

> kubectl scale deployment platform --replicas=3

Immediately we have three pods scheduled and running. One important question to ask here is but Where are these pods running? In this case we can see that we have one pod running on node 1 and two pods running on node 2. Let’s really digest what this means in an upgrade scenario.

When node 1 is upgrading, the pod is evicted. In contrast to what we had before our clients are still being serviced since we have 2/3 of our capacity available.

Once again the pod is rescheduled to run on a different node; in this case let’s assume it’s node 3.

When we upgrade node 2, we end up in a situation where we lose 2/3 of our serving capacity. The clients are still being served by the pod on node 3 but under high load this situation might be uncomfortable.

Once again, the two pods are rescheduled by Kubernetes and this situations recovers.

This is clearly not good enough. So, what can we do further?

Pod anti-affinity rules

What we can do in this case is tell the scheduler “Hey, I know what I’m doing, try to schedule those particular replicas on different nodes”. Which is to say that we plan to use pod anti-affinity.

# File: affinity-patch.yaml
affinity:
   podAntiAffinity:
     requiredDuringSchedulingIgnoredDuringExecution:
     - labelSelector:
         matchLabels:
           app: platform
       topologyKey: "kubernetes.io/hostname"

> kubectl patch deployment platform --patch "$(cat affinity-patch.yaml)"

Once we update our deployment to use pod anti-affinity the scheduler distributes the pods evenly across the nodes.

Here, you can rely on the fact that 2/3 of the client capacity will always be available during an upgrade.

Take away #1 - Redundancy

Replicas and Pod Anti-Affinity rules lead us to our first take away - redundancy. There are many things which GKE does (such as surge upgrades) but we have to help ourselves by giving ourselves a little bit of slack. Here we are going to use the simplest formula from SRE - N+1 - which informally translates to “give yourself some breathing room”. Not only that but also use this breathing room as an advantage. You can think of your application as different fault domains that you want to separate and run individually so if part of your application fails the others can survive and serve traffic.

Protection

So, is redundancy enough? Let’s have a look. Ralph (a.k.a Wreck It Ralph since the incident) joined the team and was working on a script.

for node in `kubectl get nodes -o jsonpath='{range.items[*]}{.metadata.name} '`
do
	drain="kubectl drain $node --ignore-daemonsets &"
	eval $drain
done

As it turns out this script ended up draining the cluster causing a total outage; Ralph cordoned all the nodes and also evicted all the pods.

What can we do to protect our pods?

Pod disruption budgets

Here we can see that this is an honest mistake but the key takeaway here is that no amount of redundancy could have saved us.

What can we do to protect ourselves from this situation? Kubernetes is such a huge universe that there are many mechanisms. One simple thing we can do here is to add a pod disruption budget.

# pod-disruption-budget-platform.yaml
apiVersion: policy/v1beta1
kind: PodDisruptionBudget
metadata:
  name: platform-pdb
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: platform

> kubectl create -f pod-disruption-budget-platform.yaml

A pod disruption budget is a place where you say to Kubernetes “OK, these are the pods that I want to protect”. In this case the rule we want to apply is the minAvailable. What this means is that at any point in time there should be at least 2 pods available. There are other rules like maxUnavailable, which specifies how many at a time can be unavailable.

If Ralph tries to drain everything again he will get these error messages.

error when evicting pod "platform-68ddf77fc8-44hch" (will retry after 5s):
Cannot evict pod as it would violate the pod's disruption budget.

error when evicting pod "platform-578f5c9499-vrgtq" (will retry after 5s):
Cannot evict pod as it would violate the pod's disruption budget.

The scheduler here is telling us that it cannot evict the pod because it would violate the rules.

Let’s look at the current situation of pods and nodes below.

As you can see, we still did some damage here. We got rid of one pod from node 1 and that all nodes have been cordoned but what’s important here is that there is no total outage. We are still serving traffic and we have time to recover.

Take away #2 - Protection

So redundancy is not enough. You have to put some protection if you are extra paranoid and it’s good to be extra paranoid for sensitive resources.

Liveness and Readiness Probes

Kubernetes does not know what an application running inside a pod is doing - it’s a black box. If a pod crashes Kubernetes will automatically restart it but at times applications stop working without their underlying process crashing. For example, out of memory exceptions in Java or wrong application code. Let’s have a look

var requestCount = 0;

var handler = function(request, response) {
  console.log("Received request from " + request.connection.remoteAddress);
  requestCount++;
  if (requestCount > 5) {
    response.writeHead(500);
    response.end("I'm not well!");
    return;
  }
  response.writeHead(200);
  response.end("I’m healthy!);
};

One of our developers accidentally made changes to the handler logic of our application. After 5 request our application will reply with HTTP status code 500. This is clearly not what we wanted. After approximately 15 requests all of our replicas will start reporting 500 errors.

From a Kubernetes point-of-view the application is healthy and no pods are restarted. But we can do better than this. By giving Kubernetes some insight into our pods Kubernetes can help us out. We do this specifically with the readiness and the liveness probe.

• Liveness probe determines whether your application is healthy enough. If the application is not healthy, Kubernetes will restart the pod.

• Readiness probe allows Kubernetes to check whether your application is ready to receive traffic but will not restart the pod.

In case of our simple application we will use an HTTP probe to determine whether the application is healthy (liveness)

livenessProbe:
  httpGet:
    path: /
    port: 8080
  initialDelaySeconds: 3
  periodSeconds: 3

As soon as the pod starts returning errors, the pod will fail the liveness check and will eventually be restarted.

Take away #3 - Insights

So take away number three, help Kubernetes help you by giving Kubernetes insight into when your application is ready and available.

Additional Protection Mechanisms

There are other features in GKE which are worth mentioning.

• Surge Upgrades First feature, which we already discussed, is surge upgrades. Surge upgrades will really reduce the disruption times by creating an extra VM before draining old nodes.

• Enhanced Maintenance Windows Google has a feature called auto-upgrades which automatically updates worker nodes. Unfortunately this feature is rarely used since this takes a lot of control from us. As application administrators we want to be fully in control when an upgrade happens since we want to really reduce the impact to our business. Enhanced Maintenance windows allow us to specify that we want to avoid upgrades during inappropriate times such as weekends, Black Friday or Cyber Mondays. Furthermore, enhanced maintenance windows allow us to postpone (snooze) a schedule for a short period of time.

• Canary Clusters This enables us to create canary clusters and link them to our production clusters. This will indicate to GKE to roll out new versions to the canary cluster first, allowing us to run automated tests. Roll out to production clusters will be conditioned on the results of these tests.

Conclusion

In this blog post we looked at how we can control disruptions during node upgrades. In summary we should really focus on three take aways

• Redundancy - give yourself some slack by adding more replicas and using pod anti-affinity rules
• Protection - put protection mechanisms in place for pods which you want to protect
• Insights - give Kubernetes a bit more insight into your pods via liveness and readiness probes.

There are also some interesting features coming up which you should look out for such as surge upgrades and enhanced maintenance windows which will help us further control disruptions. As always, stay safe, keep hacking.

Acme Corp

Acme Corporation is a company that sells a variety of items - for a full catalogue click here . Customers log in via their email address and order products. Wile E. Coyote, the Product Owner, also wants customers to be able to retrieve a summary of their product purchases via their email address.

Throughout our code samples, we will model our domain using these case classes: User, Product and PurchaseHistory. User represents a logged in user, Product represents a purchased product and PurchaseHistory represents the product purchase summary for a logged in user.

case class User(id: Long, email: String, name: String)
case class Product(id: Long, description: String)
case class PurchaseHistory(email: String, name: String, purchases: List[Product])

Imperative Solution

Wile’s product vision can be implemented imperatively as follows

object ImperativeApp {
  private[this] def getProductsForUser(userId: Long): List[Product] = {
    userId match {
      case 1 => List(Product(1L, "Bird Seeds"), Product(2L, "Artificial Rock"))
      case _ => List.empty[Product]
    }
  }

  private[this] def searchUserAccount(email: String): User = {
    email match {
      case "wile@acme.com" => User(1L, "wile@acme.com", "Will")
      case _ =>
        Logger.log(s"User $email is not in the database")
        throw new RuntimeException("User not found!")
    }
  }

  def getAllUserData(email: String): PurchaseHistory = {
    Logger.log(s"Searching For User Account $email")
    val user = searchUserAccount(email)
    val products = getProductsForUser(user.id)
    PurchaseHistory(user.email, user.name, products)
  }
}

The method getAllUserData is a method which given a user’s email address will first search for the user in the Acme database - searchUserAccount - and if present, loads all the purchased products for the user - getProductsForUser. We can run our program as follows

def main(args: Array[String]): Unit = {
  try {
    val PurchaseHistory = getAllUserData("wile@acme.com")
    Logger.log(s"Retrieved $PurchaseHistory")
  } catch {
    case e: Throwable => Logger.log(s"Error Occurred $e")
  }
}

Note that we have to wrap our calls with a try/catch, because our implementation throws exceptions. Try beepbeep@acme.com and see what happens - as always Acme products explode! :boom: :fire:

What’s the problem doc?

Imperative programming is all about procedures. Procedures are

• Partial - Procedures do not return values for some inputs (e.g. at times they throw exceptions).
• Non-Deterministic - Procedures return different outputs for the same input. This typically implies share state.
• Impure - Procedures perform side-effects which mutate data or interact with the outside world.

In the imperative implementation, searchUserAccount is partial and impure. Partial since it throws exceptions for any email which is not wile@acme.com and impure since it interacts with the logging environment which can have additional side-effects (e.g. transfer logs to a remote server). Compare this with getProductsForUser which is total (not partial), deterministic and pure.

Imperative programs are harder to reason about since it is impossible to determine from the signature what is happening inside. In the implementation above, searchUserAccount declares that it always returns a User given an email which is clearly not the case.

Functional programming is all about pure functions. Pure functions have three properties:

• Total - Return a value for every possible input.
• Deterministic - Return the same value for the same input.
• Inculpable - No (direct) interactions with the world or program state.

Together these properties give us an incredible ability to reason about programs. Functional Programming for Mortals is an excellent resource if you are interested in learning further about the benefits of these properties. Let’s see how we can refactor our program to get these desired properties.

Modelling Effects with Monad Transformers

One approach which has been recommended in Scala community is to model such problems using Monad Transformers. I’m including this technique in this blog for one reason - to avoid it! This technique should be avoided since it leads to slow performance and large heap-churns. If you are using Monad Transformers today please stop and read on Effect Rotation. Note that this technique is still better than imperative, so if you are using this technique today in production don’t despair! (I’m in that spot exactly)

Let’s look at the update program

type Error = String
type Log = Vector[String]

object MonadTransformerApp {
  private[this] def getProductsForUser(userId: Long):
    SourcedEitherT[Log, Error, List[Product]] = {
    userId match {
      case 1 => List(Product(1L, "Bird Seeds"), Product(2L, "Artificial Rock")).pureT
      case _ => List.empty[Product].pureT
    }
  }

  private[this] def searchUserAccount(email: String):
    SourcedEitherT[Log, Error, User] = {
    email match {
      case "wile@acme.com" => User(1L, "wile@acme.com", "Will").pureT
      case _ => for {
        _ <- Vector(s"User $email is not in the database").logT
        error <- "User not in our database.  ".raiseT[Log, User]
      } yield error
    }
  }

  def getAllUserData(email: String):
    SourcedEitherT[Log, Error, PurchaseHistory] = {
    for {
      _ <- Vector(s"Searching For User Account $email").logT
      user <- searchUserAccount(email)
      _ <- Vector(s"Searching For Products For Account $email").logT
      products <- getProductsForUser(user.id)
    } yield PurchaseHistory(user.email, user.name, products)
  }
}

So what’s the advantage? Well for one our functions are pure; they are total, deterministic and inculpable. As an example searchUserAccount now always returns a value (could be an error value) and does not interact directly with the log environment.

In contrast to our previous implementation the types here are honest e.g.

private[this] def searchUserAccount(email: String): SourcedEitherT[Log, Error, User]

The above declares that the function will log via a Writer of type Log and return an Error on failure or a User on success. Such honesty allows us to reason clearly about our business logic and refactor with confidence. Additionally, this new implementation avoids throwing and catching exceptions which is broken in async environments.

For completeness I’m including the details of the SourcedEitherT stack together with the helper functions used. Seriously though, don’t try this at home (or work)!

type SourcedEitherT[Raw, Err, Value] = EitherT[Writer[Raw, ?], Err, Value]
type Error = String
type Log = Vector[String]

// Monad Transforms are painful!
implicit class SourcedEitherSyntax[A](a: A) {
  def logT[Err]: EitherT[Writer[A, ?], Error, Unit] = EitherT[Writer[A, ?], Error, Unit](Writer(a, ().asRight[Error]))

  def pureT[Log, Err](implicit evidence: Monoid[Log]): EitherT[Writer[Log, ?], Error, A] = EitherT[Writer[Log, ?], Error, A](Writer(Monoid[Log].empty, a.asRight[Error]))

  def raiseT[Log, Result](implicit evidence: Monoid[Log]): EitherT[Writer[Log, ?], A, Result] = EitherT[Writer[Log, ?], A, Result](Writer(Monoid[Log].empty, a.asLeft[Result]))
}

Modelling Effects with ZIO

So a couple of weeks back I was happy coding away using Monad Stacks! Then ZIO happened! ZIO uses horizontal effects - Effect Rotation - instead of vertical effects which allow us to create functional code without the undesired runtime overheads. Additionally the ZIO version is concurrent-safe which means that we can freely mix concurrent / parallel operations. Thank you @jdegoes for explaining this technique. Let’s update the code

object ZIOApp {
  private[this] def getProductsForUser(userId: Long): MyZIO[Log, Error, List[Product]] =
    userId match {
      case 1 => ZIO.succeed(List(Product(1L, "Bird Seeds"), Product(2L, "Artificial Rock")))
      case _ => ZIO.succeed(List.empty[Product])
    }

  private[this] def searchUserAccount(email: String): MyZIO[Log, Error, User] =
    email match {
      case "wile@acme.com" => ZIO.succeed(User(1L, "wile@acme.com", "Will"))
      case _ => log(s"User $email is not in the database") *> ZIO.fail("User not in our database.")
    }

  def getAllUserData(email: String): MyZIO[Log, Error, PurchaseHistory] =
    for {
      _         <- log(s"Searching For User Account $email")
      user      <- searchUserAccount(email)
      _         <- log(s"Searching For Products For Account $email")
      products  <- getProductsForUser(user.id)
    } yield PurchaseHistory(user.email, user.name, products)

}

where MyZIO and the other helper methods are defined as

trait Writer[W] {
  def writer: Ref[Vector[W]]
}

// Writer helpers:
def log[W](w: W): ZIO[Writer[W], Nothing, Unit] = ZIO.accessM[Writer[W]](_.writer.update(vector => vector :+ w)).unit
def getLogs[W]: ZIO[Writer[W], Nothing, Vector[W]] = ZIO.accessM[Writer[W]](_.writer.get)
def clearLogs[W]: ZIO[Writer[W], Nothing, Unit] = ZIO.accessM[Writer[W]](_.writer.set(Vector()))

// Types and Helpers
type MyZIO[W, E, A] = ZIO[Writer[W], E, A]

ZIO helps us create descriptions of what our program should do (rather than do it!). Describing what a program should instead of doing it is powerful, extremely powerful. To illustrate why, let’s update our program to handle a flaky connection with the database when searching for the user account - searchUserAccount.

def getAllUserData(email: String): MyZIO[Log, Error, PurchaseHistory] =
    for {
      _         <- log(s"Searching For User Account $email")
      user      <- searchUserAccount(email).retry(Schedule.recurs(10))
      _         <- log(s"Searching For Products For Account $email")
      products  <- getProductsForUser(user.id)
    } yield PurchaseHistory(user.email, user.name, products)

That’s it! Our program will now retry the searchUserAccount 10 times before failing. There are more powerful combinators in the ZIO library which allow us to compose and modify program descriptions.

So, how do we run these descriptions? ZIO comes packaged with a DefaultRuntime which takes a pure program description and executes its effects onto the world via the unsafeRun method.

def main(args: Array[String]): Unit = {
  val runtime = new DefaultRuntime{}

  val program = for {
    _                   <- getAllUserData("wile@acme.com")
    logForValidSearch   <- getLogs[String]
    _                   <- console.putStrLn(logForValidSearch.mkString("\n"))
  } yield ()

  runtime.unsafeRun(for {
    wref    <- Ref.make[Vector[String]](Vector())
    result  <- program.provide(new console.Console.Live with Writer[String] { def writer = wref  })
  } yield result)
}

Conclusion

In this post we have looked at how we can convert an imperative program into a pure functional “equivalent” using two techniques; Monad Transformers and Effect Rotation (via ZIO). ZIO is more than just an Effect Rotation implementation. ZIO is a library for asynchronous and concurrent programming powered by highly-scalable, non-blocking fibers that never waste or leak resources. ZIO will be one of the most influential libraries in the functional ecosystem. The community is also super helpful and welcoming. Get started today - head over the project microsite and the gitter channel. As always…stay safe and keep hacking!

Cathedrals vs Baazars

Back in 2006 the world was definitely a simpler place. Large deployments consisted of a couple of servers, API response times were measured in seconds and customers were tolerant to hours of downtime. Today, large deployments consist of hundreds (even thousands) of servers, customers demand sub-second response times and downtimes are not tolerated at all.

Since 2006 systems have grown significantly larger making scale-up infeasible. New requirements require new architectures; big monoliths need to be broken down into smaller independent components called microservices in order to be developed, maintained and scaled independently (scaled-out).

Reactive applications

If the previous section resonated with the reactive manifesto, you are right, it sure does. Around 2014, I started following content from Jonas Bonér (@jboner), Roland Kuhn (@rolandkuhn) and Martin Odersky (@odersky) and the seeds of reactive systems were planted.

But what are reactive applications? Merriam Webster dictionary defines reactive as readily responding to stimulus. In the case of reactive applications this specifically means four things:

1. React to events: reactive systems consist of a number of loosely coupled systems that need to communicate together asynchronously via messages.
2. React to load: reactive systems need to handle non-uniform loads with huge variances.
3. Reactive to failure: the ‘let it crash’ philosophy is ‘built-in’ into reactive system rather than patched on top. Failure is not an exceptional event but assumed.
4. React to users: as a result of systems which communicate asynchronously, react to load and react to failure we can create systems which respond to users in a timely manner.

Microservices, microservices everywhere

So, the vision was clear. We wanted to create microservices which

• cooperate together asynchronously via messages,
• scale independently to buffer load and optimise costs, and
• react to failure without manual intervention.

We also wanted to develop microservices in a functional paradigm but that’s a story for some another time :smile:.

From a developer’s POV, moving to reactive systems (and microservices) is easy. Microservices are easy to understand hence easier to develop, understand and maintain.

From a DevOps perspective microservices are hard. Hard to:

• Isolate: how do we make sure that microservices do not step on each other’s toes?
• Schedule: how do we schedule micorservices across a number of nodes?
• Configure: how do we configure services so that they can communicate with each other? How do we expose services to the outside world?
• Supervise: how do we supervise microservices to know that they are alive?
• Recover (from failure): how do we handle failure?

Ok great, vision - check! Mental map - check! First stop down microservices lane was isolation!

Isolating Running Apps

Google was the first company to face this problem at scale and created two technologies (cgroups and namespaces) which would unlock container orchestration engines. Looking back, there were (and still are) three main techniques available:

1. Naive Approach (faith is a requirement): Applications are deployed on a couple of machines and are assumed to be homogeneous; same libraries, same environment. Assuming that all microservices developed have the same requirements is naive and limiting.

2. VM Approach (thou shall be wasteful): To solve the divergence problem, most people turn to VMs. The main drawback with VMs is that as components get smaller (and the number of components increase) hardware resources are not fully utilised. VMs also create a huge workload for system administrators.

3. Containers Approach (thou shall be resourceful): The ultimate solution and the solution we ended up using is _linux containers. Using containers we run processes on a host operating system and isolate these processes through the use of namespaces. Resources utilised by an applications are restricted through the use of cgroups.

Kubernetes

Having found a solution to the problem of isolation, we focused on scheduling, configuring, supervision and failure recovery. It turned out that Kubernetes solved all of these problems. Hard to believe right? Let’s see how Kubernetes helps us solve Scheduling, Configuring, Supervision and Failure recovery.

Scheduling

Creating Containers

When we discuss scheduling we typically think of deploying a container (or pod in Kubernetes lingo) on some server. Assuming that we have the image repository/platform:v1 how do we deploy 5 instances of this application across our available nodes? One way of doing this in Kubernetes is via a deployment resources. First we create a file deployment.yaml (although the name is not important)

# File: deployment.yaml
apiVersion: apps/v1beta1
kind: Deployment
metadata:
  name: platform
spec:
  replicas: 5 
  template:
    metadata:
      name: platform
      labels:
        app: platform
    spec:
      containers:
     : image: repository/platform:v1
        name: platform

and submit the deployment resources to the Kubernetes master via the control plane

> kubectl create -f deployment.yaml

The Kubernetes master will orchestrate all the Kubernetes worker nodes to achieve the desired state (5 platform pods).

Scaling

Ok great! Our application is really performing well and now we want to scale-up to handle heavier loads. With Kubernetes this is easy - we update the spec.replicas field from 5 to say 10,

# File: deployment.yaml
apiVersion: apps/v1beta1
kind: Deployment
metadata:
  name: platform
spec:
  replicas: 10 # Change number of replicas
  template:
    metadata:
      name: platform
      labels:
        app: platform
    spec:
      containers:
     : image: repository/platform:v1 # Still circle thingies!
        name: platform

submit this to the Kubernetes master

> kubectl apply -f deployment.yaml 

and voila! We scaled our application. Alternatively we could have achieved the above by simply running the command

> kubectl scale deployment platform --replicas=10

A hand-wavy explanation of what just happened; Kubernetes identified a mismatch between the desired state (10 application instances) and the actual state (5 application instances) and resolved the mismatch by orchestrating more pods across the available nodes. If you are interested in Kubernetes internals I would highly recommend the book Kubernetes in Action by Marko Lukša (@markoluksa). Another great resource to learn Kubernetes is the github repository; kubernetes is an open source project and reading the codebase can be quite educational.

Rolling Updates

One thing in which Kubernetes really shines is rolling updates. So imagine the following scenario; we have deployed version 1 of our application, things are going great and we are ready to roll out version 2. How do we do this without incurring any downtime? In Kubernetes, we simply update the field spec.template.spec.containers.image field from repository/platform:v1 to repository/platform:v2

# File: deployment.yaml
apiVersion: apps/v1beta1
kind: Deployment
metadata:
  name: platform
spec:
  replicas: 3
  template:
    metadata:
      name: platform
      labels:
        app: platform
    spec:
      containers:
     : image: repository/platform:v2 # Change image
        name: platform

inform the Kubernetes master of our desired state

> kubectl apply -f deployment.yaml

and Kubernetes will automatically start scaling up new deployments and scaling down the old deployments until all pods are on the latest version. There is also a big bang approach but typically you would want to phase out the deployment to avoid downtime.

Configuring

Having discussed scheduling, we shall now focus on how we can configure our pods to communicate with each other and how we can communicate with pods from the outside word.

Accessing Pods within the cluster

One requirement of reactive systems is that they are able to communicate with each other asynchronously. Given that pods are ephermal: remember let it crash, how do we contact our pods from other pods if they are moving targets? In order to understand how we do this let us first create a CMS Deploymnent resource and spin up three nodes!

# File: cms.yaml
apiVersion: apps/v1beta1
kind: Deployment
metadata:
  name: cms
spec:
  replicas: 3
  template:
    metadata:
      name: cms
      labels:
        app: cms
    spec:
      containers:
     : image: repository/cms:v1
        name: cms

> kubectl create -f cms.yaml

How do we allow our previously created platform pods to communicate with our newly created cms pods? In a non-Kubernetes world, a sysadmin would need to configure each cms and platform container manually but when using Kubernetes we utilize a service resource

# File: service.yaml
apiVersion: v1
kind: Service
metadata:
  name: cms-service
spec:
  ports:
    name: http
    port: 80
    targetPort: 8080
  selector:
    app: cms