[draft] create

draft.md

@@ -0,0 +1,69 @@
+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