This repository has been archived on 2021-01-16. You can view files and clone it, but cannot push or open issues/pull-requests.
satyr/docs/CHAT.md

126 lines
4.9 KiB
Markdown
Raw Permalink Normal View History

# 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](https://socket.io/), you can find clients for [Java](https://github.com/socketio/socket.io-client-java), [C++](https://github.com/socketio/socket.io-client-cpp), [Swift](https://github.com/socketio/socket.io-client-swift), [Dart](https://github.com/rikulo/socket.io-client-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.