render 1.0.1__py3-none-any.whl

render/experimental/sandbox/tests/test_e2e.py

@@ -0,0 +1,252 @@
+"""End-to-end test for the sandbox client.
+
+Creates a real sandbox, runs commands through exec (token mint plus proxy
+stream), verifies the streamed output and exit codes, and always terminates the
+sandbox. Gated on real credentials, so it is skipped by default.
+
+Run with:
+    uv run pytest render/experimental/sandbox/tests/test_e2e.py -m e2e -v
+
+CI runs this against staging as `test+sdk-e2e@test.render.com`, in its own
+`Python Sandbox E2E Tests` job so it reports separately from the rest of the e2e
+set. The API key is in shared 1Password. Staging sandboxes now reach `running`,
+so these cases exercise the real token mint, proxy stream and file transfer.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+
+import pytest
+
+from render.experimental.sandbox import (
+    SandboxExecExit,
+    SandboxExecOutput,
+    SandboxFileNotFoundError,
+)
+from render.render_async import RenderAsync
+
+_OWNER_ID = os.environ.get("RENDER_E2E_OWNER_ID") or os.environ.get(
+    "RENDER_WORKSPACE_ID"
+)
+
+pytestmark = [
+    pytest.mark.e2e,
+    pytest.mark.sandbox_e2e,
+    pytest.mark.skipif(
+        not os.environ.get("RENDER_API_KEY") or not _OWNER_ID,
+        reason=(
+            "RENDER_API_KEY and RENDER_E2E_OWNER_ID (or RENDER_WORKSPACE_ID) "
+            "required for sandbox e2e tests"
+        ),
+    ),
+]
+
+
+@pytest.fixture
+def sandboxes():
+    render = RenderAsync(
+        base_url=os.environ.get("RENDER_BASE_URL") or "https://api.render.com"
+    )
+    return render.experimental.sandboxes
+
+
+async def _wait_until_running(sandboxes, sandbox_id, owner_id, timeout_s=180.0):
+    """Poll from_id until the sandbox is running, or fail on timeout/error."""
+    deadline = time.monotonic() + timeout_s
+    while True:
+        sandbox = await sandboxes.from_id(sandbox_id, owner_id=owner_id)
+        if sandbox.status == "running":
+            return sandbox
+        if sandbox.status in ("errored", "terminated"):
+            raise AssertionError(
+                f"sandbox {sandbox_id} reached terminal status {sandbox.status!r}"
+            )
+        if time.monotonic() > deadline:
+            raise AssertionError(
+                f"sandbox {sandbox_id} still {sandbox.status!r} after {timeout_s}s"
+            )
+        await asyncio.sleep(3.0)
+
+
+async def _exec_output(sandboxes, sandbox_id, owner_id, command):
+    """Run command and return its stdout, asserting a zero exit."""
+    outputs = []
+    exit_event = None
+    async for event in sandboxes.exec(sandbox_id, command, owner_id=owner_id):
+        if isinstance(event, SandboxExecOutput):
+            if event.stream == "stdout":
+                outputs.append(event.data)
+        elif isinstance(event, SandboxExecExit):
+            exit_event = event
+    assert exit_event is not None
+    assert exit_event.exit_code == 0, f"{command!r} exited {exit_event.exit_code}"
+    return "".join(outputs)
+
+
+@pytest.mark.asyncio
+async def test_create_exec_terminate(sandboxes):
+    owner_id = _OWNER_ID
+
+    sandbox = await sandboxes.create(owner_id=owner_id)
+    assert sandbox.id.startswith("sbx-")
+    try:
+        await _wait_until_running(sandboxes, sandbox.id, owner_id)
+
+        # from_id round-trips the same sandbox
+        fetched = await sandboxes.from_id(sandbox.id, owner_id=owner_id)
+        assert fetched.id == sandbox.id
+
+        # list includes the new sandbox
+        page = await sandboxes.list(owner_id=owner_id)
+        assert any(s.id == sandbox.id for s in page.sandboxes)
+
+        filtered = await sandboxes.list(
+            owner_id=owner_id, status=["running", "creating"], limit=100
+        )
+        assert any(s.id == sandbox.id for s in filtered.sandboxes)
+        assert all(s.status in {"running", "creating"} for s in filtered.sandboxes)
+
+        excluded = await sandboxes.list(
+            owner_id=owner_id, status=["suspended"], limit=100
+        )
+        assert all(s.id != sandbox.id for s in excluded.sandboxes)
+        assert all(s.status == "suspended" for s in excluded.sandboxes)
+
+        # exec streams stdout and reports a zero exit
+        outputs = []
+        exit_event = None
+        async for event in sandboxes.exec(
+            sandbox.id, "echo hello-from-e2e", owner_id=owner_id
+        ):
+            if isinstance(event, SandboxExecOutput):
+                outputs.append(event.data)
+            elif isinstance(event, SandboxExecExit):
+                exit_event = event
+        assert "hello-from-e2e" in "".join(outputs)
+        assert exit_event is not None
+        assert exit_event.exit_code == 0
+
+        # a non-zero process exit is reported via the exit event, not an error
+        exit_event = None
+        async for event in sandboxes.exec(sandbox.id, "exit 3", owner_id=owner_id):
+            if isinstance(event, SandboxExecExit):
+                exit_event = event
+        assert exit_event is not None
+        assert exit_event.exit_code == 3
+    finally:
+        await sandboxes.terminate(sandbox.id, owner_id=owner_id)
+
+
+@pytest.mark.asyncio
+async def test_copy_from_file_and_directory(sandboxes, tmp_path):
+    owner_id = _OWNER_ID
+
+    sandbox = await sandboxes.create(owner_id=owner_id)
+    try:
+        await _wait_until_running(sandboxes, sandbox.id, owner_id)
+
+        # build a tree inside the sandbox to pull back out
+        await _exec_output(
+            sandboxes,
+            sandbox.id,
+            owner_id,
+            'cd "$HOME" && mkdir -p copy-from-tree/nested '
+            '&& printf "hello from copy_from\\n" > copy-from-greeting.txt '
+            '&& printf "nested file\\n" > copy-from-tree/nested/data.txt '
+            "&& ln -sf nested/data.txt copy-from-tree/link.txt",
+        )
+
+        # a single file lands at exactly the path asked for
+        target = tmp_path / "greeting.txt"
+        written = await sandboxes.copy_from(
+            sandbox.id, "copy-from-greeting.txt", target, owner_id=owner_id
+        )
+        assert written == str(target)
+        assert target.read_text() == "hello from copy_from\n"
+
+        # into an existing directory, the name comes from the sandbox
+        inbox = tmp_path / "inbox"
+        inbox.mkdir()
+        written = await sandboxes.copy_from(
+            sandbox.id, "copy-from-greeting.txt", inbox, owner_id=owner_id
+        )
+        assert written == str(inbox / "copy-from-greeting.txt")
+        assert (
+            inbox / "copy-from-greeting.txt"
+        ).read_text() == "hello from copy_from\n"
+
+        # a directory arrives as an x-tar archive under Content-Encoding: gzip
+        # and is extracted under local_path, symlink stored rather than followed
+        tree = tmp_path / "tree"
+        written = await sandboxes.copy_from(
+            sandbox.id, "copy-from-tree", tree, owner_id=owner_id
+        )
+        assert written == str(tree)
+        assert (tree / "nested" / "data.txt").read_text() == "nested file\n"
+        assert os.readlink(tree / "link.txt") == "nested/data.txt"
+
+        # a path the sandbox does not have is a missing file, not a missing
+        # sandbox: the agent says so with a file_not_found code in the body
+        with pytest.raises(SandboxFileNotFoundError):
+            await sandboxes.copy_from(
+                sandbox.id,
+                "no-such-file.txt",
+                tmp_path / "nope.txt",
+                owner_id=owner_id,
+            )
+    finally:
+        await sandboxes.terminate(sandbox.id, owner_id=owner_id)
+
+
+@pytest.mark.asyncio
+async def test_copy_to_file_and_directory(sandboxes, tmp_path):
+    owner_id = _OWNER_ID
+
+    (tmp_path / "greeting.txt").write_text("hello from copy_to\n")
+    tree = tmp_path / "tree"
+    (tree / "nested").mkdir(parents=True)
+    (tree / "nested" / "data.txt").write_text("nested file\n")
+    (tree / "link.txt").symlink_to("nested/data.txt")
+
+    sandbox = await sandboxes.create(owner_id=owner_id)
+    try:
+        await _wait_until_running(sandboxes, sandbox.id, owner_id)
+
+        # a single file arrives as raw bytes. A relative remote path resolves
+        # under the sandbox's home directory, scp style.
+        await sandboxes.copy_to(
+            sandbox.id,
+            tmp_path / "greeting.txt",
+            "copy-to-greeting.txt",
+            owner_id=owner_id,
+        )
+        contents = await _exec_output(
+            sandboxes, sandbox.id, owner_id, 'cat "$HOME/copy-to-greeting.txt"'
+        )
+        assert contents == "hello from copy_to\n"
+
+        # a directory arrives as an archive the sandbox extracts, with entry
+        # names relative to the local root
+        await sandboxes.copy_to(sandbox.id, tree, "copy-to-tree", owner_id=owner_id)
+        listing = await _exec_output(
+            sandboxes,
+            sandbox.id,
+            owner_id,
+            'cd "$HOME" && find copy-to-tree -mindepth 1 | sort',
+        )
+        assert listing.split() == [
+            "copy-to-tree/link.txt",
+            "copy-to-tree/nested",
+            "copy-to-tree/nested/data.txt",
+        ]
+
+        # the symlink was stored, not followed into a second copy of the file
+        target = await _exec_output(
+            sandboxes, sandbox.id, owner_id, 'readlink "$HOME/copy-to-tree/link.txt"'
+        )
+        assert target.strip() == "nested/data.txt"
+    finally:
+        await sandboxes.terminate(sandbox.id, owner_id=owner_id)

render/experimental/sandbox/tests/test_tar.py

@@ -0,0 +1,153 @@
+import asyncio
+import gzip
+import io
+import os
+import tarfile
+import threading
+from pathlib import Path
+
+import pytest
+
+from render.experimental.sandbox._tar import (
+    CHUNK_SIZE,
+    aiter_tar_gzip,
+    iter_tar_gzip,
+)
+
+
+def _members(chunks: list[bytes]) -> dict[str, tarfile.TarInfo]:
+    raw = gzip.decompress(b"".join(chunks))
+    with tarfile.open(fileobj=io.BytesIO(raw)) as tar:
+        return {member.name: member for member in tar.getmembers()}
+
+
+def _tree(root: Path) -> Path:
+    (root / "a.txt").write_text("a\n")
+    (root / "sub").mkdir()
+    (root / "sub" / "b.txt").write_text("b\n")
+    return root
+
+
+def test_entries_are_relative_and_the_root_is_not_emitted(tmp_path):
+    members = _members(list(iter_tar_gzip(_tree(tmp_path))))
+
+    assert set(members) == {"a.txt", "sub", "sub/b.txt"}
+    assert members["sub"].isdir()
+    assert members["a.txt"].isreg()
+    assert str(tmp_path) not in " ".join(members)
+
+
+def test_symlinks_are_stored_not_followed(tmp_path):
+    _tree(tmp_path)
+    (tmp_path / "link.txt").symlink_to("sub/b.txt")
+
+    members = _members(list(iter_tar_gzip(tmp_path)))
+
+    assert members["link.txt"].issym()
+    assert members["link.txt"].linkname == "sub/b.txt"
+    assert members["link.txt"].size == 0
+
+
+def test_special_files_are_skipped(tmp_path):
+    _tree(tmp_path)
+    os.mkfifo(tmp_path / "pipe")
+
+    members = _members(list(iter_tar_gzip(tmp_path)))
+
+    assert "pipe" not in members
+    assert "a.txt" in members
+
+
+def test_hardlinks_are_stored_as_regular_files(tmp_path):
+    (tmp_path / "one.txt").write_text("shared\n")
+    os.link(tmp_path / "one.txt", tmp_path / "two.txt")
+
+    raw = gzip.decompress(b"".join(iter_tar_gzip(tmp_path)))
+    with tarfile.open(fileobj=io.BytesIO(raw)) as tar:
+        members = {member.name: member for member in tar.getmembers()}
+        # Both names carry their own content, as the CLI's archive does: an
+        # extractor never has to resolve one entry against another.
+        assert members["one.txt"].isreg()
+        assert members["two.txt"].isreg()
+        assert tar.extractfile("two.txt").read() == b"shared\n"
+
+
+def test_a_symlinked_root_is_followed(tmp_path):
+    real = tmp_path / "real"
+    real.mkdir()
+    _tree(real)
+    link = tmp_path / "link"
+    link.symlink_to(real)
+
+    members = _members(list(iter_tar_gzip(link)))
+
+    assert set(members) == {"a.txt", "sub", "sub/b.txt"}
+
+
+def test_producer_failure_reaches_the_consumer(tmp_path):
+    with pytest.raises(FileNotFoundError):
+        list(iter_tar_gzip(tmp_path / "missing"))
+
+
+def test_multi_chunk_archive_round_trips(tmp_path):
+    # Incompressible data well past CHUNK_SIZE, so the sink actually splits the
+    # archive and the chunk boundaries have to land in the right places. Every
+    # other test here fits in a single chunk and never exercises that.
+    payloads = {f"blob{i}.bin": os.urandom(900_000) for i in range(4)}
+    for name, data in payloads.items():
+        (tmp_path / name).write_bytes(data)
+
+    chunks = list(iter_tar_gzip(tmp_path))
+
+    assert len(chunks) > 1
+    assert all(len(chunk) == CHUNK_SIZE for chunk in chunks[:-1])
+    raw = gzip.decompress(b"".join(chunks))
+    with tarfile.open(fileobj=io.BytesIO(raw)) as tar:
+        extracted = {}
+        for member in tar.getmembers():
+            handle = tar.extractfile(member)
+            assert handle is not None
+            extracted[member.name] = handle.read()
+    assert extracted == payloads
+
+
+def test_abandoning_the_archive_stops_the_producer(tmp_path):
+    # Incompressible data larger than the queue holds, so the producer is
+    # parked on a full queue at the moment the consumer walks away.
+    (tmp_path / "big.bin").write_bytes(os.urandom(6 * 1024 * 1024))
+
+    chunks = iter_tar_gzip(tmp_path)
+    next(chunks)
+    chunks.close()
+
+    assert not [t for t in threading.enumerate() if t.name == "render-sdk-sandbox-tar"]
+
+
+@pytest.mark.asyncio
+async def test_cancelling_mid_archive_stops_the_producer(tmp_path):
+    # Big enough that the producer is still working when the cancellation
+    # lands, so the close races an in-flight next().
+    (tmp_path / "big.bin").write_bytes(os.urandom(6 * 1024 * 1024))
+
+    chunks = aiter_tar_gzip(tmp_path)
+    await chunks.__anext__()
+    pending = asyncio.ensure_future(chunks.__anext__())
+    await asyncio.sleep(0.01)
+    pending.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await pending
+
+    # Must not raise ValueError("generator already executing"), which would
+    # mask the cancellation and leave the producer parked.
+    await chunks.aclose()
+
+    assert not [t for t in threading.enumerate() if t.name == "render-sdk-sandbox-tar"]
+
+
+@pytest.mark.asyncio
+async def test_async_archive_matches_the_sync_one(tmp_path):
+    _tree(tmp_path)
+
+    collected = [chunk async for chunk in aiter_tar_gzip(tmp_path)]
+
+    assert set(_members(collected)) == {"a.txt", "sub", "sub/b.txt"}

render/experimental/sandbox/tests/test_types.py

@@ -0,0 +1,57 @@
+from datetime import datetime
+
+from render.client.errors import ClientError, RenderError
+from render.experimental.sandbox.errors import (
+    SandboxExecError,
+    SandboxExecStreamError,
+    SandboxNotFoundError,
+)
+from render.experimental.sandbox.types import (
+    Sandbox,
+    SandboxExecExit,
+    SandboxExecOutput,
+    SandboxList,
+)
+
+
+def test_sandbox_has_expected_fields():
+    sb = Sandbox(
+        id="sbx-1",
+        status="running",
+        plan="starter",
+        network_policy="deny-all",
+        region="oregon",
+        timeout_seconds=7200,
+        created_at=datetime(2026, 7, 17),
+    )
+    assert sb.id == "sbx-1"
+    assert sb.network_policy == "deny-all"
+    assert sb.terminated_at is None
+
+
+def test_sandbox_list_defaults_are_empty():
+    page = SandboxList()
+    assert page.sandboxes == []
+    assert page.next_cursor is None
+
+
+def test_exec_event_shapes():
+    out = SandboxExecOutput(stream="stdout", data="hi\n")
+    done = SandboxExecExit(exit_code=7)
+    assert out.stream == "stdout"
+    assert out.data == "hi\n"
+    assert done.exit_code == 7
+
+
+def test_not_found_is_a_client_error():
+    err = SandboxNotFoundError("missing")
+    assert isinstance(err, ClientError)
+    assert isinstance(err, RenderError)
+
+
+def test_exec_errors_subclass_render_error():
+    stream_err = SandboxExecStreamError(408, "timed out")
+    assert stream_err.status == 408
+    assert stream_err.message == "timed out"
+    assert isinstance(stream_err, RenderError)
+    assert isinstance(SandboxExecError("boom"), RenderError)

render/experimental/sandbox/types.py

@@ -0,0 +1,46 @@
+"""Public return and event types for the sandbox client."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class Sandbox:
+    """A sandbox snapshot returned by create, from_id, and list."""
+
+    id: str
+    status: str
+    plan: str
+    network_policy: str
+    region: str
+    timeout_seconds: int
+    created_at: datetime
+    terminated_at: datetime | None = None
+
+
+@dataclass
+class SandboxList:
+    """A page of sandboxes with an optional pagination cursor."""
+
+    sandboxes: list[Sandbox] = field(default_factory=list)
+    next_cursor: str | None = None
+
+
+@dataclass
+class SandboxExecOutput:
+    """A chunk of stdout or stderr from an exec stream."""
+
+    stream: str
+    data: str
+
+
+@dataclass
+class SandboxExecExit:
+    """The terminal exit event of an exec stream."""
+
+    exit_code: int
+
+
+SandboxExecEvent = SandboxExecOutput | SandboxExecExit

render/public_api/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing Render Public API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

render/public_api/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

render/public_api/api/artifact_sources/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""