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.

```http
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
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 ...                |
+---------------------------------------------------------------+
```