69 lines
2.4 KiB
Markdown
69 lines
2.4 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 |