terminaide 0.0.1__py3-none-any.whl

terminaide/__init__.py

@@ -0,0 +1,148 @@
+# terminaide/__init__.py
+
+"""
+terminaide: Serve Python CLI applications in the browser using ttyd.
+
+This package provides tools to easily serve Python CLI applications through
+a browser-based terminal using ttyd. It handles binary installation and
+management automatically across supported platforms.
+
+Supported Platforms:
+- Linux x86_64 (Docker containers)
+- macOS ARM64 (Apple Silicon)
+"""
+
+import logging
+from fastapi import FastAPI
+from pathlib import Path
+from typing import Optional, Dict, Any, Union
+
+# Configure package-level logging
+logging.getLogger("terminaide").addHandler(logging.NullHandler())
+
+# Core functionality
+from .core.settings import TTYDConfig
+from .serve import serve_tty, _configure_app
+
+# Installation management
+from .installer import setup_ttyd, get_platform_info
+
+# Expose all exceptions
+from .exceptions import (
+    terminaideError,
+    BinaryError,
+    InstallationError,
+    PlatformNotSupportedError,
+    DependencyError,
+    DownloadError,
+    TTYDStartupError,
+    TTYDProcessError,
+    ClientScriptError,
+    TemplateError,
+    ProxyError,
+    ConfigurationError
+)
+
+__version__ = "0.2.0"  # Updated version number
+__all__ = [
+    # Main functionality
+    "serve_tty",
+    "TTYDConfig",
+    
+    # Binary management
+    "setup_ttyd",
+    "get_platform_info",
+    
+    # Exceptions
+    "terminaideError",
+    "BinaryError",
+    "InstallationError",
+    "PlatformNotSupportedError",
+    "DependencyError",
+    "DownloadError",
+    "TTYDStartupError",
+    "TTYDProcessError",
+    "ClientScriptError",
+    "TemplateError",
+    "ProxyError",
+    "ConfigurationError"
+]
+
+# Type aliases for better documentation
+ThemeConfig = Dict[str, str]
+TTYDOptions = Dict[str, Any]
+
+def serve_tty(
+    app: FastAPI,
+    client_script: Union[str, Path],
+    *,
+    mount_path: str = "/tty",
+    port: int = 7681,
+    theme: Optional[ThemeConfig] = None,
+    ttyd_options: Optional[TTYDOptions] = None,
+    template_override: Optional[Union[str, Path]] = None,
+    debug: bool = False
+) -> None:
+    """
+    Configure FastAPI application to serve a Python script through a browser-based terminal.
+
+    This function automatically handles ttyd binary installation and setup for the
+    current platform. Supported platforms are Linux x86_64 (for Docker) and
+    macOS ARM64 (Apple Silicon).
+
+    Args:
+        app: FastAPI application instance
+        client_script: Path to Python script to run in terminal
+        mount_path: URL path to mount terminal (default: "/tty")
+        port: Port for ttyd process (default: 7681)
+        theme: Terminal theme configuration (default: {"background": "black"})
+        ttyd_options: Additional ttyd process options
+        template_override: Custom HTML template path
+        debug: Enable development mode with auto-reload (default: False)
+
+    Raises:
+        InstallationError: If ttyd binary installation fails
+        PlatformNotSupportedError: If running on an unsupported platform
+        DependencyError: If required system libraries are missing
+        TTYDStartupError: If ttyd fails to start
+        ClientScriptError: If client script cannot be found or executed
+        ConfigurationError: If provided configuration values are invalid
+
+    Example:
+        ```python
+        from fastapi import FastAPI
+        from terminaide import serve_tty
+
+        app = FastAPI()
+        
+        # Basic usage
+        serve_tty(app, "client.py")
+
+        # Custom configuration
+        serve_tty(
+            app,
+            "client.py",
+            mount_path="/terminal",
+            theme={"background": "#1a1a1a"},
+            debug=True
+        )
+        ```
+
+    Notes:
+        - For Docker deployments, the package automatically handles ttyd installation
+        - Binary installation happens on first use and is cached for subsequent runs
+        - In Docker, required system libraries (libwebsockets, json-c) must be present
+    """
+    # Create configuration object
+    config = TTYDConfig(
+        client_script=client_script,
+        mount_path=mount_path,
+        port=port,
+        theme=theme or {"background": "black"},
+        ttyd_options=ttyd_options or {},
+        template_override=template_override,
+        debug=debug
+    )
+    
+    # Configure the application with our ttyd setup
+    _configure_app(app, config)

terminaide/core/manager.py

@@ -0,0 +1,272 @@
+# terminaide/core/manager.py
+
+"""
+TTYd process management and lifecycle control.
+
+This module is responsible for starting, monitoring, and stopping the ttyd process.
+It ensures proper process cleanup and provides health monitoring capabilities.
+The manager adapts its behavior based on whether we're using root or non-root
+mounting configurations.
+"""
+
+import os
+import signal
+import logging
+import subprocess
+from datetime import datetime
+from typing import Optional, List, Dict, Any
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+
+from ..exceptions import TTYDStartupError, TTYDProcessError
+from ..installer import setup_ttyd
+from .settings import TTYDConfig
+
+logger = logging.getLogger("terminaide")
+
+class TTYDManager:
+    """
+    Manages the lifecycle of the ttyd process.
+    
+    This class handles all aspects of the ttyd process, including:
+    - Process startup and shutdown
+    - Health monitoring
+    - Resource cleanup
+    - Signal handling
+    """
+    
+    def __init__(self, config: TTYDConfig):
+        """
+        Initialize the TTYDManager.
+
+        Args:
+            config: TTYDConfig instance with process configuration
+        """
+        self.config = config
+        self.process: Optional[subprocess.Popen] = None
+        self._start_time: Optional[datetime] = None
+        self._ttyd_path: Optional[Path] = None
+        self._setup_ttyd()
+
+    def _setup_ttyd(self) -> None:
+        """
+        Set up ttyd binary and verify it's ready to use.
+        
+        This method handles the installation and verification of the ttyd binary,
+        using our installer module to manage platform-specific binaries.
+        """
+        try:
+            self._ttyd_path = setup_ttyd()
+            logger.info(f"Using ttyd binary at: {self._ttyd_path}")
+        except Exception as e:
+            logger.error(f"Failed to set up ttyd: {e}")
+            raise TTYDStartupError(f"Failed to set up ttyd: {e}")
+
+    def _build_command(self) -> List[str]:
+        """
+        Build the ttyd command with all necessary arguments.
+        
+        This method constructs the command line arguments for ttyd based on
+        the current configuration, taking into account both root and non-root
+        mounting scenarios.
+        
+        Returns:
+            List of command arguments for ttyd process
+        """
+        if not self._ttyd_path:
+            raise TTYDStartupError("ttyd binary path not set")
+            
+        cmd = [str(self._ttyd_path)]
+        
+        # Basic configuration
+        cmd.extend(['-p', str(self.config.port)])
+        cmd.extend(['-i', self.config.ttyd_options.interface])
+        
+        # Security settings
+        if not self.config.ttyd_options.check_origin:
+            cmd.append('--no-check-origin')
+        
+        if self.config.ttyd_options.credential_required:
+            if not (self.config.ttyd_options.username and self.config.ttyd_options.password):
+                raise TTYDStartupError("Credentials required but not provided")
+            cmd.extend([
+                '-c', 
+                f"{self.config.ttyd_options.username}:{self.config.ttyd_options.password}"
+            ])
+        
+        # Debug mode settings
+        if self.config.debug:
+            cmd.extend(['-d', '3'])  # Maximum debug output
+        
+        # Terminal customization
+        theme_json = self.config.theme.model_dump_json()
+        cmd.extend(['-t', f'theme={theme_json}'])
+        
+        # Explicitly set writable or read-only mode
+        if self.config.ttyd_options.writable:
+            cmd.append('--writable')
+        else:
+            cmd.append('-R')
+        
+        # Add client script to run in the terminal
+        cmd.extend([
+            'python',
+            str(self.config.client_script)
+        ])
+        
+        return cmd
+
+    def start(self) -> None:
+        """
+        Start the ttyd process with the current configuration.
+        
+        This method launches ttyd with appropriate settings and monitors
+        its startup to ensure it's running correctly.
+
+        Raises:
+            TTYDStartupError: If process fails to start
+            TTYDProcessError: If process is already running
+        """
+        if self.is_running:
+            raise TTYDProcessError("TTYd process is already running")
+
+        cmd = self._build_command()
+        cmd_str = ' '.join(cmd)
+        logger.info(f"Starting ttyd with command: {cmd_str}")
+
+        try:
+            # Start the process in a new session to isolate signals
+            self.process = subprocess.Popen(
+                cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                start_new_session=True
+            )
+            self._start_time = datetime.now()
+
+            # Monitor startup with longer timeout in debug mode
+            timeout = 4 if self.config.debug else 2
+            check_interval = 0.1
+            checks = int(timeout / check_interval)
+
+            for _ in range(checks):
+                if self.process.poll() is not None:
+                    stderr = self.process.stderr.read().decode('utf-8')
+                    logger.error(f"ttyd failed to start. Error: {stderr}")
+                    raise TTYDStartupError(stderr=stderr)
+                    
+                if self.is_running:
+                    mount_type = "root" if self.config.is_root_mounted else "non-root"
+                    logger.info(
+                        f"ttyd process started successfully with PID {self.process.pid} "
+                        f"({mount_type} mounting)"
+                    )
+                    return
+                    
+                import time
+                time.sleep(check_interval)
+                
+            logger.error("ttyd process did not start within timeout")
+            raise TTYDStartupError("ttyd process did not start within timeout")
+
+        except subprocess.SubprocessError as e:
+            logger.error(f"Failed to start ttyd: {e}")
+            raise TTYDStartupError(str(e))
+
+    def stop(self) -> None:
+        """
+        Stop the ttyd process if it's running.
+        
+        This method ensures clean process termination using SIGTERM first,
+        followed by SIGKILL if necessary. It handles cases where the process
+        might have already been terminated.
+        """
+        if self.process:
+            logger.info("Stopping ttyd process...")
+            
+            try:
+                # Try graceful shutdown first
+                if os.name == 'nt':  # Windows
+                    self.process.terminate()
+                else:  # Unix-like
+                    try:
+                        pgid = os.getpgid(self.process.pid)
+                        os.killpg(pgid, signal.SIGTERM)
+                    except ProcessLookupError:
+                        # Process is already gone, which is fine
+                        pass
+
+                try:
+                    self.process.wait(timeout=5)  # Wait up to 5 seconds
+                except subprocess.TimeoutExpired:
+                    # Force kill if graceful shutdown fails
+                    if os.name == 'nt':
+                        self.process.kill()
+                    else:
+                        try:
+                            pgid = os.getpgid(self.process.pid)
+                            os.killpg(pgid, signal.SIGKILL)
+                        except ProcessLookupError:
+                            # Process is already gone, which is fine
+                            pass
+                    
+                    try:
+                        self.process.wait(timeout=1)
+                    except subprocess.TimeoutExpired:
+                        # If we still can't wait, the process is probably zombie or gone
+                        pass
+
+            except Exception as e:
+                logger.warning(f"Error during process cleanup: {e}")
+            
+            self.process = None
+            self._start_time = None
+            logger.info("ttyd process stopped successfully")
+
+    @property
+    def is_running(self) -> bool:
+        """Check if ttyd process is currently running."""
+        return bool(self.process and self.process.poll() is None)
+
+    @property
+    def uptime(self) -> Optional[float]:
+        """Get process uptime in seconds, if running."""
+        if self._start_time and self.is_running:
+            return (datetime.now() - self._start_time).total_seconds()
+        return None
+
+    def check_health(self) -> Dict[str, Any]:
+        """
+        Get comprehensive health check information about the process.
+        
+        Returns:
+            Dictionary containing process status, uptime, and configuration details
+        """
+        return {
+            "status": "running" if self.is_running else "stopped",
+            "uptime": self.uptime,
+            "pid": self.process.pid if self.process else None,
+            "mounting": "root" if self.config.is_root_mounted else "non-root",
+            "terminal_path": self.config.terminal_path,
+            "ttyd_path": str(self._ttyd_path) if self._ttyd_path else None,
+            **self.config.get_health_check_info()
+        }
+
+    @asynccontextmanager
+    async def lifespan(self, app: FastAPI):
+        """
+        Manage ttyd process lifecycle within FastAPI application.
+        
+        This context manager ensures proper startup and cleanup of the ttyd
+        process during the application lifecycle.
+        
+        Usage:
+            app = FastAPI(lifespan=manager.lifespan)
+        """
+        try:
+            self.start()
+            yield
+        finally:
+            self.stop()

terminaide/core/proxy.py

@@ -0,0 +1,281 @@
+# terminaide/core/proxy.py
+
+"""
+Proxy management for ttyd HTTP and WebSocket connections.
+
+This module handles the proxying of both HTTP and WebSocket connections to the ttyd
+process, with special handling for path management to support both root and non-root
+mounting configurations.
+"""
+
+import json
+import logging
+import asyncio
+from typing import Optional, Dict, Any
+from urllib.parse import urljoin
+
+import httpx
+import websockets
+import websockets.exceptions
+from fastapi import Request, WebSocket, HTTPException
+from fastapi.responses import Response, StreamingResponse
+
+from ..exceptions import ProxyError
+from .settings import TTYDConfig
+
+logger = logging.getLogger("terminaide")
+
+class ProxyManager:
+    """
+    Manages HTTP and WebSocket proxying for ttyd while maintaining same-origin security.
+    
+    This class handles the complexities of proxying requests to the ttyd process,
+    including path rewriting and WebSocket connection management. It supports both
+    root ("/") and non-root ("/path") mounting configurations.
+    """
+    
+    def __init__(self, config: TTYDConfig):
+        """
+        Initialize the proxy manager.
+
+        Args:
+            config: TTYDConfig instance with proxy configuration
+        """
+        self.config = config
+        self._client: Optional[httpx.AsyncClient] = None
+        
+        # Build base URLs for the ttyd process
+        host = f"{self.config.ttyd_options.interface}:{self.config.port}"
+        self.target_url = f"http://{host}"
+        self.ws_url = f"ws://{host}/ws"
+        
+        logger.info(
+            f"Proxy configured for ttyd at {self.target_url} "
+            f"(terminal path: {self.config.terminal_path})"
+        )
+
+    @property
+    def http_client(self) -> httpx.AsyncClient:
+        """Lazy initialization of HTTP client."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                timeout=httpx.Timeout(30.0),
+                follow_redirects=True
+            )
+        return self._client
+
+    async def cleanup(self) -> None:
+        """Clean up resources."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    def _strip_path_prefix(self, path: str) -> str:
+        """
+        Strip the mount path prefix from the request path.
+        
+        This method handles both root and non-root mounting scenarios to ensure
+        requests are properly forwarded to ttyd.
+        
+        Args:
+            path: Original request path
+            
+        Returns:
+            Path with prefix stripped for ttyd
+        """
+        # For root mounting, we only need to strip the /terminal prefix
+        if self.config.is_root_mounted:
+            if path.startswith("/terminal/"):
+                return path.replace("/terminal", "", 1)
+            return "/"
+            
+        # For non-root mounting, strip both the mount path and /terminal
+        prefix = self.config.terminal_path
+        if path.startswith(prefix):
+            return path.replace(prefix, "", 1) or "/"
+        return "/"
+
+    async def _handle_sourcemap(self, path: str) -> Response:
+        """Handle sourcemap requests with minimal response."""
+        return Response(
+            content=json.dumps({
+                "version": 3,
+                "file": path.split('/')[-1].replace('.map', ''),
+                "sourceRoot": "",
+                "sources": ["source.js"],
+                "sourcesContent": ["// Source code unavailable"],
+                "names": [],
+                "mappings": ";;;;;;;",
+            }),
+            media_type='application/json',
+            headers={'Access-Control-Allow-Origin': '*'}
+        )
+
+    async def proxy_http(self, request: Request) -> Response:
+        """
+        Proxy HTTP requests to ttyd.
+        
+        This method handles path rewriting and forwards the request to the ttyd
+        process, supporting both root and non-root mounting configurations.
+
+        Args:
+            request: Incoming FastAPI request
+
+        Returns:
+            Proxied response from ttyd
+
+        Raises:
+            ProxyError: If proxying fails
+        """
+        path = request.url.path
+        
+        # Handle sourcemap requests
+        if path.endswith('.map'):
+            return await self._handle_sourcemap(path)
+            
+        # Strip the appropriate prefix based on mounting configuration
+        target_path = self._strip_path_prefix(path)
+        
+        try:
+            # Forward the request to ttyd
+            headers = dict(request.headers)
+            headers.pop("host", None)  # Remove host header
+            
+            response = await self.http_client.request(
+                method=request.method,
+                url=urljoin(self.target_url, target_path),
+                headers=headers,
+                content=await request.body()
+            )
+            
+            # Clean response headers that might cause issues
+            response_headers = {
+                k: v for k, v in response.headers.items()
+                if k.lower() not in {
+                    'content-encoding',
+                    'content-length',
+                    'transfer-encoding'
+                }
+            }
+            
+            return StreamingResponse(
+                response.aiter_bytes(),
+                status_code=response.status_code,
+                headers=response_headers,
+                media_type=response.headers.get('content-type')
+            )
+
+        except httpx.RequestError as e:
+            logger.error(f"HTTP proxy error: {e}")
+            raise ProxyError(f"Failed to proxy request: {e}")
+
+    async def proxy_websocket(self, websocket: WebSocket) -> None:
+        """
+        Proxy WebSocket connections to ttyd.
+        
+        This method handles the WebSocket connection to the ttyd process,
+        including proper error handling and cleanup.
+
+        Args:
+            websocket: Incoming WebSocket connection
+
+        Raises:
+            ProxyError: If WebSocket proxying fails
+        """
+        try:
+            # Accept the incoming connection with ttyd subprotocol
+            await websocket.accept(subprotocol='tty')
+            
+            logger.info(f"Opening WebSocket connection to {self.ws_url}")
+            
+            async with websockets.connect(
+                self.ws_url,
+                subprotocols=['tty'],
+                ping_interval=None,
+                close_timeout=5
+            ) as target_ws:
+                logger.info("WebSocket connection established")
+                
+                # Set up bidirectional forwarding
+                async def forward(source: Any, dest: Any, is_client: bool = True) -> None:
+                    """Forward data between WebSocket connections."""
+                    try:
+                        while True:
+                            try:
+                                # Handle different WebSocket implementations
+                                if is_client:
+                                    data = await source.receive_bytes()
+                                    await dest.send(data)
+                                else:
+                                    data = await source.recv()
+                                    if isinstance(data, bytes):
+                                        await dest.send_bytes(data)
+                                    else:
+                                        await dest.send_text(data)
+                            except websockets.exceptions.ConnectionClosed:
+                                logger.info(
+                                    f"{'Client' if is_client else 'Target'} "
+                                    "connection closed normally"
+                                )
+                                break
+                            except Exception as e:
+                                if not isinstance(e, asyncio.CancelledError):
+                                    logger.error(
+                                        f"{'Client' if is_client else 'Target'} "
+                                        f"connection error: {e}"
+                                    )
+                                break
+
+                    except asyncio.CancelledError:
+                        logger.info(
+                            f"{'Client' if is_client else 'Target'} "
+                            "forwarding cancelled"
+                        )
+                        raise
+                    except Exception as e:
+                        if not isinstance(e, websockets.exceptions.ConnectionClosed):
+                            logger.error(f"WebSocket forward error: {e}")
+
+                # Create forwarding tasks
+                tasks = [
+                    asyncio.create_task(forward(websocket, target_ws)),
+                    asyncio.create_task(forward(target_ws, websocket, False))
+                ]
+                
+                try:
+                    # Wait for either direction to complete
+                    await asyncio.wait(
+                        tasks,
+                        return_when=asyncio.FIRST_COMPLETED
+                    )
+                finally:
+                    # Clean up tasks
+                    for task in tasks:
+                        if not task.done():
+                            task.cancel()
+                            try:
+                                await task
+                            except asyncio.CancelledError:
+                                pass
+
+        except Exception as e:
+            logger.error(f"WebSocket proxy error: {e}")
+            if not isinstance(e, websockets.exceptions.ConnectionClosed):
+                raise ProxyError(f"WebSocket proxy error: {e}")
+        
+        finally:
+            # Ensure WebSocket is closed
+            try:
+                await websocket.close()
+            except Exception:
+                pass  # Connection already closed
+
+    def get_routes_info(self) -> Dict[str, Any]:
+        """Get information about proxy routes for monitoring."""
+        return {
+            "http_endpoint": self.target_url,
+            "ws_endpoint": self.ws_url,
+            "mount_path": self.config.mount_path,
+            "terminal_path": self.config.terminal_path,
+            "is_root_mounted": self.config.is_root_mounted
+        }