brainlet/resources/Docs/DOCS.md

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:

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

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

Example:

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
session_id	A UUIDv4
channels	An array of channels

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

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

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

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)