Packets

Example

a0::Packet pkt("binary payload data");
a0::Packet pkt_with_custom_headers({
    {"header_key", "header_val_a"},
    {"header_key", "header_val_b"},
}, "binary payload data");

pkt.id();       // unique id (uuidv4)
pkt.headers();  // unordered multimap of utf8 key-value pairs
pkt.payload();  // binary payload

What is a packet

A simple container with the following elements: ID, Headers, Payload.
Capable of being serialized and deserialized.

ID

Unique UUID associated with the packet.
Provided on construction and immutable.

Headers

Headers are an unordered multimap of utf8 key-value pairs.

Keys starting with a0_ are reserved for AlephZero internals. Among them are:

  • a0_deps: The ID of dependent packets. May be used as a key multiple times.

  • a0_time_mono: Monotonic/steady clock value. See Time for more info.

  • a0_time_wall: Wall/system clock value (in RFC3339 / ISO8601 format). See Time for more info.

  • a0_transport_seq: Sequence number among all packets in the transport.

  • a0_writer_seq: Sequence number from the writer.

  • a0_writer_id: UUID of the writer.

  • …

Note

Header keys & values are c-strings and include a null terminator.

Payload

Arbitrary binary string.

Serialization Format

The serialized form has four parts:

  • Packet id.

  • Index.

  • Header contents.

  • Payload content.

The index is added for O(1) lookup of headers and the payload.

ID (a0_uuid_t)

num headers (size_t)

offset for hdr 0 key (size_t)

offset for hdr 0 val (size_t)

. . . . . . .

. . . . . . .

offset for hdr N key (size_t)

offset for hdr N val (size_t)

offset for payload (size_t)

hdr 0 key content

hdr 0 val content

. . . . . . .

. . . . . . .

hdr N key content

hdr N val content

payload content

Flat Packet

The headers and payload can be read directly from a serialized buffer.

References