Crate veloren_network_protocol

Network Protocol

a I/O-Free protocol for the veloren network crate. This crate defines multiple different protocols over UnreliableDrain and UnreliableSink traits, which allows it to define the behavior of a protocol separated from the actual io.

For example we define the TCP protocol on top of Drains and Sinks that can send chunks of bytes. You can now implement your own Drain And Sink that sends the data via tokio’s or std’s implementation. Or you just use a std::mpsc::channel for unit tests without needing a actual tcp socket.

This crate currently defines:

• TCP
• MPSC
• QUIC

eventually a pure UDP implementation will follow

warning: don’t mix protocol, using the TCP variant for actual UDP socket will result in dropped data using UDP with a TCP socket will be a waste of resources.

A channel in this crate is defined as a combination of read and write protocol.

adding a protocol

We start by defining our DataFormat. For most this is prob Vec<u8> or Bytes. MPSC can directly send a msg without serialisation.

Create 2 structs, one for the receiving and sending end. Based on a generic Drain/Sink with your required DataFormat. Implement the SendProtocol and RecvProtocol traits respectively.

Implement the Handshake: InitProtocol, alternatively you can also implement ReliableDrain and ReliableSink, by this, you use the default Handshake.

This crate also contains consts and definitions for the network protocol.

For an example see TcpDrain and TcpSink in the tcp.rs

Modules

_internal

use at own risk, might change any time, for internal benchmarks

error 🔒

event 🔒

frame 🔒

handshake 🔒

message 🔒

metrics 🔒

mpsc 🔒

prio 🔒

quic 🔒

tcp 🔒

types 🔒

util 🔒

Structs

MpscRecvProtocol

MPSC implementation of RecvProtocol

MpscSendProtocol

MPSC implementation of SendProtocol

Pid

Support struct used for uniquely identifying Participant over the Network.

Promises

use promises to modify the behavior of Streams. see the consts in this struct for

ProtocolMetricCache

Cache for ProtocolMetrics, more optimized and cleared up after channel disconnect.

ProtocolMetrics

Use 1 ProtocolMetrics per Network. I will contain all protocol related prometheus information

QuicDataFormat

QuicRecvProtocol

QUIC implementation of RecvProtocol

QuicSendProtocol

QUIC implementation of SendProtocol

Sid

Unique ID per Stream, in one Channel. one side will always start with 0, while the other start with u64::MAX / 2. number increases for each created Stream.

TcpRecvProtocol

TCP implementation of RecvProtocol

TcpSendProtocol

TCP implementation of SendProtocol

Enums

InitProtocolError

All possible Errors that can happen during Handshake InitProtocol

MpscMsg

used for implementing your own MPSC Sink and Drain

ProtocolError

When you return closed you must stay closed!

ProtocolEvent

used for communication with SendProtocol and RecvProtocol

QuicDataFormatStream

Constants

HIGHEST_PRIO

Maximal possible Prio to choose (for performance reasons)

VELOREN_NETWORK_VERSION

When this semver differs, 2 Networks can’t communicate.

Traits

InitProtocol

Handshake: Used to connect 2 Channels.

RecvProtocol

Generic Network Recv Protocol. See: SendProtocol

SendProtocol

Generic Network Send Protocol. Implement this for your Protocol of choice ( tcp, udp, mpsc, quic) Allows the creation/deletions of Streams and sending messages via ProtocolEvent.

UnreliableDrain

This crate makes use of UnreliableDrains, they are expected to provide the same guarantees like their IO-counterpart. E.g. ordered messages for TCP and nothing for UDP. The respective Protocol needs then to handle this. This trait is an abstraction above multiple Drains, e.g. tokio async-std std or even async-channel

UnreliableSink

Sink counterpart of UnreliableDrain

Type Aliases

Bandwidth

guaranteed Bandwidth. See Prio

Cid

ChannelID, unique ID per Channel (Protocol)

Prio

Every Stream has a Prio and guaranteed Bandwidth. Every send, the guarantees part is used first. If there is still bandwidth left, it will be shared by all Streams with the same priority. Prio 0 will be send first, then 1, … till the last prio 7 is send. Prio must be < 8!