Crate hopr_protocol_session

Expand description

Contains implementation of a Session message protocol.

The implementation in this crate follows the HOPR RFC-0007.

§What is `Session` protocol?

Session protocol is a simple protocol for unreliable networks that implements basic TCP-like features, such as segmentation, retransmission and acknowledgement.

The goal of this protocol is to establish a read-write session between two parties, where one is a message sender and the other one is the receiver. The messages are called frames which are split and are delivered as segments from the sender to the recipient. The session has some reliability guarantees given by the retransmission and acknowledgement capabilities of individual segments.

The UnreliableSocket acts as an unreliable Session protocol socket, taking care only of segmentation, reassembly and sequencing.

The ReliableSocket has (in addition to segmentation, reassembly and sequencing) an internal state that allows acknowledging frames, retransmit unacknowledged frames and/or requesting of missing frame segments. It therefore offers data some delivery guarantees up to the pre-defined frame expiration time.

The above sockets can be constructed on top of any transport that implements [futures::io::AsyncRead] and [futures::io::AsyncWrite], also using the extension methods.

§Overview of the crate

Protocol messages are defined in the protocol submodule.
Socket-like Session interface is defined in socket submodule.
Frames and segments are defined in the frames module.
Segmentation, reassembly and sequencing are defined in the processing submodule.

Modules§

errors: Contains errors thrown from this module.

Structs§

AcknowledgementState: Represents a Session socket state is able to process acknowledgements.
AcknowledgementStateConfig: Configuration object of the AcknowledgementState.
FrameAcknowledgements: Holds the Frame Acknowledgement message. This carries an ordered set of up to FrameAcknowledgements::MAX_ACK_FRAMES frame IDs that has been acknowledged by the counterparty.
FrameInspector: Allows inspecting incomplete frame buffer inside the Reassembler.
NoopTracker: Session socket statistics tracker that does nothing.
Segment: Represents a frame segment.
SegmentId: Convenience type that identifies a segment within a frame.
SegmentRequest: Holds the Segment Retransmission Request message.
SeqIndicator: Carries segment flags and the length of the segment sequence.
SessionSocket: Socket-like object implementing the Session protocol that can operate on any transport that implements [futures::io::AsyncRead] and [futures::io::AsyncWrite].
SessionSocketConfig: Configuration object for SessionSocket.
SocketComponents: Components the [SessionSocket] exposes to a SocketState.
Stateless: Represents a stateless Session socket.

Enums§

AcknowledgementMode: Indicates the acknowledgement mode of a stateful Session socket.
SessionMessageDiscriminants: Auto-generated discriminant enum variants

Traits§

SessionSocketExt: Adaptors for [futures::io::AsyncRead] + [futures::io::AsyncWrite] transport to use Session protocol.
SessionTelemetryTracker: Used to track various statistics of a SessionSocket.
SocketState: Abstraction of the SessionSocket state.

Functions§

session_socket_mtu: Computes the Session Socket MTU, given the MTU C of the underlying socket.

Type Aliases§

FrameId: ID of a [Frame].
ReliableSocket: Represents a socket with reliable delivery.
UnreliableSocket: Represents a stateless (and therefore unreliable) socket.