bromine/SPECIFICATON.md

# Specification

This specification is split into two parts. The first one explaining how each type is represented in binary form and the
second one specifying the behaviour of event passing and handling.

## Binary Representation of Events

Events store contain two types of data. The header data with the id, name, namespace and referenced event id and the
payload with the associated data. Both the header and the payload have a dynamic length and should be extendable while
ensuring backwards compatibility. The binary layout looks like this:

| Name          | Type      | Length (bytes)             | Description                        |
|---------------|-----------|----------------------------|------------------------------------|
| total_length  | `u64`     | 8                          | total length of the event in bytes |
| header_length | `u16`     | 2                          | length of the event header         |
| header        | `Header`  | header_length              | the header of the event            |
| data          | `Vec<u8>` | total_length - data_length | the payload of the event           |

### Header

| Name             | Type     | Length (bytes)   | Description                                          |
|------------------|----------|------------------|------------------------------------------------------|
| format_version   | `[u8]`   | 3                | version of the specification                         |
| id               | `u64`    | 8                | id of the event                                      |
| ref_id_exists    | `u8`     | 1                | 0xFF indicates that a ref id exists and must be read |
| ref_id           | `u64`    | 8                | ref id. only when the indicator is 0xFF              |
| namespace_length | `u16`    | 2                | length of the namespace. 0 means there's none        |
| namespace        | `String` | namespace_length | namespace of the event                               |
| name_length      | `u16`    | 2                | length of the event name                             |
| name             | `String` | name_length      | name of the event                                    |

The header format ensures that it can be read without knowing its length.
That means that a valid header can be deserialized even if the length of the header bytes
is longer. Additional header fields can therefore be appended without having to worry about
backwards compatibility of the format.


## Binary Representation of Special Payloads

### Raw Payload

The raw payload is a `Vec<u8>` and written as is without serialization or deserialization.


### Tandem Payload

The tandem payload contains two inner payloads which can be serialized and deserialized
independently.
Its layout is as follows:

| Name            | Type  | Length (bytes)  | Description                  |
|-----------------|-------|-----------------|------------------------------|
| payload1_length | `u64` | 8               | length of the first payload  |
| payload1        | `T1`  | payload1_length | the first payload            |
| payload2_length | `u64` | 8               | length of the second payload |
| payload2        | `T2`  | payload2_length | the second payload           |


### Serde Payload

The serde payload stores an encoded payload with additional information about the format
the data was serialized as.

| Name      | Type | Length (bytes) | Description                              |
|-----------|------|----------------|------------------------------------------|
| format_id | `u8` | 1              | the format the payload was serialized as |
| payload   | `T`  | ~              | the serialized payload                   |


## Behaviour

### Receiving events

When receiving an event the handler registered for the name of the event is called.
The event will be ignored if no handler is registered.


### Receiving namespaced events

Namespaced events are handled similar to regular event handling. Instead of searching 
for a handler that handles the event with the given name, first the namespace for the
event is retrieved. On the namespace the handler registered for that specific event is called.
If no namespace for the event namespace is registered or no handler is registered for
the event name, the event will be ignored.


### Receiving replies to emitted events

When emitting an event to a peer, the emitter can wait for an answer to that event.
This is achieved by emitting events as a response to a specific event id.
When an event with a reference event id (ref_id) is received, first the registry is
searched for handlers waiting for a response (by trying to receive from a channel).
If a handler can be found, the event is passed to the handler waiting for the response.
Otherwise, the event will be processed as a regular event.
Events passed from an event handler are always passed as replies to the event that
called that handler.