torrus 0.1.0__tar.gz

torrus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anudeep Dhavaleswarapu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

torrus-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: torrus
+Version: 0.1.0
+Summary: Web-based SSH terminal that works behind any reverse proxy
+Author-email: Anudeep Dhavaleswarapu <anudeepd2@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/anudeepd/torrus
+Project-URL: Repository, https://github.com/anudeepd/torrus
+Project-URL: Issues, https://github.com/anudeepd/torrus/issues
+Keywords: ssh,terminal,web,xterm,remote
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: python-socketio>=5.11.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: paramiko>=3.4.0
+Requires-Dist: aiofiles>=23.2.0
+Requires-Dist: click>=8.1.0
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/anudeepd/torrus/main/assets/logo.svg" alt="Torrus" width="120"/>
+</p>
+
+<h1 align="center">Torrus</h1>
+
+<p align="center">A web-based SSH terminal that works behind any reverse proxy. Install it, run it, use it.</p>
+
+## Features
+
+- **Web-based SSH terminal** with full xterm.js emulation
+- **Multi-tab support** — open multiple SSH sessions side by side
+- **Saved servers** — save, edit, import, and export connection configs
+- **Works behind reverse proxies** — uses Socket.IO for reliable transport
+- **Session sidebar** — quick-connect to saved servers
+
+## Install
+
+```bash
+pip install torrus
+```
+
+## Usage
+
+```bash
+torrus serve
+```
+
+Opens the terminal in your browser. Connect to any SSH server from there.
+
+Options:
+
+```
+--host TEXT     Bind host. [default: 0.0.0.0]
+--port INTEGER  Bind port. [default: 8080]
+--no-browser    Don't open the browser automatically.
+```
+
+## Development
+
+Requires [uv](https://github.com/astral-sh/uv).
+
+```bash
+git clone https://github.com/anudeepd/torrus
+cd torrus
+uv sync
+make dev
+```
+
+## License
+
+MIT

torrus-0.1.0/README.md

@@ -0,0 +1,52 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/anudeepd/torrus/main/assets/logo.svg" alt="Torrus" width="120"/>
+</p>
+
+<h1 align="center">Torrus</h1>
+
+<p align="center">A web-based SSH terminal that works behind any reverse proxy. Install it, run it, use it.</p>
+
+## Features
+
+- **Web-based SSH terminal** with full xterm.js emulation
+- **Multi-tab support** — open multiple SSH sessions side by side
+- **Saved servers** — save, edit, import, and export connection configs
+- **Works behind reverse proxies** — uses Socket.IO for reliable transport
+- **Session sidebar** — quick-connect to saved servers
+
+## Install
+
+```bash
+pip install torrus
+```
+
+## Usage
+
+```bash
+torrus serve
+```
+
+Opens the terminal in your browser. Connect to any SSH server from there.
+
+Options:
+
+```
+--host TEXT     Bind host. [default: 0.0.0.0]
+--port INTEGER  Bind port. [default: 8080]
+--no-browser    Don't open the browser automatically.
+```
+
+## Development
+
+Requires [uv](https://github.com/astral-sh/uv).
+
+```bash
+git clone https://github.com/anudeepd/torrus
+cd torrus
+uv sync
+make dev
+```
+
+## License
+
+MIT

torrus-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "torrus"
+version = "0.1.0"
+description = "Web-based SSH terminal that works behind any reverse proxy"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Anudeep Dhavaleswarapu", email = "anudeepd2@gmail.com" }]
+keywords = ["ssh", "terminal", "web", "xterm", "remote"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Networking",
+]
+dependencies = [
+    "fastapi>=0.110.0",
+    "python-socketio>=5.11.0",
+    "uvicorn[standard]>=0.29.0",
+    "paramiko>=3.4.0",
+    "aiofiles>=23.2.0",
+    "click>=8.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/anudeepd/torrus"
+Repository = "https://github.com/anudeepd/torrus"
+Issues = "https://github.com/anudeepd/torrus/issues"
+
+[project.scripts]
+torrus = "torrus.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+torrus = ["static/**/*", "static/*"]

torrus-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

torrus-0.1.0/src/torrus/__init__.py

@@ -0,0 +1,3 @@
+"""torrus — web-based SSH terminal that works behind any reverse proxy."""
+
+__version__ = "0.1.0"

torrus-0.1.0/src/torrus/cli.py

@@ -0,0 +1,40 @@
+import logging
+import threading
+import webbrowser
+
+import click
+import uvicorn
+
+
+@click.group()
+def main():
+    """torrus — web-based SSH terminal."""
+    pass
+
+
+@main.command()
+@click.option("--host", default="0.0.0.0", show_default=True, help="Bind host")
+@click.option("--port", default=8080, show_default=True, help="Bind port")
+@click.option("--no-browser", is_flag=True, default=False, help="Don't open browser on startup")
+@click.option("--reload", is_flag=True, default=False, hidden=True, help="Dev auto-reload")
+def serve(host, port, no_browser, reload):
+    """Start the torrus SSH web terminal."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)-8s %(name)s %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+    if not no_browser:
+        browse_host = "127.0.0.1" if host == "0.0.0.0" else host
+        url = f"http://{browse_host}:{port}"
+        # Open after a short delay so uvicorn has time to bind
+        threading.Timer(1.5, webbrowser.open, args=[url]).start()
+
+    uvicorn.run(
+        "torrus.server:app",
+        host=host,
+        port=port,
+        reload=reload,
+        log_level="info",
+    )

torrus-0.1.0/src/torrus/server.py

@@ -0,0 +1,249 @@
+"""FastAPI + Socket.IO ASGI application."""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from contextlib import asynccontextmanager
+from importlib.resources import files
+from pathlib import Path
+
+import socketio
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from torrus.ssh_manager import SSHManager
+
+logger = logging.getLogger("torrus.server")
+
+_SAFE_ID = re.compile(r'^[a-zA-Z0-9_\-]+$')
+_DEV_MODE = bool(os.getenv("TORRUS_DEV"))
+
+
+def _safe_int(value, default: int) -> int:
+    """Parse an integer from untrusted input, returning default on failure."""
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _valid_id(value: str) -> bool:
+    """Check that an ID contains only safe characters."""
+    return bool(value and _SAFE_ID.match(value))
+
+
+def _static_dir() -> Path | None:
+    try:
+        p = Path(str(files("torrus").joinpath("static")))
+        return p if p.exists() else None
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Socket.IO + FastAPI setup
+# ---------------------------------------------------------------------------
+
+sio = socketio.AsyncServer(
+    async_mode="asgi",
+    cors_allowed_origins=(
+        ["http://localhost:5173", "http://127.0.0.1:5173"]
+        if _DEV_MODE
+        else []
+    ),
+    max_http_buffer_size=10_000_000,
+    ping_timeout=60,
+    ping_interval=25,
+    logger=False,
+    engineio_logger=False,
+)
+
+fastapi_app = FastAPI(title="torrus", docs_url=None, redoc_url=None)
+
+# CORS for Vite dev server
+if _DEV_MODE:
+    fastapi_app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["http://localhost:5173", "http://127.0.0.1:5173"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+# Combined ASGI app — uvicorn runs this
+app = socketio.ASGIApp(sio, other_asgi_app=fastapi_app)
+
+ssh_manager = SSHManager(sio)
+
+
+# ---------------------------------------------------------------------------
+# Static files + SPA fallback (only when built frontend exists)
+# ---------------------------------------------------------------------------
+
+_static = _static_dir()
+
+if _static:
+    # Serve /assets/ from Vite build output
+    assets_dir = _static / "assets"
+    if assets_dir.exists():
+        fastapi_app.mount("/assets", StaticFiles(directory=str(assets_dir)), name="assets")
+
+    # Serve /fonts/ from Python static dir (JetBrains Mono)
+    fonts_dir = _static / "fonts"
+    if fonts_dir.exists():
+        fastapi_app.mount("/fonts", StaticFiles(directory=str(fonts_dir)), name="fonts")
+
+
+@fastapi_app.get("/{full_path:path}", include_in_schema=False)
+async def spa_fallback(full_path: str):
+    if full_path.startswith("socket.io"):
+        return JSONResponse(status_code=404, content={"detail": "Not found"})
+    if _static:
+        index = _static / "index.html"
+        if index.exists():
+            return FileResponse(str(index))
+    return JSONResponse(
+        status_code=503,
+        content={"detail": "Frontend not built. Run: cd frontend && npm run build"},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Socket.IO lifecycle
+# ---------------------------------------------------------------------------
+
+@sio.on("connect")
+async def on_connect(sid, environ):
+    remote = environ.get("REMOTE_ADDR", "unknown")
+    logger.info("Client connected: %s (from %s)", sid, remote)
+
+
+@sio.on("disconnect")
+async def on_disconnect(sid):
+    ssh_manager.unmap_sid(sid)
+    logger.info("Client disconnected: %s", sid)
+
+
+# ---------------------------------------------------------------------------
+# Session registration / recovery
+# ---------------------------------------------------------------------------
+
+@sio.on("session:register")
+async def on_session_register(sid, data):
+    session_id = data.get("session_id", "")
+    tab_id = data.get("tab_id", "")
+    if not _valid_id(session_id) or not _valid_id(tab_id):
+        return
+
+    status = await ssh_manager.restore_session(sid, session_id, tab_id)
+    await sio.emit("session:restored", {"tab_id": tab_id, "status": status}, to=sid)
+    # Force shell redraw AFTER session:restored so the frontend clears the
+    # viewport first, then the fresh prompt from SIGWINCH overwrites it.
+    if status == "active":
+        await ssh_manager.force_redraw(session_id, tab_id)
+
+
+# ---------------------------------------------------------------------------
+# SSH events
+# ---------------------------------------------------------------------------
+
+@sio.on("ssh:connect")
+async def on_ssh_connect(sid, data):
+    host = data.get("host", "").strip()
+    port = _safe_int(data.get("port", 22), 22)
+    username = data.get("username", "").strip()
+    password = data.get("password", "")
+    session_id = data.get("session_id", "")
+    tab_id = data.get("tab_id", "")
+    cols = _safe_int(data.get("cols", 220), 220)
+    rows = _safe_int(data.get("rows", 50), 50)
+
+    if not host or not username or not _valid_id(session_id) or not _valid_id(tab_id):
+        await sio.emit(
+            "ssh:error",
+            {"tab_id": tab_id, "message": "Missing required fields.", "code": "invalid_request"},
+            to=sid,
+        )
+        return
+
+    await ssh_manager.connect(
+        sid=sid,
+        session_id=session_id,
+        tab_id=tab_id,
+        host=host,
+        port=port,
+        username=username,
+        password=password,
+        cols=cols,
+        rows=rows,
+    )
+
+
+@sio.on("ssh:input")
+async def on_ssh_input(sid, data):
+    await ssh_manager.handle_input(
+        data.get("session_id", ""),
+        data.get("tab_id", ""),
+        data.get("data", ""),
+    )
+
+
+@sio.on("terminal:resize")
+async def on_terminal_resize(sid, data):
+    await ssh_manager.handle_resize(
+        data.get("session_id", ""),
+        data.get("tab_id", ""),
+        _safe_int(data.get("cols", 80), 80),
+        _safe_int(data.get("rows", 24), 24),
+    )
+
+
+@sio.on("ssh:disconnect")
+async def on_ssh_disconnect(sid, data):
+    await ssh_manager.disconnect_session(
+        data.get("session_id", ""),
+        data.get("tab_id", ""),
+    )
+
+
+@sio.on("ssh:clone")
+async def on_ssh_clone(sid, data):
+    session_id = data.get("session_id", "")
+    source_tab_id = data.get("source_tab_id", "")
+    new_tab_id = data.get("new_tab_id", "")
+    cols = _safe_int(data.get("cols", 220), 220)
+    rows = _safe_int(data.get("rows", 50), 50)
+
+    if not _valid_id(session_id) or not _valid_id(source_tab_id) or not _valid_id(new_tab_id):
+        await sio.emit(
+            "ssh:error",
+            {"tab_id": new_tab_id, "message": "Missing required fields.", "code": "invalid_request"},
+            to=sid,
+        )
+        return
+
+    await ssh_manager.clone(
+        sid=sid,
+        session_id=session_id,
+        source_tab_id=source_tab_id,
+        new_tab_id=new_tab_id,
+        cols=cols,
+        rows=rows,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Startup
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def lifespan(app):
+    ssh_manager.start_background_tasks()
+    yield
+
+
+fastapi_app.router.lifespan_context = lifespan