Struct comm::node::Node

pub struct Node { /* fields omitted */ }

A Node is a peer in the network. It represents another network participant such as ourself. It has an address, and a means to be sent messages. When we receive messages, they come from other nodes.

Currently, a node is connected via UDP socket, but in a future iteration, a Node will be decoupled from the underlying connection method. A Node semantically represents a "participant," i.e. a person, robot, agent, etc. Not a single device, or single IP address.

That participant may be connected to the network via a variety of means. Most common would be over the internet via UDP, but it could very well include more connections via LAN, Bluetooth, shortwave radio, signal lamp, or any other medium that can transmit packets.

This in an important feature to the goals of comm. The comm network should be able to overlay partitioned networks. If a subnetwork is connected via Bluetooth, and at least one participant has a connection to the larger network, all participants are thereby connected to the larger network.

Methods

impl Node

pub fn from_socket_addrs<S: ToSocketAddrs>(
    address: Address,
    socket_address: S
) -> Result<Node, String>

pub fn is_bad(&self) -> bool

Whether the node should be considered bad or unreliable. A bad node has not been heard from in the last MINUTES_UNTIL_QUESTIONABLE minutes, and hasn't responded to at least FAILED_TO_RESPOND_THRESHOLD queries.

Generally, a bad node SHOULD NOT be sent queries, since it's likely to be a waste of network traffic. However, the node should not forgotten until its bucket is full, cannot be split, and a new node is being inserted into it. At that point, it's advantageous to remove the worst node from the bucket and insert another in its place.

If a bad node begins responding to queries, it can become good again. The goal is to minimize wasted network traffic, but also to minimize network volatility. Repeatedly ejecting and reintroducing flaky nodes makes for a volatile network.

TODO: Should we forgive a bad node's pending_query_count() if it becomes good again?

pub fn is_questionable(&self) -> bool

Whether the node is questionable and should therefore be pinged. A questionable node SHOULD still be sent relevant queries, and SHOULD be given every benefit of being treated as if it were good. Questionable only means that we don't know whether it's still good, and we should ask it.

pub fn last_seen(&self) -> Tm

The last time we received either a query or a response from a node.

pub fn pending_query_count(&self) -> usize

How many unanswered queries we've sent to a node.

pub fn received_query(&mut self, transaction_id: TransactionId)

Update the last_received_query timestamp for a node. Any time the network receives a query from a node, this method should be called, passing in the query's TransactionId.

The TID is currently unused, but may be useful in the future.

pub fn received_response(&mut self, transaction_id: TransactionId)

Update the last_received_response timestamp if we're indeed waiting for a response to a query we previously sent with a TID of transaction_id.

If we're not expecting a response from this node for a query we sent previously, this method call is ignored and the timestamp is left as is.

pub fn send(&self, message: Vec<u8>)

Send an encoded message to a node via its UDP socket.

In the future, a node will support numerous connection types, and it should be send using all connections that are live (i.e. not bad)

pub fn sent_query(&mut self, transaction_id: TransactionId)

Records that we're expecting a response from this node for the TID transaction_id.

TODO: Perhaps this method should be rolled together with a method like send_query that records the TID and calls send.

pub fn update_connection(&mut self, other_node: Self)

Update the socket address and port of a node. This is useful for when a node disconnects and reconnects to the internet, or changes IP addresses, etc.

In the future, a node will have n connections instead of one socket address, and we'd just add another to the set, and keep track of which are good, eventually ejecting dead connections.

TODO: this is a temporary measure until a node can support multiple connections. Rather than updating its only connection, it should just add another to the set and keep track of the most reliable connection.

Trait Implementations

impl PartialEq for Node

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Serialize for Node

fn serialize(&self) -> Node

impl Addressable for Node

fn address(&self) -> Address

The Address where self resides.

impl Debug for Node

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.