WebSocket for Beginners

WebSocket is a web technology providing a full-duplex communication channel over a single TCP connection. The communication is initiated by using a standard HTTP request which is then morphed into a persistent full-duplex link. This link is similar to a standard TCP connection except that WebSocket is frame based, i.e. packet oriented. Since WebSocket is initially starting out as a HTTP or HTTPS request, WebSocket can be made to bypass proxies and firewalls. WebSocket is also secure if the communication is initiated over HTTPS.

A WebSocket connection can solve many of the problems associated with standard Ajax. See our Ajax tutorial and the limitations in Ajax for more information.

WebSocket is available via the EventHandler in the Mako Server. The EventHandler is a component in the Barracuda Application Server Library and the Barracuda Application Server Library is in turn an integral component of the Mako Server. The EventHandler also supports techniques such as pushlet, long polling, and multipart/x-mixed-replace. The WebSocket API is new and currently not available in all browsers. The EventHandler will automatically downgrade and use one of the other technologies if WebSocket is not supported by the browser. This is completely transparent to you as a developer.

The EventHandler is loosely based on the publisher subscriber design pattern. The subscriber is an EventHandler client running in a browser. The client side of the EventHandler is implemented in JavaScript and does not require any plugins.

The server side of the EventHandler is installed into the Mako Server’s Virtual File System. You can insert any number of server side EventHandler instances in the Virtual File System.

Each client gets a unique Connection ID (CID) and the server can send messages to one client using the CID. Sending a message without using the CID sends a message to all connected clients. Sending messages to one client is in EventHandler terminology called a unicast message. Sending to all clients is called a multicast message.
eh-connect-disconnect  The server side EventHandler is an object that is created by calling function ba.create.eh(). Your server side Lua script registers a number of callbacks with this object such as connect and disconnect event functions.

The connect callback is triggered when new subscriber connects and the disconnect callback is called when the subscriber disconnects by explicitly closing the connection or if the user closes the browser window.

The EventHandler publisher subscriber model is based on providing a public interface to the peer side. An interface is similar to an object in an object oriented language. Each EventHandler instance can have one or several interfaces and each interface can have one or several methods.

In the following example, the server side Lua script provides the sCtrl (short for Sound Controller) API to the client. The client JavaScript code calls the seek method on this API to seek in the current song on the server. The client provides the sGui (short for Sound GUI) API to the server. This API includes the vuMeter method that enables the server side Lua code to set the VU Meter in the client. Calling a method in the EventHandler is asynchronous and no value is returned when calling an interface method such as the sGui.vuMeter() in the example below.


Example showing a fictitious mp3 player, where the sound engine is in the server and the GUI is in the browser.

The above was a quick introduction to the EventHandler and how you can build web applications that keep a persistent connection with the server. The Do It Yourself Tutorial includes a complete EventHandler example and shows you how to create a basic real time chat client. You will find the EventHandler tutorial under the Virtual File System section in the Do It Yourself Tutorial.

Download the Do It Yourself Tutorial.

Posted in Tutorials by bd