wsctl 0.1.0__py3-none-any.whl

wsctl/__init__.py

@@ -0,0 +1,7 @@
+"""wsctl — a modern, Python-based web terminal server."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

wsctl/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from wsctl.cli.main import app
+
+if __name__ == "__main__":
+    app()

wsctl/cli/__init__.py

@@ -0,0 +1,3 @@
+"""Command-line interface."""
+
+from __future__ import annotations

wsctl/cli/client.py

@@ -0,0 +1,135 @@
+"""Minimal HTTP client for talking to a running wsctl server.
+
+Uses only the standard library so the CLI stays dependency-free. Credentials
+(base URL + bearer token) are cached under the config directory.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import http.cookiejar
+import json
+import os
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from wsctl.core.config import default_config_dir
+
+
+class ApiError(RuntimeError):
+    def __init__(self, status: int, detail: str) -> None:
+        super().__init__(f"HTTP {status}: {detail}")
+        self.status = status
+        self.detail = detail
+
+
+def credentials_path() -> Path:
+    return default_config_dir() / "credentials.json"
+
+
+def load_credentials() -> dict[str, Any]:
+    path = credentials_path()
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text("utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def save_credentials(url: str, token: str) -> None:
+    path = credentials_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps({"url": url, "token": token}), encoding="utf-8")
+    os.chmod(path, 0o600)
+
+
+def clear_credentials() -> None:
+    path = credentials_path()
+    if path.exists():
+        path.unlink()
+
+
+class ApiClient:
+    """Synchronous JSON client bound to a base URL and optional bearer token."""
+
+    def __init__(self, base_url: str, token: str | None = None, *, timeout: float = 15.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None = None,
+        *,
+        auth: bool = True,
+    ) -> Any:
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = {"Content-Type": "application/json", "Accept": "application/json"}
+        if auth and self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        req = urllib.request.Request(
+            f"{self.base_url}{path}", data=data, headers=headers, method=method
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                payload = resp.read()
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", "replace")
+            try:
+                parsed = json.loads(detail)
+                detail = str(parsed.get("detail", detail))
+            except json.JSONDecodeError:
+                pass
+            raise ApiError(exc.code, detail) from exc
+        except urllib.error.URLError as exc:
+            raise ApiError(0, f"cannot reach {self.base_url}: {exc.reason}") from exc
+        if not payload:
+            return None
+        return json.loads(payload)
+
+    def download(self, path: str) -> bytes:
+        """Fetch a raw (non-JSON) resource such as a recording."""
+        headers = {"Accept": "*/*"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        req = urllib.request.Request(f"{self.base_url}{path}", headers=headers, method="GET")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                data: bytes = resp.read()
+                return data
+        except urllib.error.HTTPError as exc:
+            raise ApiError(exc.code, exc.read().decode("utf-8", "replace")) from exc
+        except urllib.error.URLError as exc:
+            raise ApiError(0, f"cannot reach {self.base_url}: {exc.reason}") from exc
+
+
+def login(base_url: str, username: str, password: str, *, timeout: float = 15.0) -> str:
+    """Authenticate and return the opaque session token from the cookie."""
+    jar = http.cookiejar.CookieJar()
+    opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(jar))
+    body = json.dumps({"username": username, "password": password}).encode("utf-8")
+    req = urllib.request.Request(
+        f"{base_url.rstrip('/')}/api/login",
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        opener.open(req, timeout=timeout)
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", "replace")
+        with contextlib.suppress(json.JSONDecodeError):
+            detail = str(json.loads(detail).get("detail", detail))
+        raise ApiError(exc.code, detail) from exc
+    except urllib.error.URLError as exc:
+        raise ApiError(0, f"cannot reach {base_url}: {exc.reason}") from exc
+    for cookie in jar:
+        if cookie.name == "wsctl_session":
+            return str(cookie.value)
+    raise ApiError(0, "server did not return a session cookie")

wsctl/cli/connect.py

@@ -0,0 +1,158 @@
+"""``wsctl connect`` — attach a local terminal to a remote wsctl server.
+
+The client puts the local terminal into raw mode and bridges stdin/stdout to
+the server's WebSocket protocol (binary frames for terminal bytes, JSON text
+frames for control). Reconnecting is a server-side feature, so a dropped link
+ends the local session cleanly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import signal
+import sys
+from urllib.parse import urlsplit, urlunsplit
+
+import websockets
+from websockets.exceptions import ConnectionClosed, InvalidStatus
+
+from wsctl.cli.client import ApiClient, ApiError, load_credentials
+
+DEFAULT_SIZE = (80, 24)
+READ_SIZE = 4096
+
+
+class ConnectError(RuntimeError):
+    """Raised when the local client cannot establish or maintain a link."""
+
+
+def run_connect(url: str | None, session: str | None, token: str | None) -> None:
+    creds = load_credentials()
+    base = url or (str(creds["url"]) if creds.get("url") else None)
+    if not base:
+        raise ConnectError("no server URL: pass <url> or run 'wsctl login <url>' first")
+    bearer = token or (str(creds["token"]) if creds.get("token") else None)
+    with contextlib.suppress(KeyboardInterrupt):
+        asyncio.run(_run(base, session, bearer))
+
+
+def _ws_url(base: str) -> str:
+    parsed = urlsplit(base)
+    scheme = "wss" if parsed.scheme == "https" else "ws"
+    path = parsed.path.rstrip("/") + "/ws"
+    return urlunsplit((scheme, parsed.netloc, path, "", ""))
+
+
+def _winsize() -> tuple[int, int]:
+    try:
+        size = os.get_terminal_size(sys.stdin.fileno())
+        return size.columns, size.lines
+    except OSError:
+        return DEFAULT_SIZE
+
+
+def _create_session(base: str, token: str | None) -> str:
+    client = ApiClient(base, token)
+    try:
+        info = client.request("POST", "/api/sessions", {})
+    except ApiError as exc:
+        raise ConnectError(f"cannot create a session: {exc}") from exc
+    return str(info["id"])
+
+
+def _notice(message: str) -> None:
+    sys.stderr.write(f"\r\n\x1b[33m[wsctl] {message}\x1b[0m\r\n")
+    sys.stderr.flush()
+
+
+async def _run(base: str, session: str | None, token: str | None) -> None:
+    if sys.platform == "win32":
+        raise ConnectError("wsctl connect currently requires a POSIX terminal")
+    if not sys.stdin.isatty():
+        raise ConnectError("wsctl connect requires an interactive terminal")
+
+    session_id = session or _create_session(base, token)
+    headers = {"Authorization": f"Bearer {token}"} if token else {}
+
+    try:
+        ws = await websockets.connect(_ws_url(base), additional_headers=headers, max_size=None)
+    except InvalidStatus as exc:
+        code = exc.response.status_code
+        hint = " (is the token valid?)" if code in (401, 403) else ""
+        raise ConnectError(f"server rejected the connection: HTTP {code}{hint}") from exc
+    except OSError as exc:
+        raise ConnectError(f"cannot reach {base}: {exc}") from exc
+
+    import termios
+    import tty
+
+    async with ws:
+        cols, rows = _winsize()
+        await ws.send(
+            json.dumps({"type": "attach", "session": session_id, "cols": cols, "rows": rows})
+        )
+
+        loop = asyncio.get_running_loop()
+        fd = sys.stdin.fileno()
+        saved = termios.tcgetattr(fd)
+        send_task: asyncio.Task[None] | None = None
+        notice: str | None = None
+        tty.setraw(fd)
+        try:
+            outbound: asyncio.Queue[bytes | str | None] = asyncio.Queue()
+
+            def on_stdin() -> None:
+                try:
+                    data = os.read(fd, READ_SIZE)
+                except OSError:
+                    data = b""
+                outbound.put_nowait(data if data else None)
+
+            def on_resize() -> None:
+                width, height = _winsize()
+                outbound.put_nowait(json.dumps({"type": "resize", "cols": width, "rows": height}))
+
+            loop.add_reader(fd, on_stdin)
+            with contextlib.suppress(NotImplementedError):
+                loop.add_signal_handler(signal.SIGWINCH, on_resize)
+
+            async def sender() -> None:
+                while True:
+                    item = await outbound.get()
+                    if item is None:
+                        await ws.close()
+                        return
+                    await ws.send(item)
+
+            send_task = asyncio.create_task(sender())
+            try:
+                async for message in ws:
+                    if isinstance(message, bytes):
+                        os.write(sys.stdout.fileno(), message)
+                        continue
+                    data = json.loads(message)
+                    kind = data.get("type")
+                    if kind == "exit":
+                        notice = f"session exited (code {data.get('code')})"
+                        break
+                    if kind == "error":
+                        notice = str(data.get("msg"))
+                        break
+            except ConnectionClosed:
+                notice = "connection closed"
+        finally:
+            if send_task is not None:
+                send_task.cancel()
+                with contextlib.suppress(asyncio.CancelledError, Exception):
+                    await send_task
+            with contextlib.suppress(Exception):
+                loop.remove_reader(fd)
+            with contextlib.suppress(NotImplementedError):
+                loop.remove_signal_handler(signal.SIGWINCH)
+            termios.tcsetattr(fd, termios.TCSADRAIN, saved)
+
+        if notice:
+            _notice(notice)