Module protocol

Session protocol messages

The protocol components are built via low-level types of the frame module, such as Segment and Frame. Most importantly, the Session protocol fixes the maximum number of segments per frame to 8 (see MAX_SEGMENTS_PER_FRAME). Since each segment must fit within a maximum transmission unit (MTU), a frame can be at most eight times the size of the MTU.

The current version of the protocol consists of three messages that are sent and received via the underlying transport:

• Segment message
• Retransmission request
• Frame acknowledgement

All of these messages are bundled within the SessionMessage enum, which is then encoded as a byte array of a maximum MTU size C (which is a generic const argument of the SessionMessage type). The header of the SessionMessage encoding consists of the version byte, followed by the discriminator byte of one of the above messages and then followed by the message length and message’s encoding itself.

Multiple SessionMessages can be read from a binary blob using the SessionMessageIter.

Segment message (Segment)

The Segment message contains the payload Segment of some Frame. The size of this message can range from the minimum message size up to C.

Retransmission request message (Request)

Contains a request for retransmission of missing segments in a frame. This is sent from the segment recipient to the sender, once it realizes some of the received frames are incomplete (after a certain period of time).

The encoding of this message consists of pairs of frame ID and a single byte bitmap of requested segments in this frame. Each pair is therefore ENTRY_SIZE bytes long. There can be at most MAX_ENTRIES in a single Retransmission request message, given C as the MTU size. If the message contains fewer entries, it is padded with zeros (0 is not a valid frame ID). If more frames have missing segments, multiple retransmission request messages need to be sent.

Frame acknowledgement message (Acknowledge)

This message is sent from the segment recipient to the segment sender, to acknowledge that all segments of certain frames have been completely and correctly received by the recipient.

The message consists simply of a frame ID list of the completely received frames. There can be at most MAX_ACK_FRAMES per message. If more frames need to be acknowledged, more messages need to be sent. If the message contains fewer entries, it is padded with zeros (0 is not a valid frame ID).

Structs

FrameAcknowledgements

Holds the Frame Acknowledgement message. This carries an ordered set of up to FrameAcknowledgements::MAX_ACK_FRAMES frame IDs that have been acknowledged by the counterparty.

SegmentIdIter

Iterator over SegmentId in SegmentRequest.

SegmentRequest

Holds the Segment Retransmission Request message. That is an ordered map of frame IDs and a bitmap of missing segments in each frame. The bitmap can cover up a request for up to SegmentRequest::MAX_ENTRIES segments.

SessionMessageIter

Allows parsing of multiple SessionMessages from a borrowed or an owned binary chunk.

Enums

SessionMessage

Contains all messages of the Session sub-protocol.

SessionMessageDiscriminants

Auto-generated discriminant enum variants