Expand description
§Postcard-RPC Header Format
Postcard-RPC’s header is made up of three main parts:
- A one-byte discriminant
- A 1-8 byte “Key”
- A 1-4 byte “Sequence Number”
The Postcard-RPC Header is NOT encoded using postcard’s wire format.
§Discriminant
The discriminant field is always one byte, and consists of three subfields
in the form 0bNNMM_VVVV.
- The two msbits are “key length”, where the two N length bits represent a key length of 2^N. All values are valid.
- The next two msbits are “sequence number length”, where the two M length bits represent a sequence number length of 2^M. Values 00, 01, and 10 are valid.
- The four lsbits are “protocol version”, where the four V version bits represent an unsigned 4-bit number. Currently only 0000 is a valid value.
§Key
The Key consists of an fnv1a hash of the path string and schema of the
contained message. These are calculated using the hash module,
and are natively calculated as an 8-byte hash.
Keys may be encoded with variable fidelity on the wire, as follows:
- For 8-byte keys, all key bytes appear in the form
[A, B, C, D, E, F, G, H]. - For 4-byte keys, the 8-byte form is compressed as
[A^B, C^D, E^F, G^H]. - For 2-byte keys, the 8-byte form is compressed as
[A^B^C^D, E^F^G^H]. - For 1-byte keys, the 8-byte form is compressed as
A^B^C^D^E^F^G^H.
The length of the Key is determined by the two NN bits in the discriminant.
The length of the key is usually chosen by the Server, as the server is able to calculate the minimum number of bits necessary to avoid collisions.
When Clients receive a server response, they shall note the Key length used, and match that for all subsequent messages. When Clients make first connection, they shall use the 8-byte form by default.
§Sequence Number
The Sequence Number is an unsigned integer used to match request-response pairs, and disambiguate between multiple in-flight messages.
Sequence Numbers may be encoded with variable fidelity on the wire, always in little-endian order, of 1, 2, or 4 bytes.
The length of the Sequence Number is determined by the two MM bits in the
discriminant.
The length of the key is chosen by the “originator” of the message. For Endpoints this is the client making the request. For Topics, this is the device sending the topic message.
Structs§
- VarHeader
- A variably sized message header
Enums§
- VarKey
- A variably sized header Key
- VarKey
Kind - The kind or length of the variably sized header Key
- VarSeq
- A variably sized sequence number
- VarSeq
Kind - The Kind or Length of a VarSeq