Master Server (v2)

This little mini-spec summarizes the thoughts on adding a "master server" to Verse. The idea is Eskil's, but we held a little meeting at the Blender Conference 2005 where the initial outlining was done. This then lied more or less dormant, with some support sneaking into the main Verse server but no master server being published. Now (September 2006), we've done some more work on it, with an initial master server implementation published, and the spec updated. There will be a period when the new spec is not implemented.

The idea is to add support to the Verse server to "ping" a separate master server periodically, in order to maintain a list of live servers. This list is then retrievable by clients, who are trying to figure out where to connect to. This way of working with servers is very common in the online gaming world, and used by major games such as Counter-Strike and Unreal Tournament.

Requirements

This section details the requirements for the master server system. Each of these must be addressed for the system as a whole to function.

	There must be a way for Verse servers to register with the Master server.
	There must be a way for clients to ask the Master server about available servers.
	There must be a way for the Master server to transmit a list of servers to a client.

The Solution

The solution is fairly simple and straight-forward. We simply define a set of ping message strings, that can be sent between servers, the master server, and clients. The following pings are needed:

Here, MS is the master server, S is a regular Verse server, and C a client. The numbers show the order in which the commands are sent

	MS:ANNOUNCE is sent periodically by a server to the master server, to tell the master server that the server exists. It carries no data.
	DESCRIBE is sent by the master server to the server.
	DESCRIPTION is sent by the server to the master server. This message includes a human-readable description, and (optionally) a set of tags that help describe the server and its contents.
	MS:GET is sent by a client to a master server in order to request a list of information entries from the master server. It the ability to request the human-readable descriptions for each, as well as filtering based on tags.
	MS:LIST is sent by the master server to a client, in response to MS:GET. It contains the requested entries. There might be many MS:LIST ping packets sent in response to a single MS:GET request.

The reason for the two-step server registration (ANNOUNCE followed by a DESCRIBE/DESCRIPTION pair) is to make it harder to spoof the master server. This way, anyone who sends an ANNOUNCE must also stick around and wait for the DESCRIBE command, and reply to it. This makes it slightly harder, compared to just sending the descriptive information included in the initial announcement command.

Syntax Notes

In the below, an XML-like syntax where keywords are given values is used. The syntax is not XML though, and there are some differences:

	The quotes are optional, and only needed if the value includes whitespace or quote characters. If so, then a double quote must be the first letter following the equals sign.
	Embedded quotes can be escaped by preceding them with a backslash.
	Embedded backslashes can be escaped by preceding them with another backslash.
	An illegaly quoted keyword can cause the entire message to be discarded.

Further, optional parts of messages are enclosed in square brackets. These brackets themselves are not sent. Words in lower-case are generally indicating that user-supplied content goes there.

MS:ANNOUNCE

Verse servers send MS:ANNOUNCE to register themselves with a master server. How the Verse server learns about the master server is slightly outside the scope of this text; currently it is supplied as a command-line argument.

MS:ANNOUNCE has the following syntax, schematically: 'MS:ANNOUNCE'.

DESCRIBE and DESCRIPTION

These two commands are simply used as defined in the Server Description specfication. A server does not need to treat a DESCRIBE sent to it by a master server any different from any other DESCRIBE command; there is no difference.

MS:GET

Clients use MS:GET to request a listing of servers from a master server. How the clients learn about the address of the master server is outside the scope of this text.

MS:GET has the following syntax: 'MS:GET [IP=[DE]] [TA=tag1, -tag2,...]'

The IP part selects the IP keyword, which represents the address of each known Verse server. The part after the equals sign specifies which information is to be supplied for each server. It can be either empty, in which case only the address (and port) information is sent, or it can be "DE" in which case the human-readable description is also sent. Currently, IP is the only keyword that is defined, so leaving it out will result in no results being sent.

The TA part specifies a tag filter to reduce the number of servers that match. Tags are simply listed, separated by commas. A server must include all named tags, except any preceded by a single minus sign, in its MS:ANNOUNCE's TA-part in order to be match.

MS:LIST

The master server sends MS:LIST pings to clients in order to inform them about servers matching the last MS:GET sent by that client.

The syntax of a MS:LIST ping is: 'MS:LIST (IP=ip:port [DE=desc])', where the part inside () can be repeated any number of times. IP addresses are sent in dotted-decimals form, with the port number separated from it by a colon and only included if it is not the Verse default port. The DE part is only included if the client asked for it. The tags are not included at all, but only servers whose tags match what was in the MS:GET ping are described.

For a typical single MS:GET sent to a busy master server, there will be many MS:LIST pings sent as a response, since a long server list won't fit a single UDP packet. Individual server descriptions will never be split across packets. The order in which servers are described is not defined.

Ping Communications

The Verse master server infrastructure is implemented using the Verse ping command as the sole means of data transport. Since ping is a so called "unconnected" command, meaning that a client need not be connected in order to receive it, it does not enjoy the benefits of Verse's connection management. A ping can be lost, and if that happens, it will not be detected, so no retransmission occurs.

Master server communications is not deemed to be very critical, so there is not a great deal of effort spent here to make it more safe. One common "fix" or workaround for this kind of problem is to simply duplicate the packets, i.e. send each ping twice. At the time of writing, I'm not sure that this actually works with Verse; if both pings end up in the same packet there would be no point.