Next: , Previous: , Up: Hacker's guide   [Contents][Index]

3.14 Network protocol

This section describes how Liquid War 6 handles network messages. Note that for now this is purely theorical, more of a draft, a plan, it might change before being implemented.

3.14.1 No server, no client, only nodes

Liquid War 6 does not really have the notion of server or client, any instance of the program can act as both server and client, therefore we use the term node.

A node listens on a given port, in both TCP and UDP, and can connect to other nodes on the same port. The main identifier of a node is its public url, which is typically of the form http://<ip-address>:<port>/. This url is very important for it is (or at least should be) a unique identifier of the node over the network.

Liquid War has 3 ways to communicate:

On each of these channels, messages can be exchanged in two modes, an “out of band” mode (AKA “oob”), and a regular message oriented, here we speak of “connection”.

3.14.2 Out of band messages

There are only 3 out of band messages:

You can test out of band messages by simply connecting on your server with a command like:

telnet localhost 8056

At the telnet prompt, simply type:


and press return, and you should have a description of your node.

The complete syntax of OOB messages is:

<COMMAND> [password] [url]

The password and url parameters are optionnal. password can contain either the plain text password or a checksum calculated from the password which is, for security reasons, seeded with the public url of the node we’re connecting to, so that this password can’t be re-used on another node. url is simply a clue we give to the other node to help find us, the other node will automatically try to detect our IP address and use standard LW6 port 8056, but if for some reason we use a different setting, this is a good way to pass the hint.

Here are examples of valid messages:

PING http://myhost.mydomain:1234/
INFO secret http://myhost.mydomain:1234/
LIST 12ab34cd

If there’s only one argument, the parser will first try and interpret it as a URL. If it’s not parseable that way, it will consider it’s a password. The password, in turn, may be specified as clear text or as a 32-bit checksum.

As far as OOB is concerned, TCP and UDP work almost the same, HTTP is a bit different, the OOB commands are accessed through the following URLs:

OOB messages are usually sent many times in redundant mode on the network, as there’s no tracking of them, sending them through multiple channels ensures they make their way to the right place.

The parser for these messages is located in src/lib/msg/msg-oob.c.

3.14.3 Regular messages overview

All messages that are non-OOB share a common syntax. This is called the “envelope” of messages.

The general syntax is:


Here’s an example:

LW6 0.1.3485 - 2d1dbed7 - 3003300330033003 2002200220022002 - - DATA 8 0 1 1000000035005 3003300330033003 SET 3001 11 1 1 0

In this example, the messages carried is DATA 8 0 1 1000000035005 3003300330033003 SET 3001 11 1 1 0, the rest is part of the envelope protocol.

Here’s what those fields mean:

It’s implemented in src/lib/msg/msg-envelope.c.

3.14.4 Regular control messages

To establish a connection, maintain it, and do the OOB job, a set of control message is used. Those messages carry a bunch of informations about who is sending them, in fact, they just contain the informations that would otherwise be handled by out-of-band messages, but it’s convenient to have the information first-hand rather than relying on the other protocol.

The syntax is:



LW6 0.1.3485 - ffffffff - 1001100110011001 2002200220022002 - - HELLO liquidwar6 0.1.3485 "Davy Crockett" 3485 1001100110011001 http://localhost:8057/ cGF0 RHVtbXkgdGVzdCBub2RlIEE= 0 10 0 5 372057f45b3d2ba5 10005 "Default map" 5 4 10 4 26 1 12 ""

The fields, starting from LW6 up to (and including) <LOGICAL_TO_ID> are part of the envelope, described previously.

The message fields are:

Here are the different possibilities for the <COMMAND> field.

It’s implemented in src/lib/msg/msg-cmd.c.

3.14.5 Regular MISS messages


3.14.6 Regular META messages


3.14.7 Regular DATA messages


3.14.8 Other raw technical stuff (WIP)

TCP messages:

LW6 [<passwd>] <version> <client-id>
<from-id> <to-id> <serial> <i> <n> <sig> MSG1
<from-id> <to-id> <serial> <i> <n> <sig> MSG2

TCP oobs:

<return> # only works anonymous, same as INFO
INFO [<passwd>] [<public-url>]
LIST [<passwd>] [<public-url>]
PING [<passwd>] [<public-url>]

UDP messages:

LW6 [<passwd>] <version> <client-id> <from-id> <to-id> <serial> <i> <n> <sig> MSG1
LW6 [<passwd>] <version> <client-id> <from-id> <to-id> <serial> <i> <n> <sig> MSG2

UDP oobs:

INFO [<passwd>] [<public-url>]
LIST [<passwd>] [<public-url>]
PING [<passwd>] [<public-url>]

HTTP messages:

client id & password passed in HTTP headers


HTTP public URLs:

/ -> index.html

MSG syntax:

<round> <server-id> <command> <arg1> ... <argN>

COMMAND examples:

2 1234abcd1234abcd REGISTER
3 1234abcd1234abcd ADD 5678 YELLOW
4 1234abcd1234abcd SET 5678 20 5
10 1234abcd1234abcd NOP
400 1234abcd1234abcd REMOVE 5678
1000 1234abcd1234abcd UNREGISTER

Sig is a checksum on string:

<from-id> <to-id> <serial> <i> <n> MSG

Next: , Previous: , Up: Hacker's guide   [Contents][Index]