brainlet/DOCS.md

Waffle API docs (currently not implemented)

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:

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:

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:

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
client	The name of the application the client is connecting from (e.g. browser_react_app)

Example:

1@{"token":"my totally real token","client":"amazing client"}

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.

This payload contains an empty JSON object, that may have data added to it in later versions of this software.

Example:

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:

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

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:

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. If only one user's status changes, use EVENT_CHANNEL_MEMBER_UPDATE.

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.

Example:

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.

Example:

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
author	A message author object

Message channel object

Used mostly for messages.

Field	Description
_id	The id of the channel
name	The name of the channel

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)