runtime-sdk 0.4.49__py3-none-win_amd64.whl

runtime_sdk/client.py

@@ -0,0 +1,616 @@
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass
+from typing import Any, BinaryIO, Callable
+from urllib.parse import urlencode
+
+import httpx
+
+
+class RuntimeAPIError(RuntimeError):
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+DEFAULT_WARMUP_TIMEOUT = 180.0
+
+
+@dataclass(slots=True)
+class RuntimeClient:
+    base_url: str
+    credential: str | Callable[[], str] | None = None
+    timeout: float = 10.0
+    transport: httpx.BaseTransport | None = None
+
+    def __post_init__(self) -> None:
+        self.base_url = self.base_url.rstrip("/")
+
+    def start_device_login(self) -> dict[str, Any]:
+        return self._request("POST", "/api/auth/device/start")
+
+    def poll_device_login(self, device_code: str) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            "/api/auth/device/token",
+            json={"device_code": device_code},
+            success_statuses={200},
+        )
+
+    def refresh_session(
+        self, refresh_token: str, organization_id: str
+    ) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            "/api/auth/refresh",
+            json={
+                "refresh_token": refresh_token,
+                "organization_id": organization_id,
+            },
+        )
+
+    def whoami(self) -> dict[str, Any]:
+        return self._request("GET", "/api/auth/whoami", auth_required=True)
+
+    def logout(self) -> dict[str, Any]:
+        return self._request("POST", "/api/auth/logout", auth_required=True)
+
+    def list_api_keys(self) -> dict[str, Any]:
+        return self._request("GET", "/api/api-keys", auth_required=True)
+
+    def create_api_key(self, name: str) -> dict[str, Any]:
+        return self._request("POST", "/api/api-keys", json={"name": name}, auth_required=True)
+
+    def revoke_api_key(self, key_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/api/api-keys/{key_id}", auth_required=True)
+
+    # --- GitHub App ---
+
+    def start_github_connect(self) -> dict[str, Any]:
+        return self._request("POST", "/api/github/connect", auth_required=True)
+
+    def get_github_connect_session(self, session_id: int) -> dict[str, Any]:
+        return self._request("GET", f"/api/github/connect/{session_id}", auth_required=True)
+
+    def list_github_installations(self) -> dict[str, Any]:
+        return self._request("GET", "/api/github/installations", auth_required=True)
+
+    def disconnect_github_installation(self, installation_id: int) -> dict[str, Any]:
+        return self._request("DELETE", f"/api/github/installations/{installation_id}", auth_required=True)
+
+    def list_secret_sets(self) -> dict[str, Any]:
+        return self._request("GET", "/api/secrets", auth_required=True)
+
+    def get_secret_set(self, slug: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/secrets/{slug}", auth_required=True)
+
+    def put_secret_set(self, slug: str, values: dict[str, str], delivery: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload: dict[str, Any] = {"values": values}
+        if delivery:
+            payload["deliveries"] = delivery
+        return self._request("PUT", f"/api/secrets/{slug}", json=payload, auth_required=True)
+
+    def delete_secret_set(self, slug: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/api/secrets/{slug}", auth_required=True)
+
+    def list_provider_credentials(self) -> dict[str, Any]:
+        return self._request("GET", "/api/provider-credentials", auth_required=True)
+
+    def put_provider_credential(self, provider: str, auth_json: str) -> dict[str, Any]:
+        return self._request("PUT", f"/api/provider-credentials/{provider}", json={"auth_json": auth_json}, auth_required=True)
+
+    def delete_provider_credential(self, provider: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/api/provider-credentials/{provider}", auth_required=True)
+
+    # --- Computers ---
+
+    def switch_workspace(
+        self,
+        *,
+        repo: str,
+        branch: str,
+        create: bool = False,
+        base_branch: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"repo": repo, "branch": branch, "create": create}
+        if base_branch is not None:
+            body["from"] = base_branch
+        return self._request(
+            "POST",
+            "/api/workspaces/switch",
+            json=body,
+            auth_required=True,
+            timeout=max(self.timeout, DEFAULT_WARMUP_TIMEOUT),
+        )
+
+    def create_computer(
+        self,
+        *,
+        slug: str | None = None,
+        command: str | None = None,
+        cwd: str | None = None,
+        port: int | None = None,
+        network_mode: str | None = None,
+        allowed_hosts: list[str] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        if slug:
+            body["slug"] = slug
+        if command is not None or cwd is not None or port is not None:
+            start: dict[str, Any] = {}
+            if command is not None:
+                start["command"] = command
+            if cwd is not None:
+                start["cwd"] = cwd
+            if port is not None:
+                start["port"] = port
+            body["start"] = start
+        if network_mode is not None:
+            body["network_policy"] = {
+                "mode": network_mode,
+                "allowed_hosts": list(allowed_hosts or []),
+            }
+        return self._request(
+            "POST",
+            "/api/computers",
+            json=body or None,
+            auth_required=True,
+            timeout=max(self.timeout, DEFAULT_WARMUP_TIMEOUT),
+        )
+
+    def list_computers(self) -> dict[str, Any]:
+        return self._request("GET", "/api/computers", auth_required=True)
+
+    def get_computer(self, computer_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/computers/{computer_id}", auth_required=True)
+
+    def get_computer_network(self, computer_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/computers/{computer_id}/network", auth_required=True)
+
+    def list_network_denials(self, computer_id: str) -> dict[str, Any]:
+        return self._request(
+            "GET",
+            f"/api/computers/{computer_id}/network/denials",
+            auth_required=True,
+        )
+
+    def set_computer_network(
+        self, computer_id: str, mode: str, allowed_hosts: list[str] | None = None
+    ) -> dict[str, Any]:
+        return self._request(
+            "PUT",
+            f"/api/computers/{computer_id}/network",
+            json={"mode": mode, "allowed_hosts": list(allowed_hosts or [])},
+            auth_required=True,
+        )
+
+    def get_default_network(self) -> dict[str, Any]:
+        return self._request("GET", "/api/network/default", auth_required=True)
+
+    def set_default_network(
+        self, mode: str, allowed_hosts: list[str] | None = None
+    ) -> dict[str, Any]:
+        return self._request(
+            "PUT",
+            "/api/network/default",
+            json={"mode": mode, "allowed_hosts": list(allowed_hosts or [])},
+            auth_required=True,
+        )
+
+    def set_visibility(self, computer_id: str, visibility: str) -> dict[str, Any]:
+        return self._request(
+            "PUT",
+            f"/api/computers/{computer_id}/visibility",
+            json={"visibility": visibility},
+            auth_required=True,
+        )
+
+    def get_startup_config(self, computer_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/computers/{computer_id}/startup", auth_required=True)
+
+    def get_service_config(self, computer_id: str) -> dict[str, Any]:
+        return self.get_service(computer_id)
+
+    def get_service(self, computer_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/computers/{computer_id}/service", auth_required=True)
+
+    def run_service(
+        self,
+        computer_id: str,
+        *,
+        command: str,
+        cwd: str | None = None,
+        port: int,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"command": command, "port": port}
+        if cwd is not None:
+            body["cwd"] = cwd
+        return self._request(
+            "POST",
+            f"/api/computers/{computer_id}/service/run",
+            json=body,
+            auth_required=True,
+            timeout=max(self.timeout, DEFAULT_WARMUP_TIMEOUT),
+        )
+
+    def restart_service(self, computer_id: str) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            f"/api/computers/{computer_id}/service/restart",
+            auth_required=True,
+            timeout=max(self.timeout, DEFAULT_WARMUP_TIMEOUT),
+        )
+
+    def stop_service(self, computer_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/api/computers/{computer_id}/service/stop", auth_required=True)
+
+    def clear_service(self, computer_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/api/computers/{computer_id}/service", auth_required=True)
+
+    def stream_service_logs(self, computer_id: str, *, follow: bool = False):
+        credential = self._credential()
+        path = f"/api/computers/{computer_id}/service/logs"
+        if follow:
+            path += "?follow=true"
+        client = httpx.Client(base_url=self.base_url, timeout=None, transport=self.transport)
+        try:
+            with client.stream("GET", path, headers={"Authorization": f"Bearer {credential}"}) as response:
+                if not response.is_success:
+                    body = response.read()
+                    payload: dict[str, Any] = {}
+                    if body:
+                        try:
+                            decoded = response.json()
+                            if isinstance(decoded, dict):
+                                payload = decoded
+                        except ValueError:
+                            pass
+                    message = payload.get("error") or payload.get("message") or f"http {response.status_code}"
+                    raise RuntimeAPIError(str(message), status_code=response.status_code)
+                for line in response.iter_lines():
+                    if not line:
+                        continue
+                    yield line
+        finally:
+            client.close()
+
+    def set_startup_config(
+        self,
+        computer_id: str,
+        *,
+        command: str,
+        cwd: str | None = None,
+        port: int,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"command": command, "port": port}
+        if cwd is not None:
+            body["cwd"] = cwd
+        return self._request("PUT", f"/api/computers/{computer_id}/startup", json=body, auth_required=True)
+
+    def clear_startup_config(self, computer_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/api/computers/{computer_id}/startup", auth_required=True)
+
+    def clear_service_config(self, computer_id: str) -> dict[str, Any]:
+        return self.clear_service(computer_id)
+
+    def start_computer(self, computer_id: str) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            f"/api/computers/{computer_id}/start",
+            auth_required=True,
+            timeout=max(self.timeout, DEFAULT_WARMUP_TIMEOUT),
+        )
+
+    def delete_computer(self, computer_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/api/computers/{computer_id}", auth_required=True)
+
+    def create_terminal_ticket(self, computer_id: str) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            f"/api/computers/{computer_id}/terminal-ticket",
+            auth_required=True,
+            timeout=max(self.timeout, DEFAULT_WARMUP_TIMEOUT),
+        )
+
+    def create_proxy_ticket(self, computer_id: str, port: int) -> dict[str, Any]:
+        if port <= 0 or port > 65535:
+            raise RuntimeAPIError("port must be between 1 and 65535")
+        return self._request(
+            "POST",
+            f"/api/computers/{computer_id}/proxy-ticket",
+            json={"port": port},
+            auth_required=True,
+            timeout=max(self.timeout, DEFAULT_WARMUP_TIMEOUT),
+        )
+
+    def run_command(
+        self,
+        computer_id: str,
+        command: str,
+        *,
+        uid: int | None = None,
+        gid: int | None = None,
+        cwd: str | None = None,
+        shell: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"command": command}
+        if uid is not None:
+            body["uid"] = uid
+        if gid is not None:
+            body["gid"] = gid
+        if cwd is not None:
+            body["cwd"] = cwd
+        if shell is not None:
+            body["shell"] = shell
+        return self._request(
+            "POST",
+            f"/api/computers/{computer_id}/exec",
+            json=body,
+            auth_required=True,
+            timeout=max(self.timeout, DEFAULT_WARMUP_TIMEOUT),
+        )
+
+    def stream_command(
+        self,
+        computer_id: str,
+        command: str,
+        *,
+        stdin: bytes | None = None,
+        uid: int | None = None,
+        gid: int | None = None,
+        cwd: str | None = None,
+        shell: str | None = None,
+    ):
+        body: dict[str, Any] = {"command": command}
+        if stdin:
+            body["stdin_base64"] = base64.b64encode(stdin).decode()
+        if uid is not None:
+            body["uid"] = uid
+        if gid is not None:
+            body["gid"] = gid
+        if cwd is not None:
+            body["cwd"] = cwd
+        if shell is not None:
+            body["shell"] = shell
+        headers = self._headers(True)
+        client = httpx.Client(base_url=self.base_url, timeout=None, transport=self.transport)
+        try:
+            with client.stream("POST", f"/api/computers/{computer_id}/exec/stream", json=body, headers=headers) as response:
+                if not response.is_success:
+                    body_bytes = response.read()
+                    payload: dict[str, Any] = {}
+                    if body_bytes:
+                        try:
+                            decoded = json.loads(body_bytes.decode())
+                            if isinstance(decoded, dict):
+                                payload = decoded
+                        except ValueError:
+                            pass
+                    message = payload.get("error") or payload.get("message") or f"http {response.status_code}"
+                    raise RuntimeAPIError(str(message), status_code=response.status_code)
+                for line in response.iter_lines():
+                    if not line:
+                        continue
+                    try:
+                        frame = json.loads(line)
+                    except ValueError as exc:
+                        raise RuntimeAPIError("server returned invalid NDJSON", status_code=response.status_code) from exc
+                    if not isinstance(frame, dict):
+                        raise RuntimeAPIError("server returned non-object NDJSON", status_code=response.status_code)
+                    yield frame
+        except httpx.HTTPError as exc:
+            raise RuntimeAPIError(f"request failed: {exc}") from exc
+        finally:
+            client.close()
+
+    def read_file(self, computer_id: str, path: str) -> bytes:
+        return self._request_bytes(
+            "GET",
+            f"/api/computers/{computer_id}/files/read",
+            params={"path": path},
+            auth_required=True,
+        )
+
+    def write_file(
+        self,
+        computer_id: str,
+        path: str,
+        data: bytes,
+        *,
+        uid: int | None = None,
+        gid: int | None = None,
+        mode: str | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {"path": path}
+        if uid is not None:
+            params["uid"] = uid
+        if gid is not None:
+            params["gid"] = gid
+        if mode is not None:
+            params["mode"] = mode
+        return self._request(
+            "PUT",
+            f"/api/computers/{computer_id}/files/write",
+            params=params,
+            data=data,
+            auth_required=True,
+        )
+
+    def list_files(self, computer_id: str, path: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/computers/{computer_id}/files/list", params={"path": path}, auth_required=True)
+
+    def stat_file(self, computer_id: str, path: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/computers/{computer_id}/files/stat", params={"path": path}, auth_required=True)
+
+    def mkdir(self, computer_id: str, path: str, *, recursive: bool = False, mode: str | None = None) -> dict[str, Any]:
+        body: dict[str, Any] = {"path": path, "recursive": recursive}
+        if mode is not None:
+            body["mode"] = mode
+        return self._request("POST", f"/api/computers/{computer_id}/files/mkdir", json=body, auth_required=True)
+
+    def delete_file(self, computer_id: str, path: str, *, recursive: bool = False) -> dict[str, Any]:
+        return self._request(
+            "DELETE",
+            f"/api/computers/{computer_id}/files/delete",
+            params={"path": path, "recursive": str(recursive).lower()},
+            auth_required=True,
+        )
+
+    def upload_files(self, computer_id: str, path: str, archive: Any) -> dict[str, Any]:
+        return self._request(
+            "PUT",
+            f"/api/computers/{computer_id}/files/upload",
+            params={"path": path},
+            data=archive,
+            auth_required=True,
+        )
+
+    def download_files(self, computer_id: str, path: str) -> bytes:
+        return self._request_bytes(
+            "GET",
+            f"/api/computers/{computer_id}/files/download",
+            params={"path": path},
+            auth_required=True,
+        )
+
+    def download_files_to(self, computer_id: str, path: str, writer: BinaryIO) -> None:
+        self._request_bytes_to(
+            "GET",
+            f"/api/computers/{computer_id}/files/download",
+            writer,
+            params={"path": path},
+            auth_required=True,
+        )
+
+    def publish_port(self, computer_id: str, port: int, *, command: str | None = None, cwd: str | None = None) -> dict[str, Any]:
+        if port <= 0 or port > 65535:
+            raise RuntimeAPIError("port must be between 1 and 65535")
+        if not command:
+            raise RuntimeAPIError("publish requires -- <command...>")
+        return self.run_service(computer_id, command=command, cwd=cwd, port=port)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        data: Any = None,
+        params: dict[str, Any] | None = None,
+        auth_required: bool = False,
+        timeout: float | None = None,
+        success_statuses: set[int] | None = None,
+    ) -> dict[str, Any]:
+        headers = self._headers(auth_required)
+
+        try:
+            with httpx.Client(
+                base_url=self.base_url,
+                timeout=self.timeout if timeout is None else timeout,
+                transport=self.transport,
+            ) as client:
+                response = client.request(method, self._path(path, params), json=json, content=data, headers=headers)
+        except httpx.HTTPError as exc:
+            raise RuntimeAPIError(f"request failed: {exc}") from exc
+
+        payload = self._decode_response(response)
+        if response.is_success and (
+            success_statuses is None or response.status_code in success_statuses
+        ):
+            return payload
+
+        message = payload.get("error") or payload.get("message") or f"http {response.status_code}"
+        raise RuntimeAPIError(str(message), status_code=response.status_code)
+
+    def _request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        auth_required: bool = False,
+        timeout: float | None = None,
+    ) -> bytes:
+        headers = self._headers(auth_required)
+        try:
+            with httpx.Client(
+                base_url=self.base_url,
+                timeout=self.timeout if timeout is None else timeout,
+                transport=self.transport,
+            ) as client:
+                response = client.request(method, self._path(path, params), headers=headers)
+        except httpx.HTTPError as exc:
+            raise RuntimeAPIError(f"request failed: {exc}") from exc
+
+        if response.is_success:
+            return response.content
+
+        payload = self._decode_response(response)
+        message = payload.get("error") or payload.get("message") or f"http {response.status_code}"
+        raise RuntimeAPIError(str(message), status_code=response.status_code)
+
+    def _request_bytes_to(
+        self,
+        method: str,
+        path: str,
+        writer: BinaryIO,
+        *,
+        params: dict[str, Any] | None = None,
+        auth_required: bool = False,
+        timeout: float | None = None,
+    ) -> None:
+        headers = self._headers(auth_required)
+        try:
+            with httpx.Client(
+                base_url=self.base_url,
+                timeout=self.timeout if timeout is None else timeout,
+                transport=self.transport,
+            ) as client:
+                with client.stream(method, self._path(path, params), headers=headers) as response:
+                    if response.is_success:
+                        for chunk in response.iter_bytes():
+                            writer.write(chunk)
+                        return
+                    response.read()
+                    payload = self._decode_response(response)
+        except httpx.HTTPError as exc:
+            raise RuntimeAPIError(f"request failed: {exc}") from exc
+
+        message = payload.get("error") or payload.get("message") or f"http {response.status_code}"
+        raise RuntimeAPIError(str(message), status_code=response.status_code)
+
+    def _headers(self, auth_required: bool) -> dict[str, str]:
+        if not auth_required:
+            return {}
+        return {"Authorization": f"Bearer {self._credential()}"}
+
+    def _credential(self) -> str:
+        value = self.credential() if callable(self.credential) else self.credential
+        if not value:
+            raise RuntimeAPIError("missing credential")
+        return value
+
+    @staticmethod
+    def _path(path: str, params: dict[str, Any] | None = None) -> str:
+        if not params:
+            return path
+        query = urlencode({key: value for key, value in params.items() if value is not None})
+        if not query:
+            return path
+        separator = "&" if "?" in path else "?"
+        return f"{path}{separator}{query}"
+
+    @staticmethod
+    def _decode_response(response: httpx.Response) -> dict[str, Any]:
+        if not response.content:
+            return {}
+        try:
+            decoded = response.json()
+        except ValueError as exc:
+            raise RuntimeAPIError("server returned invalid JSON", status_code=response.status_code) from exc
+
+        if not isinstance(decoded, dict):
+            raise RuntimeAPIError("server returned non-object JSON", status_code=response.status_code)
+        return decoded