From 0cef65038c2f71044c50fff47fba919e1c788888 Mon Sep 17 00:00:00 2001 From: Konrad Rosenbaum Date: Sun, 29 Jun 2014 20:33:47 +0200 Subject: [PATCH] modify protocol description to reflect new encoding --- doc/protocol.html | 233 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 files changed, 225 insertions(+), 8 deletions(-) diff --git a/doc/protocol.html b/doc/protocol.html index bfc64f4..eef749c 100644 --- a/doc/protocol.html +++ b/doc/protocol.html @@ -13,21 +13,238 @@

Hand-Shake

+

The child process connects to the process that started it - i.e. agent connects to controller, runner connects to agent.

+ + +

Instance Identification

+ +

Each instance in a controller-runner connection network is identified by a UUID that is dynamically generated when that instance starts.

+ + + +

Message Encoding

+ +

Data Encoding

+ +

Integers: are encoded most significant byte first, with a length of 1, 2, 4, or 8 bytes.

+ +

UUIDs: are encoded in the binary format described in RFC 4122 (16 bytes wide, same order as the printed hex digits).

+ +

Byte arrays: are naively encoded as a list of bytes.

+ +

Strings: are encoded in UTF-8 format.

+ +

The special BinStrings are encoded by prefixing them with a single byte containing their length in bytes (excluding the length byte itself). The maximum length is currently 127 bytes, bigger length values are reserved for future extensions and should currently be rejected as invalid.

Framing Format

-(Like HTTP streaming, but bi-directional) -
-30\r\n
-<HelloWorld>hi</HelloWorld>\r\n
-
+

Each frame consists of a length, a header, and optional message body. The length is just a 32bit integer in big endian byte order (most significant first) - it contains the length of the entire message, header plus body, but without the length bytes themselves.

+ +

Message Header

+ +

The message header contains the following fields:

+ + + + + + + + + + + + + + +
Field + Size in Bytes + Description +
Message Type + 1 + defines the type of message; 0 = notification message, no response expected; 1 = request message, needs a response; 2 = response message +
Receiver + 16 + UUID of the receiver instance of this message, set to the null UUID it means the message is handled and broadcast in the same direction it is currently travelling in (up- or down-stream) +
Sender + 16 + UUID of the sender of the message +
Transaction ID + 16 + identifies the transaction of this message - a request and the corresponding response carry the same transaction ID +
Function Name + 1-128 + BinString describing the purpose of the message, Notifications and Requests must carry a Function Name, while successful Responses usually do not have one - unsuccessful Responses may carry a Function Name like "error" (see Function descriptions for details) +
+ +

Body Encoding

+ +

If a body is present it is a data item or hierarchy of data items - usually it is encoded as a dictionary of key-value-pairs.

+ +

Each data item starts with a type description byte:

+ + + + +
Bit +  1 
MSB + 		 2  +  3  +  4  +  5  +  6  +  7  +  8 
LSB
Data + Length
Bytes + 		Element
Size + 		Type Code
+ +

The bits describing Length Bytes can have the following values:

+ + + +

The bits describing Element Size can have the following values:

+ + + +

The bits describing the Type Code can have the following values:

+ + + +

Taken together these are valid type codes:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Binary Code + Hex Code + Description
01 000 000 0x40 + Key-Value Dictionary with one length bytes (max. 255 Key-Value pairs)
10 000 000 0x80 + Key-Value Dictionary with 2 length bytes (max. 64k Key-Value pairs)
11 000 000 0xC0 + Key-Value Dictionary with 4 length bytes (max. 4G Key-Value pairs)
01 000 001 0x41 + List with one length bytes (max. 255 items)
10 000 001 0x81 + List with 2 length bytes (max. 64k items)
11 000 001 0xC1 + List with 4 length bytes (max. 4G items)
01 001 010 0x4A + Byte Array with one length bytes (max. 255 items)
10 001 010 0x8A + Byte Array with one length bytes (max. 64k items)
11 001 010 0xCA + Byte Array with one length bytes (max. 4G items)
01 001 011 0x4B + String with one length bytes (max. 255 items)
10 001 011 0x8B + String with one length bytes (max. 64k items)
11 001 011 0xCB + String with one length bytes (max. 4G items)
00 001 100 0x0C + One byte signed Integer
00 010 100 0x14 + Two byte signed Integer
00 011 100 0x1C + Four byte signed Integer
00 100 100 0x24 + Eight byte signed Integer
00 101 101 0x2D + UUID - 16 bytes, binary notation
+ +

All other Type Codes are currently invalid.

+ +

Encoding of Scalar Values

+ +

For all scalar values (Integers, UUIDs) the type code is immediately followed by the binary encoded value.

+ +

E.g. The byte sequence 14 07 D0 describes the two byte integer 2000 (0x7d0 in hex).

+ +

Encoding of Byte Arrays and Strings

+ +

The type code is followed by the length bytes, which contain the amount of bytes it takes to encode the value. The value bytes follow the length bytes.

+ +

E.g. the byte sequence 4B 0D 48 65 6c 6c c3 b6 20 57 c3 b6 72 6c 64 describes a UTF-8 encoded string with one length byte (4B), with a length of 13 bytes (0D) and the value "Hellö Wörld" ("ö" is encoded as c3b6).

+ +

Encoding of Complex Types

+ +

Complex types are encoded as type code followed by length bytes, followed by values. The length bytes contain the number of sub-items encoded in this complex item.

+ +

For lists each item is just encoded exactly as described above.

+ +

For key-value dictionaries each item is encoded as a key in BinString format, followed by the item encoded as described above. Dictionaries may contain several values for the same key, by encoding several items with the same key.

+ +

Lists and Dictionaries can be recursively nested.

+ +

E.g. 4102 0c2f 4b05 68656c6c6f represents a list with one length byte and 2 items, specifically the one-byte integer 47 (0x2f) and the string "hello".

+ +

E.g. 40 03 0131 0c2a 0131 0c2f 023132 0c2b represents a dictionary with two keys ("1" and "12") and three values: +

+ + + + +

Message Functions

-

Frame content is always XML.

+ -

Generic Messages

+

Generic Functions

-

Whenever a Runner receives a message that it does not understand, it can reject it with the following notification:

+

Whenever a Runner receives a message that it does not understand, it can reject it with the following error response:

 <RejectMsg reason="unknownmessage" message="ProvokeError" reqid="1234z" originalsize="456"/>
-- 
1.7.2.5