chore(connlib): tidy up logs and docs (#4265)

Wrong / outdated docs are worse than no docs. This PR removes some of
these stale docs. We may add new docs at a later point again.

rust/connlib/clients/shared/src/eventloop.rs

@@ -62,7 +62,6 @@ impl<C> Eventloop<C>
 where
     C: Callbacks + 'static,
 {
-    #[tracing::instrument(name = "Eventloop::poll", skip_all, level = "debug")]
     pub fn poll(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), phoenix_channel::Error>> {
         loop {
             match self.rx.poll_recv(cx) {
@@ -259,7 +258,7 @@ where
 
                 match self
                     .tunnel
-                    .request_connection(resource_id, gateway_id, relays)
+                    .create_or_reuse_connection(resource_id, gateway_id, relays)
                 {
                     Ok(firezone_tunnel::Request::NewConnection(connection_request)) => {
                         // TODO: keep track for the response

rust/connlib/tunnel/src/client.rs

@@ -75,9 +75,6 @@ where
     CB: Callbacks + 'static,
 {
     /// Adds a the given resource to the tunnel.
-    ///
-    /// Once added, when a packet for the resource is intercepted a new data channel will be created
-    /// and packets will be wrapped with wireguard and sent through it.
     pub fn add_resources(
         &mut self,
         resources: &[ResourceDescription],
@@ -189,7 +186,6 @@ where
         self.role_state.update_system_resolvers(new_dns, now);
     }
 
-    /// Sets the interface configuration and starts background tasks.
     #[tracing::instrument(level = "trace", skip(self))]
     pub fn set_interface(&mut self, config: InterfaceConfig) -> connlib_shared::Result<()> {
         self.role_state.interface_config = Some(config);
@@ -239,11 +235,8 @@ where
         Ok(())
     }
 
-    /// Clean up a connection to a resource.
-    // FIXME: this cleanup connection is wrong!
     pub fn cleanup_connection(&mut self, id: ResourceId) {
         self.role_state.on_connection_failed(id);
-        // self.peer_connections.lock().remove(&id.into());
     }
 
     #[tracing::instrument(level = "trace", skip(self))]
@@ -261,19 +254,7 @@ where
             .add_remote_candidate(conn_id, ice_candidate, Instant::now());
     }
 
-    /// Initiate an ice connection request.
-    ///
-    /// Given a resource id and a list of relay creates a [RequestConnection]
-    /// and prepares the tunnel to handle the connection once initiated.
-    ///
-    /// # Parameters
-    /// - `resource_id`: Id of the resource we are going to request the connection to.
-    /// - `relays`: The list of relays used for that connection.
-    ///
-    /// # Returns
-    /// A [RequestConnection] that should be sent to the gateway through the control-plane.
-    #[tracing::instrument(level = "trace", skip_all, fields(%resource_id, %gateway_id))]
-    pub fn request_connection(
+    pub fn create_or_reuse_connection(
         &mut self,
         resource_id: ResourceId,
         gateway_id: GatewayId,
@@ -287,9 +268,6 @@ where
         )
     }
 
-    /// Called when a response to [ClientTunnel::request_connection] is ready.
-    ///
-    /// Once this is called, if everything goes fine, a new tunnel should be started between the 2 peers.
     pub fn received_offer_response(
         &mut self,
         resource_id: ResourceId,
@@ -518,6 +496,7 @@ impl ClientState {
         Ok(())
     }
 
+    #[tracing::instrument(level = "debug", skip_all, fields(%resource_id, %gateway_id))]
     fn create_or_reuse_connection(
         &mut self,
         resource_id: ResourceId,
@@ -525,7 +504,7 @@ impl ClientState {
         allowed_stun_servers: HashSet<SocketAddr>,
         allowed_turn_servers: HashSet<(SocketAddr, String, String, String)>,
     ) -> connlib_shared::Result<Request> {
-        tracing::trace!("request_connection");
+        tracing::trace!("create_or_reuse_connection");
 
         let desc = self
             .resource_ids

rust/connlib/tunnel/src/gateway.rs

@@ -26,7 +26,6 @@ impl<CB> GatewayTunnel<CB>
 where
     CB: Callbacks + 'static,
 {
-    /// Sets the interface configuration and starts background tasks.
     #[tracing::instrument(level = "trace", skip(self))]
     pub fn set_interface(&mut self, config: &InterfaceConfig) -> connlib_shared::Result<()> {
         // Note: the dns fallback strategy is irrelevant for gateways
@@ -47,12 +46,6 @@ where
     }
 
     /// Accept a connection request from a client.
-    ///
-    /// Sets a connection to a remote SDP, creates the local SDP
-    /// and returns it.
-    ///
-    /// # Returns
-    /// The connection details
     #[allow(clippy::too_many_arguments)]
     pub fn accept(
         &mut self,
@@ -113,7 +106,6 @@ where
         })
     }
 
-    /// Clean up a connection to a resource.
     pub fn cleanup_connection(&mut self, id: &ClientId) {
         self.role_state.peers.remove(id);
     }
@@ -159,15 +151,18 @@ where
         None
     }
 
-    pub fn remove_access(&mut self, id: &ClientId, resource_id: &ResourceId) {
-        let Some(peer) = self.role_state.peers.get_mut(id) else {
+    #[tracing::instrument(level = "debug", skip_all, fields(%resource, %client))]
+    pub fn remove_access(&mut self, client: &ClientId, resource: &ResourceId) {
+        let Some(peer) = self.role_state.peers.get_mut(client) else {
             return;
         };
 
-        peer.transform.remove_resource(resource_id);
+        peer.transform.remove_resource(resource);
         if peer.transform.is_emptied() {
-            self.role_state.peers.remove(id);
+            self.role_state.peers.remove(client);
         }
+
+        tracing::debug!("Access removed");
     }
 
     pub fn add_ice_candidate(&mut self, conn_id: ClientId, ice_candidate: String) {

rust/gateway/src/eventloop.rs

@@ -44,7 +44,6 @@ impl Eventloop {
 }
 
 impl Eventloop {
-    #[tracing::instrument(name = "Eventloop::poll", skip_all, level = "debug")]
     pub fn poll(&mut self, cx: &mut Context<'_>) -> Poll<Result<Infallible>> {
         loop {
             match self.tunnel.poll_next_event(cx) {
@@ -52,8 +51,6 @@ impl Eventloop {
                     conn_id: client,
                     candidate,
                 })) => {
-                    tracing::debug!(%client, %candidate, "Sending ICE candidate to client");
-
                     self.portal.send(
                         PHOENIX_TOPIC,
                         EgressMessages::BroadcastIceCandidates(BroadcastClientIceCandidates {
@@ -124,8 +121,6 @@ impl Eventloop {
                     ..
                 }) => {
                     for candidate in candidates {
-                        tracing::debug!(client = %client_id, %candidate, "Adding ICE candidate from client");
-
                         self.tunnel.add_ice_candidate(client_id, candidate);
                     }
                     continue;
@@ -139,8 +134,6 @@ impl Eventloop {
                         }),
                     ..
                 }) => {
-                    tracing::debug!(client = %client_id, resource = %resource_id, "Access removed");
-
                     self.tunnel.remove_access(&client_id, &resource_id);
                     continue;
                 }