rwws/PROTOCOL.md

This file documents the websocket /api/ws

## Message format
lways bytes! \
Packet id followed by arguments \
Some packets don't have arguments so send just the packet id \
There can be multiple packets in one message, those with unknown amount of arguments have to be terminated \
All number types are signed

## Authentication
Unsurprisingly, tokens are used to authenticate.

The first message from the server is:
- `0x6d 0x73`

The client replies with a single message:
1. `0xb6 0xc4`
2. client version (byte), currently it's `0` and won't change until everything is complete
3. length of access key (byte)
4. token (bytes), decoded from base64

Authentication complete. \
If something's wrong the server disconnects, see below for reason codes. \
Otherwise the client receives a pong. \
No commands are handled during this time

# Commands
### Server bound (Client -> Server)
| Code   | Name     | Data                                                                   | Notes                                                                                                              |
|--------|----------|------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| `0x00` | Ping     |                                                                        | the server replies with pong<br/>must be sent by client every at most 30 seconds, otherwise the server disconnects |
| `0x01` | Settings | 1. byte: setting id<br/>2. value<br/>3. and so on (terminated by 0xFF) | see below for IDs, value type varies                                                                               |

### Client bound (Server -> Client)

| Code   | Name | Data                 | Notes                                                                |
|--------|------|----------------------|----------------------------------------------------------------------|
| `0x00` | Pong | 1. long: unix millis | A response to ping, also sent by server on successful authentication |

## Disconnect reasons
Alongside code, there's always a human-readable message which contains more specific information

| Code   | Name               | Notes                                           |
|--------|--------------------|-------------------------------------------------|
| `3000` | reserved           |                                                 |
| `3001` | unauthorized       | used during authentication phase                |
| `3002` | version mismatch   | incompatible client                             |
| `3003` | timeout            | client wasn't sending pings                     |
| `3004` | access key revoked | when the access key was revoked while connected |
| `3005` | server error       |                                                 |

## Settings
| Code   | Name       | Notes                                           |
|--------|------------|-------------------------------------------------|
| `0x00` | reserved   |                                                 |
| `0xFF` | terminator | not a setting, just used to terminate sequences |