docsss

mirrord/intproxy/src/proxies/incoming/tasks.rs

@@ -7,9 +7,19 @@ use mirrord_protocol::{
 };
 use thiserror::Error;
 
+/// Messages produced by the [`BackgroundTask`](crate::background_tasks::BackgroundTask)s used in
+/// the [`IncomingProxy`](super::IncomingProxy).
 pub enum InProxyTaskMessage {
-    Tcp(Vec<u8>),
-    Http(HttpOut),
+    /// Produced by the [`TcpProxyTask`](super::tcp_proxy::TcpProxyTask) in steal mode.
+    Tcp(
+        /// Data received from the local application.
+        Vec<u8>,
+    ),
+    /// Produced by the [`HttpGatewayTask`](super::http_gateway::HttpGatewayTask).
+    Http(
+        /// HTTP spefiic message.
+        HttpOut,
+    ),
 }
 
 impl fmt::Debug for InProxyTaskMessage {
@@ -24,11 +34,16 @@ impl fmt::Debug for InProxyTaskMessage {
     }
 }
 
+/// Messages produced by the [`HttpGatewayTask`](super::http_gateway::HttpGatewayTask).
 #[derive(Debug)]
 pub enum HttpOut {
+    /// Response from the local application's HTTP server.
     ResponseBasic(HttpResponse<Vec<u8>>),
+    /// Response from the local application's HTTP server.
     ResponseFramed(HttpResponse<InternalHttpBody>),
+    /// Response from the local application's HTTP server.
     ResponseChunked(ChunkedResponse),
+    /// Upgraded HTTP connection, to be handled as a remote connection stolen without any filter.
     Upgraded(OnUpgrade),
 }
 
@@ -44,6 +59,17 @@ impl From<HttpOut> for InProxyTaskMessage {
     }
 }
 
+/// Errors that can occur in the [`BackgroundTask`](crate::background_tasks::BackgroundTask)s used
+/// in the [`IncomingProxy`](super::IncomingProxy).
+///
+/// All of these can occur only in the [`TcpProxyTask`](super::tcp_proxy::TcpProxyTask)
+/// and mean that the local connection is irreversibly broken.
+/// The [`HttpGatewayTask`](super::http_gateway::HttpGatewayTask) produces no errors
+/// and instead responds with an error HTTP response to the agent.
+///
+/// However, due to [`BackgroundTasks`](crate::background_tasks::BackgroundTasks)
+/// type constraints, we need a common error type.
+/// Thus, this type implements [`From<Infallible>`].
 #[derive(Error, Debug)]
 pub enum InProxyTaskError {
     #[error("io failed: {0}")]
@@ -58,10 +84,15 @@ impl From<Infallible> for InProxyTaskError {
     }
 }
 
+/// Types of [`BackgroundTask`](crate::background_tasks::BackgroundTask)s used in the
+/// [`IncomingProxy`](super::IncomingProxy).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum InProxyTask {
+    /// [`TcpProxyTask`](super::tcp_proxy::TcpProxyTask) handling a mirrored connection.
     MirrorTcpProxy(ConnectionId),
+    /// [`TcpProxyTask`](super::tcp_proxy::TcpProxyTask) handling a stolen connection.
     StealTcpProxy(ConnectionId),
+    /// [`HttpGatewayTask`](super::http_gateway::HttpGatewayTask) handling a stolen HTTP request.
     HttpGateway(HttpGatewayId),
 }
 
@@ -71,8 +102,12 @@ pub enum InProxyTask {
 /// error response in case the task somehow panics.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct HttpGatewayId {
+    /// Id of the remote connection.
     pub connection_id: ConnectionId,
+    /// Id of the stolen request.
     pub request_id: RequestId,
+    /// Remote port from which the request was stolen.
     pub port: Port,
+    /// HTTP version of the stolen request.
     pub version: Version,
 }