doc: add missing documentation to refine session and hosts

src/net/hosts.rs

@@ -220,7 +220,8 @@ impl HostState {
 
     // Try to change the state to Suspend. Only possible when we are
     // currently moving this host, since we suspend a host after failing
-    // to connect to it and then downgrading in move_host.
+    // to connect to it in `outbound_session::try_connect` and then downgrading
+    // in `hosts::move_host`.
     fn try_suspend(&self) -> Result<Self> {
         let start = self.to_string();
         let end = HostState::Suspend.to_string();
@@ -1034,18 +1035,6 @@ impl Hosts {
         false
     }
 
-    // TODO: doc
-    pub async fn is_connection_to_self(&self, url: &Url) -> bool {
-        let host_str = url.host_str().unwrap();
-        if self.settings.localnet {
-            // If on localhost, check whether this connection is to our own port.
-            self.settings.external_addrs.iter().any(|ext| url.port() == ext.port())
-        } else {
-            // Otherwise, check whether this connection is to our own external address.
-            self.settings.external_addrs.iter().any(|ext| host_str == ext.host_str().unwrap())
-        }
-    }
-
     /// Filter given addresses based on certain rulesets and validity. Strictly called only on
     /// the first time learning of a new peer.
     async fn filter_addresses(
@@ -1170,7 +1159,8 @@ impl Hosts {
         ret
     }
 
-    // TODO: doc
+    /// Method to fetch the last_seen field for a give address when we do
+    /// not know what hostlist it is on.
     pub async fn fetch_last_seen(&self, addr: &Url) -> Option<u64> {
         if self.container.contains(HostColor::Gold as usize, addr).await {
             self.container.get_last_seen(HostColor::Gold as usize, addr).await

src/net/session/mod.rs

@@ -40,6 +40,8 @@ pub mod refine_session;
 pub use refine_session::{RefineSession, RefineSessionPtr};
 
 /// Bitwise selectors for the `protocol_registry`
+// TODO: SESSION_ALL currently does not include SESSION_REFINE, which is
+// conceptually wrong.  Should we rename SESSION_ALL to SESSION_DEFAULT?
 pub type SessionBitFlag = u32;
 pub const SESSION_INBOUND: SessionBitFlag = 0b0001;
 pub const SESSION_OUTBOUND: SessionBitFlag = 0b0010;

src/net/session/refine_session.rs

@@ -16,7 +16,16 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-//! TODO: doc
+//! `RefineSession` manages two processes, the `GreylistRefinery`, which
+//! periodically pings entries on the greylist and updates them to whitelist
+//! if active, and `SelfHandshake`, which periodically pings our own external
+//! addresses to ensure they are active before broadcasting to the network.
+//!
+//! Both processes make use of a `RefineSession` method called
+//! `handshake_node()`, which uses a `Connector` to establish a `Channel` with
+//! a provided address, and then does a version exchange across the channel
+//! (`perform_handshake_protocols`). `handshake_node()` can either succeed,
+//! fail, or timeout.
 
 use std::{
     collections::HashMap,
@@ -67,6 +76,7 @@ impl RefineSession {
         self_
     }
 
+    /// Start the refinery and self handshake processes.
     pub(crate) async fn start(self: Arc<Self>) {
         debug!(target: "net::refine_session", "Starting greylist refinery process");
         self.refinery.clone().start().await;
@@ -75,6 +85,7 @@ impl RefineSession {
         self.self_handshake.clone().start().await;
     }
 
+    /// Stop the refinery and self handshake processes.
     pub(crate) async fn stop(&self) {
         debug!(target: "net::refine_session", "Stopping refinery process");
         self.refinery.clone().stop().await;
@@ -83,7 +94,10 @@ impl RefineSession {
         self.self_handshake.clone().stop().await;
     }
 
-    // TODO: doc and explain why it's public
+    /// Globally accessible function to perform a version exchange with a
+    /// given address.  Returns `true` if an address is accessible, false
+    /// otherwise.  Used by `GreylistRefinery`, `SelfHandshake`, and in
+    /// `Lilith`, which contains an implemenenation of a whitelist refinery.
     pub async fn handshake_node(self: Arc<Self>, addr: Url, p2p: P2pPtr) -> bool {
         let self_ = Arc::downgrade(&self);
         let connector = Connector::new(self.p2p().settings(), self_);
@@ -251,7 +265,8 @@ impl GreylistRefinery {
 
                     // Freeze the greylist in this state. Necessary since the greylist
                     // can be modified by `hosts::move_host()` or `hosts::store()`.
-                    let mut greylist = hosts.container.hostlists[HostColor::Grey as usize].write().await;
+                    let mut greylist =
+                        hosts.container.hostlists[HostColor::Grey as usize].write().await;
 
                     if !self.session().handshake_node(url.clone(), self.p2p().clone()).await {
                         greylist.remove(position);