Move.Me Writing Your Own WebSocket Server

The WebSocket protocol has applications beyond plain vanilla web development.  I will explain how the protocol works, how to implement your own server and share some insights I had along the way. Before we get down and dirty, I will explain what I’ve been doing with it.

At this point I expect many of you are saying “I’m not working on a web game this doesn’t seem relevant to me.” Well, neither am I. I embed a WebSocket server into my game engine and with a local web application use the WebSocket protocol as a medium to control, configure and monitor my game engine. Some concrete examples of what I’ve done so far:

• Monitor memory allocation statistics
• Monitor performance of subsystems
• Set and query configuration variables
• Live edit the world
• Loaded asset preview

Soon, I will attempt to stream the display of the game to the web browser and stream mouse,  as well as the keyboard data back to the game. In other words, remote desktop for the game engine. Another use case I would like to investigate is writing unit tests for the engine in javascript and drive it from the web browser. The possibilities are endless.

Another benefit of this approach is that your development UI is platform independent. This is nice when you are developing a title against many architectures. For example, consoles where the target does not usually have keyboard or mouse input are harder to interact with- by moving your UI to the web browser this problem is avoided.

Hang in there, this article is about the plumbing. My next article will be about the above applications.

WebSocket is a communication protocol that allows for bi-directional text and binary message passing. The client is a Javascript application running inside a web browser and, typically, the server is a web server. I say ‘typically’ because that is not how I use it.

WebSocket was developed because sending data between the web server and web application over HTTP was inefficient. The WebSocket protocol is very bandwidth efficient (message framing is at most 14 bytes) and the payloads are custom to the application. A WebSocket connection begins life as a regular HTTP connection. The connection is upgraded from HTTP to WebSocket. This upgrade is one way- you can’t revert back to an HTTP connection. You can read more about WebSocket at WikiPedia and the complete specification is available. The WebSocket protocol was only recently finalized in December 2011.

Okay, let’s dive into how WebSocket works. I will cover creating a connection, sending and receiving messages, and responding to pings.

1
2
3
4
5
6

       GET /servicename HTTP/1.1
       Host: server.example.com
       Upgrade: websocket
       Connection: Upgrade
       Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
       Origin: http://example.com

1
2
3
4

       HTTP/1.1 101 Switching Protocols
       Upgrade: websocket
       Connection: Upgrade
       Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

1
2
3
4
5
6
7

  SpecifcationGUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
  FullWebSocketKey = concatenate(Sec-WebSocket-Key, SpecifcationGUID);
    // dGhlIHNhbXBsZSBub25jZQ==258EAFA5-E914-47DA-95CA-C5AB0DC85B11
  KeyHash = SHA-1(FullWebSocketKey);
    // 0xb3 0x7a 0x4f 0x2c 0xc0 0x62 0x4f 0x16 0x90 0xf6 0x46 0x06 0xcf 0x38 0x59 0x45 0xb2 0xbe 0xc4 0xea
  Sec-Websocket-Accept = base64(KeyHash);
    // s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

Transmission

WebSocket is a message based protocol. Each message begins with a header defining the length of the message, the type (text, binary or control) and other meta-data. The payload immediately follows the header. All incoming messages will include a 32-bit mask which must be applied to the entire payload with a XOR operation. Each message will have a different mask. The masking is used to guard against simple snooping.

The header begins with a 16-bit mask (blue) and up to 12-bytes of optional header (orange).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

struct WebSocketMessageHeader {
  union {
    struct {
      unsigned int OP_CODE : 4;
      unsigned int RSV1 : 1;
      unsigned int RSV2 : 1;
      unsigned int RSV3 : 1;
      unsigned int FIN : 1;
      unsigned int PAYLOAD : 7;
      unsigned int MASK : 1;
    } bits;
    uint16_t short_header;
  };
 
  size_t GetMessageLength() const;
  size_t GetPayloadOffset() const;
  size_t GetPayloadLength() const;
  uint32_t GetMask() const;
  uint8_t GetOpCode() const;
  bool IsFinal() const;
  bool IsMasked() const;
  // …
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class WebSocketServer {
public:
  WebSocketServer();
  int AcceptConnection(TcpListener* listener);
  int CloseConnection();
  void Update();
 
  int SendTextMessage(const char* msg);
  int SendTextMessage(const char* msg, size_t msg_length);
 
  uint64_t PendingMessageCount() const;
  void ProcessMessages(OnMessageDelegate del, void* userdata);
  void ClearMessages();
};