Hookup by BackChat.io

Reliable messaging over websockets

Reliable messaging on top of websockets.

A scala based client and server for websockets based on netty and akka futures. It draws its inspiration from finagle, faye-websocket, zeromq, akka, ...

The aim of this project is to provide a websocket client in multiple languages an to be used in non-browser applications. This client should be reliable by making a best effort not to lose any messages and gracefully recover from disconnections.

The server should serve regular websocket applications but can be configured for more reliability too.


To reach said goals this library implements:

Protocol features:

These features are baked into the default JsonProtocolWireFormat or in the WebSocket spec.

Message Acking:

You can decide if you want to ack a message on a per message basis.

client ! "the message".needsAck(within = 5 seconds)


This is baked into the websocket protocol, the library ensures it really happens

Client only features:

There are a number of extras baked into the client, of course they can be enabled and disabled based on config.


The client reconnects to the server on a backoff schedule indefinitely or for a maximum amount of times

Message buffering

During phases of disconnection it will buffer the messages to a file so that upon reconnection the messages will all be sent to the server.


This library is available on maven central.

libraryDependencies += "io.backchat.hookup" %% "hookup" % "0.2.2"

Create a websocket server

import io.backchat.hookup._

(HookupServer(8125) {
  new HookupServerClient {
    def receive = {
      case TextMessage(text) =>

Create a websocket client

import io.backchat.hookup._

new DefaultHookupClient(HookupClientConfig(new URI("ws://localhost:8080/thesocket"))) {

  def receive = {
    case Disconnected(_)  
      println("The websocket to " + uri.toASCIIString + " disconnected.")
    case TextMessage(message)  {
      println("RECV: " + message)
      send("ECHO: " + message)

  connect() onSuccess {
    case Success 
      println("The websocket is connected to:"+this.uri.toASCIIString+".")
      system.scheduler.schedule(0 seconds, 1 second) {
        send("message " + messageCounter.incrementAndGet().toString)
    case _ 

There are code examples that show all the events being raised and a chat server/client.


Patches are gladly accepted from their original author. Along with any patches, please state that the patch is your original work and that you license the work to the backchat-websocket project under the MIT License.


MIT licensed. check the LICENSE file