path: root/doc/peers-v2.0.txt

	HAProxy's peers v2.0 protocol 08/18/2016

Author: Emeric Brun ebrun@haproxy.com


I) Encoded Integer and Bitfield.


       0  <= X < 240        : 1 byte  (7.875 bits)  [ XXXX XXXX ]
      240 <= X < 2288       : 2 bytes (11 bits)     [ 1111 XXXX ] [ 0XXX XXXX ]
     2288 <= X < 264432     : 3 bytes (18 bits)     [ 1111 XXXX ] [ 1XXX XXXX ]   [ 0XXX XXXX ]
   264432 <= X < 33818864   : 4 bytes (25 bits)     [ 1111 XXXX ] [ 1XXX XXXX ]*2 [ 0XXX XXXX ]
 33818864 <= X < 4328786160 : 5 bytes (32 bits)     [ 1111 XXXX ] [ 1XXX XXXX ]*3 [ 0XXX XXXX ]




I) Handshake

Each peer try to connect to each others, and each peer is listening
for a connect from other peers.


Client                             Server
	    Hello Message
         ------------------------>

	    Status Message
         <------------------------

1) Hello Message

Hello message is composed of 3 lines:

<protocol> <version>
<remotepeerid>
<localpeerid> <processpid> <relativepid>

protocol: current value is "HAProxyS"
version: current value is "2.0"
remotepeerid: is the name of the target peer as defined in the configuration peers section.
localpeerid: is the name of the local peer as defined on cmdline or using hostname.
processid: is the system process id of the local process.
relativepid: is the haproxy's relative pid (0 if nbproc == 1)

2) Status Message

Status message is a code followed by a LF.

200: Handshake succeeded
300: Try again later
501: Protocol error
502: Bad version
503: Local peer name mismatch
504: Remote peer name mismatch


IV) Messages

Messages:

0 - - - - - - - 8 - - - - - - - 16
  Message Class| Message Type

if Message Type >= 128

0 - - - - - - - 8 - - - - - - - 16 .....
  Message Class|  Message Type  | encoded data length | data

Message Classes:
0:   control
1:   error
10:  related to stick table updates
255: reserved


1) Control Messages Class

Available message Types for class control:
0: resync request
1: resync finished
2: resync partial
3: resync confirm


a) Resync Request Message

This message is used to request a full resync from a peer

b) Resync Finished Message

This message is used to signal remote peer that locally known updates have been pushed, and local peer was considered up to date.

c) Resync Partial Message

This message is used to signal remote peer that locally known updates have been pushed, and but the local peer is not considered up to date.

d) Resync Confirm Message

This message is an ack for Resync Partial or Finished Messages.

It's allow the remote peer to go back to "on the fly" update process.


2) Messages Class

Available message Types for this class are:
0: protocol error
1: size limit reached

a) Protocol Message

To signal that a protocol error occurred. Connection will be shutdown just after sending this message.

b) Size Limit Error Message

To signal that a message is outsized and can not be correctly handled. Connection will be broken.



3) Stick Table Updates Messages Class

Available message Types for this class are:
0: Entry update
1: Incremental entry update
2: table definition
3: table switch
4: updates ack message.


a) Update Message

0 - - - - - - - 8 - - - - - - - 16 .....
 Message class  | Message Type  | encoded data length | data


data is composed like this

0 - - - - - - - 32 .............................
Local Update ID |  Key value | data values ....

Update ID in a 32bits identifier of the local update.

Key value format depends of the table key type:

- for keytype string

0 .................................
encoded string length | string value

- for keytype integer
0 - - - - - - - - - - 32
encoded integer value |

- for other key type

The value length is announced in table definition message
0 ....................
value


b) Incremental Update Message

Same format than update message  except the Update ID is not present, the receiver should
consider that the update ID is an increment of 1 of the previous considered update message (partial or not)


c) Table Definition Message

This message is used by the receiver to identify the stick table concerned by next update messages and
to know which data is pushed in these updates.

0 - - - - - - - 8 - - - - - - - 16 .....
 Message class  | Message Type  | encoded data length | data


data is composed like this

0 ...................................................................
Encoded Sender Table Id | Encoded Local Table Name Length | Table Name | Encoded Table Type | Encoded Table Keylen | Encoded Table Data Types Bitfield


Encoded Sender Table ID present a the id numerical ID affected to that table by the sender
It will be used by "Updates Aknowlegement Messages" and "Table Switch Messages".

Encoded Local Table Name Length present the length to read the table name.

"Table Name" is the shared identifier of the table (name of the current table in the configuration)
It permits the receiver to identify the concerned table. The receiver should keep in memory the matching
between the "Sender Table ID" to identify it directly in case of "Table Switch Message".

Table Type present the numeric type of key used to store stick table entries:
integer
 2: signed integer
 4: IPv4 address
 5: IPv6 address
 6: string
 7: binary

Table Keylen present the key length or max length in case of strings or binary (padded with 0).

Data Types Bitfield present the types of data linearly pushed in next updates message (they will be linearly pushed in the update message)
Known types are
bit
  0: server id
  1: gpt0
  2: gpc0
  3: gpc0 rate
  4: connections counter
  5: connection rate
  6: number of current connections
  7: sessions counter
  8: session rate
  9: http requests counter
 10: http requests rate
 11: errors counter
 12: errors rate
 13: bytes in counter
 14: bytes in rate
 15: bytes out rate
 16: bytes out rate
 17: gpc1
 18: gpc1 rate
 19: server key
 20: http fail counter
 21: http fail rate
 22: gpt array
 23: gpc array
 24: gpc rate array

d) Table Switch Message

After a Table Message Define, this message can be used by the receiver to identify the stick table concerned by next update messages.

0 - - - - - - - 8 - - - - - - - 16 .....
 Message class  | Message Type  | encoded data length | data


data is composed like this


0 .....................
encoded Sender Table Id

c) Update Ack Message

0 - - - - - - - 8 - - - - - - - 16 .....
 Message class  | Message Type  | encoded data length | data

data is composed like this

0 ....................... - - - - - - - - 32
Encoded Remote Table Id | Update Id


Remote Table Id is the numeric identifier of the table on the remote side.
Update Id is the id of the last update locally committed.

If a re-connection occurred, the sender should know they will have to restart the push of updates from this point.

III) Initial full resync process.


a) Resync from local old process

An old soft-stopped process will close all established sessions with remote peers and will try to connect to a new
local process to push all known ending with a Resync Finished Message or a Resync Partial Message (if it it does not consider itself as full updated).

A new process will wait for a an incoming connection from a local process during 5 seconds. It will learn the updates from this
process until it receives a Resync Finished Message or a Resync Partial Message. If it receive a  Resync Finished Message it will consider itself
as fully updated and stops to ask for resync. If it receive a Resync Partial Message it will wait once again for 5 seconds for an other incoming connection from a local process.
Same thing if the session was broken before receiving any "Resync Partial Message" or "Resync Finished Message".

If one of these 5 seconds timeout expire, the process will try to request resync from a remote connected peer (see b). The process will wait until 5seconds
if no available remote peers are found.

If the timeout expire, the process will consider itself ass fully updated

b) Resync from remote peers

The process will randomly choose a remote connected peer and ask for a full resync using a Resync Request Message. The process will wait until 5seconds
if no available remote peers are found.

The chosen remote peer will push its all known data ending with a Resync Finished Message or a Resync Partial Message (if it it does not consider itself as full updated).

If it receives a Resync Finished Message it will consider itself as fully updated and stops to ask for resync.

If it receives a Resync Partial Message, the current peer will be flagged to anymore be requested and any other connected peer will be randomly chosen for a resync request (5s).

If the session is broken before receiving any of these messages any other connected peer will be randomly chosen for a resync request (5s).

If the timeout expire, the process will consider itself as fully updated