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