runcloud-sdk 0.7.3__tar.gz → 0.8.0__tar.gz

{runcloud_sdk-0.7.3/runcloud_sdk.egg-info → runcloud_sdk-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runcloud-sdk
-Version: 0.7.3
+Version: 0.8.0
 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.3 → runcloud_sdk-0.8.0}/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.3 → runcloud_sdk-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "runcloud-sdk"
-version = "0.7.3"
+version = "0.8.0"
 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.3 → runcloud_sdk-0.8.0}/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.7.3 → runcloud_sdk-0.8.0}/runcloud/client.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import base64
+import codecs
 import json
 import os
+import threading
 import time
 import urllib.error
 import urllib.parse
@@ -13,9 +15,12 @@ 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.7.3"
+USER_AGENT = "runcloud-python/0.8.0"
 
 
 class RunCloudError(Exception):
@@ -27,7 +32,9 @@ class RunCloudError(Exception):
 
 class UnsupportedCompatibilityFeatureError(Exception):
     def __init__(self, provider: str, feature: str, alternative: str = ""):
-        message = f"{provider} compatibility does not support {feature} on run.cloud yet"
+        message = (
+            f"{provider} compatibility does not support {feature} on run.cloud yet"
+        )
         if alternative:
             message += f"; {alternative}"
         super().__init__(message)
@@ -42,6 +49,156 @@ class ExecResult:
     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
@@ -90,6 +247,7 @@ class Client:
         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(
@@ -120,20 +278,23 @@ class Client:
         ).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={
-                "Authorization": "Bearer " + self.api_key,
-                "Content-Type": "application/json",
-                "User-Agent": USER_AGENT,
-            },
+            headers=headers,
         )
         try:
             with urllib.request.urlopen(request, timeout=self.timeout) as response:
@@ -143,11 +304,43 @@ class Client:
             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
+                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",
@@ -230,6 +423,29 @@ class Sandbox:
             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:
         payload = self._client.request(
             "POST",

{runcloud_sdk-0.7.3 → runcloud_sdk-0.8.0}/runcloud/compat/modal.py

@@ -2,11 +2,11 @@
 
 from __future__ import annotations
 
-import io
 from typing import Optional
 
 from runcloud.client import (
     Client,
+    ExecProcess,
     UnsupportedCompatibilityFeatureError,
 )
 from runcloud.client import (
@@ -42,21 +42,20 @@ class Image:
 
 
 class Process:
-    def __init__(self, result):
-        self._result = result
-        self.stdout = _Reader(result.stdout)
-        self.stderr = _Reader(result.stderr)
-        self.returncode = result.exit_code
+    def __init__(self, native: ExecProcess):
+        self._native = native
+        self.stdout = native.stdout
+        self.stderr = native.stderr
 
-    def wait(self):
-        return self.returncode
-
-    def poll(self):
-        return self.returncode
+    @property
+    def returncode(self):
+        return self._native.returncode
 
+    def wait(self, timeout=None):
+        return self._native.wait(timeout)
 
-class _Reader(io.StringIO):
-    pass
+    def poll(self):
+        return self._native.poll()
 
 
 class App:
@@ -145,11 +144,16 @@ class Sandbox:
 
     def exec(self, *args, timeout=None, workdir=None, env=None, **_ignored):
         cmd = list(args) if len(args) > 1 else args[0]
-        return Process(self.native.exec(cmd, cwd=workdir, env=env, timeout=timeout))
+        return Process(
+            self.native.exec_stream(cmd, cwd=workdir, env=env, timeout=timeout)
+        )
 
     def terminate(self, wait=True):
         self.native.destroy()
 
+    def detach(self):
+        return None
+
     def poll(self):
         self.native.refresh()
         return None if self.native.state in {"running", "starting", "pending"} else 0

{runcloud_sdk-0.7.3 → runcloud_sdk-0.8.0/runcloud_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runcloud-sdk
-Version: 0.7.3
+Version: 0.8.0
 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.3 → runcloud_sdk-0.8.0}/runcloud_sdk.egg-info/SOURCES.txt

@@ -13,5 +13,6 @@ runcloud/compat/vercel.py
 runcloud_sdk.egg-info/PKG-INFO
 runcloud_sdk.egg-info/SOURCES.txt
 runcloud_sdk.egg-info/dependency_links.txt
+runcloud_sdk.egg-info/requires.txt
 runcloud_sdk.egg-info/top_level.txt
 tests/test_sdk.py

runcloud_sdk-0.8.0/runcloud_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+websockets<16,>=13

{runcloud_sdk-0.7.3 → runcloud_sdk-0.8.0}/tests/test_sdk.py

@@ -3,6 +3,7 @@ import base64
 import json
 import os
 import tempfile
+import threading
 import time
 import unittest
 from pathlib import Path
@@ -22,6 +23,7 @@ SANDBOX = {"id": "sb_python", "name": "compat", "state": "running"}
 class Recorder:
     def __init__(self):
         self.calls = []
+        self.stream_calls = []
 
     def __call__(self, method, path, body):
         self.calls.append((method, path, body))
@@ -33,6 +35,20 @@ class Recorder:
             return {"items": [SANDBOX]}
         return SANDBOX
 
+    def stream(self, path, body):
+        self.stream_calls.append((path, body))
+
+        def frames():
+            yield json.dumps(
+                {
+                    "stream": "stdout",
+                    "data": base64.b64encode(b"ok\n").decode(),
+                }
+            )
+            yield json.dumps({"stream": "exit", "code": 0})
+
+        return frames()
+
 
 class Response:
     def __enter__(self):
@@ -45,10 +61,35 @@ class Response:
         return b"{}"
 
 
+class WebSocketSession:
+    def __init__(self):
+        self.sent = []
+        self.closed = False
+
+    def send(self, value):
+        self.sent.append(value)
+
+    def close(self):
+        self.closed = True
+
+    def __iter__(self):
+        yield json.dumps(
+            {
+                "stream": "stdout",
+                "data": base64.b64encode(b"live\n").decode(),
+            }
+        )
+        yield json.dumps({"stream": "exit", "code": 0})
+
+
 class SDKTests(unittest.TestCase):
     def setUp(self):
         self.recorder = Recorder()
-        self.client = Client(api_key="rc_live_test", transport=self.recorder)
+        self.client = Client(
+            api_key="rc_live_test",
+            transport=self.recorder,
+            stream_transport=self.recorder.stream,
+        )
 
     def test_native_routes(self):
         box = self.client.create(cpu=1.5, memory=2048)
@@ -78,6 +119,21 @@ class SDKTests(unittest.TestCase):
         self.assertEqual(read_process.wait(), 0)
         iter_process = modal_sandbox.exec("echo ok")
         self.assertEqual(list(iter_process.stdout), ["ok\n"])
+        self.assertEqual(iter_process.wait(), 0)
+        self.assertIsNone(modal_sandbox.detach())
+        self.assertEqual(
+            self.recorder.stream_calls,
+            [
+                (
+                    "/run-cloud/sandboxes/sb_python/exec/stream?mode=command",
+                    {"cmd": ["/bin/sh", "-c", "echo ok"]},
+                ),
+                (
+                    "/run-cloud/sandboxes/sb_python/exec/stream?mode=command",
+                    {"cmd": ["/bin/sh", "-c", "echo ok"]},
+                ),
+            ],
+        )
         self.assertEqual(
             E2BSandbox.create(client=self.client).commands.run("echo ok").exit_code, 0
         )
@@ -92,6 +148,73 @@ class SDKTests(unittest.TestCase):
         asyncio.run(async_blaxel.delete())
         self.assertTrue(SpritesClient(client=self.client).create_sprite("compat"))
 
+    def test_modal_process_delivers_output_before_exit(self):
+        first_frame_sent = threading.Event()
+        release_exit = threading.Event()
+
+        def stream_transport(path, body):
+            self.assertEqual(
+                path,
+                "/run-cloud/sandboxes/sb_python/exec/stream?mode=command",
+            )
+            self.assertEqual(
+                body,
+                {
+                    "cmd": ["bash", "-c", "run"],
+                    "cwd": "/workspace",
+                    "env": {"CI": "true"},
+                    "timeout_seconds": 30,
+                },
+            )
+
+            def frames():
+                yield json.dumps(
+                    {
+                        "stream": "stdout",
+                        "data": base64.b64encode(b"first\n").decode(),
+                    }
+                )
+                first_frame_sent.set()
+                release_exit.wait(2)
+                yield json.dumps(
+                    {
+                        "stream": "stderr",
+                        "data": base64.b64encode(b"warning\n").decode(),
+                    }
+                )
+                yield json.dumps(
+                    {
+                        "stream": "stdout",
+                        "data": base64.b64encode(b"second\n").decode(),
+                    }
+                )
+                yield json.dumps({"stream": "exit", "code": 7})
+
+            return frames()
+
+        client = Client(
+            api_key="rc_live_test",
+            transport=self.recorder,
+            stream_transport=stream_transport,
+        )
+        process = modal.Sandbox(client.get("sb_python")).exec(
+            "bash",
+            "-c",
+            "run",
+            workdir="/workspace",
+            env={"CI": "true"},
+            timeout=30,
+        )
+
+        self.assertTrue(first_frame_sent.wait(1))
+        self.assertIsNone(process.poll())
+        self.assertEqual(process.stdout.readline(), "first\n")
+        release_exit.set()
+        self.assertEqual(list(process.stdout), ["second\n"])
+        self.assertEqual(process.stderr.read(), "warning\n")
+        self.assertEqual(process.wait(), 7)
+        self.assertEqual(process.poll(), 7)
+
     def test_unsupported_features_fail_loudly(self):
         with self.assertRaises(UnsupportedCompatibilityFeatureError):
             modal.Image.debian_slim().pip_install("requests")
@@ -104,7 +227,54 @@ class SDKTests(unittest.TestCase):
             Client(api_key="rc_live_test").request("GET", "/run-cloud/account")
 
         request = urlopen.call_args.args[0]
-        self.assertEqual(request.get_header("User-agent"), "runcloud-python/0.7.3")
+        self.assertEqual(request.get_header("User-agent"), "runcloud-python/0.8.0")
+
+    def test_exec_stream_opens_authenticated_websocket_and_sends_command(self):
+        session = WebSocketSession()
+        with patch(
+            "runcloud.client.websocket_connect",
+            return_value=session,
+        ) as connect:
+            client = Client(
+                api_key="rc_live_test",
+                api_url="https://api.example.test",
+            )
+            process = client.open_exec_stream(
+                "/run-cloud/sandboxes/sb_1/exec/stream?mode=command",
+                {"cmd": ["echo", "live"]},
+            )
+
+        self.assertEqual(process.stdout.read(), "live\n")
+        self.assertEqual(process.wait(), 0)
+        self.assertTrue(session.closed)
+        self.assertEqual(
+            session.sent,
+            [
+                '{"cmd": ["echo", "live"]}',
+                '{"stream": "stdin_close"}',
+            ],
+        )
+        connect.assert_called_once_with(
+            "wss://api.example.test/run-cloud/sandboxes/sb_1/exec/stream?mode=command",
+            additional_headers={"Authorization": "Bearer rc_live_test"},
+            user_agent_header="runcloud-python/0.8.0",
+            open_timeout=60.0,
+            close_timeout=5,
+            max_size=8 << 20,
+        )
+
+    def test_content_type_is_only_sent_with_a_json_body(self):
+        with patch(
+            "runcloud.client.urllib.request.urlopen",
+            return_value=Response(),
+        ) as urlopen:
+            client = Client(api_key="rc_live_test")
+            client.request("DELETE", "/run-cloud/sandboxes/sbx_test")
+            client.request("POST", "/run-cloud/sandboxes", {})
+
+        delete_request, post_request = (call.args[0] for call in urlopen.call_args_list)
+        self.assertIsNone(delete_request.get_header("Content-type"))
+        self.assertEqual(post_request.get_header("Content-type"), "application/json")
 
 
 class CredentialTests(unittest.TestCase):