Crate msgpacknet

A networking layer based on MessagePack messages.

This crate provides an abstraction layer above TCP that uses MessagePack encoded messages instead of pure byte streams. It also abstracts from addresses and connections and instead uses node identifiers to distinguish and address nodes.

The main struct of this crate is Node which can be parametrized:

• Message - The nodes using this crate communicate via messages that conform to the Message trait. These messages are serialized using serde to the efficient MessagePack format.

• NodeId - This crate identifies and distinguishes nodes based on their NodeId. It is required that all communicating nodes have different ids. Therefore the node ids should be unique. This can be achieved by using the IP address and port number of the main listening socket. Alternatively, a large random number can be used (128 bit should be enough to expect uniqueness).

• InitMessage - The first message exchanged on all connections uses the InitMessage trait instead of Message.

Low-level protocol

When establishing a new connection (either incoming or outgoing), first an InitMessage is sent to the remote node together with the local NodeId and then the initialization message and the remote NodeId is read from that node. After inspecting the initialization message, the connection is either rejected and closed or accepted and added to the connection registry.

When established, the connection can be used to send multiple messages of the Message type.

When idle for a certain timeout or when closing the node by dropping its CloseGuard, the connection is closed.

Examples

To use this crate, first a Node has to be created with a node id and an initialization message which are sent to other nodes as first message.

use msgpacknet::*;
let node = Node::<String, (u64, u64)>::create_default();

Then, sockets can be opened for listening and accepting connections. The method node.listen_defaults() can be used to listen on free ports on IPv4 and IPv6.

node.listen_defaults().expect("Failed to bind");

The actual addresses can be obtained using node.addresses().

println!("Addresses: {:?}", node.addresses());
let addr = node.addresses()[0];

Connections to other nodes can be established via connect(...). The result of the call is the remote side's node id.

let peer_id = node.connect(addr).expect("Failed to connect");

Then, messages can be sent via send(...)...

let msg = "Hello world".to_owned();
node.send(&peer_id, &msg).expect("Failed to send");

...and received via receive().

let event = node.receive();

Structs

CloseGuard	A guard that closes the node when dropped.
ConnectionRequest	The request to establish a connection
ConnectionStats	Statistics of one connection
Node	The node struct
NodeStats	Node statistics

Enums

Error	The error type used througout the crate
Event	The enum used for events

Traits

InitMessage	The trait used for initialization messages
Message	The trait used for messages
NodeId	The trait used for node identifiers