Skip navigation

WebSockets in Netty

by trustin
on

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.

WebSocket is part of the W3C drive towards HTML 5.

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, browsers 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-15, 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 specified 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).

Netty WebSocket Support

Netty 3.2.6 supports Hixie-75 and 76 but NOT Hybi-10. Refer to the org.jboss.netty.handler.codec.http.websocket package and associated examples.

Netty 4.0 (unreleased) will support both Hixie-75 and 76 AND Hybi-10. The code is now in the Netty master branch (see pull request #26).

Points about this implementation:

  1. The existing org.jboss.netty.handler.codec.http.websocket package remains unchanged. There are quite a few frameworks using this package so we will just leave well enough alone.
  2. The new code for web socket support has been placed in the org.jboss.netty.handler.codec.http.websocketx package. The “x” is intended to represent multiple versions.
  3. The websocketx package supports both WebSocket versions (“Hixie-75/76/Hybi-00” and “Hybi-10”)
  4. The websocketx supports both client and server.
  5. Examples - refer to package-info.java in each package for instructions.
    • org.jboss.netty.example.http.websocketx.autobahn - echo server used for running AutoBahn tests
    • org.jboss.netty.example.http.websocketx.client - web socket client implementation
    • org.jboss.netty.example.http.websocketx.server - web socket server implementation that echo the text you send it in upper case
    • org.jboss.netty.example.http.websocketx.sslserver - example of how to use SSL with the web socket server
  6. 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.
  7. Encoders and Decoders
    • Hixie-75/76/Hybi-00 is implemented as WebSocket00FrameDecoder and WebSocket00FrameEncoder.
    • 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.
  8. 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.
  9. 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 parameter.
    • See org.jboss.netty.example.http.websocketx.client.App for an example.
  10. This implementation has passed the AutoBahn Server Tests V 0.4.2 

Thank You

This implementation uses code from Webbit (for which Aslak Hellesøy has written hybi-10 support) and from cgbystrom (for web socket clients).

Next

It is my understanding that Chrome 16 will support Hybi-17. I’ll be looking to add Netty support for this web socket version shortly.