ws/draft.md

This document describes the expected usage of the library. It mixes go code and prose to expose what is intended. Also it features expected behavior and some library rules and websocket standards (e.g. RFC).

Warning

This document is not a documentation, it is used by developers to try to find the best interface for an eased usage by other developers using this library.

Handshake

1. Client HTTP Upgrade Request

This request is sent by clients which want to open a new websocket connection.

GET {uri} HTTP/{httpClientVersion}
Host: {host}
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: {clientKey}
Origin: {origin}
Sec-WebSocket-Protocol: {clientProtocols[]}
Sec-WebSocket-Extensions: {clientExtensions[]}
Sec-WebSocket-Version: {wsVersion}

Required fields

• httpClientVersion at least 1.1
• host ...
• Upgrade: websocket header (not case sensitive)
• Connection: Upgrade header (not case sensitive)
• Origin for security issues only when from browser (to study)
• clientKey because it is not consistent websocket without it. It must be a 16-byte value base64 encoded
• wsVersion is required to be 13

Optional fields

• clientProtocols[] if not received is an empty list
• clientExtensions[] if not received is an empty list

2. Server HTTP Response

HTTP/{httpServerVersion} {errorCode} Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: {serverKey}
Sec-WebSocket-Protocol: {serverProtocol}

Required fields

• Upgrade: websocket header because RFC
• Connection: Upgrade header because RFC
• errorCode is 101 on success, other on failure
  • 400 Bad Request on missing or malformed headers
  • 403 Forbidde on invalid Origin or https/wss required, ...
  • 426 Upgrade Required on invalid wsVersion
  • 404 Not Found on unserved or invalid uri
  • 1002 Protocol Error if received a non-masked frame
• serverKey but can be invalid if server don't want to accept the connection

Optional fields

• serverProtocol if the server has chosen one

Clients management

• It is required that for a same host and port pair, a client can only have one connection in a CONNECTING state. It means that one client can open a 2nd connection only when the 1st succeeded or failed.

Frames

• RFC requires the server to close all connections which sends a non-masked frame

 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-------+-+-------------+-------------------------------+
|F|R|R|R| opcode|M| Payload len |    Extended payload length    |
|I|S|S|S|  (4)  |A|     (7)     |             (16/64)           |
|N|V|V|V|       |S|             |   (if payload len==126/127)   |
| |1|2|3|       |K|             |                               |
+-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - +
|     Extended payload length continued, if payload len == 127  |
+ - - - - - - - - - - - - - - - +-------------------------------+
|                               |Masking-key, if MASK set to 1  |
+-------------------------------+-------------------------------+
| Masking-key (continued)       |          Payload Data         |
+-------------------------------- - - - - - - - - - - - - - - - +
:                     Payload Data continued ...                :
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
|                     Payload Data continued ...                |
+---------------------------------------------------------------+