From afd8d5b38ab19d4e71bcebd6cb36568fa3b85422 Mon Sep 17 00:00:00 2001 From: flashwave Date: Tue, 30 Aug 2022 18:08:44 +0200 Subject: [PATCH] Merged draft protocol file into main one. --- Protocol-draft.md | 1374 --------------------------------------- Protocol.md | 1574 +++++++++++++++++++++++++-------------------- 2 files changed, 863 insertions(+), 2085 deletions(-) delete mode 100644 Protocol-draft.md diff --git a/Protocol-draft.md b/Protocol-draft.md deleted file mode 100644 index d8fd791..0000000 --- a/Protocol-draft.md +++ /dev/null @@ -1,1374 +0,0 @@ -# Sock Chat Protocol Information -The protocol operates on a websocket in text mode. Messages sent between the client and server are a series of concatenated strings delimited by the vertical tab character, represented in most languages by the escape sequence `\t` and defined in ASCII as `0x09`. -The first string in this concatenation must be the packet identifier, sent as an `int`. - -Newer versions of the protocol are implemented as extensions, a client for Version 1 should have no trouble using a server built for Version 2 as long as authentication is understood. - -The current stable version of the protocol is **Version 1**. - - -## Types - -### `bool` -A value that indicates a true or a false state. `0` represents false and anything non-`0` represents true, please stick to `1` for representing true though. - - -### `int` -Any number ranging from `-9007199254740991` to `9007199254740991`, `Number.MAX_SAFE_INTEGER` and `Number.MIN_SAFE_INTEGER` in JavaScript. - - -### `string` -Any printable unicode character, except `\t` which is used to separate packets. - - -### `timestamp` -Extends `int`, contains a second based UNIX timestamp. - - -### `channel name` -A `string` containing only alphanumeric characters (any case), `-` or `_`. - - -### `session id` -A `string` containing only alphanumeric characters (any case), `-` or `_`. - - -### `color` -Any valid value for the CSS `color` property. -Further documentation can be found [on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). - - -### `message flags` -Message flags alter how a message should be displayed to the client, these are all `bool` values. -The parts are as follows: - - - Username should appear using a **bold** font. - - Username should appear using a *cursive* font. - - Username should appear __underlined__. - - A colon `:` should be displayed between the username and the message. - - The message was sent privately, directly to the current user. - -As an example, the most common message flagset is `10010`. This indicates a bold username with a colon separator. - - -### `user permissions` -User permissions are a set of flags separated by either the form feed character (`\f` / `0x0C`) or a space ( / `0x20`). -The reason there are two options is due to a past mixup that we now have to live with. -Which of the methods is used remains consistent per server however, so the result of a test can be cached. - - - - - - - - - - - - - - - - - - - - - - - - - - - -
intRank of the user. Used to determine what channels a user can access or what other users the user can moderate.
boolIndicates whether the user the ability kick/ban/unban others.
boolIndicates whether the user can access the logs. This should always be 0, unless the client has a dedicated log view that can be accessed without connecting to the chat server.
boolIndicates whether the user can set an alternate display name.
intIndicates whether the user can create channel. If 0 the user cannot create channels, if 1 the user can create channels but they are to disappear when all users have left it and if 2 the user can create channels that permanently stay in the channel assortment.
- - -## Client Packets -These are the packets sent from the client to the server. - -### Packet `0`: Ping -Used to prevent the client from closing the session due to inactivity. - - - - - - - -
intUser ID
- - -### Packet `1`: Authentication -Takes a variable number of parameters that are fed into the authentication script associated with the chat. - - - - - - - -
...stringAny amount of data required to complete authentication
- - -### Packet `2`: Message -Informs the server that the user has sent a message. - -Commands are described lower in the document. - - - - - - - - - - - - -
intUser ID
stringMessage text, may not contain \t
- - -## Server Packets -These are the packets sent from the server to the client. - -### Packet `0`: Pong -Response to client packet `0`: Ping. - - - - - - - -
timestampTime the packet was sent to the clientOriginally this field contained the string pong, but this value was completely unused and can be safely replaced.
- - -### Packet `1`: Join/Auth -While authenticated this packet indicates that a new user has joined the server/channel. Before authentication this packet serves as a response to client packet `1`: Authentication. - -#### Successful authentication response -Informs the client that authentication has succeeded. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
stringy
intUser ID
stringUsername
colorUsername color
user permissionsUser permissions
channel nameDefault channel the user will join following this packet
- - -#### Failed authentication response -Informs the client that authentication has failed. - - - - - - - - - - - - - - - - - -
stringn
string - Reason for failure. -
    -
  • authfail: Authentication data is invalid.
    • -
  • userfail: Username in use.
    • -
  • sockfail: A connection has already been started (used to cap maximum connections to 5 in SharpChat).
    • -
  • joinfail: User attempting to authenticate is banned.
    • -
-
timestampIf joinfail this contains expiration time of the ban, otherwise it is empty.
- - -#### User joining -Informs the client that a user has joined. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
timestampTime the user joined
intUser ID
stringUsername
colourUsername color
user permissionsUser permissions
intSequence ID
- - -### Packet `2`: Chat message -Informs the client that a chat message has been received. - - - - - - - - - - - - - - - - - - - - - - - - - - - -
timestampTime when the message was received by the server
int - User ID. - If -1 this message is an informational message from the server and the next field takes on a special form. -
string -

Message, sanitised by the server

-

- If this is an informational message this field is formatted as follows and concatenated by the form feed character \f, respresented in ASCII by 0x0C. Bot message formats are described lower in the document. - - - - - - - - - - - - - -
int - Message type. -
    -
  • 0 for a normal informational message.
    • -
  • 1 for an error.
    • -
-
stringAn id of a string in the legacy language files.
...stringAny number of parameters used to format the language string.
-

-
intSequence ID
message flagsMessage flags
- - -### Packet `3`: User disconnect -Informs the client that a user has disconnected. - - - - - - - - - - - - - - - - - - - - - - - - - - - -
intUser ID
stringUsername
string - One of four disconnect reasons. -
    -
  • leave: The user gracefully left, e.g. "x logged out".
    • -
  • timeout: The user lost connection unexpectedly, e.g. "x timed out".
    • -
  • kick: The user has been kicked, e.g. "x has been kicked".
    • -
  • flood: The user has been kicked for exceeding the flood protection limit, e.g. "x has been kicked for spam".
    • -
-
timestampTime when the user disconnected
intSequence ID
- - -### Packet `4`: Channel event -This packet informs the user about channel related updates. The only consistent parameter across sub-packets is the first one described as follows. - - - - - - - -
int - Channel information update event ID. -
    -
  • 0: A channel has been created.
    • -
  • 1: A channel has been updated.
    • -
  • 2: A channel has been deleted.
    • -
-
- - -#### Sub-packet `0`: Channel creation -Informs the client that a channel has been created. - - - - - - - - - - - - - - - - - -
channel nameThe name of the new channel
boolIndicates whether the channel is password protected
boolIndicates whether the channel is temporary, meaning the channel will be deleted after the last person departs
- - -#### Sub-packet `1`: Channel update -Informs the client that details of a channel has changed. - - - - - - - - - - - - - - - - - - - - - - -
channel nameOld/current name of the channel
channel nameNew name of the channel
boolIndicates whether the channel is password protected
boolIndicates whether the channel is temporary, meaning the channel will be deleted after the last person departs
- - -#### Sub-packet `2`: Channel deletion -Informs the client that a channel has been deleted - - - - - - - -
channel nameName of the channel that has been deleted
- - -### Packet `5`: Channel switching -This packet informs the client about channel switching. - - - - - - - -
int - Channel information update event ID. -
    -
  • 0: A user joined the channel. Sent to all users in said channel.
    • -
  • 1: A user left the channel. Sent to all users in said channel.
    • -
  • 2: The client is to forcibly join a channel.
    • -
-
- - -#### Sub-packet `0`: Channel join -Informs the client that a user has joined the channel. - - - - - - - - - - - - - - - - - - - - - - -
intUser ID
stringUsername
colorUsername color
intSequence ID
- - -#### Sub-packet `1`: Channel departure -Informs the client that a user has left the channel. - - - - - - - - - - - - -
intUser ID
intSequence ID
- - -#### Sub-packet `2`: Forced channel switch -Informs the client that it has been forcibly switched to a different channel. - - - - - - - -
channel nameThe name of the channel that the user has been switched to
- - -### Packet `6`: Message deletion -Informs the client that a message has been deleted. - - - - - - - -
intSequence ID of the deleted message
- - -### Packet `7`: Context information -Informs the client about the context of a channel before the client was present. - - - - - - - -
int - Context event ID. -
    -
  • 0: Users present in the current channel.
    • -
  • 1: A message already in the channel, occurs more than once per channel.
    • -
  • 2: Channels on the server.
    • -
-
- -#### Sub-packet `0`: Existing users -Informs the client about users already present in the channel. - - - - - - - - - - - - -
intAmount of users present in the channel
Context UserAn amount of repetitions of this object based on the number in the previous param, the object is described below
- -##### Context User object - - - - - - - - - - - - - - - - - - - - - - - - - - - -
intUser ID
stringUsername
colorUsername color
user permissionsUser permissions
boolWhether the user should be visible in the users list
- - -#### Sub-packet `1`: Existing message -Informs the client about an existing message in a channel. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
timestampTime when the message was received by the server
intUser ID
stringUsername
colorUsername color
user permissionsUser permissions
stringMessage text, functions the same as described in Packet 2: Chat message
intSequence ID
boolWhether the client should notify the user about this message
message flagsMessage flags
- - -#### Sub-packet `2`: Channels -Informs the client about the channels on the server. - - - - - - - - - - - - -
intAmount of channels on the channel
Context ChannelAn amount of repetitions of this object based on the number in the previous param, the object is described below
- -##### Context Channel object - - - - - - - - - - - - - - - - - -
channel nameName of the channel
boolIndicates whether the channel is password protected
boolIndicates whether the channel is temporary, meaning the channel will be deleted after the last person departs
- - -### Packet `8`: Context clearing -Informs the client that the context has been cleared. - - - - - - - -
int - Number indicating what has been cleared. -
    -
  • 0: The message list has been cleared.
    • -
  • 1: The user list has been cleared.
    • -
  • 2: The channel list has been cleared.
    • -
  • 3: Both the message and user listing have been cleared.
    • -
  • 4: The message, user and channel listing have all been cleared.
    • -
-
- - -### Packet `9`: Forced disconnect -Informs the client that they have either been banned or kicked from the server. - - - - - - - - - - - - -
bool -
    -
  • 0: The client has been kicked, can reconnect immediately.
    • -
  • 1: The client has been banned, can reconnect after the timestamp (documented below) in the next param has expired.
    • -
-
timestampBan expiration time
- - -### Packet `10`: User update -Informs that another user's details have been updated. - - - - - - - - - - - - - - - - - - - - - - -
intUser ID of the affected user
stringNew username
colorNew username color
user permissionsUser permissions
- - -## Bot Messages -Formatting IDs sent by user -1. - -### Informational - -#### `say`: Broadcast -Just echo whatever is specified in the first argument. - -##### Arguments - - `string`: Message to be broadcast. - - -#### `silence`: Silence notice -Informs the client that they've been silenced. - - -#### `unsil`: Silence revocation notice -Informs the client that their silence has been revoked. - - -#### `silok`: Silence confirmation -Informs the client that they have successfully silenced another user. - -##### Arguments - - `string`: Username of the user. - - -#### `usilok`: Silence revocation confirmation -Informs the client that they have successfully revoked another user's silence. - -##### Arguments - - `string`: Username of the user. - - -#### `flwarn`: Flood protection warning -Informs the client that they are risking getting kicked for flood protection (spam) if they continue sending messages at the same rate. - - -#### `unban`: Ban revocation confirmation -Informs the client that they have successfully revoked a ban on a user or an IP address. - - -#### `banlist`: List of banned entities -Provides the client with a list of all banned users and IP addresses. - -##### Arguments - - `string`: HTML with the information on the users with the following format: "<a href="javascript:void(0);" onclick="Chat.SendMessageWrapper('/unban '+ this.innerHTML);">{0}</a>" where {0} is the username of the banned user or the banned IP address. The set is separated by ", ". - - -#### `who`: List of online users -Provides the client with a list of users currently online on the server. - -##### Arguments - - `string`: HTML with the information on the users with the following format: "<a href="javascript:void(0);" onclick="UI.InsertChatText(this.innerHTML);">{0}</a>" where {0} is the username of a user. The current online user is highlighted with " style="font-weight: bold;"" before the closing > of the opening <a> tag. The set is separated by ", ". - - -#### `whochan`: List of users in a channel. -Provides the client with a list of users currently online in a channel. - -##### Arguments - - `string`: HTML with the information on the users with the following format: "<a href="javascript:void(0);" onclick="UI.InsertChatText(this.innerHTML);">{0}</a>" where {0} is the username of a user. The current online user is highlighted with " style="font-weight: bold;"" before the closing > of the opening <a> tag. The set is separated by ", " - - -#### `join`: User connected -Informs the client that a user just connected to the server. - -##### Arguments - - `string`: Username of the user. - - -#### `jchan`: User joined channel -Informs the client that a user just joined a channel they're in. - -##### Arguments - - `string`: Username of the user. - - -#### `leave`: User disconnected -Informs the client that a user just disconnected from the server. - -##### Arguments - - `string`: Username of the user. - - -#### `lchan`: User left channel -Informs the client that a user just left a channel they're in. - - -#### `kick`: User has been kicked -Informs the client that another user has just been kicked. - -##### Arguments - - `string`: Username of the user. - - -#### `flood`: User exceeded flood limit -Informs the client that another user has just been kicked for exceeding the flood protection limit. - -##### Arguments - - `string`: Username of the user. - - -#### `timeout`: User has timed out -Informs the client that another user has been disconnected from the server automatically. - -##### Arguments - - `string`: Username of the user. - - -#### `nick`: User has changed their nickname -Informs the client that a user has changed their nickname. - -##### Arguments - - `string`: Previous username of the user. - - `string`: New username of the user. - - -#### `crchan`: Channel creation confirmation -Informs the client that the channel they attempted to create has been successfully created. - -##### Arguments - - `string`: Name of the target channel. - - -#### `delchan`: Channel deletion confirmation -Informs the client that the channel they attempted to delete has been successfully deleted. - -##### Arguments - - `string`: Name of the target channel. - - -#### `cpwdchan`: Channel password update confirmation -Informs the client that they've successfully changed the password of a channel. - - -#### `cprivchan`: Channel rank update confirmation -Informs the client that they've successfully changed the minimum required rank to join a channel. - - -#### `ipaddr`: IP address -Shows the IP address of another user to a user with moderation privileges. - -##### Arguments - - `string`: Name of the target user. - - `string`: IP address. - - -### Errors - -#### `generr`: Generic Error -Informs the client that Something went Wrong. - - -#### `nocmd`: Command not found -Informs the client that the command they tried to run does not exist. - -##### Arguments - - `string`: Name of the command. - - -#### `cmdna`: Command not allowed -Informs the client that they are not allowed to use a command. - -##### Arguments - - `string`: Name of the command. - - -#### `cmderr`: Command format error -Informs the client that the command they tried to run was incorrectly formatted. - -##### Arguments - - `string`: Name of the command. - - -#### `usernf`: User not found -Informs the client that the user argument of a command contains a user that is not known by the server. - -##### Arguments - - `string`: Name of the target user. - - -#### `rankerr`: Rank error -Informs the client that they are not allowed to do something because their ranking is too low. - - -#### `nameinuse`: Name in use -Informs the the client that the name they attempted to choose is already in use by another user. - -##### Arguments - - `string`: Name that is in use. - - -#### `whoerr`: User listing error -Informs the client that they do not have access to the channel they tried to query. - -##### Arguments - - `string`: Name of the channel. - - -#### `kickna`: Kick or ban not allowed -Informs the client that they are not allowed to kick a user. - -##### Arguments - - `string`: Username of the user in question. - - -#### `notban`: Not banned -Informs the client that the ban they tried to revoke was not in place. - -##### Arguments - - `string`: Username or IP address in question. - - -#### `nochan`: Channel not found -Informs the client that the channel they tried to join does not exist. - -##### Arguments - - `string`: Name of the channel. - - -#### `samechan`: Already in channel -Informs the client that they attempted to join a channel they are already in. - -##### Arguments - - `string`: Name of the channel. - - -#### `ipchan`: Channel join not allowed -Informs the client that they do not have sufficient rank or permissions to join a channel. - -##### Arguments - - `string`: Name of the channel. - - -#### `nopwchan`: No password provided -Informs the client that they must specify a password to join a channel. - -##### Arguments - - `string`: Name of the channel. - - -#### `ipwchan`: No password provided -Informs the client that the password they provided to join a channel was invalid. - -##### Arguments - - `string`: Name of the channel. - - -#### `inchan`: Invalid channel name -Informs the client that the name they tried to give to a channel contains invalid characters. - - -#### `nischan`: Channel name in use -Informs the client that the name they tried to give to a channel is already used by another channel. - -The first argument contains the name of the channel. - - -#### `ndchan`: Channel deletion error -Informs the client that they are not allowed to delete a channel. - -The first argument contains the name of the channel. - - -#### `namchan`: Channel edit error -Informs the client that they are not allowed to edit a channel. - -The first argument contains the name of the channel. - - -#### `delerr`: Message deletion error -Informs the client that they are not allowed to delete a message. - - -#### `silerr`: Already silenced -Informs the client that the user they attempted to silence has already been silenced. - - -#### `usilerr`: Not silenced -Informs the client that the user whose silence they attempted to revoke has not been silenced. - - -#### `silperr`: Silence permission error -Informs the client that they are not allowed to silence the other user. - - -#### `usilperr`: Silence revocation permission error -Informs the client that they are not allowed to revoke the silence on the other user. - - -#### `silself`: Self silence -Informs the client that they are not allowed to silence themselves. - - -## Commands -Actions sent through messages prefixed with `/`. Arguments are described as `[name]`, optional arguments as `[name?]`. The `.` character is ignored in command names (replaced by nothing). - -### `/afk`: Setting status to away -Marks the current user as afk, the first 5 characters from the user string are prefixed uppercase to the current username prefixed by `&lt;` and suffixed by `&gt;_` resulting in a username that looks like `<AWAY>_flash` if `/afk away` is ran by the user `flash`. If no reason is specified "`AFK`" is used. - -#### Format -``` -/afk [reason?] -``` - - -### `/nick`: Change nickname -Temporarily changes the user's nickname, generally with a prefix such as `~` to avoid name clashing with real users. If the user's original name or no argument at all is specified, the command returns the user's name to its original state without the prefix. - -#### Format -``` -/nick [name?] -``` - -#### Responses - - `cmdna`: User is not allowed to change their own nickname. - - `nameinuse`: The specified nickname is already in use by another user. - - `nick`: Username has changed. - - -### `/msg`: Sending a Private Message -Sends a private message to another user. - -#### Format -``` -/msg [username] [message] -``` - -#### Aliases - - `/whisper` - -#### Responses - - `cmderr`: Missing username and/or message arguments. - - `usernf`: Target user could not be found by the server. - - -### `/me`: Describing an action -Sends a message but with flags `11000` instead of the regular `10010`, used to describe an action. - -#### Format -``` -/me [message] -``` - -#### Aliases - - `/action` - - -### `/who`: Requesting a user list -Requests a list of users either currently online on the server in general or in a channel. If no argument is specified it'll return all users on the server, if a channel is specified it'll return all users in that channel. - -#### Format -``` -/who [channel?] -``` - -#### Responses - - `nochan`: The given channel does not exist. - - `whoerr`: The user does not have access to the channel. - - `whochan`: Listing of users in the channel. - - `who`: Listing of users in the server. - - -### `/delete`: Deleting a message or channel -Due to an oversight in the original implementation, this command was specified to be both the command for deleting messages and for channels. Fortunately messages always have numeric IDs and channels must start with an alphabetic character. Thus if the argument is entirely numeric this function acts as an alias for `/delmsg`, otherwise `/delchan`. - -#### Format -``` -/delete [channel name or message id] -``` - -#### Responses -Inherits the responses of whichever command is forwarded to. - - -### `/join`: Joining a channel -Switches or joins the current user to a different channel. - -#### Format -``` -/join [channel] [password?] -``` - -#### Responses - - `nochan`: The given channel does not exist. - - `ipchan`: The client does not have the required rank to enter the given channel. - - `nopwchan`: A password is required to enter the given channel. - - `ipwchan`: The password provided was invalid. - - -### `/leave`: Leaving a channel -Leave a specified channel. - -#### Format -``` -/leave [channel] -``` - -#### Responses - - `nocmd`: The client tried to run this command without specifying the `MCHAN` capability. - - -### `/create`: Creating a channel -Creates a new channel. - -#### Format -``` -/create [rank?] [name...] -``` - -If the first argument is numeric, it is taken as the minimum required rank to join the channel. All further arguments are glued with underscores to create the channel name. - -#### Responses - - `cmdna`: The client is not allowed to create channels. - - `cmderr`: The command is formatted incorrectly. - - `rankerr`: The specified rank is higher than the client's own rank. - - `inchan`: The given channel name contains invalid characters. - - `nischan`: A channel with this name already exists. - - `crchan`: The channel has been created successfully. - - -### `/delchan`: Deleting a channel -Deletes an existing channel. - -#### Format -``` -/delchan [name] -``` - -#### Responses - - `cmderr`: The command is formatted incorrectly. - - `nochan`: No channel exists with this name. - - `ndchan`: The client is not allowed to delete this channel. - - `delchan`: The target channel has been deleted. - - -### `/password`: Update channel password -Changes the password for a channel. Removes the password if no argument is given. - -#### Format -``` -/password [password?] -``` - -#### Aliases - - `/pwd` - -#### Responses - - `cmdna`: The client is not allowed to change the password for this channel. - - `cpwdchan`: The password of the channel has been successfully updated. - - -### `/rank`: Update channel minimum rank -Changes what user rank is required to enter a channel. - -#### Format -``` -/rank [rank] -``` - -#### Aliases - - `/privilege` - - `/priv` - -#### Responses - - `cmdna`: The client is not allowed to change the rank of the target channel. - - `rankerr`: Missing rank argument or the given rank is higher than the client's own rank. - - `cprivchan`: The minimum rank of the channel has been successfully updated. - - -### `/say`: Broadcast a message -Broadcasts a message as the server/chatbot to all users in all channels. - -#### Format -``` -/say [message] -``` - -#### Responses - - `cmdna`: The client is not allowed to broadcast messages. - - `say`: The broadcasted message. - - -### `/delmsg`: Deleting a message -Deletes a given message. - -#### Format -``` -/delmsg [message id] -``` - -#### Responses - - `cmdna`: The client is not allowed to delete messages. - - `cmderr`: The given message ID was invalid. - - `delerr`: The target message does not exist or the client is not allowed to delete this message. - - -### `/kick`: Kick a user -Kicks a user from the serer. If not time is specified, then kick expires immediately. - -#### Format -``` -/kick [username] [time?] -``` - -#### Responses - - `cmdna`: The client is not allowed to kick others. - - `usernf`: The target user could not be found on the server. - - `kickna`: The client is trying to kick someone who they are not allowed to kick, or someone that is currently banned. - - `cmderr`: The provided time is invalid. - - -### `/ban`: Bans a user -Bans a user and their IP addresses from the server. If no time is specified the ban will never expire. - -#### Format -``` -/ban [user] [time?] -``` - -#### Responses - - `cmdna`: The client is not allowed to kick others. - - `usernf`: The target user could not be found on the server. - - `kickna`: The client is trying to kick someone who they are not allowed to kick, or someone that is currently banned. - - `cmderr`: The provided time is invalid. - - -### `/pardon`: Revokes a user ban -Revokes a ban currently placed on a user. - -#### Format -``` -/pardon [user] -``` - -### Aliases - - `/unban` - -#### Responses - - `cmdna`: The client is not allowed to revoke user bans. - - `notban`: The target user is not banned. - - `unban`: The ban on the target user has been successfully revoked. - - -### `/pardonip`: Revokes an IP address ban -Revokes a ban currently placed on an IP address. - -#### Format -``` -/pardonip [address] -``` - -#### Aliases - - `/unbanip` - -#### Responses - - `cmdna`: The client is not allowed to revoke IP bans. - - `notban`: The target address is not banned. - - `unban`: The ban on the target address has been successfully revoked. - - -### `/bans`: List of bans -Retrieves a list of banned users and IP addresses. - -#### Format -``` -/bans -``` - -#### Aliases - - `/banned` - -#### Responses - - `cmdna`: Not allowed to view banned users and IP addresses. - - `banlist`: The list of banned users and IP addresses. - - -### `/silence`: Silence a user -Silences a user. If the time argument is not specified, the silence is indefinite. - -#### Format -``` -/silence [username] [time?] -``` - -#### Responses - - `cmdna`: The client is not allowed to silence users. - - `usernf`: The target user could not be found on the server. - - `silself`: The client tried to silence themselves. - - `silperr`: The target user has a higher rank that the client. - - `silerr`: The target user is already silenced. - - `cmderr`: The time argument is formatted incorrectly. - - `silence`: Informs the target user that they have been silenced. - - `silok`: The target has been successfully silenced. - - -### `/unsilence`: Revokes a user silence -Revokes a user's silenced status. - -#### Format -``` -/unsilence [username] -``` - -#### Responses - - `cmdna`: The client is not allowed to revoke silences. - - `usernf`: The target user could not be found. - - `usilperr`: The target user has a higher rank than the client. - - `usilerr`: The target user isn't silenced. - - `unsil`: Informs the target user that their silenced status has been revoked. - - `usilok`: The silenced status placed on the target has been successfully revoked. - - -### `/ip`: Retrieve IP addresses -Retrieves a user's IP addresses. If the user has multiple connections, multiple `ipaddr` responses may be sent. - -#### Format -``` -/ip [username] -``` - -#### Aliases - - `whois` - -#### Responses - - `cmdna`: The client is not allowed to view IP addresses. - - `usernf`: The target user is not connected to the server. - - `ipaddr`: (One of) The target user's IP address(es). diff --git a/Protocol.md b/Protocol.md index 6d70d06..6c2ce9a 100644 --- a/Protocol.md +++ b/Protocol.md @@ -1,60 +1,137 @@ # Sock Chat Protocol Information The protocol operates on a websocket in text mode. Messages sent between the client and server are a series of concatenated strings delimited by the vertical tab character, represented in most languages by the escape sequence `\t` and defined in ASCII as `0x09`. -The first string in this concatenation must be the packet identifier, sent as an integer. The packet identifiers are as follows. +The first string in this concatenation must be the packet identifier, sent as an `int`. -Some instructions are specific to newer revisions of the protocol and some instructions behave differently in newer revisions, all versions are documented but it is recommended you use the latest one. If a packet is marked as deprecated and you only aim to implement the latest version, you may omit it in your implementation as it will never be sent. +Newer versions of the protocol are implemented as extensions, a client for Version 1 should have no trouble using a server built for Version 2 as long as authentication is understood. The current stable version of the protocol is **Version 1**. -## Client + +## Types + +### `bool` +A value that indicates a true or a false state. `0` represents false and anything non-`0` represents true, please stick to `1` for representing true though. + + +### `int` +Any number ranging from `-9007199254740991` to `9007199254740991`, `Number.MAX_SAFE_INTEGER` and `Number.MIN_SAFE_INTEGER` in JavaScript. + + +### `string` +Any printable unicode character, except `\t` which is used to separate packets. + + +### `timestamp` +Extends `int`, contains a second based UNIX timestamp. + + +### `channel name` +A `string` containing only alphanumeric characters (any case), `-` or `_`. + + +### `session id` +A `string` containing only alphanumeric characters (any case), `-` or `_`. + + +### `color` +Any valid value for the CSS `color` property. +Further documentation can be found [on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). + + +### `message flags` +Message flags alter how a message should be displayed to the client, these are all `bool` values. +The parts are as follows: + + - Username should appear using a **bold** font. + - Username should appear using a *cursive* font. + - Username should appear __underlined__. + - A colon `:` should be displayed between the username and the message. + - The message was sent privately, directly to the current user. + +As an example, the most common message flagset is `10010`. This indicates a bold username with a colon separator. + + +### `user permissions` +User permissions are a set of flags separated by either the form feed character (`\f` / `0x0C`) or a space ( / `0x20`). +The reason there are two options is due to a past mixup that we now have to live with. +Which of the methods is used remains consistent per server however, so the result of a test can be cached. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
intRank of the user. Used to determine what channels a user can access or what other users the user can moderate.
boolIndicates whether the user the ability kick/ban/unban others.
boolIndicates whether the user can access the logs. This should always be 0, unless the client has a dedicated log view that can be accessed without connecting to the chat server.
boolIndicates whether the user can set an alternate display name.
intIndicates whether the user can create channel. If 0 the user cannot create channels, if 1 the user can create channels but they are to disappear when all users have left it and if 2 the user can create channels that permanently stay in the channel assortment.
+ + +## Client Packets These are the packets sent from the client to the server. ### Packet `0`: Ping Used to prevent the client from closing the session due to inactivity. - - - +
Version 1
int User ID
+ ### Packet `1`: Authentication Takes a variable number of parameters that are fed into the authentication script associated with the chat. - - - - + +
Version 1
...any...string Any amount of data required to complete authentication
+ ### Packet `2`: Message Informs the server that the user has sent a message. -Required commands for Version 1 are described lower in the document. +Commands are described lower in the document. - - - + - - + + +
Version 1
int User ID
...stringMessage text, additional packet parameters should be glued on the server using \tstringMessage text, may not contain \t
-## Server + +## Server Packets These are the packets sent from the server to the client. ### Packet `0`: Pong @@ -62,14 +139,13 @@ Response to client packet `0`: Ping. - - - - - + + +
Version 1
stringThe literal string pongtimestampTime the packet was sent to the clientOriginally this field contained the string pong, but this value was completely unused and can be safely replaced.
+ ### Packet `1`: Join/Auth While authenticated this packet indicates that a new user has joined the server/channel. Before authentication this packet serves as a response to client packet `1`: Authentication. @@ -77,45 +153,47 @@ While authenticated this packet indicates that a new user has joined the server/ Informs the client that authentication has succeeded. - - - - + + - + + + - - + + + - - + + + - + +
Version 1
stringLiteral string y for yesy
intSession User IDUser ID
string Username
stringCSS username colorcolorUsername color
permissions (string)User permissions, documented belowuser permissionsUser permissions
stringchannel name Default channel the user will join following this packet
+ #### Failed authentication response Informs the client that authentication has failed. - - - - + + @@ -128,56 +206,61 @@ Informs the client that authentication has failed.
  • joinfail: User attempting to authenticate is banned.
    • + - - + + +
    Version 1
    stringLiteral string n for non
    string
    intIf joinfail; A timestamp (documented below) indicating the length of the bantimestampIf joinfail this contains expiration time of the ban, otherwise it is empty.
    + #### User joining Informs the client that a user has joined. - - - - - + + + + + - - + + + - - + + + +
    Version 1
    intTimestamp, documented below of when the user joinedtimestampTime the user joined
    int User ID
    string Username
    stringCSS username colorcolourUsername color
    permissions (string)User permissions, documented belowuser permissionsUser permissions
    int Sequence ID
    + ### Packet `2`: Chat message Informs the client that a chat message has been received. - - - - - + + + @@ -185,6 +268,7 @@ Informs the client that a chat message has been received. User ID. If -1 this message is an informational message from the server and the next field takes on a special form. + @@ -214,31 +298,34 @@ Informs the client that a chat message has been received.
    Version 1
    intTimestamp, documented below of when the message was received by the servertimestampTime when the message was received by the server
    int
    string

    + int Sequence ID + message flags - Message flags, documented below + Message flags + + ### Packet `3`: User disconnect Informs the client that a user has disconnected. - - - + + @@ -251,24 +338,25 @@ Informs the client that a user has disconnected.
  • flood: The user has been kicked for exceeding the flood protection limit, e.g. "x has been kicked for spam".
    • + - - + + + +
    Version 1
    int User ID
    string Username
    string
    intTimestamp, documented below of when the user disconnectedtimestampTime when the user disconnected
    int Sequence ID
    + ### Packet `4`: Channel event This packet informs the user about channel related updates. The only consistent parameter across sub-packets is the first one described as follows. - - - +
    Version 1
    int @@ -279,75 +367,76 @@ This packet informs the user about channel related updates. The only consistent
  • 2: A channel has been deleted.
    		•
    + #### Sub-packet `0`: Channel creation Informs the client that a channel has been created. - - - - + + + +
    Version 1
    stringchannel name The name of the new channel
    bool Indicates whether the channel is password protected
    bool Indicates whether the channel is temporary, meaning the channel will be deleted after the last person departs
    + #### Sub-packet `1`: Channel update Informs the client that details of a channel has changed. - + + + - - - - - - + + + + +
    Version 1channel nameOld/current name of the channel
    stringThe old/current name of the channel
    stringThe new name of the channelchannel nameNew name of the channel
    bool Indicates whether the channel is password protected
    bool Indicates whether the channel is temporary, meaning the channel will be deleted after the last person departs
    + #### Sub-packet `2`: Channel deletion Informs the client that a channel has been deleted - - - - - + + +
    Version 1
    stringThe name of the channel that has been deletedchannel nameName of the channel that has been deleted
    + ### Packet `5`: Channel switching This packet informs the client about channel switching. - - - +
    Version 1
    int @@ -358,84 +447,83 @@ This packet informs the client about channel switching.
  • 2: The client is to forcibly join a channel.
    		•
    + #### Sub-packet `0`: Channel join Informs the client that a user has joined the channel. - - - + + - - + + + +
    Version 1
    int User ID
    string Username
    stringCSS username colorcolorUsername color
    int Sequence ID
    + #### Sub-packet `1`: Channel departure Informs the client that a user has left the channel. - - - + +
    Version 1
    int User ID
    int Sequence ID
    + #### Sub-packet `2`: Forced channel switch Informs the client that it has been forcibly switched to a different channel. - - - - + +
    Version 1
    stringchannel name The name of the channel that the user has been switched to
    + ### Packet `6`: Message deletion Informs the client that a message has been deleted. - - - +
    Version 1
    int Sequence ID of the deleted message
    + ### Packet `7`: Context information Informs the client about the context of a channel before the client was present. - - - +
    Version 1
    int @@ -446,6 +534,7 @@ Informs the client about the context of a channel before the client was present.
  • 2: Channels on the server.
    		•
    @@ -453,106 +542,114 @@ Informs the client about the context of a channel before the client was present. Informs the client about users already present in the channel. - - - + +
    Version 1
    int Amount of users present in the channel
    Context User An amount of repetitions of this object based on the number in the previous param, the object is described below
    ##### Context User object - - - + + - - + + + - - + + + +
    Version 1
    int User ID
    string Username
    stringCSS username colorcolorUsername color
    permissions (string)User permissions, documented belowuser permissionsUser permissions
    bool Whether the user should be visible in the users list
    + #### Sub-packet `1`: Existing message Informs the client about an existing message in a channel. - - - - - + + + + + - - + + + - - + + + + + + - + +
    Version 1
    intTimestamp, documented belowtimestampTime when the message was received by the server
    int User ID
    string Username
    stringCSS username colorcolorUsername color
    permissions (string)User permissions, documented belowuser permissionsUser permissions
    string Message text, functions the same as described in Packet 2: Chat message
    int Sequence ID
    bool Whether the client should notify the user about this message
    message flagsMessage flags, documented belowMessage flags
    + #### Sub-packet `2`: Channels Informs the client about the channels on the server. - - - + +
    Version 1
    int Amount of channels on the channel
    Context Channel An amount of repetitions of this object based on the number in the previous param, the object is described below
    @@ -560,29 +657,27 @@ Informs the client about the channels on the server. - - - - - + + + + +
    Version 1
    stringChannel namechannel nameName of the channel
    bool Indicates whether the channel is password protected
    bool Indicates whether the channel is temporary, meaning the channel will be deleted after the last person departs
    + ### Packet `8`: Context clearing Informs the client that the context has been cleared. - - - +
    Version 1
    int @@ -595,16 +690,15 @@ Informs the client that the context has been cleared.
  • 4: The message, user and channel listing have all been cleared.
    		•
    + ### Packet `9`: Forced disconnect Informs the client that they have either been banned or kicked from the server. - - - + - - + + +
    Version 1
    bool @@ -613,613 +707,671 @@ Informs the client that they have either been banned or kicked from the server.
  • 1: The client has been banned, can reconnect after the timestamp (documented below) in the next param has expired.
    		•
    intA timestamp (documented below) containing the ban expiration date and timetimestampBan expiration time
    + ### Packet `10`: User update Informs that another user's details have been updated. - - - + + - - + + + - - + + +
    Version 1
    int User ID of the affected user
    string New username
    stringNew CSS username colorcolorNew username color
    permissions (string)User permissions, documented belowuser permissionsUser permissions
    -## Timestamps - -Timestamps in Sock Chat are seconds elapsed since a certain date. Under Sock Chat V1 timestamps are regular Unix Epoch timestamps where `0` is `1970-01-01 00:00:00 UTC`. - -## User Permission String -The User Permission String consists out of five (5) parts concatenated by a space operator, indentified in most languages as the escape sequence and defined as the ASCII character `0x20`. -In the original specification it appeared as if custom permission flags were possible, these have always gone completely unused and should thus be avoided. -The parts are as follows: - -- An integer indicating the hierarchy of the user, this is used to determine whether a user has access to certain channels or is able to act out moderator actions upon certain users (lower can't affect higher). -- A boolean indicating whether the user has the ability to kick people. -- A boolean indicating whether the user has access to the logs, this should be zero unless the client has direct access to the message history without a connection the actual chat. -- A boolean indicating whether the user is able to change their nick/display name. -- An integer ranging from 0 to 2 indicating whether the user can create channels - - `0`: User cannot create channels. - - `1`: User can create channels, but only temporary ones. These _usually_ disappear after the last user left. - - `2`: User can create permanent channels. - -### Message Flags -The Message Flags alter how a message should be displayed to the client, these are all boolean values. -I'm not entirely sure if these allowed for custom flags, but much like the custom flags in the User Permission String, these have gone unused and should thus, also, be avoided. -The parts are as follows: - -- Username should appear using a **bold** font. -- Username should appear using a *cursive* font. -- Username should appear __underlined__. -- A colon `:` should be displayed between the username and the message. -- The message was sent privately, directly to the current user. - -As an example, the most common message flagset is `10010`. ## Bot Messages +Formatting IDs sent by user -1. -Formatting IDs sent by user -1 in Version 1 of the protocol. +### Informational + +#### `say`: Broadcast +Just echo whatever is specified in the first argument. + +##### Arguments + - `string`: Message to be broadcast. + + +#### `silence`: Silence notice +Informs the client that they've been silenced. + + +#### `unsil`: Silence revocation notice +Informs the client that their silence has been revoked. + + +#### `silok`: Silence confirmation +Informs the client that they have successfully silenced another user. + +##### Arguments + - `string`: Username of the user. + + +#### `usilok`: Silence revocation confirmation +Informs the client that they have successfully revoked another user's silence. + +##### Arguments + - `string`: Username of the user. + + +#### `flwarn`: Flood protection warning +Informs the client that they are risking getting kicked for flood protection (spam) if they continue sending messages at the same rate. + + +#### `unban`: Ban revocation confirmation +Informs the client that they have successfully revoked a ban on a user or an IP address. + + +#### `banlist`: List of banned entities +Provides the client with a list of all banned users and IP addresses. + +##### Arguments + - `string`: HTML with the information on the users with the following format: "<a href="javascript:void(0);" onclick="Chat.SendMessageWrapper('/unban '+ this.innerHTML);">{0}</a>" where {0} is the username of the banned user or the banned IP address. The set is separated by ", ". + + +#### `who`: List of online users +Provides the client with a list of users currently online on the server. + +##### Arguments + - `string`: HTML with the information on the users with the following format: "<a href="javascript:void(0);" onclick="UI.InsertChatText(this.innerHTML);">{0}</a>" where {0} is the username of a user. The current online user is highlighted with " style="font-weight: bold;"" before the closing > of the opening <a> tag. The set is separated by ", ". + + +#### `whochan`: List of users in a channel. +Provides the client with a list of users currently online in a channel. + +##### Arguments + - `string`: HTML with the information on the users with the following format: "<a href="javascript:void(0);" onclick="UI.InsertChatText(this.innerHTML);">{0}</a>" where {0} is the username of a user. The current online user is highlighted with " style="font-weight: bold;"" before the closing > of the opening <a> tag. The set is separated by ", " + + +#### `join`: User connected +Informs the client that a user just connected to the server. + +##### Arguments + - `string`: Username of the user. + + +#### `jchan`: User joined channel +Informs the client that a user just joined a channel they're in. + +##### Arguments + - `string`: Username of the user. + + +#### `leave`: User disconnected +Informs the client that a user just disconnected from the server. + +##### Arguments + - `string`: Username of the user. + + +#### `lchan`: User left channel +Informs the client that a user just left a channel they're in. + + +#### `kick`: User has been kicked +Informs the client that another user has just been kicked. + +##### Arguments + - `string`: Username of the user. + + +#### `flood`: User exceeded flood limit +Informs the client that another user has just been kicked for exceeding the flood protection limit. + +##### Arguments + - `string`: Username of the user. + + +#### `timeout`: User has timed out +Informs the client that another user has been disconnected from the server automatically. + +##### Arguments + - `string`: Username of the user. + + +#### `nick`: User has changed their nickname +Informs the client that a user has changed their nickname. + +##### Arguments + - `string`: Previous username of the user. + - `string`: New username of the user. + + +#### `crchan`: Channel creation confirmation +Informs the client that the channel they attempted to create has been successfully created. + +##### Arguments + - `string`: Name of the target channel. + + +#### `delchan`: Channel deletion confirmation +Informs the client that the channel they attempted to delete has been successfully deleted. + +##### Arguments + - `string`: Name of the target channel. + + +#### `cpwdchan`: Channel password update confirmation +Informs the client that they've successfully changed the password of a channel. + + +#### `cprivchan`: Channel rank update confirmation +Informs the client that they've successfully changed the minimum required rank to join a channel. + + +#### `ipaddr`: IP address +Shows the IP address of another user to a user with moderation privileges. + +##### Arguments + - `string`: Name of the target user. + - `string`: IP address. + + +### Errors + +#### `generr`: Generic Error +Informs the client that Something went Wrong. + + +#### `nocmd`: Command not found +Informs the client that the command they tried to run does not exist. + +##### Arguments + - `string`: Name of the command. + + +#### `cmdna`: Command not allowed +Informs the client that they are not allowed to use a command. + +##### Arguments + - `string`: Name of the command. + + +#### `cmderr`: Command format error +Informs the client that the command they tried to run was incorrectly formatted. + +##### Arguments + - `string`: Name of the command. + + +#### `usernf`: User not found +Informs the client that the user argument of a command contains a user that is not known by the server. + +##### Arguments + - `string`: Name of the target user. + + +#### `rankerr`: Rank error +Informs the client that they are not allowed to do something because their ranking is too low. + + +#### `nameinuse`: Name in use +Informs the the client that the name they attempted to choose is already in use by another user. + +##### Arguments + - `string`: Name that is in use. + + +#### `whoerr`: User listing error +Informs the client that they do not have access to the channel they tried to query. + +##### Arguments + - `string`: Name of the channel. + + +#### `kickna`: Kick or ban not allowed +Informs the client that they are not allowed to kick a user. + +##### Arguments + - `string`: Username of the user in question. + + +#### `notban`: Not banned +Informs the client that the ban they tried to revoke was not in place. + +##### Arguments + - `string`: Username or IP address in question. + + +#### `nochan`: Channel not found +Informs the client that the channel they tried to join does not exist. + +##### Arguments + - `string`: Name of the channel. + + +#### `samechan`: Already in channel +Informs the client that they attempted to join a channel they are already in. + +##### Arguments + - `string`: Name of the channel. + + +#### `ipchan`: Channel join not allowed +Informs the client that they do not have sufficient rank or permissions to join a channel. + +##### Arguments + - `string`: Name of the channel. + + +#### `nopwchan`: No password provided +Informs the client that they must specify a password to join a channel. + +##### Arguments + - `string`: Name of the channel. + + +#### `ipwchan`: No password provided +Informs the client that the password they provided to join a channel was invalid. + +##### Arguments + - `string`: Name of the channel. + + +#### `inchan`: Invalid channel name +Informs the client that the name they tried to give to a channel contains invalid characters. + + +#### `nischan`: Channel name in use +Informs the client that the name they tried to give to a channel is already used by another channel. + +##### Arguments + - `string`: Name of the channel. + + +#### `ndchan`: Channel deletion error +Informs the client that they are not allowed to delete a channel. + +##### Arguments + - `string`: Name of the channel. + + +#### `namchan`: Channel edit error +Informs the client that they are not allowed to edit a channel. + +##### Arguments + - `string`: Name of the channel. + + +#### `delerr`: Message deletion error +Informs the client that they are not allowed to delete a message. + + +#### `silerr`: Already silenced +Informs the client that the user they attempted to silence has already been silenced. + + +#### `usilerr`: Not silenced +Informs the client that the user whose silence they attempted to revoke has not been silenced. + + +#### `silperr`: Silence permission error +Informs the client that they are not allowed to silence the other user. + + +#### `usilperr`: Silence revocation permission error +Informs the client that they are not allowed to revoke the silence on the other user. + + +#### `silself`: Self silence +Informs the client that they are not allowed to silence themselves. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Informational
    StringDescriptionArguments
    sayJust echoes the arguments in a message.The message.
    silenceInforms the client that they have been silenced.
    unsilInforms the client that they are no longer silenced.
    silokInforms the client that they have successfully silenced another user.The username of the silenced user.
    usilokInforms the client that they have successfully removed the silencing from another user.The username of the unsilenced user.
    flwarnInforms the client that they are risking being kicking for flood protection (spam).
    unbanInforms the client that they have successfully removed the ban from a user or ip address.
    banlistProvides a list with banned users and IP addresses. - Sets of "<a href="javascript:void(0);" onclick="Chat.SendMessageWrapper('/unban '+ this.innerHTML);">{0}</a>" where {0} is the username of the banned user or the banned IP address. The set is separated by ", " -
    whoProvides a list of users currently online. - Sets of "<a href="javascript:void(0);" onclick="UI.InsertChatText(this.innerHTML);">{0}</a>" where {0} is the username of a user. The current online user is highlighted with " style="font-weight: bold;"" before the closing > of the opening <a> tag. The set is separated by ", " -
    whochanProvides a list of users currently online in a specific channel. - Sets of "<a href="javascript:void(0);" onclick="UI.InsertChatText(this.innerHTML);">{0}</a>" where {0} is the username of a user. The current online user is highlighted with " style="font-weight: bold;"" before the closing > of the opening <a> tag. The set is separated by ", " -
    joinInforms the client that a user connected with the server.The username of said user.
    jchanInforms the client that a user moved into the channel.The username of said user.
    leaveInforms the client that a user disconnected from the server.The username of said user.
    lchanInforms the client that a user moved out of the channel.The username of said user.
    kickInforms the client that a user has disconnect because they got kicked.The username of said user.
    floodInforms the client that a user has disconnect because they got kicked for flood protection.The username of said user.
    nickInforms the client that a user has changed their nickname.The first argument is the previous username of said user, the second argument is their new username.
    crchanInforms the client that they have successfully created a channel.The name of the channel.
    delchanInforms the client that they have successfully deleted a channel.The name of the channel.
    cpwdchanInforms the client that they have successfully changed the password of the channel.
    cprivchanInforms the client that they have successfully changed the hierarchy level required for the channel.
    ipaddrShows the IP address of another user.First argument is the username, second argument is the IP address.
    Error
    StringDescriptionArguments
    generrGeneric fallback error.
    silerrInforms the client that the user they tried to silence had already been silenced.
    usilerrInforms the client that the user whose silence they tried to revoke hasn't been silenced.
    silperrInforms the client that they are not allowed to silence that user.
    usilperrInforms the client that they are not allowed to remove the silence from that user.
    silselfInforms the client that they cannot silence themselves.
    delerrInforms the client that they are not allowed to delete a message.
    notbanInforms the client that a username or IP address is not banned.The provided username or IP address.
    whoerrInforms the client that they do not have access to the channel they specified for the /who command.The provided channel name.
    cmdnaTells the client they're not allowed to use a command.First argument is the name of the command.
    nocmdTells the client the command they tried to run does not exist.First argument is the name of the command.
    cmderrTells the client that they formatted the last command incorrectly.
    usernfTells the client that the user they requested was not found on the server.The requested username.
    kicknaTells the client that they are not allowed to kick a given user.Username of the user they tried to kick.
    samechanTells the client that they are already in the channel they are trying to switch to.The name of the channel.
    ipchanTells the client that they aren't allowed to switch to the provided channel.The name of the channel.
    nochanTells the client that the channel they tried to switch to does not exist.The name of the channel.
    nopwchanTells the client that the channel they tried to switch to requires a password.The name of the channel.
    ipwchanTells the client that the password to tried to switch to the channel to was invalid.The name of the channel.
    inchanInforms the client that the channel name contained invalid characters.
    nischanTells the client that a channel with that name already exists.The name of the channel.
    ndchanTells the client that they're not allowed to delete that channel.The name of the channel.
    namchanTells the client that they're not allowed to edit that channel.The name of the channel.
    nameinuseTells the client that the nickname they tried to use is already being used by someone else.The name.
    rankerrTells the client that they're not allowed to do something to a user because they have a higher hierarchy than them.
    ## Commands +Actions sent through messages prefixed with `/`. Arguments are described as `[name]`, optional arguments as `[name?]`. The `.` character is ignored in command names (replaced by nothing). -Actions sent through messages prefixed with `/` in Version 1 of the protocol. Arguments are described as `[name]`, optional arguments as `[name?]`. +### `/afk`: Setting status to away +Marks the current user as afk, the first 5 characters from the user string are prefixed uppercase to the current username prefixed by `&lt;` and suffixed by `&gt;_` resulting in a username that looks like `<AWAY>_flash` if `/afk away` is ran by the user `flash`. If no reason is specified "`AFK`" is used. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameActionExpected bot messages
    /afk [reason?]Marks the current user as afk, the first 5 characters from the user string are prefixed uppercase to the current username prefixed by &lt; and suffixed by &gt;_ resulting in a username that looks like <AWAY>_flash if /afk away is ran by the user flash. If no reason is specified "AFK" is used.
    /nick [name?]Temporarily changes the user's nickname prefixed with ~. If the user's original name or no argument at all is specified the command returns the user's name to its original state without the prefix. -
      -
    • cmdna: Not allowed to change own nickname.
      • -
    • nameinuse: Someone else is using the username.
      • -
    • nick: Username has changed.
      • -
    -
    - /msg [username] [message]
    - /whisper [username] [message] -     		Sends a private message to another user. -
      -
    • cmderr: Missing username and/or message arguments.
      • -
    • usernf: User not found.
      • -
    -
    - /me [message]
    - /action [message] -     		Sends a message but with flags 11000 instead of the regular 10010, used to describe an action.
    - /who [channel?] - If no argument is specified it'll return all users on the server, if a channel is specified it'll return all users in that channel. -
      -
    • nochan: The given channel does not exist.
      • -
    • whoerr: The user does not have access to the channel.
      • -
    • whochan: Listing of users in a channel.
      • -
    • who: Listing of users.
      • -
    -
    - /delete [channel name or message id] - If the argument is entirely numeric this function acts as an alias for /delmsg, otherwise /delchan.
    - /join [channel] [password?] - Switches the current user to a different channel. -
      -
    • nochan: The given channel does not exist.
      • -
    • ipchan: The user does not have access to the channel.
      • -
    • ipwchan: The provided password was invalid.
      • -
    • nopwchan: A password is required to enter the given channel.
      • -
    -
    - /create [hierarchy?] [name] - Creates a new channel. -
      -
    • cmdna: Not allowed to create channels.
      • -
    • cmderr: Command isn't formatted correctly.
      • -
    • rankerr: Tried to set channel hierarchy higher than own.
      • -
    • inchan: Given name contained invalid characters.
      • -
    • nischan: A channel with the given name already exists.
      • -
    • crchan: Successfully created channel.
      • -
    -
    - /delchan [name] - Deletes an existing channel. -
      -
    • cmderr: Command isn't formatted correctly.
      • -
    • nochan: No channel with the given name exists.
      • -
    • ndchan: Not allowed to delete this channel.
      • -
    • delchan: Deleted channel.
      • -
    -
    - /password [password?]
    - /pwd [password?] -     		Changes the password for a channel. Specify no argument to remove the password. -
      -
    • cmdna: Not allowed to change the password.
      • -
    • cpwdchan: Success.
      • -
    -
    - /privilege [hierarchy]
    - /rank [hierarchy]
    - /priv [hierarchy] -     		Changes what user hierarchy is required to enter a channel. -
      -
    • cmdna: Not allowed to change hierarchy.
      • -
    • rankerr: Missing rank argument or trying to set hierarchy to one higher than their own.
      • -
    • cprivchan: Success.
      • -
    -
    - /say [message] - Broadcasts a message as the server to all users in all channels. -
      -
    • cmdna: Not allowed to broadcast.
      • -
    • say: Broadcast message.
      • -
    -
    - /delmsg [message id] - Deletes a message. -
      -
    • cmdna: Not allowed to delete messages.
      • -
    • cmderr: Invalid arguments.
      • -
    • delerr: The message does not exist, or the user's hierarchy is lower than the sender.
      • -
    -
    - /kick [user] [time?] - Kicks a user from the server. If no time is specified the kick expires immediately. -
      -
    • cmdna: Not allowed to kick users.
      • -
    • usernf: User not found.
      • -
    • kickna: Sender is trying to kick themselves, someone with a higher hierarchy or someone that's already banned.
      • -
    • cmderr: Provided time is invalid.
      • -
    -
    - /ban [user] [time?] - Kicks a user and IP address from the server. If no time is specified the kick will never expire. -
      -
    • cmdna: Not allowed to kick users.
      • -
    • usernf: User not found.
      • -
    • kickna: Sender is trying to kick themselves, someone with a higher hierarchy or someone that's already banned.
      • -
    • cmderr: Provided time is invalid.
      • -
    -
    - /unban [user]
    - /pardon [user] -     		Revokes the ban of a user. -
      -
    • cmdna: Not allowed to revoke user bans.
      • -
    • notban: User is not banned.
      • -
    • unban: Success.
      • -
    -
    - /unbanip [user]
    - /pardonip [user] -     		Revokes the ban of an ip address. -
      -
    • cmdna: Not allowed to revoke ip bans.
      • -
    • notban: IP address is not banned.
      • -
    • unban: Success.
      • -
    -
    - /bans
    - /banned -     		Retrieves the list of banned users and ip addresses. -
      -
    • cmdna: Not allowed to revoke ip bans.
      • -
    • banlist: List of bans.
      • -
    -
    - /silence [username] [time?] - Silences a user. If the time argument is not specified the silence is indefinite. -
      -
    • cmdna: Not allowed to silence users.
      • -
    • usernf: User not found.
      • -
    • silself: Tried to silence self.
      • -
    • silperr: Tried to silence user of higher hierarchy.
      • -
    • silerr: User is already silenced.
      • -
    • cmderr: Time isn't formatted correctly.
      • -
    • silence: Informs the user they have been silenced.
      • -
    • silok: Tells the sender that the user has been silenced.
      • -
    -
    - /unsilence [username] - Revokes a silence. -
      -
    • cmdna: Not allowed to revoke silences.
      • -
    • usernf: User not found.
      • -
    • usilperr: Tried to revoke silence of user of higher hierarchy.
      • -
    • usilerr: User isn't silenced.
      • -
    • unsil: Informs the user that their silence has been revoked.
      • -
    • usilok: Tells the sender that the user's silence has been revoked.
      • -
    -
    - /ip [username]
    - /whois [username] -     		Gets a user's IP address. -
      -
    • cmdna: Not allowed to view IP addresses.
      • -
    • usernf: User not found.
      • -
    • ipaddr: IP address of user.
      • -
    -
    +#### Format +``` +/afk [reason?] +``` + + +### `/nick`: Change nickname +Temporarily changes the user's nickname, generally with a prefix such as `~` to avoid name clashing with real users. If the user's original name or no argument at all is specified, the command returns the user's name to its original state without the prefix. + +#### Format +``` +/nick [name?] +``` + +#### Responses + - `cmdna`: User is not allowed to change their own nickname. + - `nameinuse`: The specified nickname is already in use by another user. + - `nick`: Username has changed. + + +### `/msg`: Sending a Private Message +Sends a private message to another user. + +#### Format +``` +/msg [username] [message] +``` + +#### Aliases + - `/whisper` + +#### Responses + - `cmderr`: Missing username and/or message arguments. + - `usernf`: Target user could not be found by the server. + + +### `/me`: Describing an action +Sends a message but with flags `11000` instead of the regular `10010`, used to describe an action. + +#### Format +``` +/me [message] +``` + +#### Aliases + - `/action` + + +### `/who`: Requesting a user list +Requests a list of users either currently online on the server in general or in a channel. If no argument is specified it'll return all users on the server, if a channel is specified it'll return all users in that channel. + +#### Format +``` +/who [channel?] +``` + +#### Responses + - `nochan`: The given channel does not exist. + - `whoerr`: The user does not have access to the channel. + - `whochan`: Listing of users in the channel. + - `who`: Listing of users in the server. + + +### `/delete`: Deleting a message or channel +Due to an oversight in the original implementation, this command was specified to be both the command for deleting messages and for channels. Fortunately messages always have numeric IDs and channels must start with an alphabetic character. Thus if the argument is entirely numeric this function acts as an alias for `/delmsg`, otherwise `/delchan`. + +#### Format +``` +/delete [channel name or message id] +``` + +#### Responses +Inherits the responses of whichever command is forwarded to. + + +### `/join`: Joining a channel +Switches or joins the current user to a different channel. + +#### Format +``` +/join [channel] [password?] +``` + +#### Responses + - `nochan`: The given channel does not exist. + - `ipchan`: The client does not have the required rank to enter the given channel. + - `nopwchan`: A password is required to enter the given channel. + - `ipwchan`: The password provided was invalid. + + +### `/leave`: Leaving a channel +Leave a specified channel. + +#### Format +``` +/leave [channel] +``` + +#### Responses + - `nocmd`: The client tried to run this command without specifying the `MCHAN` capability. + + +### `/create`: Creating a channel +Creates a new channel. + +#### Format +``` +/create [rank?] [name...] +``` + +If the first argument is numeric, it is taken as the minimum required rank to join the channel. All further arguments are glued with underscores to create the channel name. + +#### Responses + - `cmdna`: The client is not allowed to create channels. + - `cmderr`: The command is formatted incorrectly. + - `rankerr`: The specified rank is higher than the client's own rank. + - `inchan`: The given channel name contains invalid characters. + - `nischan`: A channel with this name already exists. + - `crchan`: The channel has been created successfully. + + +### `/delchan`: Deleting a channel +Deletes an existing channel. + +#### Format +``` +/delchan [name] +``` + +#### Responses + - `cmderr`: The command is formatted incorrectly. + - `nochan`: No channel exists with this name. + - `ndchan`: The client is not allowed to delete this channel. + - `delchan`: The target channel has been deleted. + + +### `/password`: Update channel password +Changes the password for a channel. Removes the password if no argument is given. + +#### Format +``` +/password [password?] +``` + +#### Aliases + - `/pwd` + +#### Responses + - `cmdna`: The client is not allowed to change the password for this channel. + - `cpwdchan`: The password of the channel has been successfully updated. + + +### `/rank`: Update channel minimum rank +Changes what user rank is required to enter a channel. + +#### Format +``` +/rank [rank] +``` + +#### Aliases + - `/privilege` + - `/priv` + +#### Responses + - `cmdna`: The client is not allowed to change the rank of the target channel. + - `rankerr`: Missing rank argument or the given rank is higher than the client's own rank. + - `cprivchan`: The minimum rank of the channel has been successfully updated. + + +### `/say`: Broadcast a message +Broadcasts a message as the server/chatbot to all users in all channels. + +#### Format +``` +/say [message] +``` + +#### Responses + - `cmdna`: The client is not allowed to broadcast messages. + - `say`: The broadcasted message. + + +### `/delmsg`: Deleting a message +Deletes a given message. + +#### Format +``` +/delmsg [message id] +``` + +#### Responses + - `cmdna`: The client is not allowed to delete messages. + - `cmderr`: The given message ID was invalid. + - `delerr`: The target message does not exist or the client is not allowed to delete this message. + + +### `/kick`: Kick a user +Kicks a user from the serer. If not time is specified, then kick expires immediately. + +#### Format +``` +/kick [username] [time?] +``` + +#### Responses + - `cmdna`: The client is not allowed to kick others. + - `usernf`: The target user could not be found on the server. + - `kickna`: The client is trying to kick someone who they are not allowed to kick, or someone that is currently banned. + - `cmderr`: The provided time is invalid. + + +### `/ban`: Bans a user +Bans a user and their IP addresses from the server. If no time is specified the ban will never expire. + +#### Format +``` +/ban [user] [time?] +``` + +#### Responses + - `cmdna`: The client is not allowed to kick others. + - `usernf`: The target user could not be found on the server. + - `kickna`: The client is trying to kick someone who they are not allowed to kick, or someone that is currently banned. + - `cmderr`: The provided time is invalid. + + +### `/pardon`: Revokes a user ban +Revokes a ban currently placed on a user. + +#### Format +``` +/pardon [user] +``` + +### Aliases + - `/unban` + +#### Responses + - `cmdna`: The client is not allowed to revoke user bans. + - `notban`: The target user is not banned. + - `unban`: The ban on the target user has been successfully revoked. + + +### `/pardonip`: Revokes an IP address ban +Revokes a ban currently placed on an IP address. + +#### Format +``` +/pardonip [address] +``` + +#### Aliases + - `/unbanip` + +#### Responses + - `cmdna`: The client is not allowed to revoke IP bans. + - `notban`: The target address is not banned. + - `unban`: The ban on the target address has been successfully revoked. + + +### `/bans`: List of bans +Retrieves a list of banned users and IP addresses. + +#### Format +``` +/bans +``` + +#### Aliases + - `/banned` + +#### Responses + - `cmdna`: Not allowed to view banned users and IP addresses. + - `banlist`: The list of banned users and IP addresses. + + +### `/silence`: Silence a user +Silences a user. If the time argument is not specified, the silence is indefinite. + +#### Format +``` +/silence [username] [time?] +``` + +#### Responses + - `cmdna`: The client is not allowed to silence users. + - `usernf`: The target user could not be found on the server. + - `silself`: The client tried to silence themselves. + - `silperr`: The target user has a higher rank that the client. + - `silerr`: The target user is already silenced. + - `cmderr`: The time argument is formatted incorrectly. + - `silence`: Informs the target user that they have been silenced. + - `silok`: The target has been successfully silenced. + + +### `/unsilence`: Revokes a user silence +Revokes a user's silenced status. + +#### Format +``` +/unsilence [username] +``` + +#### Responses + - `cmdna`: The client is not allowed to revoke silences. + - `usernf`: The target user could not be found. + - `usilperr`: The target user has a higher rank than the client. + - `usilerr`: The target user isn't silenced. + - `unsil`: Informs the target user that their silenced status has been revoked. + - `usilok`: The silenced status placed on the target has been successfully revoked. + + +### `/ip`: Retrieve IP addresses +Retrieves a user's IP addresses. If the user has multiple connections, multiple `ipaddr` responses may be sent. + +#### Format +``` +/ip [username] +``` + +#### Aliases + - `whois` + +#### Responses + - `cmdna`: The client is not allowed to view IP addresses. + - `usernf`: The target user is not connected to the server. + - `ipaddr`: (One of) The target user's IP address(es).