Crate msgpacknet [−] [src]
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 theMessage
trait. These messages are serialized usingserde
to the efficient MessagePack format.NodeId
- This crate identifies and distinguishes nodes based on theirNodeId
. 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 theInitMessage
trait instead ofMessage
.
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 |