Crate routing [−] [src]
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 XorName
s. XorName
s 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 collection of nodes called a "section", or a subset of a section called a "group".
In all cases, messages are cryptographically signed by the sender, and in the case of sections
and groups, it is verified that a sufficient number of 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.
Section and group authorities are also addressed using a single XorName
. The members are the
nodes that are closest to that name. Sections contain a minimum number of nodes with the minimum
value specified as a network-wide constant. Groups are of fixed size, defined as the above
minimum section size. Since nodes are assigned their name by the network, this provides
redundancy and resilience: a node has no control over which section or group authority it will
be a member of, and without a majority in the section or group it cannot forge a message from
there.
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 min_section_size = 8; let (sender, _receiver) = mpsc::channel::<Event>(); let full_id = FullId::new(); // Generate new keys. let _ = Client::new(sender, Some(full_id.clone()), min_section_size).unwrap(); let _ = full_id.public_id().name();
Messages can be sent using the methods of client
, and received as Event
s from the
receiver
.
Node creation
Creating a node looks even simpler:
use routing::Node; let min_section_size = 8; let _ = Node::builder().create(min_section_size).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 Event
s from the receiver
.
The node can act as an individual node or as part of a section or group authority. Sending a
message as a section or group authority only has an effect if sufficiently many other nodes in
that authority send the same message.
Sequence diagrams
Modules
client_errors |
Error communication between vaults and core |
messaging |
Messaging infrastructure |
Macros
try_ev |
A version of |
try_evx |
A version of |
Structs
AppendedData |
An appended data item, pointing to another data chunk in the network. |
Client |
Interface for sending and receiving messages to and from a network of nodes in the role of a client. |
Evented |
An Evented |
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 |
NullCache |
A no-op implementation of the |
Prefix |
A section prefix, i.e. a sequence of bits specifying the part of the network's name space consisting of all names that start with this sequence. |
PrivAppendableData |
Private appendable data. |
PrivAppendedData |
A private appended data item: an encrypted |
PubAppendableData |
Public appendable data. |
PublicId |
Network identity component containing name and public keys. |
RoutingTable |
A routing table to manage contacts for a node. |
StructuredData |
Mutable structured data. |
XorName |
A |
Enums
AppendWrapper |
An |
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 |
Filter |
The type of access filter for appendable data. |
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. |
RoutingTableError |
Routing table error variants. |
XorNameFromHexError |
Errors that can occur when decoding a |
Constants
MAX_IMMUTABLE_DATA_SIZE_IN_BYTES |
Maximum allowed size for a serialised Immutable Data (ID) to grow to |
MAX_PRIV_APPENDABLE_DATA_SIZE_IN_BYTES |
Maximum allowed size for a private appendable data to grow to |
MAX_PUB_APPENDABLE_DATA_SIZE_IN_BYTES |
Maximum allowed size for a public appendable data to grow to |
MAX_STRUCTURED_DATA_SIZE_IN_BYTES |
Maximum allowed size for a Structured Data to grow to |
NO_OWNER_PUB_KEY |
A signing key with no matching private key. Passing ownership to it will make a chunk effectively immutable. |
QUORUM |
The quorum, as a percentage of the number of members of the authority. |
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 |
XOR_NAME_LEN |
Constant byte length of |
Traits
Cache |
A cache that stores |
EventStream |
Trait to fake a channel. |
Xorable |
A sequence of bits, as a point in XOR space. |