Documentation

Overview

RUDP (Reliable UDP) implements psuedo-connections using UDP to achieve many of the benefits of a connection-based protocol like TCP, but crucially allows NAT traversal where TCP cannot. Furthermore, all data is encrypted between both endpoints using a secure, verifiable RSA public key exchange mechanism. This forms part of the PKI which is provided by the MaidSafe Network.

The library's interface is provided in the following files:

• [managed_connections.h][mc] - this is the main API and is discussed in more detail below
• [parameters.h][params] - provides library configuration variables
• [return_codes.h][rc] - In the future, the use of return codes will be replaced with the error-handling mechanisms provided in the MaidSafe-Common library.
• [nat_type.h][nt] - an enumeration of the relevant NAT types the library needs to identify

The library makes heavy use of Boost.Asio, both for network-related operations and asynchronous operations. It also depends on the MaidSafe libraries Common, Private, and Passport.

Background

Two RUDP nodes maintain a psuedo-connection or "managed connection" by continually sending small keepalive control messages between each other. The connection can be closed by either peer by sending a shutdown control message, hence under normal circumstances peers become aware very quickly of a closed connection. Should a fixed number of keepalives fail to be received in a row for a given connection, the node considers the connection to be dead. This is a slower mechanism than using the shutdown message, however, it should be far less common since it is caused by the peer process terminating unexpectedly, or by the peer's network connection dropping unexpectedly for example.

For each connection, a node has an EndpointPair associated with itself and another for the peer. The EndpointPair contains the "local" endpoint (IP/Port as seen inside or behind the router) and the "external" endpoint (IP/Port as seen outside the router). External endpoints are preferred, internals are used in case the external fails and the two peers are both behind a router which disallows hairpinning.

A connection cannot be established between two peers which are both behind routers providing Symmetric NAT. The MaidSafe Routing library handles this by providing a proxy node for each such "hidden" node, and as such the RUDP library doesn't attempt to resolve this issue.

Details

[managed_connections.h][mc] defines three functors; MessageReceivedFunctor, ConnectionLostFunctor, and MessageSentFunctor. The first two must be provided in the ManagedConnections::Bootstrap function, can be called many times by RUDP and are self-explanatory.

The MessageSentFunctor will be invoked exactly once per call to ManagedConnections::Send. It indicates that the associated message has been received by the target peer, (not just enqueued for sending, but actually received), or else has failed. It is anticipated (but not required) that a separate instance of MessageSentFunctor will be passed in each call to Send.

Internally, a ManagedConnections class maintains several (up to Parameters::max_transports) transport objects, each with its own actual network socket. This socket is used to maintain several, (currently up to 50) (see [transport.h][transport], Transport::kMaxConnections) psuedo-connections. Therefore, it is likely that having very few ManagedConnections objects will provide optimal performance.

Bootstrapping a ManagedConnections object can be a slow process, as connections are attempted to the various candidate endpoints until one succeeds.

ManagedConnections::kResiliencePort() provides a network-wide known port which can be used in a disaster-recovery situation. Every ManagedConnections instance attempts to open this port locally. After network segmentation for example, nodes can try to rejoin by attempting to connect to other local nodes, or to direct-connected nodes using this known port.

Further details of the individual functions can be found in the [managed_connections.h][mc] file itself.

[mc]: https://github.com/maidsafe/MaidSafe-RUDP/blob/master/include/maidsafe/rudp/managed_connections.h "#include "maidsafe/rudp/managed_connections.h"" [params]: https://github.com/maidsafe/MaidSafe-RUDP/blob/master/include/maidsafe/rudp/parameters.h "#include "maidsafe/rudp/parameters.h"" [rc]: https://github.com/maidsafe/MaidSafe-RUDP/blob/master/include/maidsafe/rudp/return_codes.h "#include "maidsafe/rudp/return_codes.h"" [nt]: https://github.com/maidsafe/MaidSafe-RUDP/blob/master/include/maidsafe/rudp/nat_type.h "#include "maidsafe/rudp/nat_type.h"" [transport]: https://github.com/maidsafe/MaidSafe-RUDP/blob/master/src/maidsafe/rudp/transport.h "transport.h - not part of the API"