ptn 0.1.0__py3-none-any.whl

porterminal/__init__.py

@@ -0,0 +1,288 @@
+"""
+Porterminal - Web-based terminal accessible via Cloudflare Tunnel.
+
+This package provides:
+- FastAPI server with WebSocket terminal endpoint
+- PTY management with cross-platform support (Windows/Unix)
+- Session management with reconnection support
+- Configuration system with shell auto-detection
+"""
+
+__version__ = "0.1.0"
+
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from threading import Thread
+
+from rich.console import Console
+
+from porterminal.cli import display_startup_screen, parse_args
+from porterminal.infrastructure import (
+    CloudflaredInstaller,
+    drain_process_output,
+    find_available_port,
+    is_port_available,
+    start_cloudflared,
+    start_server,
+    wait_for_server,
+)
+
+console = Console()
+
+
+def _run_in_background(args) -> int:
+    """Spawn the server in background and return immediately."""
+    import tempfile
+
+    # Create temp file for URL communication
+    url_file = Path(tempfile.gettempdir()) / f"porterminal-{os.getpid()}.url"
+
+    # Build command without --background flag, with URL file
+    cmd = [sys.executable, "-m", "porterminal", f"--_url-file={url_file}"]
+    if args.path:
+        cmd.append(args.path)
+    if args.no_tunnel:
+        cmd.append("--no-tunnel")
+    if args.verbose:
+        cmd.append("--verbose")
+
+    # Start subprocess
+    popen_kwargs = {
+        "stdout": subprocess.DEVNULL,
+        "stderr": subprocess.DEVNULL,
+        "stdin": subprocess.DEVNULL,
+    }
+
+    if sys.platform == "win32":
+        # Windows: CREATE_NO_WINDOW hides console window
+        CREATE_NO_WINDOW = 0x08000000
+        popen_kwargs["creationflags"] = CREATE_NO_WINDOW
+    else:
+        # Unix: start_new_session to detach from terminal
+        popen_kwargs["start_new_session"] = True
+
+    try:
+        proc = subprocess.Popen(cmd, **popen_kwargs)
+    except Exception as e:
+        console.print(f"[red]Error starting process:[/red] {e}")
+        return 1
+
+    # Wait for URL file to be created (with timeout)
+    timeout = 30
+    start_time = time.time()
+
+    with console.status("[cyan]Starting in background...[/cyan]", spinner="dots") as status:
+        while time.time() - start_time < timeout:
+            if url_file.exists():
+                try:
+                    content = url_file.read_text().strip()
+                    if content:
+                        status.stop()
+                        url = content
+                        is_tunnel = url.startswith("https://")
+                        cwd = args.path or os.getcwd()
+
+                        # Display full startup screen with QR code
+                        display_startup_screen(url, is_tunnel=is_tunnel, cwd=cwd)
+
+                        # Add background mode info
+                        console.print(
+                            f"[green]Running in background[/green] [dim](PID: {proc.pid})[/dim]"
+                        )
+                        stop_cmd = (
+                            f"taskkill /T /PID {proc.pid} /F"
+                            if sys.platform == "win32"
+                            else f"kill {proc.pid}"
+                        )
+                        console.print(f"[dim]Stop with: {stop_cmd}[/dim]\n")
+
+                        # Cleanup temp file
+                        try:
+                            url_file.unlink()
+                        except OSError:
+                            pass
+                        return 0
+                except OSError:
+                    pass
+
+            if proc.poll() is not None:
+                status.stop()
+                console.print(
+                    f"[red]Error:[/red] Process exited unexpectedly (code: {proc.returncode})"
+                )
+                # Cleanup temp file
+                try:
+                    url_file.unlink()
+                except OSError:
+                    pass
+                return 1
+
+            time.sleep(0.2)
+
+    console.print("[red]Error:[/red] Timeout waiting for server to start")
+    # Kill the process tree (includes child shells)
+    if sys.platform == "win32":
+        subprocess.run(["taskkill", "/T", "/PID", str(proc.pid), "/F"], capture_output=True)
+    else:
+        proc.terminate()
+        try:
+            proc.wait(timeout=3)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+    return 1
+
+
+def main() -> int:
+    """Main entry point."""
+    args = parse_args()
+    verbose = args.verbose
+
+    # Handle background mode
+    if args.background:
+        return _run_in_background(args)
+
+    # Set log level based on verbose flag
+    if verbose:
+        os.environ["PORTERMINAL_LOG_LEVEL"] = "DEBUG"
+
+    # Validate and set working directory
+    cwd_str = None
+    if args.path:
+        cwd = Path(args.path).resolve()
+        if not cwd.exists():
+            console.print(f"[red]Error:[/red] Path does not exist: {cwd}")
+            return 1
+        if not cwd.is_dir():
+            console.print(f"[red]Error:[/red] Path is not a directory: {cwd}")
+            return 1
+        cwd_str = str(cwd)
+        os.environ["PORTERMINAL_CWD"] = cwd_str
+
+    from porterminal.config import get_config
+
+    config = get_config()
+    bind_host = config.server.host
+    preferred_port = config.server.port
+    port = preferred_port
+    # Use 127.0.0.1 for health checks (can't connect to 0.0.0.0)
+    check_host = "127.0.0.1" if bind_host == "0.0.0.0" else bind_host
+
+    # Check cloudflared (skip if --no-tunnel)
+    if not args.no_tunnel and not CloudflaredInstaller.is_installed():
+        console.print("[yellow]cloudflared not found[/yellow]")
+        if not CloudflaredInstaller.install():
+            console.print("[red]Error:[/red] Failed to install cloudflared")
+            console.print()
+            console.print("Install manually: [cyan]winget install cloudflare.cloudflared[/cyan]")
+            return 1
+        # Verify installation
+        if not CloudflaredInstaller.is_installed():
+            console.print("[red]Error:[/red] cloudflared still not found after install")
+            return 1
+
+    # Show startup status
+    with console.status("[cyan]Starting...[/cyan]", spinner="dots") as status:
+        # Start or reuse server
+        if wait_for_server(check_host, port, timeout=1):
+            if verbose:
+                console.print(f"[dim]Reusing server on {bind_host}:{port}[/dim]")
+            server_process = None
+        else:
+            if not is_port_available(bind_host, port):
+                port = find_available_port(bind_host, preferred_port)
+                if verbose:
+                    console.print(f"[dim]Using port {port}[/dim]")
+
+            status.update("[cyan]Starting server...[/cyan]")
+            server_process = start_server(bind_host, port, verbose=verbose)
+
+            if not wait_for_server(check_host, port, timeout=30):
+                console.print("[red]Error:[/red] Server failed to start")
+                if server_process and server_process.poll() is None:
+                    server_process.terminate()
+                    try:
+                        server_process.wait(timeout=3)
+                    except subprocess.TimeoutExpired:
+                        server_process.kill()
+                        server_process.wait()
+                return 1
+
+        tunnel_process = None
+        tunnel_url = None
+
+        if not args.no_tunnel:
+            status.update("[cyan]Establishing tunnel...[/cyan]")
+            tunnel_process, tunnel_url = start_cloudflared(port)
+
+            if not tunnel_url:
+                console.print("[red]Error:[/red] Failed to establish tunnel")
+                for proc in [server_process, tunnel_process]:
+                    if proc and proc.poll() is None:
+                        proc.terminate()
+                        try:
+                            proc.wait(timeout=3)
+                        except subprocess.TimeoutExpired:
+                            proc.kill()
+                            proc.wait()
+                return 1
+
+    # Determine final URL
+    display_cwd = cwd_str or os.getcwd()
+    if args.no_tunnel:
+        display_url = f"http://{check_host}:{port}"
+    else:
+        display_url = tunnel_url
+
+    # If running as background child, write URL to file and skip display
+    if args.url_file:
+        try:
+            Path(args.url_file).write_text(display_url)
+        except OSError as e:
+            console.print(f"[red]Error writing URL file:[/red] {e}")
+    else:
+        # Display final screen (only in foreground mode)
+        display_startup_screen(display_url, is_tunnel=not args.no_tunnel, cwd=display_cwd)
+
+    # Drain process output silently in background (only when not verbose)
+    if server_process is not None and not verbose:
+        Thread(target=drain_process_output, args=(server_process,), daemon=True).start()
+    if tunnel_process is not None:
+        Thread(target=drain_process_output, args=(tunnel_process,), daemon=True).start()
+
+    # Wait for Ctrl+C or process exit
+    try:
+        while True:
+            if server_process is not None and server_process.poll() is not None:
+                console.print("\n[red]Server stopped unexpectedly[/red]")
+                break
+            if tunnel_process is not None and tunnel_process.poll() is not None:
+                console.print("\n[red]Tunnel stopped unexpectedly[/red]")
+                break
+            time.sleep(1)
+
+    except KeyboardInterrupt:
+        console.print("\n[dim]Shutting down...[/dim]")
+
+    # Cleanup - terminate gracefully, then kill if needed
+    def cleanup_process(proc: subprocess.Popen | None, name: str) -> None:
+        if proc is None or proc.poll() is not None:
+            return
+        try:
+            proc.terminate()
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()  # Reap the killed process
+
+    cleanup_process(server_process, "server")
+    cleanup_process(tunnel_process, "tunnel")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

porterminal/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running as python -m porterminal."""
+
+import sys
+
+from porterminal import main
+
+if __name__ == "__main__":
+    sys.exit(main())

porterminal/app.py

@@ -0,0 +1,315 @@
+"""FastAPI application with security checks and WebSocket endpoint."""
+
+import asyncio
+import ctypes
+import logging
+import os
+import signal
+from contextlib import asynccontextmanager, suppress
+from pathlib import Path
+
+from fastapi import FastAPI, Query, Request, Response, WebSocket, WebSocketDisconnect
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.middleware.base import RequestResponseEndpoint
+
+from .composition import create_container
+from .container import Container
+from .domain import SessionId, TerminalDimensions, UserId
+from .infrastructure.web import FastAPIWebSocketAdapter
+from .logging_setup import setup_logging_from_env
+
+logger = logging.getLogger(__name__)
+
+# Path to static files (inside package)
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+def is_admin() -> bool:
+    """Check if running as administrator (Windows)."""
+    try:
+        return ctypes.windll.shell32.IsUserAnAdmin() != 0
+    except Exception:
+        return False
+
+
+def security_preflight_checks() -> None:
+    """Run security checks before starting the application."""
+    # Check not running as admin
+    if is_admin():
+        logger.warning(
+            "SECURITY WARNING: Running as Administrator is not recommended. "
+            "This exposes excessive privileges to remote users."
+        )
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan manager."""
+    # Startup
+    setup_logging_from_env()
+    security_preflight_checks()
+
+    # Create DI container with all wired dependencies
+    config_path = os.environ.get("PORTERMINAL_CONFIG_PATH", "config.yaml")
+    cwd = os.environ.get("PORTERMINAL_CWD")
+
+    container = create_container(config_path=config_path, cwd=cwd)
+    app.state.container = container
+
+    await container.session_service.start()
+
+    logger.info("Porterminal server started")
+
+    yield
+
+    # Shutdown
+    await container.session_service.stop()
+    logger.info("Porterminal server stopped")
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    app = FastAPI(
+        title="Porterminal",
+        description="Web-based terminal accessible from phone via Cloudflare Tunnel",
+        version="0.1.0",
+        lifespan=lifespan,
+    )
+
+    @app.middleware("http")
+    async def no_cache_static_assets(
+        request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        """Disable caching for static assets to ensure live updates during development."""
+        response = await call_next(request)
+        if request.url.path.startswith("/static/"):
+            response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
+            response.headers["Pragma"] = "no-cache"
+            response.headers["Expires"] = "0"
+        return response
+
+    # Mount static files
+    if STATIC_DIR.exists():
+        app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+    @app.get("/", response_class=HTMLResponse)
+    async def index():
+        """Serve the main page."""
+        index_path = STATIC_DIR / "index.html"
+        if index_path.exists():
+            content = index_path.read_text(encoding="utf-8")
+            return HTMLResponse(
+                content=content,
+                headers={
+                    "Cache-Control": "no-cache, no-store, must-revalidate",
+                    "Pragma": "no-cache",
+                    "Expires": "0",
+                },
+            )
+        return JSONResponse(
+            {"error": "index.html not found"},
+            status_code=404,
+        )
+
+    @app.get("/health")
+    async def health():
+        """Health check endpoint."""
+        container: Container = app.state.container
+        return {
+            "status": "healthy",
+            "sessions": container.session_service.session_count(),
+        }
+
+    @app.get("/api/config")
+    async def get_client_config():
+        """Get client configuration (shells and buttons)."""
+        container: Container = app.state.container
+        return {
+            "shells": [{"id": s.id, "name": s.name} for s in container.available_shells],
+            "buttons": container.buttons,
+            "default_shell": container.default_shell_id,
+        }
+
+    @app.post("/api/config/reload")
+    async def reload_configuration():
+        """Reload configuration from file.
+
+        Note: With the new DI architecture, hot-reload requires server restart.
+        """
+        return JSONResponse(
+            {"status": "info", "message": "Config reload requires server restart"},
+            status_code=501,
+        )
+
+    @app.post("/api/shutdown")
+    async def shutdown_server(request: Request):
+        """Shutdown the server and tunnel.
+
+        Only allowed from localhost or authenticated Cloudflare Access users.
+        """
+        # Check if request is from localhost
+        client_host = request.client.host if request.client else None
+        is_localhost = client_host in ("127.0.0.1", "::1", "localhost")
+
+        # Check for Cloudflare Access authentication
+        cf_user = request.headers.get("cf-access-authenticated-user-email")
+
+        if not is_localhost and not cf_user:
+            logger.warning(
+                "Unauthorized shutdown attempt from %s",
+                client_host,
+            )
+            return JSONResponse(
+                {
+                    "error": "Unauthorized - must be localhost or authenticated via Cloudflare Access"
+                },
+                status_code=403,
+            )
+
+        logger.info("Shutdown requested via API by %s", cf_user or client_host)
+
+        # Send response before shutting down
+        asyncio.get_running_loop().call_later(0.5, lambda: os.kill(os.getpid(), signal.SIGTERM))
+
+        return {"status": "ok", "message": "Server shutting down..."}
+
+    @app.websocket("/ws")
+    async def websocket_terminal(
+        websocket: WebSocket,
+        session_id: str | None = Query(None),
+        shell: str | None = Query(None),
+        skip_buffer: str | None = Query(None),
+    ):
+        """WebSocket endpoint for terminal communication."""
+        logger.info(
+            "WebSocket connect attempt client=%s session_id=%s shell=%s skip_buffer=%s",
+            getattr(websocket.client, "host", None),
+            session_id,
+            shell,
+            skip_buffer,
+        )
+        # Accept the connection
+        await websocket.accept()
+
+        # Get dependencies from container
+        container: Container = websocket.app.state.container
+        session_service = container.session_service
+        terminal_service = container.terminal_service
+
+        # Get user ID from headers (Cloudflare Access)
+        # For local testing, use a default user
+        user_id = UserId(websocket.headers.get("cf-access-authenticated-user-email", "local-user"))
+        connection = FastAPIWebSocketAdapter(websocket)
+        session = None
+
+        logger.info(
+            "WebSocket accepted client=%s user_id=%s session_id=%s shell=%s",
+            getattr(websocket.client, "host", None),
+            user_id,
+            session_id,
+            shell,
+        )
+
+        try:
+            if session_id:
+                # Reconnect to existing session
+                logger.info(
+                    "WebSocket reconnect requested user_id=%s session_id=%s", user_id, session_id
+                )
+                session = await session_service.reconnect_session(SessionId(session_id), user_id)
+                if not session:
+                    await connection.send_message(
+                        {
+                            "type": "error",
+                            "message": "Session not found or unauthorized",
+                        }
+                    )
+                    await connection.close(code=4004)
+                    logger.warning(
+                        "WebSocket reconnect denied user_id=%s session_id=%s", user_id, session_id
+                    )
+                    return
+                # reconnect_session already calls add_client()
+            else:
+                # Try to auto-join existing session first (for device switching)
+                session = session_service.get_active_session(user_id)
+                if session:
+                    # Join existing session
+                    session.add_client()
+                    logger.info(
+                        "WebSocket auto-joined existing session user_id=%s session_id=%s client_count=%d",
+                        user_id,
+                        session.session_id,
+                        session.connected_clients,
+                    )
+                else:
+                    # Create new session
+                    shell_cmd = container.get_shell(shell)
+                    if not shell_cmd:
+                        await connection.send_message(
+                            {"type": "error", "message": "No shell available"}
+                        )
+                        await connection.close(code=4006)
+                        return
+
+                    dims = TerminalDimensions(container.default_cols, container.default_rows)
+
+                    logger.info(
+                        "WebSocket creating new session user_id=%s shell=%s cols=%d rows=%d",
+                        user_id,
+                        shell_cmd.id,
+                        dims.cols,
+                        dims.rows,
+                    )
+                    session = await session_service.create_session(
+                        user_id=user_id,
+                        shell=shell_cmd,
+                        dimensions=dims,
+                    )
+                    session.add_client()
+                    logger.info(
+                        "WebSocket created session user_id=%s session_id=%s shell_id=%s",
+                        user_id,
+                        session.session_id,
+                        session.shell_id,
+                    )
+
+            # Handle the session using TerminalService
+            await terminal_service.handle_session(
+                session, connection, skip_buffer=bool(skip_buffer)
+            )
+
+        except ValueError as e:
+            # Session limit exceeded
+            await connection.send_message(
+                {
+                    "type": "error",
+                    "message": str(e),
+                }
+            )
+            await connection.close(code=4005)
+            logger.warning("WebSocket session limit user_id=%s error=%s", user_id, e)
+
+        except WebSocketDisconnect:
+            logger.info("Client disconnected user_id=%s", user_id)
+
+        except Exception:
+            logger.exception("WebSocket error user_id=%s", user_id)
+            with suppress(Exception):
+                await connection.close(code=1011)
+        finally:
+            if session:
+                session_service.disconnect_session(session.id)
+            actual_session_id = session_id or (session.session_id if session else None)
+            logger.info(
+                "WebSocket handler finished user_id=%s session_id=%s",
+                user_id,
+                actual_session_id,
+            )
+
+    return app
+
+
+# Create the app instance
+app = create_app()

porterminal/application/__init__.py

@@ -0,0 +1 @@
+"""Application layer - use cases and orchestration."""

porterminal/application/ports/__init__.py

@@ -0,0 +1,9 @@
+"""Application layer ports - interfaces for presentation layer."""
+
+from .config_port import ConfigPort
+from .connection_port import ConnectionPort
+
+__all__ = [
+    "ConnectionPort",
+    "ConfigPort",
+]

porterminal/application/ports/config_port.py

@@ -0,0 +1,42 @@
+"""Configuration port - interface for configuration access."""
+
+from typing import Any, Protocol
+
+
+class ConfigPort(Protocol):
+    """Protocol for configuration access.
+
+    Infrastructure layer implements this with actual config loading.
+    """
+
+    def get_server_host(self) -> str:
+        """Get server bind host."""
+        ...
+
+    def get_server_port(self) -> int:
+        """Get server port."""
+        ...
+
+    def get_default_cols(self) -> int:
+        """Get default terminal columns."""
+        ...
+
+    def get_default_rows(self) -> int:
+        """Get default terminal rows."""
+        ...
+
+    def get_default_shell_id(self) -> str:
+        """Get default shell ID."""
+        ...
+
+    def get_shell_by_id(self, shell_id: str) -> dict[str, Any] | None:
+        """Get shell configuration by ID."""
+        ...
+
+    def get_available_shells(self) -> list[dict[str, Any]]:
+        """Get list of available shells."""
+        ...
+
+    def get_buttons(self) -> list[dict[str, Any]]:
+        """Get custom button configurations."""
+        ...