play2-sockjs is a SockJS server implementation for Play Framework that aims to provide an api as similar as possible to the WebSocket one provided by Play:

// Play WebSocket api:
def websocket = WebSocket.using[String](handler)

// play2-sockjs api:
def sockjs = SockJS.using[String](handler)

// same request handler
val handler = { (request: RequestHeader) =>
  // Log events to the console
  val in = Iteratee.foreach[String](println).map { _ =>
    println("Disconnected")
  }
  // Send a single 'Hello!' message and close
  val out = Enumerator("Hello!") >>> Enumerator.eof
  (in, out)
}

It provides both Scala and Java API. All transports offered by SockJS have been implemented according to the 0.3.3 protocol specifications.

Jump to: Installing - API reference

What is SockJS?

SockJS is a browser JavaScript library that provides a WebSocket-like object. SockJS gives you a coherent, cross-browser, Javascript API which creates a low latency, full duplex, cross-domain communication channel between the browser and the web server.

Under the hood SockJS tries to use native WebSockets first. If that fails it can use a variety of browser-specific transport protocols and presents them through WebSocket-like abstractions.

SockJS is intended to work for all modern browsers and in environments which don't support WebSocket protocol, for example behind restrictive corporate proxies.

Installing

Add play2-sockjs dependency to your build.sbt or project/Build.scala:

libraryDependencies += "com.github.fdimuccio" %% "play2-sockjs" % "0.5.0"

You may also need to add the Sonatype Repository as a resolver:

resolvers += Resolver.sonatypeRepo("releases")

or if using snapshot version:

resolvers += Resolver.sonatypeRepo("snapshots")

API reference

• Play 2.1.x : 0.1.6
• Play 2.2.x : 0.2.6
• Play 2.3.x : 0.3.6
• Play 2.4.x : 0.4.6
• Play 2.5.x : 0.5.3

Load balancing and sticky sessions

If your Play application is deployed in a load balanced environment you must make sure that all requests for a single session must reach the same server.

SockJS has two mechanisms that can be useful to achieve that:

* Urls are prefixed with server and session id numbers, like:
  /resource/<server_number>/<session_id>/transport. This is useful for load
  balancers that support prefix-based affinity (HAProxy does).

* JESSIONID cookie: it's possible to enable cookie writing for load balancers that
  support sticky sessions. In order to enable this feature please supply
  CookieFunctions.jessionid when configuring SockJS, it's disabled
  by default. It's also possible to implement custom functions if needed.

Samples

In the samples/ folder there are two sample applications:

• sockjs-protocol-test: server for SockJS 0.3.3 protocol specifications tests
• sockjs-chat: a port of the Play sample websocket-chat to SockJS