From 82229ac063cc65d26c1ef13ca43b760ef61b52d9 Mon Sep 17 00:00:00 2001 From: rachel-rose Date: Tue, 6 Apr 2021 11:26:23 +0200 Subject: [PATCH] more verbose doc on each protocol. explains the role of each protocol in a network connection. --- src/net/protocols/protocol_address.rs | 13 +++++++++---- src/net/protocols/protocol_jobs_manager.rs | 4 +++- src/net/protocols/protocol_ping.rs | 12 ++++++++++-- src/net/protocols/protocol_seed.rs | 5 +++++ src/net/protocols/protocol_version.rs | 9 ++++++++- 5 files changed, 35 insertions(+), 8 deletions(-) diff --git a/src/net/protocols/protocol_address.rs b/src/net/protocols/protocol_address.rs index b398db0d3..ae61d1387 100644 --- a/src/net/protocols/protocol_address.rs +++ b/src/net/protocols/protocol_address.rs @@ -8,15 +8,20 @@ use crate::net::messages; use crate::net::protocols::{ProtocolJobsManager, ProtocolJobsManagerPtr}; use crate::net::{ChannelPtr, HostsPtr}; -/// Protocol for address and get-address messages. +/// Protocol for address and get-address messages. Implements how nodes exchange +/// connection information about other nodes on the network. Address and +/// get-address messages are exchanged continually alongside ping-pong messages +/// as part of a network connection. +/// +/// Protocol starts by creating a subscription to address and get address +/// messages. Then the protocol sends out a get address message and waits for an +/// address message. Upon receiving an address messages, nodes add the +/// address information to their local store. pub struct ProtocolAddress { channel: ChannelPtr, - addrs_sub: MessageSubscription, get_addrs_sub: MessageSubscription, - hosts: HostsPtr, - jobsman: ProtocolJobsManagerPtr, } diff --git a/src/net/protocols/protocol_jobs_manager.rs b/src/net/protocols/protocol_jobs_manager.rs index edd7d5c47..68ef85352 100644 --- a/src/net/protocols/protocol_jobs_manager.rs +++ b/src/net/protocols/protocol_jobs_manager.rs @@ -11,7 +11,9 @@ use crate::system::ExecutorPtr; /// Pointer to protocol jobs manager. pub type ProtocolJobsManagerPtr = Arc; -/// Manages the tasks for the network protocol. +/// Manages the tasks for the network protocol. Used by other connection +/// protocols to handle asynchronous task execution across the network. Runs all +/// tasks that are handed to it on an executor that has stopping functionality. pub struct ProtocolJobsManager { name: &'static str, channel: ChannelPtr, diff --git a/src/net/protocols/protocol_ping.rs b/src/net/protocols/protocol_ping.rs index 491f6450c..3c5feafa1 100644 --- a/src/net/protocols/protocol_ping.rs +++ b/src/net/protocols/protocol_ping.rs @@ -10,11 +10,19 @@ use crate::net::protocols::{ProtocolJobsManager, ProtocolJobsManagerPtr}; use crate::net::utility::sleep; use crate::net::{ChannelPtr, SettingsPtr}; -/// Protocol for ping-pong keep-alive messages. +/// Protocol for ping-pong keep-alive messages. Implements ping message and pong +/// response. These messages are like the network heartbeat- they are sent +/// continually between nodes, to ensure each node is still alive and active. +/// Ping-pong messages ensure that the network doesn't +/// time out. +/// +/// Protocol starts by creating a subscription to ping and pong messages. Then +/// it starts a loop with a timer and runs ping-pong in the task manager. It +/// sends out a ping and waits for pong reply. Then waits for ping and replies +/// with a pong. pub struct ProtocolPing { channel: ChannelPtr, settings: SettingsPtr, - jobsman: ProtocolJobsManagerPtr, } diff --git a/src/net/protocols/protocol_seed.rs b/src/net/protocols/protocol_seed.rs index 02d3a61ff..731e7a33e 100644 --- a/src/net/protocols/protocol_seed.rs +++ b/src/net/protocols/protocol_seed.rs @@ -8,6 +8,11 @@ use crate::net::{ChannelPtr, HostsPtr, SettingsPtr}; /// Seed server protocol. Seed server is used when connecting to the network for /// the first time. Returns a list of IP addresses that nodes can connect to. +/// +/// To start the seed protocol, we create a subscription to the address message, +/// and send our address to the seed server. Then we send a get-address message +/// and receive an address message. We add these addresses to our internal +/// store. pub struct ProtocolSeed { channel: ChannelPtr, hosts: HostsPtr, diff --git a/src/net/protocols/protocol_version.rs b/src/net/protocols/protocol_version.rs index f70d3454d..2d782432e 100644 --- a/src/net/protocols/protocol_version.rs +++ b/src/net/protocols/protocol_version.rs @@ -10,7 +10,14 @@ use crate::net::utility::sleep; use crate::net::{ChannelPtr, SettingsPtr}; /// Protocol for version information handshake between nodes at the start of a -/// connection. +/// connection. Implements the process for exchanging version information +/// between nodes. This is the first step when establishing a p2p connection. +/// +/// The version protocol starts of by instantiating the protocol and creating a +/// new subscription to version and version acknowledgement messages. Then we +/// run the protocol. Nodes send a version message and wait for a version +/// acknowledgement, while asynchronously waiting for version info from the +/// other node and sending the version acknowledgement. pub struct ProtocolVersion { channel: ChannelPtr, version_sub: MessageSubscription,