WebSockets and Netty

What are WebSockets?

Current web browser communications protocol is limited to the HTTP request and response paradigm – i.e. the browser requests and the server responds.

What if we want to use a different communications paradigm?  For example, what if we want to perform 2 way communications where the server sends a request and the browser responds?  A common use case would be the server notifies the client that an event has occurred.

This is where WebSockets come into play. WebSocket is a technology providing for bi-directional, full-duplex communications channels, over a single Transmission Control Protocol (TCP) socket.

In addition, because WebSockets can co-exist with other HTTP traffic over port 80 and 443, firewalls will not have to be re-configured.

Version Confusion

WebSockets is an evolving standard.  Just have a look at the different implementations and the different versions each support.

There have been numerous version of the WebSocket standards under different names.  So far, browser have converged on 2 versions.

  • Hixie-76/HyBi-00
    • Safari 5+, Chrome 4-13 and Firefox 4 supports this standard.
    • There are two names for this version because the Hixie-76 documentation is used as input into the new HiBi IETF working group.
    • A flaw in this standard was discovered in the handshaking which requires exchange of binary data in the HTTP body.  This did not work across some proxy servers.
  • HyBi-10
    • Chrome  14, Firefox 7 and IE 10 Developer Preview supports this standard.
    • Handshaking is performed in HTTP request and response headers
    • Uses wire protocol version 8.  You will see “Sec-WebSocket-Version: 8″ in the HTTP header.

Hybi-00 and Hybi-10 both represents versions of the specification document.  The version of the wire protocol are actually 0 and 8 respectively.

Typically, the wire protocol (sequence of bits and bytes sent over the network) does not change between different versions of the specification document.  As such, the wire protocol version is set by the version of the specification document at which the change was made to the wire protocol.  So version 8 of the wire protocol was made in Hybi-08.

What changes are made between different versions of the specification document? Corrections of typos, clarification of concepts and adjustments in handshaking.

The latest version is Hybi-17 (with a wire protocol version of 13).  So far, no browsers have supported that version.

Netty WebSocket Support

I’m using Netty 3.2.5 in building Chililog (topic for another blog post).

Netty 3.2.5 supports Hixie-75 and 76 but NOT Hybi-10.

I’ve compiled together my own WebSocket package for Chililog to support both “Hixie-75/76/Hybi-00″ and “Hybi-10″.  This allows my Chililog server to support all of today’s major browsers (except for IE which does not support Web Sockets at all).

I’ve used the word “compiled” because I’ve extensively used code from Netty and Webbit (for which Aslak Hellesøy has written hybi-10 support).  I’ve also used code from cgbystrom to help build web socket clients.

I’ve submitted the work back to Netty as pull request #26.

Points of interest:

  1. I’ve not changed the existing org.jboss.netty.handler.codec.http.websocket package.  I’ve found quite a few frameworks using this package.  I think it would be best if the next version of Netty can be a “drop-in” replacement.
  2. I’ve put all my changes in org.jboss.netty.handler.codec.http.websocketx.  The “x” is intended to represent multiple versions.
  3. The websocketx package supports both WebSocket versions (“Hixie-75/76/Hybi-00″ and “Hybi-10″)  for both client and server.
  4. Frames
    • Data is sent between client and server in frames.
    • The old websocket package implements only the DefaultWebSocketFrame.  Text, binary and closing frames are encapsulated into this single class.
    • The new websocketx package implements frames as a different class: TextWebSocketFrame, BinaryWebSocketFrame, CloseWebSocketFrame, PingWebSocketFrame and PongWebSocketFrame.  I felt that this made the code easier to read and understand.
  5. Encoders and Decoders
    1. Hixie-75/76/Hybi-00 is implemented as WebSocket00FrameDecoder and WebSocket00FrameEncoder.
    2. Hybi-10 is implemented as WebSocket08FrameDecoder and WebSocket08FrameEncoder.  The version #8 is used because the wire protocol #8 is used in conjunction  with the specification document version #10.
  6. Server Handshake
    • Implements the handshaking protocol on the server side.
    • Hixie-75/76/Hybi-00 is implemented in WebSocketServerHandshaker00  
    • Hybi-10 is implemented in WebSocketServerHandshaker10  
    • WebSocketServerHandshakerFactory picks the correct handshaker to use based on the handshaking request sent by the client.
    • See org.jboss.netty.example.http.websocketx.server.WebSocketServer  for an example.
  7. Client Handshake
    • Implements the handshaking protocol on the client side.
    • Hixie-75/76/Hybi-00 is implemented in WebSocketClientHandshaker00
    • Hybi-10 is implemented in WebSocketClientHandshaker10  
    • WebSocketClientHandshakerFactory picks the correct handshaker to use based on the version of the specification passed in as a paramter.
    • See org.jboss.netty.example.http.websocketx.client.App  for an example.

Hope this helps anyone looking for Hybi-10 support in Netty.

27 Oct 2011 – Update

Pull #26 request has been merged into Netty.  This feature should be in upcoming Netty release 3.3.

20 Jan 2012 – Update

This has now been released in Netty 3.3. See blog post.

9 thoughts on “WebSockets and Netty

  1. Hey,

    thanks you for this nice article. Especially the section “Version Confusion” helped me.

    You wrote “browser have converged on 2 versions”. Do you know, if newer browsers with HyBi-10 support are still supporting the Hixie-76/HyBi-00? Or just the new HyBi-10? As I understand the coexistence of both is not possible.


    • Hi Dennis,

      I don’t believe a specific browser supports multiple versions of web sockets.

      However, because different browsers support different versions (e.g. Chrome 14 is HyBi-10, Safari is HyBi-00 at this moment in time), I think your server needs to support multiple versions of web sockets.


  2. Hey Veebs,

    am I correct that with your pull request #26 a server will be able to support Hixie-75, Hixie-76 AND Hybi-10 in coexistence? Finally on server side it doesn’t matter which WebSocket version the client is using? I mean, Netty is handling the correct version?

    I haven’t done anything with Netty until now. I just want to find out which Server to use ;) . Finally I’d like to be able to handle the three WebSocket versions on server side.

    Thanks for your quick response.


    • Hi,

      Yes. Pull request #26 will be able to support all 3 web socket versions on the server – so it does not matter which web socket version of the browser is using.

      You can try it yourself using the example code in the pull request.

      I’ve used the code myself in my open source project chililog.

      Here are some instructions on how you can try it out: http://blog.chililog.org/2011/10/24/remote-javascript-logging/

      I’ve got a sample TO DO app sending web socket javascript console.log back to the server. Try starting the TO DO app in Safari, Chrome or Firefox. The server handles all of them.


      • I just saw “Merge pull request #26 from veebs/master”. Congrat. I will try to install the latest version from github now. I’ll also try your examples. Thanks for the suggestion.


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>