| Header Format | ||
|---|---|---|
| Content | Size | Description |
| Length | 4 bytes | header + data not including 4 length bytes |
| Header Length | 2 bytes | length of just the header not including this length value |
| Identifier | 4 bytes | this uniquely identifies any packet from the source |
| Flags | 1 byte | Message Flags |
| ContentType | 1 byte | Indicates generic format of content |
| Headers | variable | type-length-value options (byte, byte, variable) |
| Data | variable | the actual message data |
| Possible Headers | ||
|---|---|---|
| Name | Code | Description |
| Sequence | 1 | a counter that is added and incremented for any ordered packets |
| Timestamp | 2 | a UTC timestamp for network approximate ordering |
| SequenceID | 3 | matched with message src, provides a unique identifier for the stream that sequence number is indexing |
| Hosttime | 4 | if provided, the host time (unixtime) of the remote transport host (not necessarily src of message) |
| Source | 20 | string for the source node name |
| SrcDock | 21 | optional, dock of the sending agent if it wants a return message |
| HMAC | 22 | message authentication code to verify sender |
| DestNode | 50 | string for a destination node, could be multiple headers of this type |
| DestGroup | 51 | string for a destination group, could be multiple headers of this type |
| DestDock | 52 | string for the type of message for next layer protocols, could be multiple headers of this type |
| Content Types | |
|---|---|
| Code | Data Type |
| 0 | No data present |
| 1 | Raw binary data |
| 2 | Plain text |
| 3 | Image data |
| 4 | Protobuf encoded data |
| 5 | YAML encoded data (includes JSON) |
| 6 | XML encoded data |
| Flags | |
|---|---|
| Bit | Flag Type |
| 1 | ACK Packet |
| 2 | Don’t Aggregate |
| 4 | Request ACK |
TCP Preamble of 8 bytes identifies the start of a message for stream based transports (MAGI[0x88]PKT) followed by the serialized message data.
TCP Wire Example Field Data Preamble MAGI[0x88]PKT Length 1234 HeaderLength 29 Identifier 678 Flags 4 (Request ACK) ContentType 5 (YAML content) Header 1 52, 8, “Counters” (DestDock) Header 2 20, 4, “GUIX” (Source) Header 3 51, 5, “nodes” (DestGroup) Data YAML text (1234 bytes - header)
TCP Wire Format 1 2 3 4 5 6 7 8 9 10 11 12 MAGI[0x88]PKT 1234 29 678 4 5 52 8 .... ‘Counters’ 20 4 ‘GUIX’ 51 5 ‘nodes’ 1203 bytes of YAML data
Multicast packets consist of a multicast header and in the case of a data packet, some portion of a serialized MAGI message. The serialized MAGI message is packetized, transmitted and reassembled on the receivers end. The first byte of the multicast header indicates its type.
Neighbors track messages based on the source identifier and multicast ID. The source identifier is either an IPV4 address or the last 32bits of an IPV6 address. The multicast ID is an incrementing counter for each multicast message sent from a source. It has no direction relation to the MAGI message ID, it is only used to reassemble data fragments or request replay within a single multicast transport group. It is expected to increment by 1 for each new message to transmit
Data Packet 1 2 3 4 5 6 7 ... 0 multicastID part number part total Data MulticastID along with source, uniquely identifies a message within in the single multicast transport domain.
Part number indicates the section of the message the contained data came from.
Part total indicates the total number of parts in the message.
For multipart messages, the size of each part is assumed to be equal except for the last part which is the remainder. This allows for multiple fragment sizes as needed. The part number index starts at 1.
Request Packet 1 2 3 4 5 6 7 8 9 ... 1 multicastID source identifier part number [more parts] MulticastID along with source, uniquely identifies the message to retransmit.
The rest of the arguments are a series of part numbers that the sender is missing. If there is single part number of 0, it indicates that all parts of the message are requested.
Each member of the groups receives and processes the request packet. The node matching source will attempt to retransmit the requested parts. If the data is missing or never existed, the source will send a dead packet reply (4). All other nodes that are not the source will check to see if they are scheduled to send a request as well. If so, they avoid sending a duplicate request (NAK avoidance).
Status Packet 1 2 3 4 5 6 7 2 multicastID boot time ID is the last message ID that the source has transmitted. IDs are assumed to increment linearly starting with 1.
Boot time is the local time that the transmitter application started. This is used to determine restarts of the sender and reseting of the ID counter.
Dead Packet 1 2 3 3 multicastID ID is the ID that was requested for retransmit but the data is no longer available.
Routing messages are sent as application data in a MAGI message but are caught and processed by the lower level messaging code. All routing messages are sent to the destination dock MAGIRoute.
A Group Add message is sent when new groups are added to the list that a node is routing for (either directly or routing to another interface). There are three components, the group list as well as a count and a checksum value. The count is the current number of groups that the node has in its full list. The checksum value is a CRC32 checksum of the list in alphabetical order.
Group Add 1 2 3 4 5 6 7 8 9 ... 1 group count group list checksum list of names
A Group Delete message is just like the Group Add message except for the ID field is 2 instead of 1 and indicates that the groups are being removed.
Group Delete 1 2 3 4 5 6 7 8 9 ... 2 group count group list checksum list of names
A Group List is a sending of the complete list of groups that the node is routing for. This is sent in response to Group Resend messages as a method to resynchronize lists.
Group List 1 2 3 4 5 6 7 8 9 ... 3 group count group list checksum list of names
A Group Resend message is sent to another node if it determines that it is missing or has incorrect data. The receiving node shall send a GroupList message in response to bring the nodes back into sync.
Group Resend 1 4
The node route request is broadcast out all transports and routed out all non receiving interfaces. It is sent to find the route to the node named in the message.
Node Route Request 1 ... 5 string name
The node response is broadcast out all transports and routed out all node receiving interfaces.
Node Response 1 6