forked from hippoz/brainlet
222 lines
No EOL
5.9 KiB
Markdown
222 lines
No EOL
5.9 KiB
Markdown
# Waffle API docs (currently not implemented)
|
|
|
|
*Again, this IS NOT YET IMPLEMENTED IN THE CURRENT BRAINLET RELEASE*
|
|
|
|
# Gateway
|
|
|
|
Waffle uses a WebSocket gateway to transmit various updates from the server to the client and vice-versa (new message, user disconnecting, connect to voice, etc.)
|
|
|
|
# Gateway Payload format
|
|
|
|
All payloads sent through the gateway are *string payloads*. They all start with a number represeting the "instruction", followed by a "@" character (to delimit the instruction number from the rest of the payload), after which comes the data for the specific instruction.
|
|
|
|
Example packet:
|
|
```json
|
|
23@this is my payload data
|
|
```
|
|
Note for the example above: The "this is my payload data" text should not be user controlled. If user controlled input is required, it must be sanitized and/or passed as a JSON field.
|
|
|
|
Packets can also have JSON as a payload:
|
|
```json
|
|
32@{"name":"Alice"}
|
|
```
|
|
|
|
## Instructions
|
|
|
|
The terms "channel" and "category" are used interchangeably.
|
|
|
|
## 0:HELLO
|
|
*Part of handshake, Server to client*
|
|
|
|
Sent by the server to the client as soon as possible after they connect to the gateway.
|
|
|
|
This payload can contain a JSON object with various information about the server. It should be relied on only when absolutely necessary.
|
|
|
|
Example:
|
|
```json
|
|
0@{}
|
|
```
|
|
|
|
## 1:YOO
|
|
*Part of handshake, Client to server*
|
|
|
|
Sent by the client as soon as possible after receiving the HELLO instruction.
|
|
|
|
|
|
JSON data format:
|
|
| Field | Description |
|
|
| - | - |
|
|
| token | The authentication token |
|
|
|
|
Example:
|
|
```json
|
|
1@{"token":"my totally real token"}
|
|
```
|
|
|
|
If the token is invalid, or the connection is otherwise rejected, the client should be disconnected as soon as possible, and no YOO\_ACK should be sent.
|
|
|
|
## 2:YOO\_ACK
|
|
*Part of handshake, Server to client*
|
|
|
|
Sent by the server as soon as possible after processing the YOO payload from the client.
|
|
|
|
JSON data format:
|
|
| Field | Description |
|
|
| - | - |
|
|
| user | A [message author object](#message-author-object) |
|
|
| session_id | A UUIDv4 |
|
|
| channels | An array of [channels](#channel-object) |
|
|
|
|
Example:
|
|
```json
|
|
2@{}
|
|
```
|
|
|
|
## 3:ACTION\_CREATE\_MESSAGE
|
|
*Auth required, Client to server*
|
|
|
|
Sent by the client when sending a message.
|
|
|
|
JSON data format:
|
|
| Field | Description |
|
|
| - | - |
|
|
| content | The text content of the message |
|
|
| channel | An object that contains "_id", the id of the channel to send the message to |
|
|
|
|
Example:
|
|
```json
|
|
3@{"content":"i hate you","channel":{"_id":"totally real channel id"}}
|
|
```
|
|
|
|
## 4:EVENT\_NEW\_MESSAGE
|
|
*Auth required, Server to client*
|
|
|
|
Sent by the server when a new message is created in a channel the client is subscribed to.
|
|
|
|
JSON data format:
|
|
[Message object](#message-object)
|
|
|
|
## 5:ACTION\_UPDATE\_STATUS
|
|
*Auth required, Client to server*
|
|
|
|
Sent by the client when updating status. Usually, this packet is sent as soon as possible after getting YOO\_ACK to indicate the client is online.
|
|
|
|
JSON data format:
|
|
| Field | Description |
|
|
| - | - |
|
|
| status | Can be 0(STATUS\_OFFLINE) or 1(STATUS\_ONLINE) |
|
|
| status_text | Custom status text, max 50 characters, min 1 non-whitespace character, trimmed |
|
|
|
|
Example:
|
|
```json
|
|
5@{"status":1,"status_text":"hello"}
|
|
```
|
|
|
|
## 6:EVENT\_CHANNEL\_MEMBERS
|
|
|
|
*Auth required, Server to client*
|
|
|
|
Sent by the server after YOO\_ACK, and otherwise when the entire status needs to be updated. Usually, this will be sent only once, and when subsequent user status updates need to happen, EVENT\_CHANNEL\_MEMBER\_UPDATE should be sent.
|
|
|
|
JSON data format (this ones tough):
|
|
Contains a JSON object, where each key is a channel id and each property is an array of [user presence objects](#user-presence-object).
|
|
|
|
Example:
|
|
```json
|
|
6@{"totallyrealid":[{_id:"totallyrealuserid",username:"totallyrealusername",status:1,status_text:"hello"}]}
|
|
```
|
|
|
|
## 7:EVENT\_CHANNEL\_MEMBER\_UPDATE
|
|
|
|
*Auth required, Server to client*
|
|
|
|
Sent by the server when the status of a member changes. Of course, the client has to be in a channel with that member in order to receive this update.
|
|
|
|
JSON data format:
|
|
It's just a [user presence object](#user-presence-object).
|
|
|
|
Example:
|
|
```json
|
|
7@{_id:"totallyrealuserid",username:"totallyrealusername",status:1,status_text:"hello"}
|
|
```
|
|
|
|
## 21:ACTION\_VOICE\_BEGIN\_SESSION
|
|
|
|
*Auth required, Client to server*
|
|
|
|
Sent by the client whenever it wants to initiate a voice session in a specific channel.
|
|
|
|
JSON data format:
|
|
|
|
| Field | Description |
|
|
| - | - |
|
|
| channel | An object that contains "_id", the id of the channel to connect to |
|
|
|
|
(unfinished)
|
|
|
|
## 22:ACTION\_VOICE\_BEGIN\_SESSION
|
|
|
|
*Auth required, Client to server*
|
|
|
|
Sent by the server when the voice session request has been accepted. If it is rejected, the client MUST be disconnected from the gateway as soon as possible.
|
|
|
|
JSON data format:
|
|
|
|
| Field | Description |
|
|
| - | - |
|
|
| reportTo | The IP and port of the voice server to connect to |
|
|
|
|
(unfinished)
|
|
|
|
# Objects and data types
|
|
|
|
## Message object
|
|
|
|
| Field | Description |
|
|
| - | - |
|
|
| content | The text content of the message (max 2000 characters, min 1 character, trimmed) |
|
|
| channel | A [message channel object](#message-channel-object) |
|
|
| author | A [message author object](#message-author-object) |
|
|
|
|
## Message channel object
|
|
|
|
Used mostly for messages.
|
|
|
|
| Field | Description |
|
|
| - | - |
|
|
| _id | The id of the channel |
|
|
| name | The name of the channel |
|
|
|
|
## Channel object
|
|
|
|
| Field | Description |
|
|
| - | - |
|
|
| _id | The id of the channel |
|
|
| name | The name of the channel |
|
|
| creator | A [user object](#user-object) |
|
|
|
|
## User object
|
|
|
|
| Field | Description |
|
|
| - | - |
|
|
| _id | The id of the user |
|
|
| name | The name of the user |
|
|
| color | A hex color that represents that user |
|
|
|
|
## Message author object
|
|
|
|
Used mostly for messages.
|
|
|
|
| Field | Description |
|
|
| - | - |
|
|
| _id | The id of the user |
|
|
| name | The name of the user |
|
|
|
|
## User presence object
|
|
|
|
| Field | Description |
|
|
| - | - |
|
|
| _id | The id of the user |
|
|
| name | The name of the user |
|
|
| status | The status of the user (see ACTION_UPDATE_STATUS) |
|
|
| status_text | The text status of the user (see ACTION_UPDATE_STATUS) | |