|
|
|
Server Description
This page describes a proposed standard extension to the Verse specification. The purpose is to implement a way for servers to describe themselves, in a way suitable for both humans and (somewhat) machines to interpret.
RequirementsThese are the requirements upon the description protocol:
 | Easy to implement using existing Verse technology if possible
| | Support both a human-readable free-form description, and some kind of filterable machine-readable description.
| | Light-weight, easy to implement |
The SolutionWe simply use two textual messages, sent using Verse's existing ping command. Using Verse's ping means that the standard Verse API can be used to send and receive these commands, there is no need to do direct socket-level I/O programming.
The DESCRIBE CommandDESCRIBE is sent to a server, asking it to describe itself. The description has many components, identified by short keywords. Currently, the only defined keywords are:
| DE which is the human-readable description.
| | TA which is a list of comma-separated tags (see below) that describe the server. |
The format of the DESCRIBE command is simply the word 'DESCRIBE', in upper-case ASCII, followed by a space, followed by a comma-separated list of keywords to include in the reply. Asking for an empty description will not cause a response to be sent.
TagsTags are simply short mnemonic words, that describe some aspect of a server or its contents. They are completely user-controlled, assigned by the server operator. Examples of sensible tags might be "edit", "open", "sweden", "commons". The idea is that software can use the tags to filter lists of servers (see the Master Server spec for more on that). Tags should be lower-case, start with a letter, and contain only letters, digits, and underscores.
The DESCRIPTION CommandThe DESCRIPTION command is sent (as a ping) by a Verse server, in response to a DESCRIBE command. It includes the requested information keywords, if they were all understood. The server is free to ignore and omit any keyword, for whatever reason.
The format is 'DESCRIPTION key=value ...]', meaning that the word "DESCRIPTION" in upper-case is followed by a single space, followed by a list of space-separated keyword-assignments. Each such assignment has the keyword on the left side of an equals sign, then an equals sign, followed by the value. The value must be in double quotes if it contains spaces. If it is not quoted, it cannot contain the double quote character. A quoted value can contain quotes or backslashes, escaped by prefixing with a backslash.
ExampleConsider sending 'DESCRIBE DE,TA' to a server whose internal description string is "Open server, for random editing. Restarted daily." and the tags "open", "edit", and "daily" set. The reply would then be 'DESCRIPTION DE="Open server, for random editing. Restarted daily." TA=open,edit,daily'.
Note that the server might chose to quote the tag list as well, but since tags cannot contain spaces, there is no real need to do so.
|
|