Add forwarding between TCP ports and UNIX domain sockets

This commit adds new methods to forward local and remote TCP ports to
UNIX domain paths and vice-versa over an SSH connection. Thanks go to
Alex Rogozhnikov for suggesting this use case.

The new SSHClientConnection methods to support this are named
forward_local_port_to_path, forward_local_path_to_port,
forward_remote_port_to_path, and forward_remote_path_to_port.

Author: ronf

asyncssh/connection.py

@@ -3043,6 +3043,12 @@ class SSHClientConnection(SSHConnection):
        UNIX domain socket forwarding can be set up by calling
        :meth:`forward_local_path` or :meth:`forward_remote_path`.
 
+       Mixed forwarding from a TCP port to a UNIX domain socket or
+       vice-versa can be set up by calling :meth:`forward_local_port_to_path`,
+       :meth:`forward_local_path_to_port`,
+       :meth:`forward_remote_port_to_path`, or
+       :meth:`forward_remote_path_to_port`.
+
     """
 
     _options: 'SSHClientConnectionOptions'
@@ -4646,6 +4652,113 @@ async def listen_reverse_ssh(self, host: str = '',
         return await listen_reverse(host, port, tunnel=self,
                                     **kwargs) # type: ignore
 
+    @async_context_manager
+    async def forward_local_port_to_path(self, listen_host: str,
+                                         listen_port: int,
+                                         dest_path: str) -> SSHListener:
+        """Set up local TCP port forwarding to a remote UNIX domain socket
+
+           This method is a coroutine which attempts to set up port
+           forwarding from a local TCP listening port to a remote UNIX
+           domain path via the SSH connection. If the request is successful,
+           the return value is an :class:`SSHListener` object which can be
+           used later to shut down the port forwarding.
+
+           :param listen_host:
+               The hostname or address on the local host to listen on
+           :param listen_port:
+               The port number on the local host to listen on
+           :param dest_path:
+               The path on the remote host to forward the connections to
+           :type listen_host: `str`
+           :type listen_port: `int`
+           :type dest_path: `str`
+
+           :returns: :class:`SSHListener`
+
+           :raises: :exc:`OSError` if the listener can't be opened
+
+        """
+
+        async def tunnel_connection(
+                session_factory: SSHUNIXSessionFactory[bytes],
+                _orig_host: str, _orig_port: int) -> \
+                    Tuple[SSHUNIXChannel[bytes], SSHUNIXSession[bytes]]:
+            """Forward a local connection over SSH"""
+
+            return (await self.create_unix_connection(session_factory,
+                                                      dest_path))
+
+        self.logger.info('Creating local TCP forwarder from %s to %s',
+                         (listen_host, listen_port), dest_path)
+
+        try:
+            listener = await create_tcp_forward_listener(self, self._loop,
+                                                         tunnel_connection,
+                                                         listen_host,
+                                                         listen_port)
+        except OSError as exc:
+            self.logger.debug1('Failed to create local TCP listener: %s', exc)
+            raise
+
+        if listen_port == 0:
+            listen_port = listener.get_port()
+
+        self._local_listeners[listen_host, listen_port] = listener
+
+        return listener
+
+    @async_context_manager
+    async def forward_local_path_to_port(self, listen_path: str,
+                                         dest_host: str,
+                                         dest_port: int) -> SSHListener:
+        """Set up local UNIX domain socket forwarding to a remote TCP port
+
+           This method is a coroutine which attempts to set up UNIX domain
+           socket forwarding from a local listening path to a remote host
+           and port via the SSH connection. If the request is successful,
+           the return value is an :class:`SSHListener` object which can
+           be used later to shut down the UNIX domain socket forwarding.
+
+           :param listen_path:
+               The path on the local host to listen on
+           :param dest_host:
+               The hostname or address to forward the connections to
+           :param dest_port:
+               The port number to forward the connections to
+           :type listen_path: `str`
+           :type dest_host: `str`
+           :type dest_port: `int`
+
+           :returns: :class:`SSHListener`
+
+           :raises: :exc:`OSError` if the listener can't be opened
+
+        """
+
+        async def tunnel_connection(
+                session_factory: SSHTCPSessionFactory[bytes]) -> \
+                    Tuple[SSHTCPChannel[bytes], SSHTCPSession[bytes]]:
+            """Forward a local connection over SSH"""
+
+            return await self.create_connection(session_factory, dest_host,
+                                                dest_port, '', 0)
+
+        self.logger.info('Creating local UNIX forwarder from %s to %s',
+                         listen_path, (dest_host, dest_port))
+
+        try:
+            listener = await create_unix_forward_listener(self, self._loop,
+                                                          tunnel_connection,
+                                                          listen_path)
+        except OSError as exc:
+            self.logger.debug1('Failed to create local UNIX listener: %s', exc)
+            raise
+
+        self._local_listeners[listen_path] = listener
+
+        return listener
+
     @async_context_manager
     async def forward_remote_port(self, listen_host: str,
                                   listen_port: int, dest_host: str,
@@ -4727,6 +4840,88 @@ def session_factory() -> Awaitable[SSHUNIXSession[bytes]]:
 
         return await self.create_unix_server(session_factory, listen_path)
 
+    @async_context_manager
+    async def forward_remote_port_to_path(self, listen_host: str,
+                                          listen_port: int,
+                                          dest_path: str) -> SSHListener:
+        """Set up remote TCP port forwarding to a local UNIX domain socket
+
+           This method is a coroutine which attempts to set up port
+           forwarding from a remote TCP listening port to a local UNIX
+           domain socket path via the SSH connection. If the request is
+           successful, the return value is an :class:`SSHListener` object
+           which can be used later to shut down the port forwarding. If
+           the request fails, `None` is returned.
+
+           :param listen_host:
+               The hostname or address on the remote host to listen on
+           :param listen_port:
+               The port number on the remote host to listen on
+           :param dest_path:
+               The path on the local host to forward connections to
+           :type listen_host: `str`
+           :type listen_port: `int`
+           :type dest_path: `str`
+
+           :returns: :class:`SSHListener`
+
+           :raises: :class:`ChannelListenError` if the listener can't be opened
+
+        """
+
+        def session_factory(_orig_host: str,
+                            _orig_port: int) -> Awaitable[SSHUNIXSession]:
+            """Return an SSHTCPSession used to do remote port forwarding"""
+
+            return cast(Awaitable[SSHUNIXSession],
+                        self.forward_unix_connection(dest_path))
+
+        self.logger.info('Creating remote TCP forwarder from %s to %s',
+                         (listen_host, listen_port), dest_path)
+
+        return await self.create_server(session_factory, listen_host,
+                                        listen_port)
+
+    @async_context_manager
+    async def forward_remote_path_to_port(self, listen_path: str,
+                                          dest_host: str,
+                                          dest_port: int) -> SSHListener:
+        """Set up remote UNIX domain socket forwarding to a local TCP port
+
+           This method is a coroutine which attempts to set up UNIX domain
+           socket forwarding from a remote listening path to a local TCP
+           host and port via the SSH connection. If the request is
+           successful, the return value is an :class:`SSHListener` object
+           which can be used later to shut down the port forwarding. If
+           the request fails, `None` is returned.
+
+           :param listen_path:
+               The path on the remote host to listen on
+           :param dest_host:
+               The hostname or address to forward connections to
+           :param dest_port:
+               The port number to forward connections to
+           :type listen_path: `str`
+           :type dest_host: `str`
+           :type dest_port: `int`
+
+           :returns: :class:`SSHListener`
+
+           :raises: :class:`ChannelListenError` if the listener can't be opened
+
+        """
+
+        def session_factory() -> Awaitable[SSHTCPSession[bytes]]:
+            """Return an SSHUNIXSession used to do remote path forwarding"""
+
+            return cast(Awaitable[SSHTCPSession[bytes]],
+                        self.forward_connection(dest_host, dest_port))
+
+        self.logger.info('Creating remote UNIX forwarder from %s to %s',
+                         listen_path, (dest_host, dest_port))
+
+        return await self.create_unix_server(session_factory, listen_path)
+
     @async_context_manager
     async def forward_socks(self, listen_host: str,
                             listen_port: int) -> SSHListener:

docs/api.rst

@@ -75,7 +75,18 @@ The client can also set up TCP port forwarding by calling
 :meth:`forward_remote_port() <SSHClientConnection.forward_remote_port>` and
 UNIX domain socket forwarding by calling :meth:`forward_local_path()
 <SSHClientConnection.forward_local_path>` or :meth:`forward_remote_path()
-<SSHClientConnection.forward_remote_path>`. In these cases, data transfer on
+<SSHClientConnection.forward_remote_path>`. Mixed forwarding from a TCP port
+to a UNIX domain socket or vice-versa can be set up using the functions
+:meth:`forward_local_port_to_path()
+<SSHClientConnection.forward_local_port_to_path>`,
+:meth:`forward_local_path_to_port()
+<SSHClientConnection.forward_local_path_to_port>`,
+:meth:`forward_remote_port_to_path()
+<SSHClientConnection.forward_remote_port_to_path>`, and
+:meth:`forward_remote_path_to_port()
+<SSHClientConnection.forward_remote_path_to_port>`.
+
+In these cases, data transfer on
 the channels is managed automatically by AsyncSSH whenever new connections
 are opened, so custom session objects are not required.
 
@@ -354,16 +365,20 @@ SSHClientConnection
    .. automethod:: start_unix_server
    ====================================== =
 
-   =================================== =
+   =========================================== =
    Client forwarding methods
-   =================================== =
+   =========================================== =
    .. automethod:: forward_connection
    .. automethod:: forward_local_port
    .. automethod:: forward_local_path
+   .. automethod:: forward_local_port_to_path
+   .. automethod:: forward_local_path_to_port
    .. automethod:: forward_remote_port
    .. automethod:: forward_remote_path
+   .. automethod:: forward_remote_port_to_path
+   .. automethod:: forward_remote_path_to_port
    .. automethod:: forward_socks
-   =================================== =
+   =========================================== =
 
    =========================== =
    Connection close methods