deno-sandbox 0.1.0__tar.gz

deno_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.3
+Name: deno-sandbox
+Version: 0.1.0
+Summary: Deno Sandbox Python SDK
+Author: The Deno Team
+Author-email: The Deno Team <support@deno.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: uuid>=1.30
+Requires-Dist: websockets>=15.0.1
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Deno Sandbox Python SDK
+
+Create isolated [sandboxes on Deno Deploy](https://deno.com/deploy/sandboxes) to
+securely run code in a lightweight Linux microVM. You can securely run shell
+scripts, spawn processes, execute JavaScript applications and REPLs, and
+interact with files remotely.
+
+This Python SDK let's you create and manage sandboxes programmatically.
+
+## Installation
+
+```sh
+uv pip install deno-sandbox
+```
+
+## Quick Start
+
+TODO
+
+## License
+
+`MIT`, see the [LICENSE file](./LICENSE)

deno_sandbox-0.1.0/README.md

@@ -0,0 +1,22 @@
+# Deno Sandbox Python SDK
+
+Create isolated [sandboxes on Deno Deploy](https://deno.com/deploy/sandboxes) to
+securely run code in a lightweight Linux microVM. You can securely run shell
+scripts, spawn processes, execute JavaScript applications and REPLs, and
+interact with files remotely.
+
+This Python SDK let's you create and manage sandboxes programmatically.
+
+## Installation
+
+```sh
+uv pip install deno-sandbox
+```
+
+## Quick Start
+
+TODO
+
+## License
+
+`MIT`, see the [LICENSE file](./LICENSE)

deno_sandbox-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "deno-sandbox"
+version = "0.1.0"
+description = "Deno Sandbox Python SDK"
+readme = "README.md"
+authors = [{ name = "The Deno Team", email = "support@deno.com" }]
+requires-python = ">=3.14"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.12.5",
+    "uuid>=1.30",
+    "websockets>=15.0.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.13,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.35.0",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-timeout>=2.4.0",
+    "ruff>=0.14.8",
+]
+
+[tool.pytest.ini_options]
+timeout = 10

deno_sandbox-0.1.0/src/deno_sandbox/__init__.py

@@ -0,0 +1,5 @@
+from deno_sandbox.sandbox import AsyncSandbox
+from deno_sandbox.client import AsyncClient
+from deno_sandbox.options import Options
+
+__all__ = ["AsyncSandbox", "AsyncClient", "Options"]

deno_sandbox-0.1.0/src/deno_sandbox/client.py

@@ -0,0 +1,10 @@
+from deno_sandbox.options import Options, get_internal_options
+from deno_sandbox.sandbox import AsyncSandbox
+from deno_sandbox.volumes import AsyncVolumes
+
+
+class AsyncClient:
+    def __init__(self, options: Options):
+        self._options = get_internal_options(options or Options())
+        self.sandbox = AsyncSandbox(options)
+        self.volumes = AsyncVolumes(options)

deno_sandbox-0.1.0/src/deno_sandbox/console.py

@@ -0,0 +1,41 @@
+import httpx
+from pydantic import HttpUrl
+
+from deno_sandbox.options import Options, get_internal_options
+
+
+class AsyncConsoleClient:
+    def __init__(self, options: Options):
+        self.__options = get_internal_options(options or Options())
+
+    async def post(self, path: str, data: any) -> dict:
+        async with httpx.AsyncClient() as client:
+            req_url = HttpUrl(self.__options.console_url, path=path)
+            headers = {
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.__options.token}",
+            }
+            response = await client.post(req_url, headers=headers, json=data)
+            response.raise_for_status()
+            return await response.json()
+
+    async def get(self, path: str, search: dict | None = None) -> dict:
+        async with httpx.AsyncClient() as client:
+            req_url = HttpUrl(self.__options.console_url, path=path, search=search)
+            headers = {
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.__options.token}",
+            }
+            response = await client.get(req_url, headers=headers)
+            response.raise_for_status()
+            return await response.json()
+
+    async def delete(self, path: str) -> None:
+        async with httpx.AsyncClient() as client:
+            req_url = HttpUrl(self.__options.console_url, path=path)
+            headers = {
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.__options.token}",
+            }
+            response = await client.delete(req_url, headers=headers)
+            response.raise_for_status()

deno_sandbox-0.1.0/src/deno_sandbox/options.py

@@ -0,0 +1,47 @@
+from dataclasses import dataclass
+import os
+
+from urllib.parse import urlparse
+
+from pydantic_core import Url
+
+
+@dataclass(frozen=True)
+class Options:
+    token: str | Url | None = None
+    regions: list[str] | None = None
+
+
+@dataclass
+class InternalOptions:
+    sandbox_ws_url: Url
+    console_url: Url
+    token: Url
+    regions: list[str]
+
+
+def get_internal_options(options: Options) -> InternalOptions:
+    options = options or Options()
+
+    url = urlparse(
+        os.environ.get("DENO_DEPLOY_URL", "https://ams.sandbox-api.deno.net")
+    )
+
+    token = options.token or os.environ.get("DENO_DEPLOY_TOKEN", "")
+
+    scheme = url.scheme.replace("http", "ws")
+    sandbox_ws_url = Url(f"{scheme}://{url.netloc}/api/v2/sandbox/ws?format=json")
+
+    console_url = os.environ.get("DENO_DEPLOY_CONSOLE_URL", "https://console.deno.com")
+    parsed_console_url = urlparse(console_url)
+
+    regions = options.regions or os.environ.get(
+        "DENO_AVAILABLE_REGIONS", "ams1,ord"
+    ).split(",")
+
+    return InternalOptions(
+        console_url=parsed_console_url,
+        sandbox_ws_url=sandbox_ws_url,
+        token=token,
+        regions=regions,
+    )

deno_sandbox-0.1.0/src/deno_sandbox/rpc.py

@@ -0,0 +1,97 @@
+import asyncio
+import base64
+import json
+from typing import Any, Dict, Optional
+from pydantic import BaseModel
+from websockets import ConnectionClosed
+
+from deno_sandbox.transport import Transport
+
+
+class RpcRequest(BaseModel):
+    method: str
+    params: Dict[str, Any]
+    id: int
+    jsonrpc: str = "2.0"
+
+
+class RpcResult[T](BaseModel):
+    ok: Optional[T] = None
+    error: Optional[Any] = None
+
+
+class RpcResponse[T](BaseModel):
+    jsonrpc: str = "2.0"
+    result: Optional[RpcResult[T]] = None
+    error: Dict[str, Any] | None = None
+    id: int
+
+
+class AsyncRpcClient:
+    def __init__(self, transport: Transport):
+        self._transport = transport
+        self._id = 0
+        self._pending_requests: Dict[int, asyncio.Future[Any]] = {}
+        self._listen_task = asyncio.create_task(self._listener())
+        self._pending_processes: Dict[int, asyncio.StreamReader] = {}
+
+    async def close(self):
+        await self._transport.close()
+
+    async def call(self, method: str, params: Dict[str, Any]) -> Any:
+        req_id = self._id + 1
+        self._id = req_id
+
+        payload = RpcRequest(method=method, params=params, id=req_id)
+
+        loop = asyncio.get_running_loop()
+        future = loop.create_future()
+        self._pending_requests[req_id] = future
+
+        await self._transport.send(payload.model_dump_json())
+
+        raw_response = await future
+        response = RpcResponse[Any](**raw_response)
+
+        if response.error:
+            raise Exception(response.error)
+
+        if response.result and response.result.error:
+            raise Exception(f"Application Error: {response.result.error}")
+
+        return response.result.ok if response.result else None
+
+    async def _listener(self) -> None:
+        try:
+            async for raw in self._transport:
+                data = json.loads(raw)
+                req_id = data.get("id")
+
+                if req_id is not None and req_id in self._pending_requests:
+                    future = self._pending_requests.pop(req_id)
+                    if not future.done():
+                        future.set_result(data)
+
+                elif "method" in data:
+                    method = data["method"]
+                    params = data.get("params", {})
+
+                    if method == "$sandbox.stream.enqueue":
+                        stream_id = params.get("streamId")
+                        chunk = base64.b64decode(params.get("data", ""))
+                        stream = self._pending_processes.get(stream_id)
+                        if stream:
+                            stream.feed_data(chunk)
+                    elif method == "$sandbox.stream.end":
+                        stream_id = params.get("streamId")
+                        stream = self._pending_processes.get(stream_id)
+                        if stream:
+                            stream.feed_eof()
+                            del self._pending_processes[stream_id]
+
+        except ConnectionClosed:
+            pass
+        except Exception as e:
+            for future in self._pending_requests.values():
+                if not future.done():
+                    future.set_exception(e)

deno_sandbox-0.1.0/src/deno_sandbox/sandbox.py

@@ -0,0 +1,189 @@
+import asyncio
+from contextlib import asynccontextmanager
+from dataclasses import asdict, dataclass, field
+import json
+from typing import AsyncIterator
+import uuid
+from pydantic import BaseModel, Field
+from typing_extensions import Literal
+
+from deno_sandbox.options import Options, get_internal_options
+from deno_sandbox.rpc import AsyncRpcClient
+from deno_sandbox.sandbox_generated import (
+    Sandbox as GeneratedSandbox,
+    SpawnArgs,
+    SandboxProcess as GeneratedSandboxProcess,
+)
+from deno_sandbox.transport import (
+    Transport,
+    WebSocketTransportFactory,
+)
+
+
+type Mode = Literal["connect", "create"]
+type StdIo = Literal["piped", "null"]
+
+
+@dataclass(frozen=True)
+class SandboxCreateOptions:
+    env: dict[str, str] | None = None
+    """Environment variables to set in the sandbox."""
+    memory_mb: int | None = 1024
+    """Memory limit for the sandbox in megabytes (default: 1024)."""
+    labels: dict[str, str] | None = None
+    """
+    Labels to set on the sandbox. Up to 5 labels can be specified.
+    Each label key must be at most 64 bytes, and each label value must be at most 128 bytes.
+    """
+    volumes: dict[str, str] | None = None
+    """
+    Volumes to mount on the sandbox.
+    The key is the mount path inside the sandbox, and the value is
+    the volume ID or slug
+    """
+
+
+@dataclass(frozen=True)
+class SandboxConnectOptions:
+    id: uuid.UUID
+    """Unique id of the sandbox."""
+
+
+@dataclass
+class SandboxRequestResult:
+    revision_id: str
+
+
+@dataclass
+class SandboxDeployOptions:
+    path: str | None = None
+    entrypoint: str = "main.ts"
+    args: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SandboxInfo:
+    sandboxId: uuid.UUID
+    """The ID of the sandbox."""
+    createdAt: str
+    """The creation time of the sandbox."""
+    region: str
+    """The region where the sandbox is running."""
+
+
+@dataclass
+class AppConfig:
+    sandbox_id: str
+    mode: Mode
+    stop_at_ms: int | None
+    labels: dict[str, str] | None
+    memory_mb: int | None
+
+
+class AsyncSandboxProcess(GeneratedSandboxProcess):
+    async def spawn(self, args: SpawnArgs) -> RemoteProcess:
+        result: SpawnResult = await super().spawn(args)
+        return RemoteProcess(result, self._rpc)
+
+
+class AsyncSandboxHandle(GeneratedSandbox):
+    def __init__(self, rpc: AsyncRpcClient, sandbox_id: str):
+        super().__init__(rpc, sandbox_id)
+        self.process = AsyncSandboxProcess(rpc)
+
+
+class AsyncSandbox:
+    def __init__(
+        self,
+        options: Options | None = None,
+    ):
+        self.__options = get_internal_options(options or Options())
+        self._transport_factory = WebSocketTransportFactory()
+
+    async def _init_transport(self, app_config: AppConfig) -> Transport:
+        transport = self._transport_factory.create_transport()
+
+        headers = {
+            "Authorization": f"Bearer {self.__options.token}",
+            "x-denodeploy-config-v2": json.dumps(asdict(app_config)),
+        }
+
+        await transport.connect(url=self.__options.sandbox_ws_url, headers=headers)
+        return transport
+
+    @asynccontextmanager
+    async def create(
+        self, options: SandboxCreateOptions | None = None
+    ) -> AsyncIterator[AsyncSandboxHandle]:
+        """Creates a new sandbox instance."""
+
+        sandbox_id = str(uuid.uuid4())
+        app_config = AppConfig(
+            sandbox_id=sandbox_id,
+            mode="create",
+            stop_at_ms=None,
+            labels=options.labels if options else None,
+            memory_mb=options.memory_mb if options else None,
+        )
+        transport = await self._init_transport(app_config)
+
+        try:
+            rpc = AsyncRpcClient(transport)
+            yield AsyncSandboxHandle(rpc, sandbox_id)
+        finally:
+            await transport.close()
+
+    @asynccontextmanager
+    async def connect(
+        self, options: SandboxConnectOptions
+    ) -> AsyncIterator[AsyncSandboxHandle]:
+        """Connects to an existing sandbox instance."""
+
+        sandbox_id = str(options.id)
+        app_config = AppConfig(
+            sandbox_id=sandbox_id,
+            mode="connect",
+            stop_at_ms=None,
+            labels=None,
+            memory_mb=None,
+        )
+        transport = await self._init_transport(app_config)
+
+        try:
+            rpc = AsyncRpcClient(transport)
+            yield AsyncSandboxHandle(rpc, sandbox_id)
+        finally:
+            await transport.close()
+
+
+class SpawnResult(BaseModel):
+    pid: int
+    stdout_stream_id: int | None = Field(default=None, alias="stdoutStreamId")
+    stderr_stream_id: int | None = Field(default=None, alias="stderrStreamId")
+
+
+class ProcessExit(BaseModel):
+    code: int
+
+
+class RemoteProcess:
+    def __init__(self, res: SpawnResult, rpc: AsyncRpcClient):
+        self.pid = res.pid
+        self._stdout_stream_id = res.stdout_stream_id
+        self._stderr_stream_id = res.stderr_stream_id
+        self.returncode: int | None = None
+
+        self.stdout = asyncio.StreamReader()
+        self.stderr = asyncio.StreamReader()
+        self._wait_task = asyncio.create_task(
+            rpc.call("processWait", {"pid": self.pid})
+        )
+
+        rpc._pending_processes[self._stdout_stream_id] = self.stdout
+        rpc._pending_processes[self._stderr_stream_id] = self.stderr
+
+    async def wait(self) -> int:
+        raw = await self._wait_task
+        result = ProcessExit.model_validate(raw)
+        self.returncode = result.code
+        return self.returncode