events_encoding

Event encoding and decoding

Structure

Structure of an encoded event

<Event ID on 5 chars> \x1c <Event Argument 1> \x1c <Event Argument 2> \x1c ... \x1c <Event Argument N>

Structure of an Event Argument

<Argument ID on 2 chars> \x1e <Argument Value>

Encoded data types

Basic types

• int : the value is the string representation of the integer (e.g. 42, -7, 0)
• float : the value is the string representation of the float (e.g. 3.14, -0.001, 2.0)
• str : the value is the string itself (e.g. hello, world, example)
• bool : the value is either t (for true) or f (for false)

Complex types

• list : [ <Element 1> \x15 <Element 2> \x15 ... \x15 <Element N> ]

  where each element is encoded according to its type. support nested complex types.

• dict : { <Key 1> \x16 <Value 1> \x15 <Key 2> \x16 <Value 2> \x15 ... \x15 <Key N> \x16 <Value N> }

  where each key is a string and each value is encoded according to its type. support nested complex types.

• tuple : ( <Element 1> \x15 <Element 2> \x15 ... \x15 <Element N> )

  where each element is encoded according to its type. support nested complex types.

Special case of Any type

When the defined type of an element is Any, the actual type used to encode it is the python type determined at runtime. The type is prefixed to the value using a \x19 separator.

Examples

• An int with value 42 is encoded as: 42
• A float with value 3.14 is encoded as: 3.14
• A str with value hello is encoded as: hello
• A bool with value True is encoded as: t
• A bool with value False is encoded as: f
• A Any with value 100 (of type int) is encoded as: int\x19100
• A list[int] with value [1, 2, 3] is encoded as: [1\x152\x153]
• A dict[str, float] with value {"a": 1.0, "b": 2.5} is encoded as: {a\x161.0\x15b\x162.5}
• A tuple[str, bool] with value ("yes", True) is encoded as: (yes\x15t)
• A list[Any] with value [1, "two", 3.0] is encoded as: [int\x191\x15str\x19two\x15float\x193.0]
• A dict[str, Any] with value {"key1": 100, "key2": "value"} is encoded as: {key1\x16int\x19100\x15key2\x16str\x19value}
• A tuple[Any, Any] with value (False, [1, 2, 3]) is encoded as: (bool\x19f\x15list\x19[1\x152\x153])

Examples of encoded events

Event ID: <16>

Arguments:

• Argument ID: 1 (type: datetime, value: 2025-09-18 08:55:55)

Note: datetime is encoded as a unix timestamp (integer).

• Argument ID: 2 (type: str, value: test_server_1206)

Encoded event:

00010 \x1c 01 \x1e 1758178555 \x1d 02 \x1e test_server_1206

The control characters are represented here as \x1c, \x1e, and \x1d for clarity, they only take ONE character each.

Elements are separated by spaces. the actual encoded event does not contain spaces.

Decoding process

To decode an encoded event, first get the the Event ID, to identify the event and its arguments.

Then split the encoded event by the \x1c character to get each argument.

For each argument, split by the \x1e character to separate the Argument ID from its value.

Then, based on the Argument ID, decode the value according to its defined type.

In the case of an argument typed as Any, first split the value by the \x19 character to get the actual type and then decode the value accordingly.