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!