88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
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 ... |
|
|
+---------------------------------------------------------------+
|
|
``` |