This document is describing the Starez Protocol generic-0.
Warning: We're still working on the protocol, so this might change any moment.
The protocol uses TCP, with an optional SSL layer. The standard port for client to server contact is 7450. The standard port for server to server contact is 7455. The standard port for downloadserver to server contact is 7460. The next layer is the Starez protocol itself.
The protocol is request-response for the greatest part. Exceptions to that are, for example, the currently unimplemented instant messenger part.
The requests and the responses are formatted in the same way. Every request and response first has the case insensitive command, then a colon (:), then a colon seperated list of arguments, where every argument consists of a case insensitive variable name, then an 'equal to' sign (=), then a case sensitive value. For example:
Hello:what=world:who=all people on earth:title=Hello People on Earth:equation=5x\=6
To prevent parsing a protocol metacharacter, you must escape all metacharacters by prepending them with a \.
You should be very careful with user input. A user can deliberately enter malicious data which might disturb information transfer between the server and your client. Therefore it is advisable to substitute every protocol metacharacter with the escaped counterpart. For example, using Perl, you could use the following subroutine.
sub protocolEscape {
my ($input) = @_;
$input =~ s/\\/\\\\/g; # Escape \ to \\
$input =~ s/:/\\:/g; # Escape : to \:
$input =~ s/=/\\=/g; # Escape = to \=
$input =~ s/\n/\\n/g; # Escape newline to \n
return $input;
}
Note, too, that although you will (unless otherwise stated) always receive a reply if you send a command, consisting of the same command, you should not wait for this reply, and the server might send other replies or commands before the reply is sent. For example, in beta testing stages of the server, it was possible to send a command to shut down the server, and the server would answer like this:
C: SHUTDOWN S: SHUTDOWN S: EXIT:why=Server shutting down (Masterserver shutdown (Shutdown requested on socket))
It is part of the (asynchronous) protocol that the server might send data which is not a reply to an existing command.
Errors are sent by the server by replying to the command using the same reply as the command name (e.g. it sends REGISTER for REGISTER errors), and with an argument error and an argument etype. The etype is the type of error that occured, for example 'commands' or 'authentication'. The error is a human readable error, but machines can read some errors to generate their own user-friendly error messages, too. For some errors, there is also an action argument, describing what the server or the client was doing or asking for.
After fifteen seconds of silence, the server sends a PING command with an id parameter. Once a client receives such a parameter, it MUST reply with a PING command, with a pong parameter, whose value is the same as the value of the id parameter of the PING command.
Failure to respond correctly to a PING command within fifteen seconds will result in a disconnect.
If the client wants to, for example to compute lag between the client and the server, it can send a PING command with an id parameter to the server, and it will reply accordingly with an pong parameter.
A Starez protocol session starts with either sending the Client ID or registering for a new one. This is done by the commands CLIENTID and REGISTER respectively. The ClientID is used to distinguish client's; a client may only once register for a clientID and after that MUST remember it and send it to the server using the CLIENTID command, at the beginning of every session.
If a ClientID was already sent or REGISTER was already called, the server will reply with a 'commands' etype error, and with error set to 'ClientID already set'. It might also give an 'internal' etype error. If the CLIENTID command was succesful, the server will reply with a CLIENTID reply with the given clientid as the clientid argument. If no clientid was given as an argument to CLIENTID, the server will reply with a 'missingarg' etype error.
The server will reply with a REGISTER reply to the REGISTER command, with the new clientid in clientid.
After this phase, ClientID handshake is complete and the protocol moves on to user authentication.
To start authentication, the client sends the USER command, with one argument, the username in 'user'. The official server does not yet check anything during the USER command. The username may only consist of letters, numbers and the underscore (it must match to \w or [a-zA-Z0-9_]). If it matches to this, the only reasons for the server to output an error message are when the user is already logged in or when the clientid is unset.
With the PASS command (it has a pass argument, which consists of the plaintext password), however, the server does check if authentication is correct. If so, it answers with a PASS command without any error, and with the user and userid. If a user does not exist, the server answers with error set to "User does not exist", if the password was wrong, error is "Incorrect password".
It is currently impossible to register over the sockets; to register, ask one of the Starez operators.
A client can ask for a list of games using the command GAMELIST. It can have one argument, filters, for information on how these filters work, see the documentation for filters at http://starez.org/docs/server/Net/StarezServer/Games.html#FILTER_SYNTAX.
The server simply responds with zero or more GAME replies and ends with GAMELISTEND. The GAME command can have the arguments id being the game ID, name being the name, version being the games' latest version number, cat being a semicolon seperated list of the games' categories (e.g. 'racing;fun'), about being a one-line description of the game, and status which is the games' status.
For more information, see the documentation for the Net::StarezServer::Games SQL table in which the data is stored, at http://starez.org/docs/server/Net/StarezServer/Games.html#SQL_TABLE_REQUIRED".
The GAMELISTEND has one argument, 'numgames', being the list of games sent back to the client.
To request a download, a client needs a certain 'link' to the file ID. At the moment, the only files the client can request are 'gamefiles', files that belong to a specific version of a game.
To request a gamefile, the client sends GETGAMEFILE with a gameid argument, and optionally a versionid argument. If the versionid argument is not given, the server automatically takes the newest version of the game that belongs to this gameid.
Errors to GETGAMEFILE are given back in the same way as with the other commands, but additionally, an 'eid' argument is set to automatically see what globally went wrong. The following EID's map to the following errors:
EID - Error 1 - Game version wasn't found (you probably supplied an invalid versionid) 2 - Error occured in server version lookup (you did nothing wrong) 3 - Faulty information in database (you did nothing wrong) 4 - Error occured in server game lookup (you did nothing wrong) 5 - 'Not yet implemented', format wasn't set to 'http' (you did nothing wrong) 6 - Game wasn't found (you probably supplied an invalid gameid)
If everything went well, the response will contain a 'format' argument which at the time of writing will always be 'http' since the server doesn't know of any other formats, and a http-url argument which is the URL where the file is stored. Note that it is possible that URLs with an FTP scheme might be given sometime soon, where the format will still be 'http'. You should be prepared for that.
C: DEBUG:iets=anders S: DEBUG:action=debug C: REGISTER S: REGISTER:clientid=1182;6871;8570;6787 C: EXIT S: EXIT
C: DEBUG:iets=anders S: DEBUG:action=debug C: CLIENTID:clientid=1182;6871;8570;6787 S: CLIENTID:clientid=1182;6871;8570;6787 C: EXIT S: EXIT
C: CLIENTID:clientid=1234;5678;9012;3456 S: CLIENTID:etype=internal:action=clientid:error=That Client ID doesn't exist. C: EXIT S: EXIT
This document was written by Sjors Gielen <dazjorz@starez.org>.
