Crate routing

Client and node implementations for a resilient decentralised network.

The network is based on the kademlia_routing_table and uses the XOR metric to define the "distance" between two XorNames. XorNames are used as addresses of nodes, clients as well as data.

Messages are exchanged between authorities, where an Authority can be an individual client or node, or a group of nodes. In both cases, messages are cryptographically signed by the sender, and in the latter case it is verified that a sufficient number of group members agree on the message: Only if that quorum is reached, the message is delivered. In addition, each message has a unique ID, and is delivered only once.

Group authorities are also addressed using a single XorName. The members of that group are the nodes that are closest to that name. Since nodes are assigned their name by the network, this provides redundancy and resilience: A node has no control over which group authorities it will be a member of, and without a majority in the group it cannot forge a message from that group.

The library also provides different types for the messages' data.

Usage

A decentralised service based on the routing library uses Client to send requests to the network of nodes and receive responses.

Node is used to handle and send requests within that network, and to implement its functionality, e. g. storing and retrieving data, validating permissions, managing metadata etc.

Client creation

A client's name is a hash of its public keys. Upon creation, the client will attempt to connect to the network through any node, and exchange public keys with it. That node becomes a bootstrap node for the client, and messages to and from the client will be routed over it.

use std::sync::mpsc;
use routing::{Client, Event, FullId};

let (sender, _receiver) = mpsc::channel::<Event>();
let full_id = FullId::new(); // Generate new keys.
let _ = Client::new(sender, Some(full_id.clone())).unwrap();

let _ = full_id.public_id().name();

Messages can be sent using the methods of client, and received as Events from the receiver.

Node creation

Creating a node looks even simpler:

use std::sync::mpsc;
use routing::{Node, Event};

let (sender, _receiver) = mpsc::channel::<Event>();
let _ = Node::builder().create(sender).unwrap();

Upon creation, the node will first connect to the network as a client. Once it has client status, it requests a new name from the network, and then integrates itself in the network with that new name, adding close nodes to its routing table.

Messages can be sent using the methods of node, and received as Events from the receiver. The node can act as an individual node or as part of a group authority. Sending a message as a group authority only has an effect if sufficiently many other nodes in that authority send the same message.

Sequence diagrams

• Bootstrapping
• GetCloseGroup
• Churn (NewNode)
• Tunnel

Modules

client_errors	Error communication between vaults and core
messaging	Messaging infrastructure

Structs

Client	Interface for sending and receiving messages to and from a network of nodes in the role of a client.
FullId	Network identity component containing name, and public and private keys.
ImmutableData	An immutable chunk of data.
MessageId	Unique ID for messages
Node	Interface for sending and receiving messages to and from other nodes, in the role of a full routing node.
NodeBuilder	A builder to configure and create a new Node.
PlainData	Plain data with a name and a value.
PublicId	Network identity component containing name and public keys.
StructuredData	Mutable structured data.
XorName	A XOR_NAME_BITS-bit number, viewed as a point in XOR space.

Enums

Authority	An entity that can act as a source or destination of a message.
Data	This is the data types routing handles in the public interface
DataIdentifier	An identifier to address a data chunk.
Event	An Event raised by a Node or Client via its event sender.
InterfaceError	The type of errors that can occur if routing is unable to handle a send request.
Request	Request message types
Response	Response message types
RoutingError	The type of errors that can occur during handling of routing events.
XorNameFromHexError	Errors that can occur when decoding a XorName from a string.

Constants

GROUP_SIZE	The group size for the routing table. This is the maximum that can be used for consensus.
MAX_STRUCTURED_DATA_SIZE_IN_BYTES	Maximum allowed size for a Structured Data to grow to
QUORUM_SIZE	The quorum for group consensus.
TYPE_TAG_DNS_PACKET	Structured Data Tag for DNS Packet Type
TYPE_TAG_SESSION_PACKET	Structured Data Tag for Session Packet Type
XOR_NAME_BITS	Constant bit length of XorName.
XOR_NAME_LEN	Constant byte length of XorName.

Traits

Cache

A cache that stores Responses keyed by Requests. Should be implemented by layers above routing.