Client Server Communication

There is always one instance of the SauceBot server. This server communicates with SauceBot clients, which in turn communicate with various chat services. Client-server data communication is encoded with JSON. Each client represents one instance of a chat service.

###Client Messages A client can send various messages to the server; in JSON, each of these messages takes the form

{
    "cmd": command,
    "data": data
}

where command specifies the type of message being sent, and data is the payload of the message. Note that, unlike the examples, newlines within a message are not permitted, but each message must be separated by a newline. There are currently four types of messages that the server recognizes, listed with the format of their data payload:

• msg is for standard messages, and is the primary means of communicating chat between the chat service and server through the client. When this command is received, the SauceBot instance, defined in saucebot, passes this message to channels, along with the set of functions that can be used to respond to the client.

{
    "chan": channel,
    "user": user,
    "op": opLevel,
    "msg": message
}

channel is the channel where the message was issued, user is the user who sent the message, opLevel is the optional op level of the user, and message is the raw message itself.

• pm is used for private messages directed at the bot.

{
    "user": user,
    "msg": message
}

user is the sender of the private message, and message is the contents of the message.

• upd is sent by the client to inform the server that it needs to reload/update some of its internal information, e.g., due to a change made in the web interface. At the moment, this command is only issued by the web interface.

{
    "cookie": authCookie,
    "chan": channel,
    "type": type
}

authCookie is a cookie-based token that is used to authenticate the client to ensure that it has permission to have whatever update it is requesting done, channel is optional and can be used to limit the effects of the update to one channel, and type determines what is to be updated. The possible values for type are 'Users', which forces a reload of all users from the database; 'Channels', which reloads all of the channels; 'Help' for indicating that help is being sent to channel; and if none of these, it is the name of a module which is to be reloaded.

• get is also sent by the client, currently, only the web interface, in order to retrieve information about the current state of the bot.

{
    "cookie": authCookie,
    "chan": channel,
    "type": type
}

authCookie and channel are as in upd, but the available types in this message are different - 'Users' returns

###Server Responses As mentioned above, the server provides a number of functions to the Channel object in addition to the data received, so that the Channel can then respond appropriately to the client. These functions, listed with their arguments and the form of the data payload passed to the client, are as follows:

• say(channel, message) is used to instruct the client to send a message to the underlying chat service, on behalf of the bot.

{
    "chan": channel,
    "msg": message
}

channel is the channel to send the message to, and message is the actual message to be sent.

• ban(channel, user) is used to have the client ban a given user from the channel.

{
    "chan": channel,
    "user": user
}

As usual, channel is the channel being operated on, and user is the user to ban from the channel.

• unban(channel, user) is a complement to ban, used to remove a ban on a user in a given channel.

{
    "chan": channel,
    "user": user
}

Like ban, channel is the channel that the ban is to be lifted in, and user is the user being unbanned.

• timeout(channel, user, time) asks the client to kick a user from a channel for a specified time.

{
    "chan": channel,
    "user": user,
    "time": time
}

channel is of course the channel that the timeout is to take effect, user is the user being temporarily removed from the channel, and time is the time, in seconds, that the user cannot join the channel.

• commercial(channel) sends a message to the client that a commercial message should be displayed in the chat service.

{
    "chan": channel
}

Here, channel is the channel that the commercial is to be displayed in.

There are a few other messages that the server can send to the client - users, channels, and error. Channel objects do not receive functions to send these messages; however, these messages are used by the server to notify the client of certain situations, and should be handled by any client implementation. The error message will only be emitted when an internal error occurs within the server. The data for error messages is formatted as follows:

{
    "msg": err
}

where err is just a string indicating the nature of the error to the client. users messages are emitted in response to a get request with type 'Users', and the data payload of these messages will simply be a JSON array of the list of current users in the requested context, e.g.,

["user1", "user2", "user3"]

channels messages are used to provide updates to the client on the list of currently monitored channels. At the moment, a client will only receive this channel list after having made a get request with the 'Channels' type. The data payload of a channels message will be a JSON array of the channel objects, with each channel being represented by an object of the form

{
    "id": id,
    "name": name,
    "status": status,
    "bot": botname
}

where id is the unique identifier used in the database to distinguish the channel, name is the name of the channel, status is the status of the channel, either 1 to indicate that the channel is enabled or 0 for it being disabled, and botname is the name of the bot responsible for that channel.