more docs

mirrord/intproxy/src/protocol.rs

@@ -59,7 +59,7 @@ pub enum NewSessionRequest {
     /// Layer initialized from its constructor and has a fresh state.
     New,
     /// Layer re-initialized from a [`fork`](https://man7.org/linux/man-pages/man2/fork.2.html) detour.
-    /// It shares some state with its parent.
+    /// It inherits state from its parent.
     Forked(SessionId),
 }
 
@@ -91,19 +91,31 @@ pub struct OutgoingConnectRequest {
 /// Requests related to `incoming` features.
 #[derive(Encode, Decode, Debug)]
 pub enum IncomingRequest {
+    /// A request made by layer after it starts listening for mirrored connections.
     PortSubscribe(PortSubscribe),
+    /// A request made by the layer before it closes the socket listening for mirrored connections.
     PortUnsubscribe(PortUnsubscribe),
 }
 
+/// A request to start proxying incoming connections.
+/// 
+/// For each connection incoming to the remote port,
+/// the internal proxy will initiate a new connection to the local port specified in `listening_on`.
+/// Through this connection, the proxy will first send the [`SocketAddress`] of the original peer,
+/// serialized with [`crate::codec`]. After that, the proxy will send raw data.
 #[derive(Encode, Decode, Debug)]
 pub struct PortSubscribe {
+    /// Port on the remote pod that layer wants want to mirror.
     pub port: Port,
+    /// Local address on which the layer is listening.
     pub listening_on: SocketAddress,
 }
 
+/// A request to stop proxying incoming connections.
 #[derive(Encode, Decode, Debug)]
 pub struct PortUnsubscribe {
-    pub port: Port,
+    /// Local address on which the layer was listening.
+    pub listening_on: SocketAddress,
 }
 
 /// Messages sent by the internal proxy and handled by the layer.

mirrord/layer/src/socket.rs

@@ -168,40 +168,20 @@ impl UserSocket {
         }
     }
 
-    /// Return the local (requested) port a bound/listening (NOT CONNECTED) user socket is
-    /// conceptually bound to.
-    ///
-    /// So if the app tried to bind port 80, return `Some(80)` (even if we actually mapped it to
-    /// some other port).
-    ///
-    /// `None` if socket is not bound yet, or if this socket is a connection socket.
-    fn get_bound_port(&self) -> Option<u16> {
-        match &self.state {
-            SocketState::Bound(Bound {
-                requested_address, ..
-            })
-            | SocketState::Listening(Bound {
-                requested_address, ..
-            }) => Some(requested_address.port()),
-            _ => None,
-        }
-    }
-
-    /// Inform TCP handler about closing a bound/listening port.
+    /// Inform internal proxy about closing a listening port.
     #[tracing::instrument(level = "trace", ret)]
     pub(crate) fn close(&self) {
-        if let Some(port) = self.get_bound_port() {
-            match self.kind {
-                SocketKind::Tcp(_) => {
-                    // Ignoring errors here. We continue running, potentially without
-                    // informing the layer's and agent's TCP handlers about the socket
-                    // close. The agent might try to continue sending incoming
-                    // connections/data.
-                    let _ = common::make_proxy_request_no_response(PortUnsubscribe { port });
-                }
-                // We don't do incoming UDP, so no need to notify anyone about this.
-                SocketKind::Udp(_) => {}
+        match self {
+            Self {
+                state: SocketState::Listening(bound),
+                kind: SocketKind::Tcp(..),
+                ..
+            } => {
+                let _ = common::make_proxy_request_no_response(PortUnsubscribe {
+                    listening_on: bound.address.into(),
+                });
             }
+            _ => {}
         }
     }
 }