central/PROTOCOL

Architecture and Protocol Specification



For the sake of easyness we call the "central interconnection point" server just "central".

Connect to the central interconnection point.

Authentication is done via 'authorized_keys' as explained in the README or above. Once you are authenticated, the actual
authorization (i.e. the permissions you have) is done on the server side. So, when you connect with your client, you are
allowed to send a specific set of commands, depending on the assigned role.

Available client commands are shown upon connection to your client.

Client Commands that you can send

------------------------------------------------------------------------------------------------------------------------
C <chattext>

example: C Hey mihawk, have you seen my latest underwear? It has the Simpsons family printed on it!

Every client will receive a <chattext>. This is a connection-wide broadcast with no real meaning. It is only meant for
having a chat with other connected debug connections. So, it's good for developing and having party chat.

reply-format: C <your-name>: <your-chattext>

reply-example: C paul_specbot: Hey mihawk, have you seen my latest underwear? It has the Simpsons family printed on it!
------------------------------------------------------------------------------------------------------------------------
PART

Central will gracefully close your connection.
------------------------------------------------------------------------------------------------------------------------
PING

A command to test if connections and processing are still alive. Central will answer with "PONG [optional text]" to show
it's still kicking around and working. We encourage all clients to send PING to central on a regular basis of about
90 seconds. So your client will notice broken connections to begin reconnecting. We want a robust network. All clients
need to find their connections by themselves.

reply: PONG
------------------------------------------------------------------------------------------------------------------------
REQ_BC <network>,<frequency>,<source/channel>,'<nickname>','<message>'

example: REQ_BC QWalt,-qw-,qw://84.34.166.158:28001 3/4,'Panjabi','noob 2on2'

We request central to fan out a message broadcast with the given specifics. Central will calculate a md5-hash for this
request as an identifier and reply it to you. From now on, this request is always referenced by the md5-hash. Meanwhile,
in the background, central will send BC commands to the other clients. Those clients will answer with BC_RE with reached
user count to central. Central will forward those counts to you with BC_RE. It is up to your client to interprete and
sum up those counts after some seconds (3s) of timeout. Perhaps give those counts back to the originating human user who
sent the message. It's not needed, but it's nice.

reply-format:
BC_ID <req-md5hash> for: <network>,<frequency>,<source/channel>
BC_RE <req-md5hash> <Key1>=<Count1>[,<Key2>=<Count2>][,<Key3>=<Count3>]

reply-example:
BC_ID 0043d5c53120922b4323235fa8f839d5 for: QWalt,-qw-,qw://84.34.166.158:28001 3/4
BC_RE 0043d5c53120922b4323235fa8f839d5 Users=283,Channels=69
BC_RE 0043d5c53120922b4323235fa8f839d5 Users=32,Channels=13,Players=8,Servers=2
BC_RE 0043d5c53120922b4323235fa8f839d5 Players=41,Servers=12
------------------------------------------------------------------------------------------------------------------------
REQ_DNS <serverip>:<serverport> [server-type]

example: REQ_DNS 85.235.251.94:27501 qw

Central will try to determine how to name that game server. If a game server name is not already cached and the data is
not young enough then central will request a status from that game server to find its game server name. Inside the
game server name may be a short hostname that resolves to its ip. It also tries the reverse dns lookup of that ip.
The shorter the name, the better. If it can't establish a good hostname, it will return you the ip address.
[server-type] is not yet implemented. It defaults to quakeworld ("qw").

reply-format: DNS_RE <serverip>:<serverport> <good name>

reply-example: DNS_RE 85.235.251.94:27501 qw.foppa.dk
------------------------------------------------------------------------------------------------------------------------
WHO

This will show you who is connected to central. It's a multi-line reply consisting of the <name> of the client and
its roles. <role1> is always specified. More roles, if available, are shown as a comma-separated list. For
human-readability there should always be a space after that comma. It's optional.

reply-format: WHO_RE <name> ROLES: <role1>[, more-roles]

reply-example:
WHO_RE paul_eggdrop ROLES: everyone, broadcast
WHO_RE paul_specbot ROLES: everyone, broadcast, specbot
------------------------------------------------------------------------------------------------------------------------



Server Commands

Aside from the above replies from central to you, central can send you commands _initially_, that you, as a client, need
to understand and react or reply to. And, some commands are just "informational", which means, that you don't need to
reply. You can act on them optionally.

------------------------------------------------------------------------------------------------------------------------
HELLO <hello message>

example: HELLO Hi user 'paul_specbot'! How are you? I'm '0.6em_specservers_dupe_election'

Central says hello to you. It's supposed to be the very first message upon connection. If it's not the first. Well,
either it's missing :), or something is very wrong. It normally carries the server version. But it is not required.
------------------------------------------------------------------------------------------------------------------------
ROLES <role1>[, more-roles]

example: ROLES everyone, broadcast, specbot

Central tells you what roles you possess. Depending on the role it will tell you what commands or replies you may send.
This is part of letting the client know his authorization.
------------------------------------------------------------------------------------------------------------------------
COMMANDS <command1>[, more-commands]

example: COMMANDS PING, WHO, C, PART, REQ_BC, BC_RE, ASSIGN_RE, UNASSIGN_RE, ASSIGNMENTS_RE, REQ_DNS, MAXSERVERS_RE

Central tells you what commands or replies you may send. Other commands will trigger a command help.
------------------------------------------------------------------------------------------------------------------------
REQ_MAXSERVERS <request info text>

example: REQ_MAXSERVERS how many can you do?

You have a specbot role and central wants to know, how many servers you want to observe at maximum. So you answer with a
max server count.

reply-format: MAXSERVERS_RE <max server count>

reply-example: MAXSERVERS_RE 50
------------------------------------------------------------------------------------------------------------------------
REQ_ASSIGNMENTS [info text about the request]

example: REQ_ASSIGNMENTS gimme all your servers

Central wants to know your current servers that you observe. Thus, central determines your current server count and
may assign or unassign you more or less servers depending on your maximum server count. The reply is a multi-line reply
as there normally are many servers that are assigned to one specbot.
Central is not yet intelligent enough to do that. So this feature is not yet implemented.

reply-format: ASSIGNMENTS_RE <serverip>:<serverport>,<s-p>,<ping>

reply-example:
ASSIGNMENTS_RE 123.123.13.13:27500,1,32
ASSIGNMENTS_RE 234.234.24.24:27501,0,35
------------------------------------------------------------------------------------------------------------------------
REQ_ASSIGN <serverip>:<serverport>[,s-p]   (NYI)

example: REQ_ASSIGN 46.41.133.108:27502

Central wants you to monitor this server. You normally reply with an OK-message. If you use any other word than 'OK' it
failed. If it failed, it's not a bad thing. Central will just know, 'ok, this bot won't take any more servers from me'.

reply-format: ASSIGN_RE <serverip>:<serverport> <OK|fail> <reason>

reply-example:
ASSIGN_RE 46.41.133.108:27502 OK all good, I take it
ASSIGN_RE 46.41.133.108:27502 blah I hate you
------------------------------------------------------------------------------------------------------------------------
REQ_UNASSIGN <serverip>:<serverport>   (NYI)

example: REQ_UNASSIGN 46.41.133.108:27502

Central wants you to stop monitoring this server. If you received the unassign-command by error, and you currently don't
monitor that server, then always reply with OK, since the wanted status is that you don't monitor it. Central wants to
know you achieved that status. If you use any other word than 'OK' it failed.

reply-format: UNASSIGN_RE <serverip>:<serverport> <OK|fail> <reason>

reply-example:
UNASSIGN_RE 46.41.133.108:27502 OK all good, I'm leaving
UNASSIGN_RE 46.41.133.108:27502 yadda no way, I can't take it off
------------------------------------------------------------------------------------------------------------------------
BC <req-md5hash> <network>,<frequency>,<source/channel>,'<nickname>','<message>'

example: BC cbb8aa4a9fdce0c8c3f811f19d716d22 QWalt,-qw-,qw://qw.foppa.dk:27501 1/2,'f4t833','1v1 here'

Central wants you to write this message, with given request md5-hash, to your users in the specified network and
frequency. Of course, request md5-hash, network and frequency are identifiers which are to be taken seriously. Whereas,
the source/channel may be a free text. So, after you sent out the message, you shall instantly reply with counts of how
many people this message reached. Central will take those counts and forward it to the originating network client which
issued the REQ_BC command. The originating network client will have a small timeout (3s), after which it interpretes
those key-value-pairs and calculates the final counts.

reply-format: BC_RE <req-md5hash> <Key1>=<Count1>[,<Key2>=<Count2>][,<Key3>=<Count3>]

reply-example:
BC_RE cbb8aa4a9fdce0c8c3f811f19d716d22 Players=37,Servers=10
BC_RE cbb8aa4a9fdce0c8c3f811f19d716d22 Users=12,Channels=2
------------------------------------------------------------------------------------------------------------------------
PING [info text about the request]

example: PING alive?

Central will issue a PING command if your client has not issued a PING command within the last 180 seconds. There is no
need to answer. By writing the message to the socket of your client it will certainly fail if the connection died
earlier. There is no consequence of not replying. It's just a measure to find broken connections. We still encourage
your client to send PING (see above) to central on a regular basis of about 90 seconds. So your clients will notice
broken connections to begin reconnecting. We want a robust network. All clients need to find their connections by
themselves.
------------------------------------------------------------------------------------------------------------------------