satyr/docs/CHAT.md

A Guide to the API for Satyr's webchat

This is not a guide to using the webchat, this a reference point for writing clients.

Satyr's webchat is based on socket.io, you can find clients for Java, C++, Swift, Dart, and probably more.

Socket.IO is loosely reminiscent of IRC in that you will receive events from the server and sent events to it. The following is a list of incoming and outgoing events you will need to handle or send. If you would like to see examples, templates/chat.html is the implementation used in the webclient by satyr.

Incoming Events

These are events you will recieve from the server that need to be handled in some way.

MSG

A MSG event is a chat message. It will have data attached in the following JSON format:

{
	nick: "nickname of the sending user",
	msg: "the text of the message",
	room: "the room the message was sent to"
}

ALERT

An ALERT event is a message from the server to a room. It is just a string containing the plaintext message. Alerts notify a user about things like nickname changes, users who are kicked or banned, and errors.

JOINED

A JOINED event notifies the client that a new user has joined a room they are in. It's a JSON message in the following format:

{
	nick: "the user that joined",
	room: "the name of the room"
}

LEFT

A LEFT event notifies the client that a user has left a room they are in. It's a JSON message in the following format:

{
	nick: "the user that left",
	room: "the name of the room"
}

LIST

A LIST event will only be emitted by the server in response to receiving a LIST event from the client. It is a string containing the list of users in a room, separated by commas.

Outgoing Events

These are events sent from the client to request that the server do something.

NICK

This is a request to set the client's nickname. The data attached to a NICK event should be a JSON object in the following format. The password field is optional, and only required for registered users.

{
	nick: "the requested nickname",
	password: "the optional password"
}

During the initial connect of the client, the server will check for the "Authorization" cookie. If the cookie is a valid, signed JWT the client will be assigned the nickname of the user that cookie belongs to. If it doesn't exist or is invalid, the client will be assigned a nickname of the form Guest+some integer.

The server will send an alert notifying the client of either the nickname change, or some error.

MSG

This is a chat message to send to a room. It should be a JSON object in the following format:

{
	room: "the room to send the messag to",
	msg: "the text of the message"
}

JOINROOM

This is a request to join a room and be notified of its events. The attached data should be a string containing the name of the room.

The server will send the client an alert notifying them of having joined the room, or some error.

LEAVEROOM

This is a request to leave a room and no longer be notified of its events. The attached data should be a string containing the name of the room.

LIST

This is a request for a list of users in a room. It should be a JSON object of the following format:

{room: "the name of the room"}

KICK

This is a request to kick a user from a room. It can only be done by the owner of the room. It should be a JSON object of the following format:

{
	nick: "the user to kick",
	room: "the room to kick them from"
}

BAN

This is a request to ban a user from a room. It can only be done by the owner of the room. All bans are based on IP. It should be a JSON object of the following format:

{
	nick: "the user to ban",
	room: "the room to ban them from",
	length: 30
}

The length field is time in minutes.

LISTBAN

This is a request for a list of IP adresses banned from a room. It should be a JSON object of the following format:

{room: "the name of the room"}

The server will reply with an ALERT that contains a list of IP addresses separated by commas.

UNBAN

A request to unban an IP address. It can only be done by the owner of the room. It should be a JSON object of the following format:

{
	room: "the name of the room",
	ip: "the ip address to unban"
}

Final Notes

Sending more than 10 messages per second will cause the server to kick your client. If kicked this way 3 times, the client will be banned for 20 minutes.

Kicked or banned users will not be notified of this through an event.

The server will send your own MSG events back to you, you will need to parse them out if you want to display them immediately.

Clients who successfully authenticate as a registered user, through either a password or a signed JWT, can ignore nickname collision and have as many connections as they wish.