improve docs

Author: Frando

iroh-net/src/dialer.rs

@@ -12,7 +12,7 @@ use crate::{
     Endpoint, NodeAddr, NodeId,
 };
 use anyhow::anyhow;
-use futures_lite::future::Boxed as BoxFuture;
+use futures_lite::{future::Boxed as BoxFuture, Stream};
 use tokio::task::JoinSet;
 use tokio_util::sync::CancellationToken;
 use tracing::error;
@@ -21,9 +21,17 @@ use tracing::error;
 ///
 /// This wraps a [`Dialer`] and exposes a function to also push accepted connections.
 /// When pushing accepted connections, it is ensured that only a single connection between
-/// ourselves and a peer will prevail. If dials from both sides happen concurrently, only one of
-/// them will prevail. This is implemented by sorting our node id and the peer's node id, and only
-/// keeping the connection with the higher sorted dialing node.
+/// ourselves and a peer will prevail.
+///
+/// The [`ConnManager`] does not accept connections from the endpoint by itself. Instead, you
+/// should run an accept loop yourself, and push connections with a matching ALPN into the manager
+/// with [`ConnManager::accept`]. The connection will be dropped if we already have a connection to
+/// that node. If we are currently dialing the node, the connection will only be accepted if the
+/// peer's node id sorts lower than our node id. Through this, it is ensured that we will not get
+/// double connections with a node if both we and them dial each other at the same time.
+///
+/// The [`ConnManager`] implements [`Stream`]. It will yield new connections, both from dialing and
+/// accepting.
 #[derive(Debug)]
 pub struct ConnManager {
     dialer: Dialer,
@@ -45,12 +53,20 @@ impl ConnManager {
     }
 
     /// Push a newly accepted connection into the manager.
-    pub fn push_accept(&mut self, conn: quinn::Connection) -> anyhow::Result<()> {
+    ///
+    /// This does not check the connection's ALPN, so you should make sure that the ALPN matches
+    /// the [`ConnManager`]'s execpected ALPN before passing the connection to [`Self::accept].
+    ///
+    /// If we are currently dialing the node, the connection will be dropped if the peer's node id
+    /// sorty higher than our node id.
+    ///
+    /// Returns an error if getting the peer's node id from the TLS certificate fails.
+    pub fn accept(&mut self, conn: quinn::Connection) -> anyhow::Result<()> {
         let node_id = get_remote_node_id(&conn)?;
         if self.is_connected(&node_id) {
             return Ok(());
         }
-        // if we are also dialing this node, only accept if node id is greater than ours.
+        // If we are also dialing this node, only accept if node id is greater than ours.
         // this deduplicates connections.
         if !self.dialer.is_pending(&node_id) || node_id > self.our_node_id() {
             self.dialer.abort_dial(&node_id);
@@ -60,13 +76,11 @@ impl ConnManager {
         Ok(())
     }
 
-    fn our_node_id(&self) -> NodeId {
-        self.dialer.endpoint.node_id()
-    }
-
-    /// Remove a connection to a node, if it exists.
+    /// Remove the connection to a node.
     ///
     /// Also aborts pending dials to the node, if existing.
+    ///
+    /// Returns the connection if it existed.
     pub fn remove(&mut self, node_id: &NodeId) -> Option<Connection> {
         self.dialer.abort_dial(node_id);
         self.active.remove(node_id)
@@ -85,7 +99,7 @@ impl ConnManager {
         if self.is_dialing(&node_id) || self.is_connected(&node_id) {
             return;
         }
-        self.dialer.queue_dial(node_id, &self.alpn);
+        self.dialer.queue_dial(node_id, self.alpn);
     }
 
     /// Returns `true` if we are currently dialing the node.
@@ -97,9 +111,13 @@ impl ConnManager {
     pub fn is_connected(&self, node_id: &NodeId) -> bool {
         self.active.contains_key(node_id)
     }
+
+    fn our_node_id(&self) -> NodeId {
+        self.dialer.endpoint.node_id()
+    }
 }
 
-impl futures_lite::Stream for ConnManager {
+impl Stream for ConnManager {
     type Item = NewConnection;
 
     fn poll_next(
@@ -241,7 +259,7 @@ impl Dialer {
     }
 }
 
-impl futures_lite::Stream for Dialer {
+impl Stream for Dialer {
     type Item = (PublicKey, anyhow::Result<quinn::Connection>);
 
     fn poll_next(