diff --git a/draft.md b/draft.md new file mode 100644 index 0000000..dff0ec5 --- /dev/null +++ b/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 \ No newline at end of file