hivepods-cli 0.1.0__py3-none-any.whl

hivepods_cli/__init__.py

@@ -0,0 +1,3 @@
+"""HivePods CLI — manage DockHive pods from your terminal."""
+
+__version__ = "0.1.0"

hivepods_cli/browser_login.py

@@ -0,0 +1,193 @@
+"""Browser sign-in for the CLI.
+
+Starts a throwaway web server on 127.0.0.1, opens the DockHive sign-in page in
+the browser, and waits for the page to hand the session back to that local
+address once the user has approved. Falls back cleanly if no browser is around.
+
+The page can hand the session back two ways:
+  * POST /callback (form or JSON body with state/token/refresh) — preferred, the
+    token never appears in a URL or the browser history;
+  * GET /callback?state=…&token=…  — still accepted; the reply immediately
+    replaces the history entry so the token doesn't linger there.
+
+Anything else (wrong path, wrong state, wrong Host, stray requests from other
+pages) gets a 4xx and is ignored: we keep waiting for the genuine callback until
+the timeout.
+"""
+from __future__ import annotations
+
+import json
+import secrets
+import threading
+import time
+import urllib.parse
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Optional
+
+# How long we'll sit waiting for the browser round-trip before giving up.
+TIMEOUT_SECONDS = 300
+MAX_BODY = 64 * 1024
+
+_DONE_PAGE = b"""<!doctype html><meta charset="utf-8">
+<meta name="referrer" content="no-referrer">
+<title>DockHive CLI</title>
+<script>try{history.replaceState(null,'','/done')}catch(e){}</script>
+<style>body{font:16px -apple-system,Segoe UI,sans-serif;background:#0b0c0f;color:#e8e8e8;
+display:flex;min-height:100vh;align-items:center;justify-content:center;margin:0}
+div{text-align:center;max-width:22rem;padding:2rem}</style>
+<div><h2>%s</h2><p>%s</p></div>
+"""
+
+
+class _Result:
+    token: Optional[str] = None
+    refresh: Optional[str] = None
+    error: Optional[str] = None
+
+
+class _Handler(BaseHTTPRequestHandler):
+    # bound by start_login() before the server spins up
+    expected_state = ""
+    expected_port = 0
+    result = _Result()
+    done = None  # threading.Event set once a genuine callback was handled
+
+    def log_message(self, *_args):  # silence the default stderr logging
+        pass
+
+    def _reply(self, heading: str, detail: str, code: int = 200):
+        body = _DONE_PAGE % (heading.encode(), detail.encode())
+        self.send_response(code)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Referrer-Policy", "no-referrer")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _host_ok(self) -> bool:
+        # Blocks DNS-rebinding pages from talking to the loopback server.
+        host = (self.headers.get("Host") or "").lower()
+        return host in (f"127.0.0.1:{self.expected_port}", f"localhost:{self.expected_port}")
+
+    def _handle(self, params: dict):
+        if not self._host_ok():
+            self._reply("Not allowed", "You can close this window.", code=421)
+            return
+        state = params.get("state") or ""
+        if not isinstance(state, str) or not secrets.compare_digest(
+                state.encode(), type(self).expected_state.encode()):
+            # Not our callback (stale tab, another page probing): ignore it.
+            self._reply("Something went wrong", "This sign-in link is not valid. Close this and retry.",
+                        code=400)
+            return
+
+        result = type(self).result
+        if params.get("error"):
+            result.error = "sign-in was cancelled"
+            self._reply("Sign-in cancelled", "You can close this window.")
+            type(self).done.set()
+            return
+
+        token = params.get("token") or ""
+        if not isinstance(token, str) or not token:
+            self._reply("Something went wrong", "No session was returned. Close this and retry.", code=400)
+            return
+
+        result.token = token
+        refresh = params.get("refresh")
+        result.refresh = refresh if isinstance(refresh, str) and refresh else None
+        self._reply("You're signed in", "Head back to your terminal — you can close this window.")
+        type(self).done.set()
+
+    def do_GET(self):
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != "/callback":
+            self._reply("Not found", "You can close this window.", code=404)
+            return
+        params = {k: v[0] for k, v in urllib.parse.parse_qs(parsed.query).items()}
+        self._handle(params)
+
+    def do_POST(self):
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != "/callback":
+            self._reply("Not found", "You can close this window.", code=404)
+            return
+        try:
+            length = int(self.headers.get("Content-Length") or 0)
+        except ValueError:
+            length = 0
+        if length <= 0 or length > MAX_BODY:
+            self._reply("Something went wrong", "Invalid request.", code=400)
+            return
+        raw = self.rfile.read(length).decode("utf-8", "replace")
+        ctype = (self.headers.get("Content-Type") or "").split(";")[0].strip().lower()
+        if ctype == "application/json":
+            try:
+                params = json.loads(raw)
+            except ValueError:
+                params = None
+            if not isinstance(params, dict):
+                self._reply("Something went wrong", "Invalid request.", code=400)
+                return
+        else:
+            params = {k: v[0] for k, v in urllib.parse.parse_qs(raw).items()}
+        self._handle(params)
+
+
+def start_login(web_url: str, open_browser: bool = True,
+                timeout: float = TIMEOUT_SECONDS) -> _Result:
+    """Run the loopback sign-in dance and return the captured session.
+
+    Raises RuntimeError on timeout or if the browser reports an error.
+    """
+    state = secrets.token_urlsafe(24)
+
+    server = HTTPServer(("127.0.0.1", 0), _Handler)
+    port = server.server_address[1]
+    done = threading.Event()
+    _Handler.expected_state = state
+    _Handler.expected_port = port
+    _Handler.result = _Result()
+    _Handler.done = done
+
+    auth_url = (
+        web_url.rstrip("/")
+        + "/cli-auth?"
+        + urllib.parse.urlencode({"port": port, "state": state})
+    )
+
+    deadline = time.monotonic() + timeout
+
+    def _serve():
+        # Keep answering until the genuine callback arrives or time runs out;
+        # wrong-state / stray requests don't end the wait.
+        while not done.is_set():
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            server.timeout = min(remaining, 1.0)
+            server.handle_request()
+
+    worker = threading.Thread(target=_serve, daemon=True)
+    worker.start()
+
+    opened = webbrowser.open(auth_url) if open_browser else False
+    if not opened:
+        print("Open this URL in your browser to sign in:\n  " + auth_url)
+
+    worker.join(timeout + 5)
+    try:
+        server.server_close()
+    except OSError:
+        pass
+
+    result = _Handler.result
+    if not done.is_set():
+        raise RuntimeError("timed out waiting for the browser sign-in")
+    if result.error:
+        raise RuntimeError(result.error)
+    if not result.token:
+        raise RuntimeError("no session was returned")
+    return result

hivepods_cli/client.py

@@ -0,0 +1,410 @@
+"""HivePods API client."""
+from __future__ import annotations
+
+import base64
+import json
+import re
+import time
+from typing import Callable, Optional
+from urllib.parse import urlparse, urlunparse
+
+import requests
+
+
+# Statuses a pod passes through while the server is still working on it.
+TRANSITIONAL = frozenset({
+    "provisioning", "initializing", "starting", "stopping", "restarting",
+    "suspending", "resuming", "applying", "terminating",
+})
+
+
+class WaitTimeout(Exception):
+    """Polling gave up; `last` is the last representation seen."""
+
+    def __init__(self, last: Optional[dict]):
+        super().__init__("timed out")
+        self.last = last
+
+
+class APIError(Exception):
+    """Raised when the API returns an error. The message is safe to show."""
+
+    def __init__(self, message: str, status: Optional[int] = None):
+        super().__init__(message)
+        self.status = status
+
+
+# Anything mentioning these is an implementation detail, not something to show.
+_INTERNAL_WORDS = re.compile(
+    r"docker|container|kubernetes|k8s|kvm|qemu|traceback|daemon|celery|redis|"
+    r"postgres|psycopg|django|exception|errno|/var/|/app/|sha256:",
+    re.IGNORECASE,
+)
+
+_GENERIC = {
+    400: "The request wasn't accepted. Check the values and try again.",
+    409: "That can't be done right now. Check the environment's status and try again.",
+    413: "That file is too large.",
+    429: "Too many requests — please wait a moment and try again.",
+}
+
+
+def _jwt_expired(token: str, skew: int = 30) -> bool:
+    """True if `token` is a JWT whose exp has passed (unverified peek)."""
+    parts = token.split(".")
+    if len(parts) != 3:
+        return False
+    try:
+        pad = "=" * (-len(parts[1]) % 4)
+        claims = json.loads(base64.urlsafe_b64decode(parts[1] + pad))
+        exp = claims.get("exp")
+    except (ValueError, TypeError):
+        return False
+    return isinstance(exp, (int, float)) and exp <= time.time() + skew
+
+
+class APIClient:
+    def __init__(self, api_url: str, token: Optional[str] = None, timeout: int = 30,
+                 refresh_token: Optional[str] = None,
+                 on_tokens: Optional[Callable[[str, Optional[str]], None]] = None):
+        self.api_url = api_url.rstrip("/")
+        self.token = token
+        self.refresh_token = refresh_token
+        # Called with (access, refresh) whenever the session is renewed, so the
+        # caller can persist it.
+        self.on_tokens = on_tokens
+        self.timeout = timeout
+
+    # ---- internals -----------------------------------------------------
+    def _headers(self) -> dict:
+        headers = {"Accept": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        return headers
+
+    def refresh(self) -> bool:
+        """Swap the refresh token for a new access token. True on success."""
+        if not self.refresh_token:
+            return False
+        try:
+            resp = requests.post(
+                f"{self.api_url}/api/v1/auth/refresh",
+                json={"refresh": self.refresh_token},
+                headers={"Accept": "application/json"},
+                timeout=self.timeout,
+            )
+        except requests.RequestException:
+            return False
+        if resp.status_code != 200:
+            return False
+        try:
+            data = resp.json()
+        except ValueError:
+            return False
+        access = data.get("access")
+        if not access:
+            return False
+        self.token = access
+        # The auth service rotates refresh tokens; keep the new one if sent.
+        self.refresh_token = data.get("refresh") or self.refresh_token
+        if self.on_tokens:
+            self.on_tokens(self.token, self.refresh_token)
+        return True
+
+    def ensure_fresh(self) -> None:
+        """Renew an expired access token up front (e.g. before opening a socket)."""
+        if self.token and self.refresh_token and _jwt_expired(self.token):
+            self.refresh()
+
+    def _request(self, method: str, path: str, _retried: bool = False, **kwargs):
+        if not _retried:
+            self.ensure_fresh()
+        url = f"{self.api_url}{path}"
+        extra = kwargs.pop("headers", None) or {}  # per-call extras (X-Region)
+        headers = self._headers()
+        headers.update(extra)
+        try:
+            resp = requests.request(
+                method, url, headers=headers, timeout=self.timeout, **kwargs
+            )
+        except requests.RequestException:
+            host = urlparse(url).netloc or url
+            raise APIError(f"Could not reach DockHive ({host}). Check your connection and try again.")
+
+        if resp.status_code == 401:
+            if not _retried and self.refresh():
+                return self._request(method, path, _retried=True, headers=extra, **kwargs)
+            raise APIError("Please sign in first: run `hivepod login`.", 401)
+        if resp.status_code == 403:
+            raise APIError("Permission denied for this resource.", 403)
+        if resp.status_code == 404:
+            raise APIError("Not found.", 404)
+        if resp.status_code >= 500:
+            raise APIError(_server_message(resp), resp.status_code)
+        if resp.status_code >= 400:
+            raise APIError(_format_error(resp), resp.status_code)
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    def _paginated(self, path: str, params: Optional[dict] = None) -> list:
+        """Return all results, following DRF page pagination."""
+        items: list = []
+        data = self._request("GET", path, params=params)
+        while True:
+            if isinstance(data, dict) and "results" in data:
+                items.extend(data["results"])
+                nxt = data.get("next")
+                if not nxt:
+                    break
+                # `next` may name an internal host; keep our base, take its path+query.
+                parsed = urlparse(nxt)
+                data = self._request("GET", parsed.path + (f"?{parsed.query}" if parsed.query else ""))
+            elif isinstance(data, list):
+                items.extend(data)
+                break
+            else:
+                break
+        return items
+
+    # ---- auth ----------------------------------------------------------
+    def login(self, email: str, password: str, mfa_code: Optional[str] = None) -> dict:
+        """Password sign-in. Returns the response; {'requires_mfa': True} means
+        call again with mfa_code."""
+        body = {"email": email, "password": password}
+        if mfa_code:
+            body["mfa_code"] = mfa_code
+        data = self._request("POST", "/api/v1/auth/login", json=body) or {}
+        if data.get("requires_mfa"):
+            return data
+        token = data.get("access")
+        if not token:
+            raise APIError("Sign-in succeeded but no session was returned.")
+        self.token = token
+        self.refresh_token = data.get("refresh")
+        return data
+
+    def logout(self) -> None:
+        """Best-effort: revoke the refresh token on the server."""
+        if not (self.token and self.refresh_token):
+            return
+        try:
+            requests.post(f"{self.api_url}/api/v1/auth/logout",
+                          json={"refresh": self.refresh_token},
+                          headers=self._headers(), timeout=10)
+        except requests.RequestException:
+            pass
+
+    # ---- OS catalog ----------------------------------------------------
+    def list_os(self, include_gated: bool = False, family: Optional[str] = None) -> list:
+        params = {}
+        if include_gated:
+            params["available"] = "all"
+        if family:
+            params["family"] = family
+        return self._paginated("/api/v1/hivepods/catalog/os-images/", params=params)
+
+    # ---- pods ----------------------------------------------------------
+    def list_pods(self) -> list:
+        return self._paginated("/api/v1/hivepods/")
+
+    def get_pod(self, pod_id: str) -> dict:
+        return self._request("GET", f"/api/v1/hivepods/{pod_id}/")
+
+    def create_pod(self, payload: dict, region: Optional[str] = None) -> dict:
+        # X-Region lets the gateway route the create to a chosen region (multi-region).
+        headers = {"X-Region": region} if region else None
+        return self._request("POST", "/api/v1/hivepods/", json=payload, headers=headers)
+
+    def list_tiers(self) -> list:
+        """Resource sizes + specs. Falls back to built-ins on older servers."""
+        try:
+            return self._request("GET", "/api/v1/hivepods/tiers/") or []
+        except APIError:
+            return [
+                {"tier": "nano", "label": "Nano", "cpu": 0.5, "memory": "512m", "storage": "5g"},
+                {"tier": "micro", "label": "Micro", "cpu": 1, "memory": "1g", "storage": "10g"},
+                {"tier": "small", "label": "Small", "cpu": 2, "memory": "2g", "storage": "25g"},
+                {"tier": "medium", "label": "Medium", "cpu": 4, "memory": "4g", "storage": "50g"},
+            ]
+
+    def list_regions(self) -> list:
+        """Regions available for pod creation (best-effort)."""
+        try:
+            data = self._request("GET", "/api/v1/hivepods/regions/")
+            if isinstance(data, dict):
+                return data.get("regions", [])
+            return data or []
+        except APIError:
+            return []
+
+    def delete_pod(self, pod_id: str) -> None:
+        self._request("DELETE", f"/api/v1/hivepods/{pod_id}/")
+
+    def pod_action(self, pod_id: str, action: str, parameters: Optional[dict] = None) -> dict:
+        """Request a lifecycle action. The server answers 202 with the pod's
+        transitional status (older servers: 200 once done); see wait_for_pod."""
+        return self._request(
+            "POST", f"/api/v1/hivepods/{pod_id}/execute_action/",
+            json={"action": action, "parameters": parameters or {}},
+        ) or {}
+
+    def update_pod(self, pod_id: str, changes: dict) -> dict:
+        return self._request("PATCH", f"/api/v1/hivepods/{pod_id}/", json=changes)
+
+    def wait_for_pod(self, pod_id: str, timeout: float = 300, interval: float = 1.0,
+                     on_status: Optional[Callable[[str], None]] = None,
+                     sleep: Callable[[float], None] = time.sleep,
+                     clock: Callable[[], float] = time.monotonic) -> Optional[dict]:
+        """Poll until the pod leaves every transitional status. Returns the pod,
+        or None once it no longer exists (destroyed). Raises WaitTimeout."""
+        deadline = clock() + timeout
+        last = None
+        delay = interval
+        while True:
+            try:
+                last = self.get_pod(pod_id)
+            except APIError as exc:
+                if exc.status == 404:
+                    return None
+                raise
+            status = (last or {}).get("status", "")
+            if on_status:
+                on_status(status)
+            if status not in TRANSITIONAL:
+                return last
+            if clock() >= deadline:
+                raise WaitTimeout(last)
+            sleep(delay)
+            delay = min(delay * 1.5, 5.0)
+
+    # ---- backups -------------------------------------------------------
+    def create_backup(self, pod_id: str, name: str, description: str = "") -> dict:
+        return self._request("POST", f"/api/v1/hivepods/{pod_id}/backup/",
+                             json={"name": name, "description": description})
+
+    def list_backups(self, pod_id: Optional[str] = None) -> list:
+        params = {"pod_id": pod_id} if pod_id else None
+        return self._paginated("/api/v1/hivepods/backups/", params=params)
+
+    def get_backup(self, backup_id: str) -> dict:
+        return self._request("GET", f"/api/v1/hivepods/backups/{backup_id}/")
+
+    def delete_backup(self, backup_id: str) -> None:
+        self._request("DELETE", f"/api/v1/hivepods/backups/{backup_id}/")
+
+    def restore_backup(self, backup_id: str, name: str, **options) -> dict:
+        body = {"name": name}
+        body.update({k: v for k, v in options.items() if v not in (None, "")})
+        return self._request("POST", f"/api/v1/hivepods/backups/{backup_id}/restore/", json=body)
+
+    def wait_for_backup(self, backup_id: str, timeout: float = 3600, interval: float = 2.0,
+                        sleep: Callable[[float], None] = time.sleep,
+                        clock: Callable[[], float] = time.monotonic) -> dict:
+        deadline = clock() + timeout
+        delay = interval
+        while True:
+            backup = self.get_backup(backup_id)
+            if backup.get("status") != "creating":
+                return backup
+            if clock() >= deadline:
+                raise WaitTimeout(backup)
+            sleep(delay)
+            delay = min(delay * 1.5, 10.0)
+
+    def resolve_backup(self, ref: str) -> dict:
+        """A backup by full id or a unique id prefix (as shown by `backup list`)."""
+        ref = ref.strip().lower()
+        backups = self.list_backups()
+        exact = [b for b in backups if str(b.get("id", "")).lower() == ref]
+        if exact:
+            return exact[0]
+        if len(ref) >= 4:
+            matches = [b for b in backups if str(b.get("id", "")).lower().startswith(ref)]
+            if len(matches) == 1:
+                return matches[0]
+            if len(matches) > 1:
+                raise APIError(f"'{ref}' matches more than one backup; use more of the id.")
+        raise APIError(f"No backup with id '{ref}'.")
+
+    def pod_exec(self, pod_id: str, command: str) -> dict:
+        """Run one command; returns {'exit_code', 'output', 'truncated', 'timed_out'}."""
+        return self._request(
+            "POST", f"/api/v1/hivepods/{pod_id}/exec/", json={"command": command},
+        )
+
+    def pod_metrics(self, pod_id: str) -> dict:
+        return self._request("GET", f"/api/v1/hivepods/{pod_id}/metrics/")
+
+    def pod_logs(self, pod_id: str, tail: int = 100) -> dict:
+        return self._request("GET", f"/api/v1/hivepods/{pod_id}/logs/", params={"tail": int(tail)})
+
+    def resolve_pod(self, name_or_id: str) -> dict:
+        """Accept a pod's id (region-tagged, as listed) or its name; return the pod."""
+        pods = self.list_pods()
+        for pod in pods:
+            if pod.get("id") == name_or_id or pod.get("name") == name_or_id:
+                return pod
+        # A bare uuid still matches a region-tagged id (<region>-<uuid>).
+        for pod in pods:
+            if str(pod.get("id", "")).endswith("-" + name_or_id) and len(name_or_id) == 36:
+                return pod
+        raise APIError(f"No environment named or with id '{name_or_id}'.")
+
+    # ---- websocket helpers ---------------------------------------------
+    def ws_url(self, path: str) -> str:
+        parsed = urlparse(self.api_url)
+        scheme = "wss" if parsed.scheme == "https" else "ws"
+        base_path = parsed.path.rstrip("/")
+        return urlunparse((scheme, parsed.netloc, base_path + path, "", "", ""))
+
+    def pod_ws_url(self, pod_id: str, kind: str) -> str:
+        """Terminal/log socket for a pod, under the hivepods prefix the gateway routes."""
+        return self.ws_url(f"/api/v1/hivepods/ws/pods/{pod_id}/{kind}/")
+
+    def ws_headers(self) -> dict:
+        """Credentials for sockets go in a header, never the URL (URLs get logged)."""
+        self.ensure_fresh()
+        return {"Authorization": f"Bearer {self.token}"} if self.token else {}
+
+
+def _clean(text: str) -> Optional[str]:
+    text = str(text).strip()
+    if not text or _INTERNAL_WORDS.search(text):
+        return None
+    return text[:300]
+
+
+def _server_message(resp) -> str:
+    if resp.status_code in (502, 503, 504):
+        return "DockHive is temporarily unavailable. Please try again in a moment."
+    try:
+        data = resp.json()
+    except ValueError:
+        data = None
+    if isinstance(data, dict):
+        msg = _clean(data.get("error") or data.get("message") or "")
+        if msg:
+            return msg
+    return "Something went wrong on our side. Please try again."
+
+
+def _format_error(resp) -> str:
+    try:
+        data = resp.json()
+    except ValueError:
+        return _GENERIC.get(resp.status_code, f"The request failed (HTTP {resp.status_code}).")
+    if isinstance(data, dict):
+        parts = []
+        for key, val in data.items():
+            if isinstance(val, list):
+                val = "; ".join(str(v) for v in val)
+            elif isinstance(val, dict):
+                val = "; ".join(f"{k}: {v}" for k, v in val.items())
+            val = _clean(val)
+            if val is None:
+                continue
+            parts.append(val if key in ("error", "message", "detail", "non_field_errors") else f"{key}: {val}")
+        if parts:
+            return " | ".join(parts)
+    return _GENERIC.get(resp.status_code, f"The request failed (HTTP {resp.status_code}).")