codecraftai-protocol-ssh 1.3.0__py3-none-any.whl

ccai/protocols/ssh/sshtunnel.py

@@ -0,0 +1,464 @@
+"""
+    .. module:: sshtunnel
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Module containing the :class:`SshTunnel` class.
+    
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+    
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+from types import TracebackType
+import socket
+import select
+import threading
+
+from ccai.protocols.ssh.sshclient import SshClient
+from ccai.protocols.ssh.sshconnection import SshConnection, SshChannel
+
+from ccai.xmodules.xlogging.enhancedloggers import getEnhancedLogger
+
+logger = getEnhancedLogger()
+
+# How often, in seconds, each direction of a forwarded connection wakes up to check whether the tunnel is
+# shutting down or the other direction has finished.
+PUMP_POLL_INTERVAL = 1.0
+
+# The number of bytes read from the local socket or the channel per forwarding step.
+PUMP_CHUNK_SIZE = 32768
+
+# How long, in seconds, a finished connection waits for its channel to socket forwarding thread to exit.
+PUMP_JOIN_TIMEOUT = 5.0
+
+
+class SshTunnel:
+    """
+        The :class:`SshTunnel` represents a single SSH port forwarding tunnel for connecting to a remote service
+        through an SSH connection. Each SshTunnel instance manages exactly one port forward.
+        
+        Note: SshTunnel instances should only be created through SshAgent.open_tunnel() method.
+    """
+
+    def __init__(self, ssh_client: SshClient, local_port: int, remote_host: str, remote_port: int, _internal_create: bool = False):
+        """
+            Initialize an :class:`SshTunnel` instance with an existing SSH client and tunnel parameters.
+            
+            Note: This constructor should not be called directly. Use SshAgent.open_tunnel() instead.
+
+            :param ssh_client: An established SshClient connection.
+            :param local_port: Local port to bind for forwarding. If 0, an available port will be chosen.
+            :param remote_host: Remote host to forward to.
+            :param remote_port: Remote port to forward to.
+            :param _internal_create: Internal flag to prevent direct instantiation.
+        """
+        if not _internal_create:
+            raise RuntimeError("SshTunnel instances should only be created through SshAgent.open_tunnel() method")
+        
+        self._ssh_client = ssh_client
+        self._local_port = local_port
+        self._remote_host = remote_host
+        self._remote_port = remote_port
+        self._actual_local_port = None
+        self._local_socket = None
+        self._forward_thread = None
+        self._active = False
+        self._owns_ssh_client = True  # This tunnel owns the SSH client and should close it
+        self._connection_threads = []  # Track active connection threads
+        self._connection_lock = threading.Lock()  # Protect connection thread list
+        
+        # Start the tunnel immediately
+        self._start_tunnel()
+        return
+
+    @classmethod
+    def _create_internal(cls, ssh_client: SshClient, local_port: int, remote_host: str, remote_port: int) -> 'SshTunnel':
+        """
+            Internal method for creating SshTunnel instances. Only used by SshAgent.
+
+            :param ssh_client: An established SshClient connection.
+            :param local_port: Local port to bind for forwarding. If 0, an available port will be chosen.
+            :param remote_host: Remote host to forward to.
+            :param remote_port: Remote port to forward to.
+
+            :returns: A new SshTunnel instance.
+        """
+        return cls(ssh_client, local_port, remote_host, remote_port, _internal_create=True)
+
+    def __enter__(self):
+        """
+            Method that implements the __enter__ semantics used for 'with' statements.
+        """
+        return self
+
+    def __exit__(self, ex_type: type, ex_val: Exception, ex_tb: TracebackType) -> bool:
+        """
+            Method that implements the __exit__ semantics used for 'with' statements.
+            Shuts down the tunnel and cleans up all threads and resources.
+
+            :returns: Returns false indicating that exceptions are not handled.
+        """
+        self.shutdown()
+        handled = False
+        return handled
+
+    def close(self):
+        """
+            Closes all port forwards and cleans up resources. Also closes the SSH client.
+            This is an alias for shutdown() for backward compatibility.
+        """
+        self.shutdown()
+        return
+
+    def shutdown(self):
+        """
+            Shuts down the tunnel by stopping the port forward and cleaning up all threads and resources.
+            Also closes the SSH client since this tunnel owns it.
+        """
+        logger.info(f"Shutting down SSH tunnel 127.0.0.1:{self._actual_local_port} -> {self._remote_host}:{self._remote_port}")
+        
+        # Mark as inactive
+        self._active = False
+        
+        # Close the listening socket to stop accepting new connections
+        if self._local_socket:
+            try:
+                self._local_socket.close()
+            except Exception as e:
+                logger.debug(f"Error closing socket: {e}")
+            finally:
+                self._local_socket = None
+        
+        # Wait for the forwarding thread to complete
+        if self._forward_thread and self._forward_thread.is_alive():
+            logger.debug("Waiting for forwarding thread to complete...")
+            self._forward_thread.join(timeout=10.0)
+            if self._forward_thread.is_alive():
+                logger.warning("Forwarding thread did not complete within timeout")
+        
+        # Wait for connection handler threads to complete
+        with self._connection_lock:
+            active_connections = [t for t in self._connection_threads if t.is_alive()]
+        
+        if active_connections:
+            logger.debug(f"Waiting for {len(active_connections)} connection handler threads to complete...")
+            for thread in active_connections:
+                thread.join(timeout=5.0)
+                if thread.is_alive():
+                    logger.warning(f"Connection handler thread did not complete within timeout")
+        
+        # Close the SSH client since this tunnel owns it
+        if self._owns_ssh_client and self._ssh_client:
+            try:
+                self._ssh_client.close()
+                logger.debug("SSH client closed")
+            except Exception as e:
+                logger.warning(f"Error closing SSH client: {e}")
+            finally:
+                self._ssh_client = None
+        
+        logger.info("SSH tunnel shutdown complete")
+        return
+
+    def _start_tunnel(self):
+        """
+            Private method that starts the port forwarding tunnel.
+        """
+        # Create a local socket to listen on
+        self._local_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._local_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        
+        # If local_port is 0, let the OS choose an available port
+        self._local_socket.bind(('127.0.0.1', self._local_port))
+        self._actual_local_port = self._local_socket.getsockname()[1]
+        self._local_socket.listen(5)
+        # Closing a listening socket does not wake a thread blocked in accept() on every platform, so accept with
+        # a timeout and let the forwarding loop re-check for shutdown and a dead transport.  Accepted connections
+        # are still created in blocking mode.
+        self._local_socket.settimeout(PUMP_POLL_INTERVAL)
+        
+        # Mark as active
+        self._active = True
+        
+        # Start the forwarding loop in a separate daemon thread
+        self._forward_thread = threading.Thread(
+            target=self._forward_loop,
+            daemon=True
+        )
+        self._forward_thread.start()
+        
+        logger.info(f"SSH tunnel port forward started: 127.0.0.1:{self._actual_local_port} -> {self._remote_host}:{self._remote_port}")
+        return
+
+    def _forward_loop(self):
+        """
+            Private method that handles the port forwarding loop by accepting connections and forwarding
+            traffic over the SSH transport.
+        """
+        try:
+            while self._active:
+                try:
+                    transport = self._ssh_client.get_transport()
+                    if transport is None or not transport.is_active():
+                        logger.error("SSH transport is no longer active, stopping tunnel")
+                        break
+                    
+                    connection = self._ssh_client.connection
+
+                    # Accept incoming connections
+                    conn, addr = self._local_socket.accept()
+                    logger.debug(f"Accepted connection from {addr} for tunnel to {self._remote_host}:{self._remote_port}")
+                    
+                    # Clean up finished connection threads before creating new ones
+                    self._cleanup_finished_threads()
+                    
+                    # Create and track connection handler thread
+                    conn_thread = threading.Thread(
+                        target=self._handle_connection,
+                        args=(conn, connection),
+                        daemon=True
+                    )
+                    
+                    with self._connection_lock:
+                        self._connection_threads.append(conn_thread)
+                    
+                    conn_thread.start()
+
+                except socket.timeout:
+                    # No connection within the poll interval; loop to re-check for shutdown.
+                    continue
+                except socket.error as e:
+                    # Socket errors during accept() are expected when shutting down
+                    if self._active:
+                        logger.error(f"Socket error in port forward: {e}")
+                    else:
+                        logger.debug(f"Socket error during shutdown (expected): {e}")
+                    break
+                except Exception as e:
+                    logger.error(f"Unexpected error in port forward: {e}")
+                    break
+                    
+        except Exception as e:
+            logger.error(f"Port forward thread error: {e}")
+        finally:
+            try:
+                if self._local_socket:
+                    self._local_socket.close()
+            except Exception:
+                # Best-effort cleanup at forwarding thread exit; the listener is being discarded and there is
+                # no caller to report a close failure to.
+                pass
+
+    def _handle_connection(self, conn: socket.socket, connection: SshConnection):
+        """
+            Handle a single connection through the tunnel.
+            
+            :param conn: The client connection socket.
+            :param connection: The SSH connection to use for forwarding.
+        """
+        chan = None
+        try:
+            # RFC 4254 section 7.2: the originator is the local client whose connection is being forwarded.
+            chan = connection.open_channel(
+                "direct-tcpip",
+                dest_addr=(self._remote_host, self._remote_port),
+                src_addr=conn.getpeername()
+            )
+
+            self._pump_channel(conn, chan)
+        except Exception as e:
+            logger.debug(f"Connection handler error: {e}")
+        finally:
+            try:
+                conn.close()
+            except Exception:
+                # Best-effort cleanup; a failure to close the local socket must not prevent the channel from being closed.
+                pass
+            if chan is not None:
+                try:
+                    chan.close()
+                except Exception:
+                    # Best-effort cleanup; the forwarded connection is finished and the channel is being discarded.
+                    pass
+
+    def _pump_channel(self, conn: socket.socket, chan: SshChannel):
+        """
+            Forward data between a local socket connection and an SSH channel until one side closes.
+
+            An :class:`SshChannel` has no file descriptor, so it cannot be passed to ``select``.  The socket to
+            channel direction runs on this thread and waits on the socket with ``select``; the channel to socket
+            direction runs on a companion thread that blocks in :meth:`SshChannel.recv`, which is fed by the
+            transport thread.  Both directions check for tunnel shutdown every ``PUMP_POLL_INTERVAL`` seconds and
+            stop together as soon as either side closes.  When the peer only sends EOF (half-close, RFC 4254 section
+            5.3) the local client gets end-of-stream and can keep sending until it closes.
+
+            :param conn: The local client connection socket.
+            :param chan: The open ``direct-tcpip`` channel for the connection.
+        """
+        pump_done = threading.Event()
+
+        channel_reader = threading.Thread(
+            target=self._pump_channel_to_socket,
+            args=(conn, chan, pump_done),
+            daemon=True
+        )
+        channel_reader.start()
+
+        try:
+            self._pump_socket_to_channel(conn, chan, pump_done)
+        finally:
+            pump_done.set()
+            channel_reader.join(timeout=PUMP_JOIN_TIMEOUT)
+            if channel_reader.is_alive():
+                logger.warning("Channel to socket forwarding thread did not complete within timeout")
+
+        return
+
+    def _pump_socket_to_channel(self, conn: socket.socket, chan: SshChannel, pump_done: threading.Event):
+        """
+            Forward data from the local socket to the SSH channel until the local client closes its side, the
+            other direction finishes, or the tunnel shuts down.
+
+            :param conn: The local client connection socket.
+            :param chan: The channel to forward to.
+            :param pump_done: Set when either direction has finished.
+        """
+        while self._active is True and pump_done.is_set() is False and chan.closed is False:
+            read_ready, _, _ = select.select([conn], [], [], PUMP_POLL_INTERVAL)
+            if conn not in read_ready:
+                continue
+
+            data = conn.recv(PUMP_CHUNK_SIZE)
+            if len(data) == 0:
+                # The local client closed its side of the connection.
+                break
+
+            chan.send(data)
+
+        return
+
+    def _pump_channel_to_socket(self, conn: socket.socket, chan: SshChannel, pump_done: threading.Event):
+        """
+            Forward data from the SSH channel to the local socket until the peer closes the channel, the other
+            direction finishes, or the tunnel shuts down.  Runs on its own thread.
+
+            :param conn: The local client connection socket.
+            :param chan: The channel to forward from.
+            :param pump_done: Set when either direction has finished; set by this method when it finishes, unless
+                              the peer only half-closed the channel.
+        """
+        finish_pump = True
+        try:
+            while self._active is True and pump_done.is_set() is False:
+                data = chan.recv(PUMP_CHUNK_SIZE, timeout=PUMP_POLL_INTERVAL)
+                if len(data) > 0:
+                    conn.sendall(data)
+                elif chan.closed is True or chan.eof_received is True:
+                    # Everything the peer sent has been forwarded; let the local client see end-of-stream now
+                    # instead of when the socket direction next polls.
+                    try:
+                        conn.shutdown(socket.SHUT_WR)
+                    except OSError as xcpt:
+                        logger.debug(f"Error shutting down the local socket at the end of the channel data: {xcpt}")
+
+                    if chan.closed is False:
+                        # Half-close: the peer sends no more data but still receives, so the socket direction
+                        # keeps forwarding until the local client or the peer closes.
+                        finish_pump = False
+                    break
+                # Otherwise the receive timed out; loop to re-check for shutdown.
+        except OSError as xcpt:
+            # The local client went away while data was being written to it.
+            logger.debug(f"Local socket error while forwarding channel data: {xcpt}")
+        finally:
+            if finish_pump is True:
+                pump_done.set()
+
+        return
+
+    def _cleanup_finished_threads(self):
+        """
+            Remove finished threads from the connection thread list.
+        """
+        with self._connection_lock:
+            self._connection_threads = [t for t in self._connection_threads if t.is_alive()]
+
+    @property
+    def local_port(self) -> int:
+        """
+            Returns the actual local port being used for the tunnel.
+
+            :returns: The local port number.
+            
+            :raises: RuntimeError if the tunnel is not properly initialized.
+        """
+        if self._actual_local_port is None:
+            raise RuntimeError("Tunnel is not properly initialized - no local port assigned")
+        return self._actual_local_port
+
+    @property
+    def remote_host(self) -> str:
+        """
+            Returns the remote host being forwarded to.
+
+            :returns: The remote host.
+        """
+        return self._remote_host
+
+    @property
+    def remote_port(self) -> int:
+        """
+            Returns the remote port being forwarded to.
+
+            :returns: The remote port number.
+        """
+        return self._remote_port
+
+    @property
+    def is_active(self) -> bool:
+        """
+            Returns whether the tunnel is currently active.
+
+            :returns: True if active, False otherwise.
+        """
+        return self._active
+
+    def get_connection_string(self, database: str = None, username: str = None, password: str = None, db_type: str = 'postgresql') -> str:
+        """
+            Helper method to generate database connection strings for use with SQLAlchemy or other ORMs.
+
+            :param database: Optional database name.
+            :param username: Optional username for the connection string.
+            :param password: Optional password for the connection string.
+            :param db_type: Database type (postgresql, mysql, etc.).
+
+            :returns: A connection string template for the tunneled connection.
+            
+            :raises: RuntimeError if the tunnel is not properly initialized.
+        """
+        local_port = self.local_port  # This will raise RuntimeError if not initialized
+        base_url = f"127.0.0.1:{local_port}"
+        
+        conn_str: str
+
+        # Build authentication part
+        auth_part = ""
+        if username:
+            if password:
+                auth_part = f"{username}:{password}@"
+            else:
+                auth_part = f"{username}@"
+        
+        # Build connection string
+        if database:
+            conn_str = f"{db_type}://{auth_part}{base_url}/{database}"
+        elif auth_part or db_type != 'postgresql':
+            # Include protocol if we have auth or non-default db_type
+            conn_str = f"{db_type}://{auth_part}{base_url}"
+        else:
+            conn_str = base_url
+
+        return conn_str

codecraftai_protocol_ssh-1.3.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: codecraftai-protocol-ssh
+Version: 1.3.0
+Summary: Code Craft AI - SSH Protocol
+License-Expression: LicenseRef-CodeCraftAI-Source-Available
+License-File: LICENSE.md
+Keywords: python
+Author: Myron Walker
+Author-email: myron.walker@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX
+Requires-Dist: codecraftai-credentials (<2.0.0)
+Requires-Dist: codecraftai-foundations (<2.0.0)
+Requires-Dist: codecraftai-interop (<2.0.0)
+Requires-Dist: codecraftai-xmodules (<2.0.0)
+Requires-Dist: cryptography (>=45.0.5,<51.0.0)
+Project-URL: Issues, https://github.com/code-craft-ai-company/codecraftai-protocol-ssh/issues
+Project-URL: Repository, https://github.com/code-craft-ai-company/codecraftai-protocol-ssh
+Description-Content-Type: text/x-rst
+
+==============================
+Code Craft AI Protocol SSH
+==============================
+
+The ``codecraftai-protocol-ssh`` package is the dedicated SSH-protocol implementation for the ccai suite. It provides the building blocks (transport, session, packet handling, SFTP, tunnels, key and authentication handling, and a client/agent facade) used by any higher-level ccai package that needs to manage remote systems over SSH. It is consumed by ``codecraftai-interop``, ``codecraftai-landscaping`` (SSH-based coordinators), and the sysman packages that reach hosts over SSH.
+
+Highlights
+==========
+
+- Connection lifecycle classes: ``SshBase``, ``SshClient``, ``SshConnection``, ``SshSession``, ``SshTransport``, and ``SshAgent``.
+- ``SshAspects`` for packaging behaviour parameters (retry, timeout, action pattern) on SSH calls in the aspects style.
+- Key and authentication helpers in ``sshkeys.py`` and ``sshauth.py``.
+- SFTP and tunnel support in ``sshsftp.py`` and ``sshtunnel.py``.
+- RFC-aligned implementations of the SSH transport and user authentication layers.
+
+Repository Structure
+====================
+
+- ``development/`` - Runtime environment scripts.
+- ``repository-setup/`` - Repository homing and setup scripts.
+- ``source/packages/`` - Package source code.
+- ``source/tests/`` - ``unittest``-based tests.
+- ``source/testroots/testbase/`` - TestBase test roots.
+- ``specs/`` - Requirements, design, and reference RFC documents.
+- ``userguide/`` - Standards, conventions, and documentation.
+
+Environment Setup
+=================
+
+When working in a Codex container:
+
+.. code-block:: bash
+
+   ./development/setup-agent-container
+
+For local development:
+
+.. code-block:: bash
+
+   ./repository-setup/rehome-repository
+   ./development/setup-envrionment
+
+Running Tests
+=============
+
+Activate the virtual environment:
+
+.. code-block:: bash
+
+   source .venv/bin/activate
+
+Run ``unittest`` tests:
+
+.. code-block:: bash
+
+   python -m unittest discover -s source/tests -p "test_*.py"
+
+Run TestBase tests (when test roots are populated):
+
+.. code-block:: bash
+
+   testbase testing run --root source/testroots/testbase --includes=ccai --output=./.output
+
+Standards and Conventions
+=========================
+
+- Naming conventions: ``userguide/10-02-naming-conventions.rst``
+- Code organization: ``userguide/10-01-code-organization.rst``
+- Coding standards: ``userguide/10-00-coding-standards.rst``
+
+Additional Resources
+====================
+
+- Design documentation: ``specs/design.md``
+- Requirements: ``specs/requirements.md``
+- SSH protocol RFCs: ``specs/rfc4251.txt``, ``specs/rfc4252.txt``, ``specs/rfc4254.txt``
+

codecraftai_protocol_ssh-1.3.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+ccai/protocols/ssh/__init__.py,sha256=lu-IgDXxPNOP1XbgPcTHUDZRLydfLM_g2SVOZkVbVEk,36
+ccai/protocols/ssh/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ccai/protocols/ssh/sshagent.py,sha256=b0ibg4zcEB1v_1MfsoLx0YIxoaNialYPGOYfZA7MzKA,16161
+ccai/protocols/ssh/sshauth.py,sha256=v91KY-nzS68mpzaISpmUN83kQJPHdt4ZjIxbMhClky4,4002
+ccai/protocols/ssh/sshbase.py,sha256=srnHnSXbT2WuW51eQQowQj1hvrEh9hMZ8h23xLkBP7E,33054
+ccai/protocols/ssh/sshclient.py,sha256=-RRJzVF7dq176GS3m6B1qeHrVa7THliaNTeKZtEjv_4,6073
+ccai/protocols/ssh/sshconnection.py,sha256=VqlnzvobgiHNCWrRlPA96rjRrpHRsL6sih5K4Bw7H4U,61138
+ccai/protocols/ssh/sshconst.py,sha256=YP-C14z6ZJVfY6K-1MEshsp-GXh6r-W1HoE2hWYWk30,1686
+ccai/protocols/ssh/sshconstants.py,sha256=x69F3VmGNxa_x0epms9OwNjK31dPeJh7mFDaUeO3FeQ,3904
+ccai/protocols/ssh/sshhelpers.py,sha256=FZKZ0OmgsGZv4rOtLsICp7Kbk1na7NkTtm9sEr6rl6g,28592
+ccai/protocols/ssh/sshkeys.py,sha256=Voe-cgVcEauXr8HRUCYI_xfdlFx3Q8xn3YM1v4Szu8A,6036
+ccai/protocols/ssh/sshpacket.py,sha256=vKrIboQ5a5F3EtPoQfHSjoSzgd4fL1cSQ4aaqzabdpI,4231
+ccai/protocols/ssh/sshsession.py,sha256=6fsVPv6FUHJptyMbEtCOGbsmdfpGVWXA9Ao7o8mP5so,20280
+ccai/protocols/ssh/sshsftp.py,sha256=AivLsw8iQTMklsBhW7MSJDdN21fAkwYKvW2g4pHA_n0,10463
+ccai/protocols/ssh/sshtransport.py,sha256=Zycje7iO2Z21NZOyn8wa7KcN_2M7QYHIZmV3St7T9-s,31314
+ccai/protocols/ssh/sshtunnel.py,sha256=40xId1h9yftoFRC-ot_6gud2MJALzZte-pn6G9rxf0E,19278
+codecraftai_protocol_ssh-1.3.0.dist-info/METADATA,sha256=rtsxPI7Op5-T0KbznoF_0z7EReHr4apUFVWFRY252sg,3453
+codecraftai_protocol_ssh-1.3.0.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
+codecraftai_protocol_ssh-1.3.0.dist-info/licenses/LICENSE.md,sha256=5tyUZ2kpPxNXbULzrdiT14-ZV-jCBeBFL0xyO-zt1mg,17907
+codecraftai_protocol_ssh-1.3.0.dist-info/RECORD,,

codecraftai_protocol_ssh-1.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.5.0
+Root-Is-Purelib: true
+Tag: py3-none-any