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 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 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 (sender, receiver) = mpsc::channel::<Event>();
let full_id = FullId::new(); // Generate new keys.
let client = Client::new(sender, Some(full_id), None).unwrap();

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 routing::Node;

let node = Node::builder().create().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 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

messaging

Messaging infrastructure

sha3

SHA-3 type alias.

Macros

log_or_panic

This macro will panic with the given message if compiled with "use-mock-crust", otherwise it will simply log the message at the requested level.

Structs

AccountInfo

Account information

Client

Interface for sending and receiving messages to and from a network of nodes in the role of a client.

Config

Configuration for routing

DevConfig

Extra configuration options intended for developers

EntryActions

Helper struct to build entry actions on MutableData

FullId

Network identity component containing name, and public and private keys.

ImmutableData

An immutable chunk of data.

MessageId

Unique ID for messages

MutableData

Mutable data.

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.

NullCache

A no-op implementation of the Cache trait. Throws everything away on put and always returns None on get.

PermissionSet

Set of user permissions.

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.

PublicId

Network identity component containing name and public keys.

RoutingTable

A routing table to manage contacts for a node.

Value

A value in MutableData

XorName

A XOR_NAME_BITS-bit number, viewed as a point in XOR space.

Enums

AccountPacket

Account packet that is used to provide an invitation code for registration. After successful registration it should be replaced with AccountPacket::AccPkt with the contents of account_ciphertext as soon as possible to prevent an invitation code leak.

Action

Action a permission applies to

Authority

An entity that can act as a source or destination of a message.

ClientError

Errors in operations involving Core and Vaults

EntryAction

Action performed on a single entry: insert, update or delete.

EntryError

Entry error for ClientError::InvalidEntryActions.

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.

RoutingTableError

Routing table error variants.

User

Subject of permissions

XorNameFromHexError

Errors that can occur when decoding a XorName from a string.

Constants

ACC_LOGIN_ENTRY_KEY

Key of an account data in the account packet

MAX_IMMUTABLE_DATA_SIZE_IN_BYTES

Maximum allowed size for a serialised Immutable Data (ID) to grow to

MAX_MUTABLE_DATA_ENTRIES

Maximum allowed entries in MutableData

MAX_MUTABLE_DATA_SIZE_IN_BYTES

Maximum allowed size for MutableData (1 MiB)

MIN_SECTION_SIZE

Default minimal section size.

NO_OWNER_PUB_KEY

A signing key with no matching private key. Passing ownership to it will make a chunk effectively immutable.

QUORUM_DENOMINATOR

See QUORUM_NUMERATOR.

QUORUM_NUMERATOR

Quorum is defined as having strictly greater than QUORUM_NUMERATOR / QUORUM_DENOMINATOR agreement; using only integer arithmetic a quorum can be checked with votes * QUORUM_DENOMINATOR > voters * QUORUM_NUMERATOR.

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.

EventStream

Trait to fake a channel.

Xorable

A sequence of bits, as a point in XOR space.

Type Definitions

BootstrapConfig

Reexports crust::Config