56 lines
No EOL
3.1 KiB
Markdown
56 lines
No EOL
3.1 KiB
Markdown
This file documents the websocket /api/ws
|
|
|
|
## Message format
|
|
Always 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 | |