Module state

Session protocol state machine

The protocol always forms a middle layer between a lower layer transport (such as an unreliable UDP-like network) and any upstream protocol. The communication with the lower layer is done via SessionState; the upper layer is using the SessionSocket to pass data with the Session protocol.

Instantiation

The instantiation of the protocol state machine is done by creating the SessionSocket object, by providing it an underlying transport writer and its MTU C. The protocol can be instantiated over any transport that implements [AsyncWrite] + [AsyncRead] for sending and receiving raw data packets.

Passing data between the protocol and the upper layer

The SessionSocket exposes as [AsyncRead] + [AsyncWrite] and can be used to read and write arbitrary data to the protocol. If the writer is closed, the session is closed as well.

Passing of data between the protocol and the lower layer

As long as the underlying transport implements [AsyncRead] + [AsyncWrite], the SessionSocket automatically polls data from the underlying transport, and sends the data to the underlying transport as needed.

Protocol features

Data segmentation

Once data is written to the SessionSocket, it is segmented and written automatically to the underlying transport. Every writing to the SessionSocket corresponds to a Frame.

Frame reassembly

The receiving side performs frame reassembly and sequencing of the frames. Frames are never emitted to the upper layer transport out of order, but frames can be skipped if they exceed the frame_expiration_age.

Frame acknowledgement

The recipient can acknowledge frames to the sender once all its segments have been received. This is done with a FrameAcknowledgements message sent back to the sender.

Segment retransmission

There are two means of segment retransmission:

Recipient requested retransmission

This is useful in situations when the recipient has received only some segments of a frame. At this point, the recipient knows which segments are missing in a frame and can initiate SegmentRequest sent back to the sender. This method is more targeted, as it requests only those segments of a frame that are needed. Once the sender receives the segment request, it will retransmit the segments in question over to the receiver. The recipient can make repeating requests on retransmission, based on the network reliability. However, retransmission requests decay with an exponential backoff given by backoff_base and rto_base_receiver timeout in SessionConfig up until the frame_expiration_age.

Sender initiated retransmission

The frame sender can also automatically retransmit entire frames (= all their segments) to the recipient. This happens if the sender (within a time period) did not receive the frame acknowledgement and the recipient also did not request retransmission of any segment in that frame. This is useful in situations when the recipient did not receive any segment of a frame. Once the recipient receives at least one segment of a frame, the recipient requested retransmission is the preferred way.

The sender can make repeating frame retransmissions, based on the network reliability. However, retransmissions decay with an exponential backoff given by backoff_base and rto_base_sender timeout in SessionConfig up until the frame_expiration_age. The retransmissions of a frame by the sender stop if the frame has been acknowledged by the recipient or the recipient started requesting segment retransmission.

Retransmission timing

Both retransmission methods will work up until frame_expiration_age. Since the recipient-request-based method is more targeted, at least one should be allowed to happen before the sender-initiated retransmission kicks in. Therefore, it is recommended to set the rto_base_sender at least twice the rto_base_receiver.

The above protocol features can be enabled by setting SessionFeature options in the configuration during SessionSocket construction.

For diagrams of individual retransmission situations, see the docs on the SessionSocket object.

Structs

SessionConfig

Configuration of Session protocol.

SessionSocket

Represents a socket for a session between two nodes bound by the underlying network transport and the maximum transmission unit (MTU) of C.

SessionState

Contains the cloneable state of the session bound to a SessionSocket.

Enums

SessionFeature

Represents individual Session protocol features that can be enabled.