BEC - Socket messages

3. Socket Messages

Socket messages are how the server and the client speak to each other. All Socket Messages are JSON, usingSockJS on the server (SockJS-tornado 1.0.3) and the existing web clients (SockJS-client ^1.3.0). The server accepts certain message 'types' through the socket from the client, and the client must handle the messages sent by the server.

Yes, the keys have spaces. I like it. You can write your own chat server if you don't.

A. Client Originating Messages (client => server)

Client messages are asking the server to mutate state based on parasite actions. Each message type requires certain data be sent within the JSON message. Messages that do not contain one of the following 'type' values will be printed in the server log and ignored.

Client Messages (with the exception of type "client log") MUST contain the parasite ID of the currently authenticated parasite in the "user id", or the message will be rejected and authentication will be invalidated via an 'auth fail' message type.

    {
        "user id": "<parasite id>",
        "type": "<type string>",
        ...
    }

client log

adds a log message to the server-side client log.

level: (str) [DEBUG/INFO/WARNING/ERROR/CRITICAL] (case insensitive)
log: (str) message to log

example:

{
	"type": "client log",
	"level": "debug",
	"log": "Client settings saved!"
}

chat message

a chat message sent to a room. this is not a private message between two parasites.

message: (str) contents of the message
room id: (int) destination room id. though not currently used, a room id of null would mean the message goes to ALL rooms.

example:

{
	"user id": "banana"
	"type": "chat message",
	"message": "lol",
	"room id": 0  // 0 is the "General" room that all parasites are forced to be in
}

private message

message: (str) contents of the message
recipient id: (str) destination parasite id

example:

{
	"user id": "banana",
	"type": "private message",
	"message": "lol",
	"recipient id": "potato"
}

image

message: (str) the image url
room id: (str/int) This is either a room id OR a parasite id if the destination is a thread.
nsfw: (bool) the nsfw flag. clients are required to implement nsfw images as hidden (but visible with user interaction) by default

example:

{
	"user id": "banana",
	"type": "image",
	"message": "https://media.giphy.com/media/vggmjHQRT8mre/giphy.gif",
	"room id": "potato",  // sending a string destination indicates a private message
	"nsfw": false
}

image upload

image data: (str) the base64 encoded content of an image file
image type: (str) the mime type of the file, based on a web upload. not sure what this needs to be otherwise.
nsfw: (bool) the nsfw flag. clients are required to implement nsfw images as hidden (but visible with user interaction) by default

example:

{
	"user id": "banana",
	"type": "image upload",
	"image data": "data:image/jpeg;base64,...",  // base64 encoded file contents
	"image type": "image/jpeg",
	"nsfw": false
}

room action

the room action has an additional required field "action". there are four actions that can be taken, ['create', 'delete', 'join', 'leave', 'invite']:

action: create

anybody can create a new room

(str) room name: name of the room to make

example:

{
	"user id": "banana",
	"type": "room action",
	"action": "create",
	"room name": "Cool Kids Club"
}

action: delete

this action is only available to the room owner

room id: (int) id of the room to delete.

example:

{
	"user id": "banana",
	"type": "room action",
	"action": "delete",
	"room id": 42
}

action: join

an invition will prompt a parasite to take this action in the client, but it isn't necessary for the server logic.

room id: (int) id of the room to join
accept: (bool) TRUE if an invitation is being accepted. if FALSE, the inviter will receive an Alert saying their invitation was declined. (i think server's got a bug where if no inviter is specified, it will error)
inviter id: (str) the id of the parasite who sent the invitation, which was part of the invitation data

example:

{
	"user id": "banana",
	"type": "room action",
	"action": "join",
	"room id": 69,
	"accept": true,
	"inviter id": "potato"
}

action: leave

a parasite can only leave a room if they're in it.

room id: (int) the room to leave

example:

{
	"user id": "banana",
	"type": "room action",
	"action": "leave",
	"room id": 69
}

action: invite

send bulk invitations to other parasites to join a room, available to any member of the room.

user ids: (str[]) json array of parasite ids to send invitations to.
room id: (int) the room to which the parasites are being invited

example:

{
	"user id": "banana",
	"type": "room action",
	"action": "invite",
	"user ids": ["potato", "cucumber"],
	"room id": 69
}

status

status: (str) one of ['offline', 'active', 'idle']. other values are ignored.

example:

{
	"user id": "banana",
	"type": "status",
	"status": "idle"
}

typing

status: (bool/int/str) FALSE means the user is NOT currently typing. otherwise, the value of this corresponds to the id of the room/thread the user is currently typing in.

example:

{
	"user id": "banana",
	"type": "typing",
	"status": 69
}

version

client version: (str) the provided client version string, with format "#.#.#", is compared to the current version the server is expecting. mismatches will prompt the parasite to reload their page to receive a new client via Alert (see Section 2.E)

example:

{
	"user id": "banana",
	"type": "version",
	"client version": "3.5.1"
}

settings

settings type messages are a request to update any setting that is stored on the server. some settings are client side only - these are not listed here and will be ignored by the server. all settings will trigger an Alert (see Section 2.E) to the current parasite, whether successful or not. some settings will trigger an Alert to all connected parasites, and some will trigger an update to the user list for all connected parasites.
put all settings to update inside a "data" object

email: self explanatory
password: parasite password. must be an object with two keys: "password1", "password2". will fail if the values do not match.
username: parasite display name. must be valid (not an existing parasite id (except of the current parasite) AND is not another parasite's current display name). also sends updated user list and Alert to all connected parasites
faction: must be one of the approved factions (see Section 2.A). sends updated user list to all connected parasites
color: must be one of the approved colors (see Section 2.A).
soundSet: must be one of the approved sound sets (see Section 2.A).

example:

{
    "user id": "banana",
    "type": settings",
    "data": {
        "email": "butt@butt.butt",
        "username": "banana 🍌"
    }
}

bug

this will create an issue on github for the best-ever-chat repo with the label 'bug'. the server must have a valid github username and token in order to utilize the rest api to create an issue.

title: (str) the title of the issue to create
body: (str) the body of the issue

example:

{
	"user id": "banana",
	"type": "bug",
	"title": "message indicator on offline users looks funny",
	"body": "it's just a floating red star because there's no icon"
}

feature

this will create an issue on github for the best-ever-chat repo with the label 'feature' and the parasite's id appended to the title. the server must have a valid github username and token in order to utilize the rest api to create an issue.

title: (str) the title of the issue to create
body: (str) the body of the issue

example:

{
	"user id": "banana",
	"type": "feature",
	"title": "Age of Empires Integration",
	"body": "11"
}

B. Server Originating Messages (server => client)

Server messages are providing the client with data to update to the most recent state.

auth fail

Client must immediately log out the current parasite. on web, this is done with location.replace('/logout')

room data

rooms
all

private message data

threads

user list

users

update

this is an update to the parasite's settings, and i dont wanna write all the settings right now

[key]: [value]

chat message

room id
time
username
color
message
image url
image src url
nsfw flag

private message

sender id
recipient id: both send and recipient are here because that way the client can determine if a "sent" or "received" sound needs to be played, and if the unread message indicator ought to be displayed.
time
username
color
message
image url
image src url
nsfw flag

alert

message
alert_type: this one didn't get converted to a space, i guess, so that is annoying. one of ['fade', 'dismiss', or 'permanent']. see Section 3.B.ix for more info.

invitation

inviting parasite and room names are sent from the server so the client doesn't have to look it up locally

user: this is the display name of the inviting parasite
user id: this is the id of the inviting parasite
room id
room name