There’s a perfectly good example of a simple chat room server using the Play Framework, WebSockets, and Actors. But other than the example code and one page in the tutorial, using WebSockets with Actors isn’t terribly well-documented. So I thought I’d walk through an even simpler example that makes use of WebSockets and Actors, and explain what’s going on in more detail.
This echo server accepts a WebSocket connection then runs indefinitely until the client closes the connection. Each WebSocket message received is echoed back to the client:
def simpleIterateeWebSocket = WebSocket.using[String] {
val out = Enumerator.imperative[String]()
val in = Iteratee.foreach[String] {
msg =>
out.push(msg)
}
(in, out)
}
You can try out all the code in this tutorial by cloning the github repo. Use the echo test at websocket.org and point it to ws://localhost:9000/wsSimple
. Each example in this tutorial has its own URL that you can see in the routes file.
Iteratees
What’s going on here? First off, it’s important to understand Play iteratees. I won’t go into iteratees in great detail here other than to say that they’re a deeply interesting functional programming technique, and an incredibly useful one as well. There are already a few useful guides to them that I encourage you to read.
WebSocket.using
takes a block returning an (in, out)
pair. in
as an Iteratee
that will handle incoming messages — the framework will deliver WebSocket messages from the client to this iteratee. And out
is an Enumerator
that acts as an outbound channel. out
can be used to send messages back to the client.
The easiest way to understand Iteratee.foreach
is that it’s like an “onMessage” event handler. Iteratees are more powerful and general than event handlers. Iteratee.foreach
creates a specialized iteratee that invokes the block on each message received. In this sense, in
isn’t really the input stream so much as the handler on that input stream.
The out val is the Enumerator
that will be used to send messages back to the client. An ordinary enumerator would be crafted by chaining messages together using various basic enumerators and combinators. After the enumerator is returned by simpleIterateeWebSocket
, the framework connects the enumerator to the client and the messages on it are consumed. The framework uses its own iteratee, in fact, to consume the messages and write them to the client.
Enumerator.imperative()
creates a specialized enumerator called a PushEnumerator
. This enumerator allows you to write messages through the enumerator by calling PushEnumerator.push(msg)
. Writing the message “wakes up” the iteratee on the other side of the enumerator and invokes its message handler. As I said, this iteratee is given by the framework and writes each message out to the client. This iteratee remains alive until you send a special close message. In our example, the server will never close the connection.
Note that you can’t invoke out.push("hello world")
immediately after instantiating the enumerator. That’s because the enumerator hasn’t been connected to the client yet. push
must be invoked after simpleIterateeWebSocket
has returned and the framework has connected the enumerator to its own iteratee. In our example, push
isn’t invoked until a message is received from the client.
Asynchrony Teaser
I’ve gone into a lot of detail and we haven’t even talked about Actors yet! Before I conclude Part I, let me show you an asynchronous version of this code (that still doesn’t use actors :-):
import play.api.libs.concurrent.Akka
import play.api.Play.current // needed by Akka.future
def simpleAsyncWebSocket = WebSocket.async[String] {
Akka.future {
val out = Enumerator.imperative[String]()
val in = Iteratee.foreach[String] {
msg =>
out.push(msg)
}
(in, out)
}
}
The code turns out to be identical to the ordinary version except we use WebSocket.async
instead of WebSocket.using
. And we wrap the block in an Akka.future
. Akka.future
simply runs the block in a separate thread. It returns a Promise[T]
where T is the return type of the block. WebSocket.async
indicates a WebSocket handler just like WebSocket.using
except that it takes a block with a result of type Promise[(Iteratee, Enumerator)]
instead of simply (Iteratee, Enumerator)
. This code acts the same as the first code, except that the function runs asynchronously and returns immediately. This is trivial for now, but it sets us up for Part II when we introduce actors into the mix.