brainlet/resources/Docs/DOCS.md

# Waffle API docs

# 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

## 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.

JSON data format:   
| Field | Description |
| - | - |
| pingInterval | Every *pingInterval*, the client must send a packet simply containing `7@1`. This is the ACTION_PING payload. If the client does not send this payload at the right time, it is disconnected. |
| supportedAttributes | An array of attributes supported by the server. If a client requests an unsupported attribute, it is disconnected from the server. |

Example:
```json
0@{"pingInterval":14750,"supportedAttributes":["PRESENCE_UPDATES"]}
```

## 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 |
| attributes | An array of attributes the client wants the server to enable. The current possible values are: `PRESENCE_UPDATES` (required for presence updates to be sent to the client) |

Example:
```json
1@{"token":"my totally real token","attributes":["PRESENCE_UPDATES"]}
```

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.

**This packet is deprecated and reserved for future use**

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*

An object containing a list of user presences which were updated, where the keys are the user ids and the values are [user presence objects](#user-presence-object).

**This packet is only sent if the user has `PRESENCE_UPDATES` in their `attributes`, specified in YOO.**

Example:
```json
6@{"userid":{_id:"userid",username:"username123",status:1,status_text:"hello"}}
```

## 7:ACTION_PING

*Auth required, Client to server*

Sent by the client every `pingInterval`. The payload of this packet must always be `1`.

Example:
```json
7@1
```

## 21:ACTION_VOICE_REQUEST_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 |


## 22:EVENT_VOICE_ASSIGN_SERVER

*Auth required, Server to client*

Sent by the server when a voice server has been assigned to a channel session.

JSON data format:

| Field | Description |
| - | - |
| reportTo | The IP and port of the voice server to connect to |
| channel | An object that contains "_id", the id of the channel |

# Voice server gateway

Voice server signaling is done through a websocket gateway. This gateway is specified by the `reportTo` property in EVENT_VOICE_ASSIGN_SERVER.

## 23:ACTION_VOICE_CONNECTION_REQUEST

*Client to server*

| Field | Description |
| - | - |
| token | The authentication token |
| channel | An object that contains "_id", the id of the channel to connect to |
| offer | An SDP payload; the webrtc offer from the client |

## 24:EVENT_VOICE_CONNECTION_ANSWER

*Auth required, Server to client*

| Field | Description |
| - | - |
| session_id | A UUIDv4 |
| answer | An SDP payload; the webrtc answer from the server |


# 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) |
| _id | An ObjectId |

## 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) |