net: add hostlist documentation

src/net/hosts/mod.rs

@@ -16,8 +16,24 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-/// TODO: Rustdoc
+/// Periodically probe entries in the greylist. Randomly selects a greylist entry and tries to
+/// establish a local connection to it using the method probe_node(), which creates a channel and 
+/// does a version exchange using perform_handshake_protocols().
+///
+/// If successful, the entry is removed from the greylist and added to the whitelist with an
+/// updated last_seen timestamp. If non-successful, the entry is removed from the greylist.
+///
+/// The method probe_node() is also used by ProtocolSeed and ProtocolAddress. We try to establish
+/// local connections to our own external addresses using probe_node() to ensure the address is valid
+/// before propagating in ProtocolSeed and ProtocolAddress.
 pub(super) mod refinery;
 
-/// TODO: Rustdoc
+/// The main interface for interacting with the hostlist, which is stored in three sections: white,
+/// grey and anchorlists. The whitelist contains hosts that have been seen recently, the anchorlist
+/// contains hosts that we have been able to establish a connection to, and the greylist is an
+/// intermediary host list of recently received hosts that is periodically refreshed using the 
+/// greylist refinery.
+///
+/// Store contains various methods for reading from, quering and writing to the hostlists. It is
+/// also responsible for filtering addresses and ensuring channel transport validity.
 pub(super) mod store;

src/net/hosts/refinery.rs

@@ -120,7 +120,6 @@ impl GreylistRefinery {
 }
 
 // Ping a node to check it's online.
-// TODO: make this an actual ping-pong method, rather than a version exchange.
 pub async fn ping_node(addr: &Url, p2p: P2pPtr) -> bool {
     let session_outbound = p2p.session_outbound();
     let parent = Arc::downgrade(&session_outbound);

src/net/hosts/store.rs

@@ -54,7 +54,7 @@ const GREYLIST_MAX_LEN: usize = 2000;
 
 /// Manages a store of network addresses
 // TODO: Test the performance overhead of using vectors for white/grey/anchor lists.
-//       * Check whether anchorlist has a max size in Monero.
+// TODO: Check whether anchorlist has a max size in Monero.
 pub struct Hosts {
     // Intermediary node list that is periodically probed and updated to whitelist.
     pub greylist: RwLock<Vec<(Url, u64)>>,

src/net/protocol/protocol_address.rs

@@ -37,12 +37,9 @@ use super::{
 };
 use crate::Result;
 
-/// Defines address and get-address messages
-// New protocol that sends and receives whitelist info instead of Vec<Url>.
-// AddrMessage is of the format Vec<(Url, u64)>. On receiving GetAddr, nodes send AddrMessage
-// with whitelisted nodes. On receiving an AddrMessage, nodes enter the info into their greylists.
-// The format of GetAddrMessage remains the same.
-// TODO: cleanup documentation
+/// Defines address and get-address messages.
+/// On receiving GetAddr, nodes send an AddrMessage containing whitelisted nodes.
+/// On receiving an AddrMessage, nodes enter the info into their greylists.
 pub struct ProtocolAddress {
     channel: ChannelPtr,
     addrs_sub: MessageSubscription<AddrsMessage>,
@@ -50,7 +47,6 @@ pub struct ProtocolAddress {
     hosts: HostsPtr,
     settings: SettingsPtr,
     jobsman: ProtocolJobsManagerPtr,
-    // We require this to access ping_self() method.
     p2p: P2pPtr,
 }
 
@@ -219,8 +215,10 @@ impl ProtocolAddress {
 
 #[async_trait]
 impl ProtocolBase for ProtocolAddress {
-    /// Starts the address protocol. Runs receive address and get address
-    /// protocols on the protocol task manager. Then sends get-address msg.
+    /// Starts the address protocol. If it's an outbound session, has an external address
+    /// is set to advertise, pings our external address and sends it if everything is fine.
+    /// Runs receive address and get address protocols on the protocol task manager.
+    /// Then sends get-address msg.
     async fn start(self: Arc<Self>, ex: Arc<Executor<'_>>) -> Result<()> {
         debug!(target: "net::protocol_address::start()", "START => address={}", self.channel.address());
 

src/net/protocol/protocol_seed.rs

@@ -41,7 +41,6 @@ pub struct ProtocolSeed {
     hosts: HostsPtr,
     settings: SettingsPtr,
     addr_sub: MessageSubscription<AddrsMessage>,
-    // We require this to access ping_self() method.
     p2p: P2pPtr,
 }
 

src/net/tests.rs

@@ -88,7 +88,7 @@ async fn hostlist_propagation(ex: Arc<Executor<'static>>) {
             outbound_connect_timeout: 10,
             inbound_connections: usize::MAX,
             seeds: vec![seed_addr.clone()],
-            hostlist: String::from(format!(".config/darkfi/hosts{}.tsv", i)),
+            hostlist: String::from(format!("~/.config/darkfi/hosts{}.tsv", i)),
             peers,
             allowed_transports: vec!["tcp".to_string()],
             node_id: i.to_string(),