the central protocol. initial description

PROTOCOL

@@ -0,0 +1,198 @@
+
+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.
+
+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.
+------------------------------------------------------------------------------------------------------------------------