runcloud-sdk 0.7.4__tar.gz → 0.8.1__tar.gz

{runcloud_sdk-0.7.4/runcloud_sdk.egg-info → runcloud_sdk-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runcloud-sdk
-Version: 0.7.4
+Version: 0.8.1
 Summary: Python SDK for run.cloud, including sandbox-provider compatibility adapters
 Author: Newly
 License-Expression: Apache-2.0
@@ -13,6 +13,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: websockets<16,>=13
 Dynamic: license-file
 
 # runcloud
@@ -36,6 +37,27 @@ finally:
     box.destroy()
 ```
 
+Commands started through the Modal compatibility adapter stream output while
+they are running:
+
+```python
+from runcloud.compat import modal
+
+app = modal.App.lookup("my-app")
+box = modal.Sandbox.create(app=app)
+try:
+    process = box.exec(
+        "bash",
+        "-c",
+        "for i in {1..5}; do date +%T; sleep 0.5; done",
+    )
+    for line in process.stdout:
+        print(line, end="")
+    process.wait()
+finally:
+    box.terminate()
+```
+
 `Client()` automatically uses the credential saved by `runcloud login`. For
 automation, set `RUN_CLOUD_API_KEY` and optionally `RUN_CLOUD_API_URL`, or pass
 `api_key` and `api_url` directly.

{runcloud_sdk-0.7.4 → runcloud_sdk-0.8.1}/README.md

@@ -19,6 +19,27 @@ finally:
     box.destroy()
 ```
 
+Commands started through the Modal compatibility adapter stream output while
+they are running:
+
+```python
+from runcloud.compat import modal
+
+app = modal.App.lookup("my-app")
+box = modal.Sandbox.create(app=app)
+try:
+    process = box.exec(
+        "bash",
+        "-c",
+        "for i in {1..5}; do date +%T; sleep 0.5; done",
+    )
+    for line in process.stdout:
+        print(line, end="")
+    process.wait()
+finally:
+    box.terminate()
+```
+
 `Client()` automatically uses the credential saved by `runcloud login`. For
 automation, set `RUN_CLOUD_API_KEY` and optionally `RUN_CLOUD_API_URL`, or pass
 `api_key` and `api_url` directly.

{runcloud_sdk-0.7.4 → runcloud_sdk-0.8.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "runcloud-sdk"
-version = "0.7.4"
+version = "0.8.1"
 description = "Python SDK for run.cloud, including sandbox-provider compatibility adapters"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -12,7 +12,7 @@ classifiers = [
   "Programming Language :: Python :: 3",
   "Operating System :: OS Independent",
 ]
-dependencies = []
+dependencies = ["websockets>=13,<16"]
 
 [project.urls]
 Homepage = "https://run.cloud"

{runcloud_sdk-0.7.4 → runcloud_sdk-0.8.1}/runcloud/__init__.py

@@ -2,6 +2,7 @@
 
 from .client import (
     Client,
+    ExecProcess,
     ExecResult,
     RunCloudError,
     Sandbox,
@@ -10,6 +11,7 @@ from .client import (
 
 __all__ = [
     "Client",
+    "ExecProcess",
     "ExecResult",
     "RunCloudError",
     "Sandbox",

runcloud_sdk-0.8.1/runcloud/client.py

@@ -0,0 +1,549 @@
+"""Dependency-free Python client for the public run.cloud API."""
+
+from __future__ import annotations
+
+import base64
+import codecs
+import json
+import os
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Optional, Union
+
+from websockets.sync.client import connect as websocket_connect
+
+Transport = Callable[[str, str, Any], Any]
+StreamTransport = Callable[[str, dict[str, Any]], Any]
+DEFAULT_API_URL = "https://api.run.cloud"
+USER_AGENT = "runcloud-python/0.8.1"
+FILE_CHUNK_BYTES = 512 * 1024
+
+
+class RunCloudError(Exception):
+    def __init__(self, status: int, detail: str):
+        super().__init__(f"run.cloud API {status}: {detail}")
+        self.status = status
+        self.detail = detail
+
+
+class UnsupportedCompatibilityFeatureError(Exception):
+    def __init__(self, provider: str, feature: str, alternative: str = ""):
+        message = (
+            f"{provider} compatibility does not support {feature} on run.cloud yet"
+        )
+        if alternative:
+            message += f"; {alternative}"
+        super().__init__(message)
+        self.provider = provider
+        self.feature = feature
+
+
+@dataclass(frozen=True)
+class ExecResult:
+    exit_code: int
+    stdout: str
+    stderr: str
+
+
+class _StreamReader:
+    def __init__(self):
+        self._condition = threading.Condition()
+        self._buffer = ""
+        self._decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+        self._eof = False
+        self._error: Optional[Exception] = None
+
+    def _feed(self, data: bytes) -> None:
+        text = self._decoder.decode(data)
+        if not text:
+            return
+        with self._condition:
+            self._buffer += text
+            self._condition.notify_all()
+
+    def _finish(self, error: Optional[Exception] = None) -> None:
+        with self._condition:
+            self._buffer += self._decoder.decode(b"", final=True)
+            self._error = error
+            self._eof = True
+            self._condition.notify_all()
+
+    def _raise_error_if_empty(self) -> None:
+        if not self._buffer and self._error is not None:
+            raise self._error
+
+    def read(self, size: int = -1) -> str:
+        if size == 0:
+            return ""
+        with self._condition:
+            if size < 0:
+                while not self._eof:
+                    self._condition.wait()
+                self._raise_error_if_empty()
+                value, self._buffer = self._buffer, ""
+                return value
+
+            while len(self._buffer) < size and not self._eof:
+                self._condition.wait()
+            self._raise_error_if_empty()
+            value, self._buffer = self._buffer[:size], self._buffer[size:]
+            return value
+
+    def readline(self, size: int = -1) -> str:
+        if size == 0:
+            return ""
+        with self._condition:
+            while True:
+                newline = self._buffer.find("\n")
+                if newline >= 0:
+                    end = newline + 1
+                    break
+                if size >= 0 and len(self._buffer) >= size:
+                    end = size
+                    break
+                if self._eof:
+                    self._raise_error_if_empty()
+                    end = len(self._buffer)
+                    break
+                self._condition.wait()
+
+            if size >= 0:
+                end = min(end, size)
+            value, self._buffer = self._buffer[:end], self._buffer[end:]
+            return value
+
+    def __iter__(self):
+        return self
+
+    def __next__(self) -> str:
+        line = self.readline()
+        if line == "":
+            raise StopIteration
+        return line
+
+
+class ExecProcess:
+    def __init__(self, session: Any):
+        self.stdout = _StreamReader()
+        self.stderr = _StreamReader()
+        self._session = session
+        self._returncode: Optional[int] = None
+        self._error: Optional[Exception] = None
+        self._finished = threading.Event()
+        self._reader_thread = threading.Thread(
+            target=self._read_frames,
+            name="runcloud-exec-stream",
+            daemon=True,
+        )
+        self._reader_thread.start()
+
+    @property
+    def returncode(self) -> Optional[int]:
+        return self._returncode
+
+    @property
+    def exit_code(self) -> int:
+        return self.wait()
+
+    def poll(self) -> Optional[int]:
+        if not self._finished.is_set():
+            return None
+        if self._error is not None:
+            raise self._error
+        return self._returncode
+
+    def wait(self, timeout: Optional[float] = None) -> int:
+        if not self._finished.wait(timeout):
+            raise TimeoutError("run.cloud process did not exit before the wait timeout")
+        if self._error is not None:
+            raise self._error
+        return self._returncode if self._returncode is not None else 0
+
+    def _read_frames(self) -> None:
+        error: Optional[Exception] = None
+        try:
+            for raw in self._session:
+                if isinstance(raw, bytes):
+                    raw = raw.decode("utf-8")
+                frame = json.loads(raw)
+                stream = frame.get("stream")
+                if stream in {"stdout", "stderr"}:
+                    encoded = frame.get("data")
+                    if not isinstance(encoded, str):
+                        continue
+                    data = base64.b64decode(encoded, validate=True)
+                    target = self.stderr if stream == "stderr" else self.stdout
+                    target._feed(data)
+                elif stream == "exit":
+                    code = frame.get("code", frame.get("exit_code", 0))
+                    if isinstance(code, bool) or not isinstance(code, int):
+                        raise ValueError("exec stream returned an invalid exit code")
+                    self._returncode = code
+                    break
+            if self._returncode is None:
+                raise RuntimeError("exec stream closed before reporting an exit code")
+        except Exception as caught:
+            error = RunCloudError(0, f"exec stream failed: {caught}")
+            self._error = error
+        finally:
+            try:
+                self._session.close()
+            except Exception:
+                pass
+            self.stdout._finish(error)
+            self.stderr._finish(error)
+            self._finished.set()
+
+
+@dataclass(frozen=True)
+class _SavedCredentials:
+    api_key: str
+    api_url: str
+
+
+def _nonempty_string(value: Any) -> Optional[str]:
+    if not isinstance(value, str):
+        return None
+    normalized = value.strip()
+    return normalized or None
+
+
+def _load_saved_credentials() -> Optional[_SavedCredentials]:
+    configured_home = _nonempty_string(os.environ.get("RUN_CLOUD_HOME"))
+    credentials_home = (
+        Path(configured_home).expanduser()
+        if configured_home
+        else Path.home() / ".run-cloud"
+    )
+    try:
+        payload = json.loads((credentials_home / "credentials").read_text())
+    except (OSError, TypeError, ValueError):
+        return None
+
+    if not isinstance(payload, dict):
+        return None
+    api_key = _nonempty_string(payload.get("token"))
+    api_url = _nonempty_string(payload.get("apiUrl"))
+    expires_at = payload.get("expiresAt")
+    if (
+        not api_key
+        or not api_url
+        or isinstance(expires_at, bool)
+        or not isinstance(expires_at, (int, float))
+        or expires_at < time.time()
+    ):
+        return None
+    return _SavedCredentials(api_key=api_key, api_url=api_url)
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_url: Optional[str] = None,
+        timeout: float = 60.0,
+        transport: Optional[Transport] = None,
+        stream_transport: Optional[StreamTransport] = None,
+    ):
+        explicit_api_key = _nonempty_string(api_key)
+        environment_api_key = _nonempty_string(
+            os.environ.get("RUN_CLOUD_API_KEY")
+        ) or _nonempty_string(os.environ.get("RUN_CLOUD_API_TOKEN"))
+        saved_credentials = (
+            None
+            if explicit_api_key or environment_api_key
+            else _load_saved_credentials()
+        )
+        self.api_key = (
+            explicit_api_key
+            or environment_api_key
+            or (saved_credentials.api_key if saved_credentials else None)
+        )
+        if not self.api_key:
+            raise ValueError(
+                "Run Cloud API key required. Run `runcloud login`, set "
+                "RUN_CLOUD_API_KEY, or pass Client(api_key=...)."
+            )
+        explicit_api_url = _nonempty_string(api_url)
+        environment_api_url = _nonempty_string(os.environ.get("RUN_CLOUD_API_URL"))
+        self.api_url = (
+            explicit_api_url
+            or environment_api_url
+            or (saved_credentials.api_url if saved_credentials else None)
+            or DEFAULT_API_URL
+        ).rstrip("/")
+        self.timeout = timeout
+        self._transport = transport
+        self._stream_transport = stream_transport
+
+    def request(self, method: str, path: str, body: Any = None) -> Any:
+        if self._transport is not None:
+            return self._transport(method, path, body)
+        data = json.dumps(body).encode() if body is not None else None
+        headers = {
+            "Authorization": "Bearer " + self.api_key,
+            "User-Agent": USER_AGENT,
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        request = urllib.request.Request(
+            self.api_url + path,
+            data=data,
+            method=method,
+            headers=headers,
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                raw = response.read()
+                return json.loads(raw) if raw else None
+        except urllib.error.HTTPError as error:
+            text = error.read().decode(errors="replace")
+            try:
+                parsed = json.loads(text)
+                text = (
+                    parsed.get("detail")
+                    or parsed.get("error")
+                    or parsed.get("message")
+                    or text
+                )
+            except Exception:
+                pass
+            raise RunCloudError(error.code, str(text)) from None
+
+    def open_exec_stream(self, path: str, body: dict[str, Any]) -> ExecProcess:
+        if self._stream_transport is not None:
+            return ExecProcess(self._stream_transport(path, body))
+
+        http_url = self.api_url + path
+        if http_url.startswith("https://"):
+            websocket_url = "wss://" + http_url.removeprefix("https://")
+        elif http_url.startswith("http://"):
+            websocket_url = "ws://" + http_url.removeprefix("http://")
+        else:
+            raise ValueError("run.cloud API URL must use http or https")
+
+        try:
+            session = websocket_connect(
+                websocket_url,
+                additional_headers={"Authorization": "Bearer " + self.api_key},
+                user_agent_header=USER_AGENT,
+                open_timeout=self.timeout,
+                close_timeout=5,
+                max_size=8 << 20,
+            )
+            session.send(json.dumps(body))
+            session.send(json.dumps({"stream": "stdin_close"}))
+        except Exception as error:
+            raise RunCloudError(0, f"could not open exec stream: {error}") from None
+        return ExecProcess(session)
+
+    def create(
+        self,
+        image: str = "runcloud/agent-base",
+        cpu: Optional[float] = None,
+        memory: Optional[int] = None,
+        disk: Optional[int] = None,
+        idle_pause_seconds: Optional[int] = None,
+        timeout_seconds: Optional[int] = None,
+        region: Optional[str] = None,
+        name: Optional[str] = None,
+    ) -> "Sandbox":
+        values = {
+            "image": image,
+            "cpu": cpu,
+            "memory": memory,
+            "disk": disk,
+            "idlePauseSeconds": idle_pause_seconds,
+            "timeoutSeconds": timeout_seconds,
+            "region": region,
+            "name": name,
+        }
+        body = {key: value for key, value in values.items() if value is not None}
+        return Sandbox(self, self.request("POST", "/run-cloud/sandboxes", body))
+
+    def get(self, sandbox_id: str) -> "Sandbox":
+        sid = urllib.parse.quote(sandbox_id, safe="")
+        return Sandbox(self, self.request("GET", f"/run-cloud/sandboxes/{sid}"))
+
+    def list(self, state: Optional[str] = None) -> list["Sandbox"]:
+        query = f"?state={urllib.parse.quote(state, safe='')}" if state else ""
+        payload = self.request("GET", "/run-cloud/sandboxes" + query) or {}
+        return [Sandbox(self, item) for item in payload.get("items", [])]
+
+
+class Sandbox:
+    def __init__(self, client: Client, data: dict[str, Any]):
+        self._client = client
+        self._data = data
+        self.id = str(data["id"])
+
+    @property
+    def state(self) -> str:
+        return str(self._data.get("state", ""))
+
+    @property
+    def name(self) -> str:
+        return str(self._data.get("name") or "")
+
+    def refresh(self) -> "Sandbox":
+        self._data = self._client.request(
+            "GET", f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}"
+        )
+        return self
+
+    def exec(
+        self,
+        command: Union[str, list[str]],
+        cwd: Optional[str] = None,
+        env: Optional[dict[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> ExecResult:
+        argv = ["/bin/sh", "-c", command] if isinstance(command, str) else command
+        if not argv:
+            raise ValueError("command must not be empty")
+        body: dict[str, Any] = {"cmd": argv}
+        if cwd:
+            body["cwd"] = cwd
+        if env:
+            body["env"] = env
+        if timeout is not None:
+            body["timeout_seconds"] = timeout
+        payload = self._client.request(
+            "POST",
+            f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}/exec",
+            body,
+        )
+        return ExecResult(
+            int(payload.get("exit_code", 0)),
+            str(payload.get("stdout", "")),
+            str(payload.get("stderr", "")),
+        )
+
+    def exec_stream(
+        self,
+        command: Union[str, list[str]],
+        cwd: Optional[str] = None,
+        env: Optional[dict[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> ExecProcess:
+        argv = ["/bin/sh", "-c", command] if isinstance(command, str) else command
+        if not argv:
+            raise ValueError("command must not be empty")
+        body: dict[str, Any] = {"cmd": argv}
+        if cwd:
+            body["cwd"] = cwd
+        if env:
+            body["env"] = env
+        if timeout is not None:
+            body["timeout_seconds"] = timeout
+        sandbox_id = urllib.parse.quote(self.id, safe="")
+        return self._client.open_exec_stream(
+            f"/run-cloud/sandboxes/{sandbox_id}/exec/stream?mode=command",
+            body,
+        )
+
+    def read_file(self, path: str) -> bytes:
+        if not path:
+            raise ValueError("path must not be empty")
+        sandbox_id = urllib.parse.quote(self.id, safe="")
+        chunks: list[bytes] = []
+        offset = 0
+        while True:
+            payload = self._client.request(
+                "POST",
+                f"/run-cloud/sandboxes/{sandbox_id}/fs",
+                {
+                    "op": "read",
+                    "path": path,
+                    "offset": offset,
+                    "length": FILE_CHUNK_BYTES,
+                },
+            )
+            if payload.get("error"):
+                raise RunCloudError(0, str(payload["error"]))
+            chunk = base64.b64decode(payload.get("content") or "")
+            chunks.append(chunk)
+            if payload.get("eof") is True:
+                return b"".join(chunks)
+            raw_next_offset = payload.get("next_offset")
+            raw_size = payload.get("size")
+            if (
+                payload.get("eof") is None
+                and raw_next_offset is None
+                and raw_size is None
+            ):
+                return b"".join(chunks)
+            next_offset = int(
+                raw_next_offset if raw_next_offset is not None else offset + len(chunk)
+            )
+            if raw_size is not None and next_offset >= int(raw_size):
+                return b"".join(chunks)
+            if next_offset <= offset:
+                raise RunCloudError(0, "file read did not advance")
+            offset = next_offset
+
+    def write_file(
+        self,
+        path: str,
+        content: bytes,
+        mode: Optional[int] = None,
+    ) -> None:
+        if not path:
+            raise ValueError("path must not be empty")
+        if not isinstance(content, bytes):
+            raise TypeError("content must be bytes")
+        sandbox_id = urllib.parse.quote(self.id, safe="")
+        chunk_count = max(1, (len(content) + FILE_CHUNK_BYTES - 1) // FILE_CHUNK_BYTES)
+        for index in range(chunk_count):
+            offset = index * FILE_CHUNK_BYTES
+            chunk = content[offset : offset + FILE_CHUNK_BYTES]
+            body: dict[str, Any] = {
+                "op": "write",
+                "path": path,
+                "offset": offset,
+                "content": base64.b64encode(chunk).decode(),
+                "truncate": index == 0,
+            }
+            if mode is not None:
+                body["mode"] = mode
+            payload = self._client.request(
+                "POST",
+                f"/run-cloud/sandboxes/{sandbox_id}/fs",
+                body,
+            )
+            if payload.get("error"):
+                raise RunCloudError(0, str(payload["error"]))
+
+    def pause(self) -> "Sandbox":
+        self._data = self._client.request(
+            "POST",
+            f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}/pause",
+            {},
+        )
+        return self
+
+    def resume(self) -> "Sandbox":
+        self._data = self._client.request(
+            "POST",
+            f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}/resume",
+            {},
+        )
+        return self
+
+    def set_timeout(self, seconds: int) -> "Sandbox":
+        self._data = self._client.request(
+            "POST",
+            f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}/timeout",
+            {"timeoutSeconds": seconds},
+        )
+        return self
+
+    def destroy(self) -> None:
+        self._client.request(
+            "DELETE", f"/run-cloud/sandboxes/{urllib.parse.quote(self.id, safe='')}"
+        )