With the introduction of the Metacle service and the necessary modifications of the GGZ metaserver and its protocol, this document replaces the old metaserver specification. It does however only give an introduction, leaving the details to the text files which come with the metaserver source code, and the new protocol specification document.
Metaservers have a long tradition in gaming infrastructures: They are public databases of game servers running on other hosts, and provide a reliable static point of information about the location of such dynamic game servers, often including other meta information such as the game server's location, connection speed and version number.
The GGZ Metaserver (ggzmetaserv) is a very generic species. It has been designed to be flexible enough to hold entries of various games at the same time, and offers both a simple query mode and an XML mode. Publication, modification and removal of entries is possible, and the server supports authorisation for added security and peer notification for redundant operation.
Advanced features include incremental notifications about changes, to allow for real-time updates of interested applications (publish-subscribe method), and incremental querying based on a client-side provided time delta value.
Each entry is of a certain class and a subordinate subclass, also referred to as type or category. The class will almost always refer to the game server name, whereas the categories refer to the type of information one can retrieve. Therefore, categories commonly have a name such as connection to get connection information, or meta to find out other meta servers for this entry class. Categories could however also refer to resources only available under some classes, such as clubs to retrieve a list of web pages of online playing clubs attached to a game.
The way the server works is that an initial XML configuration file is loaded on startup, and the entries can be modified at runtime. A cache file can be given to store the modified configuration, so it will survive a server restart.
The server configuration not only contains lists of entries, one for each class, but also a global configuration section which lists user privileges and peer nodes. This section cannot be modified via the metaserver protocol, and it doesn't have to be present, but when it is, it allows to control the amount of modifications performed on the lists of entries. Normally, all operations are allowed, but as soon as a restriction appears in this section, it applies to some or all operations on the given class.
The GGZ server, ggzd, is able to publish both itself and all games which run on it to the metaserver. The first kind of publishing takes place immediately on server startup, and it allows the GGZ core clients to get information about where to find a GGZ server on the net. The class ggz and the category connection are used in such a scenario, whereas the category meta will contain all other known GGZ metaservers.
The second kind helps game authors to spread information about their games without having to run a metaserver on their own. GGZ publishes information about all game rooms, independent of running games, to a category named gameroom for each of the game classes. In addition, a connection category will dynamically contain all the running games. This information is the one which is used by the Metacle service which aggregates information harvested from many metaservers, the GGZ metaserver among them.
The following is a query and update example. For more information, have a look at the dedicated GGZ Metaserver Protocol Specification.
Wildcard query to find out the classes currently stored in the metaserver:
<list />
The result will arrive promptly:
<resultset referer="list">
<class>ggz</class>
<class>tictactoe</class>
</resultset>
Query from the client to the server to return all GGZ servers which understand protocol version 10:
<query class="ggz" type="connection">
<option name="protocol">10</option>
</query>
The answer which contains the only server that does:
<resultset referer="query">
<result uri="ggz://somehost:5689" mode="add">
<option name="preference">100</option>
<option name="location">pennsylvania, us</option>
<option name="speed">768</option>
<option name="protocol">10</option>
</result>
</resultset>
Update request which then adds another server supporting this protocol version:
<update class="ggz" type="connection" username="xxx" password="***"
mode="add" uri="ggz://anotherhost:5688">
<option name="version">0.0.14</option>
<option name="protocol">10</option>
<option name="preference">50</option>
<option name="location">lorraine/france</option>
<option name="speed">60 kB/s</option>
</update>
Apparently, the update went smooth:
<resultset referer="update">
<status>accepted</status>
</resultset>