What are WebSockets?

From wikipedia:

WebSockets is a technology providing for bi-directional, full-duplex
communications channels, over a single TCP socket

The WebSocket protocol provides a persistent low latency, low complexity way to achieve two way communication from the browser to server.

From a client point of view using WebSocket is very simple:

var ws = new WebSocket('ws://somehost/some/url');
ws.onopen = function(msg){
    //do some cool setup
}
ws.onmessage = function(msg){
    //do something cool
}
ws.onclose = function(msg){
    //do some clean up... stay cool
}

// later:
ws.send('How cool am I?!');

That’s pretty much all there is to it.

How do they work?

The socket connection that WebSocket uses is negotiated with an HTTP request/response between the client and the server

On the server side things are slightly more complex. The server must:

• Perform a handshake with the client
• Keep hold of the persistent connection
• Receive messages from the client
• Route messages to the client

The following refers to the hybi version 10 websocket spec [hybi10]

Handshake

From the browser:

GET /ws HTTP/1.1
Host: pmx
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Version: 6
Sec-WebSocket-Origin: http://pmx
Sec-WebSocket-Extensions: deflate-stream
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==

The server sends back:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=

Note

There are also mechanisms for sub-protocols and extension. These haven’t been implemented yet

See the [WebSockets] Wikipedia page for more details.

The part of the protocol that deals with framing is much more extensive than the older versions. Framing is handled by the ws4py library.

Older Versions

Note

The following is included for historical reasons only - as I understand it these have been disabled by default for security reasons in most browsers.

Handshake

The handshake version of the WebSocket protocol underwent a major revision at version 76 [ws76]. As of version 0.2, Stargate supports both this and the older [ws75]. Examples of both are below:

Version 76

From the browser:

GET /demo HTTP/1.1
Host: example.com
Connection: Upgrade
Sec-WebSocket-Key2: 12998 5 Y3 1  .P00
Sec-WebSocket-Protocol: sample
Upgrade: WebSocket
Sec-WebSocket-Key1: 4 @1  46546xW%0l 1 5
Origin: http://example.com

^n:ds[4U

The server would send back:

HTTP/1.1 101 WebSocket Protocol Handshake
Upgrade: WebSocket
Connection: Upgrade
Sec-WebSocket-Origin: http://example.com
Sec-WebSocket-Location: ws://example.com/demo
Sec-WebSocket-Protocol: sample

8jKS'y:G*Co,Wxa-

Version 75 and older

Client:

GET /demo HTTP/1.1
Host: example.com
Connection: Upgrade
Upgrade: WebSocket
Origin: http://example.com

Server:

HTTP/1.1 101 WebSocket Protocol Handshake
Upgrade: WebSocket
Connection: Upgrade
WebSocket-Origin: http://example.com
WebSocket-Location: ws://example.com/demo

The implementation of the handshake can be found in stargate.handshake

Connection

Once the handshake has been successfully negotiated there is a persistent bi-directional websocket connection from the client to the server. This is a pretty thin wrapper around a socket that sends text messages packed in the \x00 and \xFF bytes.

[WebSockets]

http://en.wikipedia.org/wiki/Web_Sockets

[hybi10]

http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10

[ws76]

http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76

[ws75]

http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-75