Implement Event bus using Akka

Implement Event bus using Akka

Lukasz Lenart

You’ve seemingly be taught such posts time and again and you might be questioning what extra I’ll repeat you about this topic. Probably now not worthy nonetheless my conception for this publish was as quickly as impressed by a precise case situation I had utilized in my mission. I will originate with occasions transferring into/out with Websockets which may maybe maybe be then propagated to Akka actors. Throughout the subsequent publish I will add RabbitMQ to boost a number of pods/circumstances of the app.

Photograph by Joey Kyber on Unsplash


In a mission I’m working in we needed to be succesful so as to add enhance to permit prospects ogle a folder for changes (we constructed a digital file machine over the give up of Dgraph). These changes then need to be propagated to the purchasers whoever did the alternate — however one different particular person, a background working route of, and so forth. So, particular person subscribes to a folder and can get notified by websocket, then we are able to re-win the folder’s recordsdata once more if main. You may maybe spy the similar mechanism when working with Github Pull Requests, the put that you’d be ready to even need to click on a Refresh button to reload modified recordsdata.

AkkaHttp vs Websockets

AkkaHttp supplies a enhance for server-side Websockets and it makes train of AkkaStreams with AkkaActors to originate the job — a mix of all the utterly completely different applied sciences. However, originate now not agonize of the pot I will voice you uncover how one can tie each of the items to position in power the event bus.

Let’s originate with defining a websocket endpoint using AkkaHttp:

trait WebsocketEventsRoute {

def machine: ActorSystem

closing def websocketEventsRoute: Route = {

course("occasions") {

val jog = ClientHandlerFlow.websocketFlow()





You needs to take heed to uncover how one can win an endpoint in AkkaHttp, so let’s maintain Websockets. First, we would like an AkkaStream Waft which is ready to be historical to accommodate incoming messages and sending encourage responses/occasions — they’re going to even be propagated from the app’s internals, it doesn’t need to be a response to the incoming websocket message.

The Waft need to be handed to a directive handleWebSocketMessages() from AkkaHttp and we’re prepared to affix using websockets.

The jog

Now I grasp to position in power the ClientHandlerFlow#websocketFlow() function and put together the jog historical within the websocket dialog. All websocket messages are handed by design of this jog which is backed by an actor — each websocket connection will win a devoted proxy actor to accommodate the connection. Person can open a number of connections and every will train a devoted proxy actor and every may maybe even be closed individually:

def websocketFlow(): Waft[Message, Message, NotUsed] = {

val handler = machine.actorOf(ClientHandlerActor.props(eventBus))

val incomingMessages: Sink[Message, NotUsed] =


.accumulate {

case TextMessage.Strict(textual content) =>


s"Reworking incoming msg [$text] into area msg"


WebsocketMsg.Incoming(textual content)


.to(Sink.actorRef[WebsocketMsg.Incoming](handler, Terminated))

val outgoingMessages: Supply[Message, NotUsed] =



.mapMaterializedValue { userActor =>

handler ! WebsocketMsg.Linked(userActor)



.accumulate {

case outMsg: WebsocketMsg.Outgoing =>


s"Reworking area msg [$outMsg] to websocket msg"


TextMessage(outMsg.textual content)

Waft.fromSinkAndSourceCoupled(incomingMessages, outgoingMessages)


First, I grasp to win a handler which is an Akka Actor and this can seemingly be historical to accommodate incoming messages and sending encourage occasions. I will moreover train this handler to accommodate area messages — that you’d be ready to even train one different actor to accommodate the alternate logic nonetheless that’s dependent to your needs.

Now, I’ll win a Sink for incomingMessages which collects your entire Websocket TextMessages and transforms them into an intermediate comprise — WebsocketMsg.Incoming(String) which then may maybe even be historical to win a factual area object. Usually I didn’t would actually like to check on String exact now in my handler.

Subsequent, I created a Supply to accommodate outgoingMessages which has two obligations:

  • first voice the handler a pair of brand name distinctive connection by handler ! WebsocketMsg.Linked(ActorRef) — that is main to well register this dialog channel with the Event bus
  • after which by gathering intermediate outgoing messages and remodeling them into Websocket TextMessages. Please endure in thoughts that Supply.actorRef creates a proxy actor historical to accommodate websocket dialog. This actor receives the incoming uncooked websocket messages and transfers them to the handler using the jog.

I think the jog is unassuming:

One line on this choice requires additional clarification:

.to(Sink.actorRef[WebsocketMsg.Incoming](handler, Terminated))

the Terminated message will seemingly be despatched to the handler as quickly because the connection is closed, I will train it to unregister the channel from the Event bus.

The handler

Now’s time to position in power my handler which is ready to be responsible for receiving messages and sending them out. The handler is utilized as an Akka actor:

private class ClientActor extends Actor {

override def obtain: Acquire = {



}object ClientActor {

def props: Props = Props(distinctive ClientActor)


Nothing out of the peculiar if how Conventional Akka Actors are working, essentially we should elaborate a obtain design to accommodate utterly completely different messages. In my case I’m going to accommodate two types of messages:

  • WebsocketMsg — wrapper spherical uncooked TextMessage websocket class
  • Enviornment — area explicit occasions


It’s time to accommodate incoming websocket message and outgoing one. To dwell this logic I will introduce an intermediate structure, that I’ve been already using within the above Waft definition:

private sealed trait WebsocketMsg

private object WebsocketMsg {

case class Linked(userActor: ActorRef) extends WebsocketMsg

case class Incoming(textual content: String) extends WebsocketMsg

case class Outgoing(textual content: String) extends WebsocketMsg

// a helper design as quickly as you occur to would actually wish to translate your outgoing

// messages into JSON using Circe

def outgoing[T: Encoder](recordsdata: T): Outgoing = {




Having this prepared, I’ll lengthen the handler to well maintain in&out:

override def obtain: Acquire = onMessage(Internet vow.empty)

private def onMessage(userActors: Internet vow[ActorRef]): Acquire = {

case WebsocketMsg.Linked(userActor) =>


context.become(onMessage(userActors + userActor))

case Terminated(userActor) =>

val openUserActors = userActors - userActor

if (openUserActors.isEmpty) {

self ! PoisonPill

} else {



case WebsocketMsg.Incoming(textual content) =>

// an occasion uncover how one can make train of Circe to remodel incoming message

// exact right into a web web page object

parse(textual content) match {

case Left(error) =>

self ! Enviornment.Error(s"Can't parse $textual content as JSON")

case Factual(designate) =>[Domain] match {

case Left(error) =>

self ! Enviornment.Error(s"Can't parse $designate as Enviornment")

case Factual(event) =>

self ! event



case outgoing: WebsocketMsg.Outgoing =>

userActors.foreach(_ ! outgoing)

case ...: Enviornment =>

// originate the alternate logic

This seems to be like like subtle nonetheless to be applicable selection is very straightforward as quickly as you understood the jog.

First, I lastly grasp historical Turn out to be/Unbecome capability to assist a methods from defending enlighten within the actor. Instruct, which comprises open particular person websocket channels, is handed to the handler each time it has modified. And the enlighten can alternate in two circumstances:

  • particular person opened a websocket connection — thus is represented by WebsocketMsg.Linked,
  • and when particular person closed the connection (or it was as quickly as triggered by a community failure, and so forth.), thus is represented by Terminated. You may maybe spy that I lastly grasp historical the similar messages after I used to be as quickly as defining the jog.

So now, as quickly as an individual opened a model distinctive connection the handler will obtain a message with a reference to the proxy actor created by AkkaHttp to accommodate the connection. Now I grasp to behold this actor to win notified as quickly as this can seemingly be terminated by using context.ogle() and I’m together with it to the enlighten as a downstream channel for sending messages encourage to the particular person.

When the handler receives Terminated(ActorRef) it removes that channel from the enlighten to assist a methods from sending messages to the closed connection. Additionally if this was as quickly because the closing open channel for that particular person, I moreover assassinate the handler to assist reminiscence smartly-kept and assist a methods from leaks — self ! PoisonPill.

What’s left is the half to accommodate in/out messages, that is occurring with two messages moreover outlined within the jog: WebsocketMsg.Incoming and .Outgoing.

I added an occasion uncover how one can swap an incoming textual content exact right into a Enviornment object using Circe — that you’d be ready to even train a JSON library of your need. Please spy that I’m checking if the message is a factual JSON and subsequent if the JSON is a factual growth to process it to the Enviornment object. If one thing is mistaken I’m sending encourage an error using Enviornment.Error. There may maybe be not anycase for such message nonetheless it completely may even peaceful locate maintain this:

case error: Enviornment.Error =>

self ! WebsocketMsg.outgoing(error)

I’m transforming the area object exact right into a websocket message and ship it out.

The bus

The entire above logic is comely until that you’d be ready to even grasp one particular person and also you need merely keep in touch with that one particular person at a given time. Nonetheless what to originate as quickly as you occur to may even grasp a number of prospects and that you’d be ready to love to voice all of them about some changes within the app?

The retort is — train the Occasion bus!

Conventional AkkaActors supplies a terribly smartly-kept enhance for imposing your occupy event bus. All that you’d be ready to even need to originate is to position in power one or maybe two traits. Additionally that you’d be ready to love to understand your area model to be dealt with by the event bus. Peep the occasion beneath:

class DomainEventBus extends EventBus with LookupClassification {

override selection Event = Enviornment

override selection Classifier = String

override selection Subscriber = ActorRef

override protected def mapSize(): Int = 100 // train a factual tag

override protected def compareSubscribers(

a: ActorRef, b: ActorRef

): Int = a.compareTo(b)

override protected def classify(evt: Enviornment): Topic = evt.topic

override protected def publish(

evt: Enviornment, subscriber: ActorRef

): Unit = {

subscriber ! evt



As that you’d be ready to even spy there’s nothing subtle on this code. It is important to elaborate a pair of varieties which may maybe maybe be barely self-explanatory plus add a barely straightforward logic.

Now, to make train of the event bus I grasp to cross it to the handler which is ready to be carried out by extending how the actor is constructed:

class ClientHandlerActor(eventbus: DomainEventBus) extends Actor {

override def obtain: Acquire = ...

}object ClientHandlerActor {

def props(eventbus: DomainEventBus): Props = {

Props(distinctive ClientActor(eventbus)



And closing step in using the event bus is to subscribe actors, in my case handlers, to be notified about occasions for a given Topic. As talked about within the background, I needed to constructed a machine to video show changes in a digital file machine and as quickly as there was as quickly as a alternate propagate it to the all subscribers of the folder.

To dwell that I got here up with the following area model:

sealed trait EventType

object EventType extends Enum[EventType] with CirceEnum[EventType] {

val values: sequence.immutable.IndexedSeq[EventType] =


case object FolderSubscribe extends EventType

case object FolderUnsubscribe extends EventType

case object FolderUpdated extends EventType

case object Error extends EventType


sealed trait Enviornment {

def topic: String

def eventType: EventType


object Enviornment {

case class FolderSubscribe(folderId: UUID) extends AssetEvent {

override val topic: String = IgnoreTopic

override val eventType: EventType = EventType.FolderSubscribe


case class FolderUnsubscribe(folderId: UUID) extends AssetEvent {

override val topic: String = IgnoreTopic

override val eventType: EventType = EventType.FolderUnsubscribe


case class FolderUpdated(folderId: UUID) extends AssetEvent {

override val topic: String = s"folder-$folderId"

override val eventType: EventType = EventType.FolderUpdated


case class Error(userId: String, message: String)

extends AssetEvent {

override val topic: String = s"person-$userId"

override val eventType: EventType = EventType.Error



First I lastly grasp historical Enumeratum library to elaborate a pair of enums (I don’t maintain enum in Scala — they’re essentially damaged) representing utterly completely different types of occasions.

Subsequent, I utilized my area with message to permit particular person subscribe a folder or unsubscribe from wanting on the folder. Additionally I added just a little class to yelp errors encourage to the given particular person. Please spy how utterly completely different points have been outlined for each of those messages as that is the clue how occasions are routed by the event bus to utterly completely different handlers.

At closing I’ll lengthen the handler to boost sub/unsub and errors:

case event: Enviornment.FolderSubscribe =>

if (!eventbus.subscribe(self, event.topic) {

log.error(s"Can't subscribe $self to topic ${event.topic}")


case event: Doamin.FolderUnsubscribe =>

if (!eventbus.unsubscribe(self, event.topic) {

log.error(s"Can't unsubscribe $self from topic ${event.topic}")


case event: Enviornment =>


I think there’s nothing to voice, if the incoming message was as quickly as FolderSubscribe I will subscribe the handler — self to obtain occasions linked to the topic represented by this message. And reverse, as quickly as FolderUnsubscribe was as quickly as received I will unsubscribe handler from occasions linked to that folder.

And on the finish I’m going by design of any utterly completely different occasions and publishing them exact now to the event bus. On this case Error and FolderUpdated which is ready to be propagated both to the given particular person (on epic of of topic s”person-$userId"), or to all prospects wanting on the folder (on epic of of topic s"folder-$folderId").

Last be aware

Implementing a websocket dialog and propagating occasions using an event bus isn’t that tough. It essentially is a cumbersome route of on the beginning put, nonetheless as quickly as you win aware of the jog this can seemingly be very straightforward.

There may maybe be one disadvantage with this implies: it actually works completely comely as quickly as you occur to are working a one event of your app. Throughout the event you originate scaling your app to a pair of circumstances (eg.: using Kubernetes and scaling onto a number of pods) your occasions win misplaced, on epic of particular person can open a websocket connection to a one event nonetheless occasions are taking place on the utterly completely different one. There may maybe be not any connection between them.

To bridge the hole within the subsequent publish I will introduce RabbitMQ to resolve that mission, assist tied!


Please enter your comment!
Please enter your name here