Chat (v2)

This additional specification describes the recommended way to implement textual chat in Verse. It centers on textual chat since that mimics a well-known application (IRC), and thus is known to be useful. It would also be interesting to implement audio chatting, but that is not covered by this text. This is a greatly simplified version of a previously published document. The previous version has been judged obsolete, and is no longer online.

Requirements

These were our functional requirements on a chat system:

	Be reasonably simple to implement, on top of Verse.
	Support some form of access limitation.
	Support many speakers and listeners at the same time, although all might not be interested in talking to each other.

The Solution

Here is how the above requirements are met by the solution presented in this specification:

	Define a dedicated chat client/server relationship on top of the ordinary Verse client/server. Implement a separate program, the chat server, to handle the chatting. Then define a protocol for chat clients to use in order to chat.
	Use Verse object methods as the transport layer. This is a very good fit.
	(Require clients to log in to the chat system before allowing them to speak.)
	Define "channels", which are virtual rooms in which conversations take place. All talk happens inside a channel, and only people who have explicitly asked to be part of that channel will receive it.

Chat Channels

As mentioned above, Verse's chat system includes the concept of "channels". A channel is intended to be a named set of clients, who want to talk to each other. All things that are said go to a channel. It is up to the actual chat implementation to define how channels are named, how clients enter and leave them, and similar details.

The Verse chat system requires the presence of one channel by default, called "" (an empty string).

Chat Methods

As mentioned above, Verse object methods are used for all chat-system communication. This means that when a client needs to send a command to the chat server, it will send a method call to the server's avatar node. Likewise, when a client needs to receive data from the chat server, the server will send a method call to the client's avatar.

In the following, the process "send a method call M to the avatar of Verse client N" is often abbreviated as "N.M()". For instance, we could describe calling a method call named login in the chat server as just "server.login()". This works for both the chat clients and the chat server, since all are clients from the Verse server's point of view.

Chat Server Methods

The chat server has a single method, which should be in a group named "chat_text" to make it recognizable as implementing this spec.

say	say(STRING channel, STRING text)
	This sends a string of text to the server, targetting the given channel. The chat server will determine of the sender is allowed to speak in the channel, if the channel exists, and so on. If the validation succeeds, the text will be sent out to all clients currently part of the channel.

Server Commands

Because it is expected that servers will need to add some sort of control layer, to let clients do things like joining and leaving channels, setting their nickname, and so on, there is a need for a way to send commands to the server. Here, a command is distinct in that it is not chat text, it is not something that is being said, but rather a request that the chat server does something.

However, to keep the number of methods needed to implement a server down, commands are sent just as if they were chat text.

In fact, this specification doesn't even say how to see the difference between text that is a chat message, and text that is a command to the server. It is up to the server implementation to impose some such rule. For example, in IRC all commands begin with slash; a message can never start with a slash. No such rule exists for the Verse chat.

That said, the following strings are reserved by the Verse chat system, to allow required features to be implemented in well-defined manner:

/VerseListCommands

This command asks the server to respond, to the channel the command is sent to, with a list of commands that it supports. The exact format of the list is not currently specified. However, due to the nature of the Verse transport layer, please take care that the list is unordered, if at all possible. The response will not be sent to all members of the channel, only to the one that asked.

Please note that although the above begins with a slash, this does not imply that strings that begin with a slash are reserved by the Verse chat system, in general. The idea here is that the entire string must match exactly, it does not say anything about other strings that begin with a slash.

Client Chat Methods

These are the methods used by clients who want to participate in the Verse chat system. The methods should be in a group named "chat_text".

hear	hear(STRING channel, STRING speaker, STRING text)
	This is called to notify a client that something has been uttered in a channel that the client is listening to. The speaker argument contains a textual name that identfies the speaker. How to set this name, if even possible, is undefined by this specification.

Holes in this Spec

There are many things not mentioned in this specification, that are simply left to the individual server implementations. The idea is that it should be possible to implement many different "flavors" of textual chat, on top of the simple infrastructure described herein.