flash-sandbox 0.1.0__tar.gz

flash_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: flash-sandbox
+Version: 0.1.0
+Summary: A Python SDK for interacting with the Sandbox Orchestrator.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: grpcio>=1.50.0
+Requires-Dist: protobuf>=4.21.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.50.0; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# Sandbox SDK
+
+A Python SDK for interacting with the Sandbox Orchestrator. Supports both
+**gRPC** and **HTTP** transports with an identical public interface, so you can swap protocols without changing application logic.
+
+## Installation
+
+```bash
+pip install flash-sandbox
+```
+
+The package pulls in `grpcio`, `protobuf`, and `requests` automatically.
+
+## Quick Start
+
+### HTTP transport (recommended for simplicity)
+
+```python
+from flash_sandbox import HTTPClient
+
+client = HTTPClient(host="localhost", port=8080)
+
+# Start a Docker sandbox
+sandbox_id = client.start_sandbox(
+    type="docker",
+    image="alpine:latest",
+    command=["tail", "-f", "/dev/null"],
+    memory_mb=128,
+    cpu_cores=0.5,
+)
+print(f"Sandbox ID: {sandbox_id}")
+
+# Execute a command
+result = client.exec_command(sandbox_id, ["echo", "Hello from HTTP!"])
+print(f"Output: {result.stdout.strip()}")
+print(f"Exit code: {result.exit_code}")
+
+# Check status
+status = client.get_status(sandbox_id)
+print(f"Status: {status}")
+
+# Get resource metrics
+metrics = client.get_metrics(sandbox_id)
+print(f"Memory: {metrics.memory_usage_bytes} / {metrics.memory_limit_bytes}")
+print(f"CPU: {metrics.cpu_percent}%")
+
+# Snapshot and resume
+snap = client.snapshot_sandbox(sandbox_id)
+print(f"Snapshot: {snap['snapshot_path']}")
+client.resume_sandbox(sandbox_id)
+
+# Stop
+client.stop_sandbox(sandbox_id)
+client.close()
+```
+
+### gRPC transport
+
+```python
+from flash_sandbox import SandboxClient
+
+client = SandboxClient(host="localhost", port=50051)
+
+# Start a Docker sandbox
+docker_id = client.start_sandbox(
+    type="docker",
+    image="alpine:latest",
+    command=["tail", "-f", "/dev/null"],
+    memory_mb=128,
+    cpu_cores=0.5,
+)
+print(f"Docker Sandbox ID: {docker_id}")
+
+# Start a Firecracker sandbox
+fc_id = client.start_sandbox(
+    type="firecracker",
+    image="alpine:latest",
+    command=["tail", "-f", "/dev/null"],
+    memory_mb=512,
+    cpu_cores=1.0,
+)
+print(f"Firecracker Sandbox ID: {fc_id}")
+
+# Start a gVisor sandbox
+gvisor_id = client.start_sandbox(
+    type="gvisor",
+    image="alpine:latest",
+    command=["tail", "-f", "/dev/null"],
+    memory_mb=256,
+    cpu_cores=1.0,
+)
+print(f"gVisor Sandbox ID: {gvisor_id}")
+
+# Check status
+status = client.get_status(fc_id)
+print(f"Firecracker Status: {status}")
+
+# Snapshot and Resume
+snap_res = client.snapshot_sandbox(fc_id)
+print(f"Snapshot Data: {snap_res}")
+client.resume_sandbox(fc_id)
+
+# Execute commands
+exec_res = client.exec_command(gvisor_id, ["echo", "Hello from gVisor!"])
+print(f"gVisor Output: {exec_res.stdout.strip()}")
+print(f"gVisor Exit Code: {exec_res.exit_code}")
+
+# Stop sandboxes
+client.stop_sandbox(docker_id)
+client.stop_sandbox(fc_id)
+client.stop_sandbox(gvisor_id)
+client.close()
+```
+
+## API Reference
+
+Both `HTTPClient` and `SandboxClient` expose the same set of methods:
+
+| Method | Description |
+|---|---|
+| `start_sandbox(type, image, command, memory_mb, cpu_cores, ...)` | Start a new sandbox and return its ID. |
+| `stop_sandbox(sandbox_id)` | Stop and remove a running sandbox. |
+| `exec_command(sandbox_id, command)` | Execute a command in a sandbox. Returns an object with `stdout`, `stderr`, and `exit_code`. |
+| `get_status(sandbox_id)` | Return the status string (`"running"`, `"stopped"`, etc.). |
+| `get_metrics(sandbox_id)` | Return point-in-time resource-usage metrics (memory, CPU, network, block I/O). |
+| `snapshot_sandbox(sandbox_id)` | Create a snapshot. Returns `{"snapshot_path": ..., "mem_file_path": ...}`. |
+| `resume_sandbox(sandbox_id)` | Resume a paused / snapshotted sandbox. |
+| `close()` | Release the underlying connection / session. |
+
+### Constructor options
+
+#### HTTPClient
+
+```python
+HTTPClient(
+    host="localhost",       # Orchestrator hostname
+    port=8080,              # HTTP port (default 8080)
+    address=None,           # Full URL, overrides host/port (e.g. "http://proxy:9090/v1/service/sandbox")
+    timeout=30.0,           # Request timeout in seconds (None = no timeout)
+    session=None,           # Optional requests.Session for custom TLS / auth / retries
+)
+```
+
+#### SandboxClient (gRPC)
+
+```python
+SandboxClient(
+    host="localhost",       # Orchestrator hostname
+    port=50051,             # gRPC port (default 50051)
+    address=None,           # Full address for proxy routing (e.g. "localhost:8092/v1/service/sandbox")
+)
+```
+
+### HTTPClient-only extras
+
+The HTTP transport includes a few additional features:
+
+- **Firecracker fields** on `start_sandbox`: `kernel_image`, `initrd_path`, `snapshot_path`, `mem_file_path`.
+- **Custom timeouts** per-client via the `timeout` parameter.
+- **Session injection** – pass your own `requests.Session` for connection pooling, mutual TLS, retry policies, or authentication headers.
+- **Typed exceptions**: `SandboxHTTPError` (with `.status_code` and `.detail`) and the more specific `SandboxNotFoundError` for 404 responses.
+
+### Response types (HTTP client)
+
+| Class | Fields |
+|---|---|
+| `ExecResult` | `stdout: str`, `stderr: str`, `exit_code: int` |
+| `MetricsResult` | `memory_usage_bytes`, `memory_limit_bytes`, `memory_percent`, `cpu_percent`, `pids_current`, `net_rx_bytes`, `net_tx_bytes`, `block_read_bytes`, `block_write_bytes` |
+| `SnapshotResult` | `snapshot_path: str`, `mem_file_path: str` |
+
+All response dataclasses are **frozen** (immutable).
+
+## Context manager
+
+Both clients support the context-manager protocol:
+
+```python
+from flash_sandbox import HTTPClient
+
+with HTTPClient(host="localhost") as client:
+    sid = client.start_sandbox(type="docker", image="alpine:latest")
+    client.stop_sandbox(sid)
+# Connection is automatically closed here.
+```
+
+## Proxy / reverse-proxy support
+
+Both clients support routing through a reverse proxy that uses path-based
+routing. Pass the full address including the path prefix:
+
+```python
+# HTTP through a proxy
+http_client = HTTPClient(address="http://proxy.example.com:8092/v1/service/sandbox")
+
+# gRPC through a proxy
+grpc_client = SandboxClient(address="proxy.example.com:8092/v1/service/sandbox")
+```
+
+## Running tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+```

flash_sandbox-0.1.0/README.md

@@ -0,0 +1,204 @@
+# Sandbox SDK
+
+A Python SDK for interacting with the Sandbox Orchestrator. Supports both
+**gRPC** and **HTTP** transports with an identical public interface, so you can swap protocols without changing application logic.
+
+## Installation
+
+```bash
+pip install flash-sandbox
+```
+
+The package pulls in `grpcio`, `protobuf`, and `requests` automatically.
+
+## Quick Start
+
+### HTTP transport (recommended for simplicity)
+
+```python
+from flash_sandbox import HTTPClient
+
+client = HTTPClient(host="localhost", port=8080)
+
+# Start a Docker sandbox
+sandbox_id = client.start_sandbox(
+    type="docker",
+    image="alpine:latest",
+    command=["tail", "-f", "/dev/null"],
+    memory_mb=128,
+    cpu_cores=0.5,
+)
+print(f"Sandbox ID: {sandbox_id}")
+
+# Execute a command
+result = client.exec_command(sandbox_id, ["echo", "Hello from HTTP!"])
+print(f"Output: {result.stdout.strip()}")
+print(f"Exit code: {result.exit_code}")
+
+# Check status
+status = client.get_status(sandbox_id)
+print(f"Status: {status}")
+
+# Get resource metrics
+metrics = client.get_metrics(sandbox_id)
+print(f"Memory: {metrics.memory_usage_bytes} / {metrics.memory_limit_bytes}")
+print(f"CPU: {metrics.cpu_percent}%")
+
+# Snapshot and resume
+snap = client.snapshot_sandbox(sandbox_id)
+print(f"Snapshot: {snap['snapshot_path']}")
+client.resume_sandbox(sandbox_id)
+
+# Stop
+client.stop_sandbox(sandbox_id)
+client.close()
+```
+
+### gRPC transport
+
+```python
+from flash_sandbox import SandboxClient
+
+client = SandboxClient(host="localhost", port=50051)
+
+# Start a Docker sandbox
+docker_id = client.start_sandbox(
+    type="docker",
+    image="alpine:latest",
+    command=["tail", "-f", "/dev/null"],
+    memory_mb=128,
+    cpu_cores=0.5,
+)
+print(f"Docker Sandbox ID: {docker_id}")
+
+# Start a Firecracker sandbox
+fc_id = client.start_sandbox(
+    type="firecracker",
+    image="alpine:latest",
+    command=["tail", "-f", "/dev/null"],
+    memory_mb=512,
+    cpu_cores=1.0,
+)
+print(f"Firecracker Sandbox ID: {fc_id}")
+
+# Start a gVisor sandbox
+gvisor_id = client.start_sandbox(
+    type="gvisor",
+    image="alpine:latest",
+    command=["tail", "-f", "/dev/null"],
+    memory_mb=256,
+    cpu_cores=1.0,
+)
+print(f"gVisor Sandbox ID: {gvisor_id}")
+
+# Check status
+status = client.get_status(fc_id)
+print(f"Firecracker Status: {status}")
+
+# Snapshot and Resume
+snap_res = client.snapshot_sandbox(fc_id)
+print(f"Snapshot Data: {snap_res}")
+client.resume_sandbox(fc_id)
+
+# Execute commands
+exec_res = client.exec_command(gvisor_id, ["echo", "Hello from gVisor!"])
+print(f"gVisor Output: {exec_res.stdout.strip()}")
+print(f"gVisor Exit Code: {exec_res.exit_code}")
+
+# Stop sandboxes
+client.stop_sandbox(docker_id)
+client.stop_sandbox(fc_id)
+client.stop_sandbox(gvisor_id)
+client.close()
+```
+
+## API Reference
+
+Both `HTTPClient` and `SandboxClient` expose the same set of methods:
+
+| Method | Description |
+|---|---|
+| `start_sandbox(type, image, command, memory_mb, cpu_cores, ...)` | Start a new sandbox and return its ID. |
+| `stop_sandbox(sandbox_id)` | Stop and remove a running sandbox. |
+| `exec_command(sandbox_id, command)` | Execute a command in a sandbox. Returns an object with `stdout`, `stderr`, and `exit_code`. |
+| `get_status(sandbox_id)` | Return the status string (`"running"`, `"stopped"`, etc.). |
+| `get_metrics(sandbox_id)` | Return point-in-time resource-usage metrics (memory, CPU, network, block I/O). |
+| `snapshot_sandbox(sandbox_id)` | Create a snapshot. Returns `{"snapshot_path": ..., "mem_file_path": ...}`. |
+| `resume_sandbox(sandbox_id)` | Resume a paused / snapshotted sandbox. |
+| `close()` | Release the underlying connection / session. |
+
+### Constructor options
+
+#### HTTPClient
+
+```python
+HTTPClient(
+    host="localhost",       # Orchestrator hostname
+    port=8080,              # HTTP port (default 8080)
+    address=None,           # Full URL, overrides host/port (e.g. "http://proxy:9090/v1/service/sandbox")
+    timeout=30.0,           # Request timeout in seconds (None = no timeout)
+    session=None,           # Optional requests.Session for custom TLS / auth / retries
+)
+```
+
+#### SandboxClient (gRPC)
+
+```python
+SandboxClient(
+    host="localhost",       # Orchestrator hostname
+    port=50051,             # gRPC port (default 50051)
+    address=None,           # Full address for proxy routing (e.g. "localhost:8092/v1/service/sandbox")
+)
+```
+
+### HTTPClient-only extras
+
+The HTTP transport includes a few additional features:
+
+- **Firecracker fields** on `start_sandbox`: `kernel_image`, `initrd_path`, `snapshot_path`, `mem_file_path`.
+- **Custom timeouts** per-client via the `timeout` parameter.
+- **Session injection** – pass your own `requests.Session` for connection pooling, mutual TLS, retry policies, or authentication headers.
+- **Typed exceptions**: `SandboxHTTPError` (with `.status_code` and `.detail`) and the more specific `SandboxNotFoundError` for 404 responses.
+
+### Response types (HTTP client)
+
+| Class | Fields |
+|---|---|
+| `ExecResult` | `stdout: str`, `stderr: str`, `exit_code: int` |
+| `MetricsResult` | `memory_usage_bytes`, `memory_limit_bytes`, `memory_percent`, `cpu_percent`, `pids_current`, `net_rx_bytes`, `net_tx_bytes`, `block_read_bytes`, `block_write_bytes` |
+| `SnapshotResult` | `snapshot_path: str`, `mem_file_path: str` |
+
+All response dataclasses are **frozen** (immutable).
+
+## Context manager
+
+Both clients support the context-manager protocol:
+
+```python
+from flash_sandbox import HTTPClient
+
+with HTTPClient(host="localhost") as client:
+    sid = client.start_sandbox(type="docker", image="alpine:latest")
+    client.stop_sandbox(sid)
+# Connection is automatically closed here.
+```
+
+## Proxy / reverse-proxy support
+
+Both clients support routing through a reverse proxy that uses path-based
+routing. Pass the full address including the path prefix:
+
+```python
+# HTTP through a proxy
+http_client = HTTPClient(address="http://proxy.example.com:8092/v1/service/sandbox")
+
+# gRPC through a proxy
+grpc_client = SandboxClient(address="proxy.example.com:8092/v1/service/sandbox")
+```
+
+## Running tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+```

flash_sandbox-0.1.0/flash_sandbox/__init__.py

@@ -0,0 +1,12 @@
+from .client import SandboxClient
+from .http_client import HTTPClient, ExecResult, MetricsResult, SnapshotResult, SandboxHTTPError, SandboxNotFoundError
+
+__all__ = [
+    "SandboxClient",
+    "HTTPClient",
+    "ExecResult",
+    "MetricsResult",
+    "SnapshotResult",
+    "SandboxHTTPError",
+    "SandboxNotFoundError",
+]

flash_sandbox-0.1.0/flash_sandbox/client.py

@@ -0,0 +1,220 @@
+import grpc
+from typing import List, Optional
+from urllib.parse import urlparse
+
+from .proto import sandbox_pb2
+from .proto import sandbox_pb2_grpc
+
+
+class _OCFProxyInterceptor(
+    grpc.UnaryUnaryClientInterceptor,
+    grpc.UnaryStreamClientInterceptor,
+    grpc.StreamUnaryClientInterceptor,
+    grpc.StreamStreamClientInterceptor,
+):
+    """Interceptor that prepends an OCF proxy path prefix to gRPC method paths.
+
+    Python's grpc library does NOT include the URL path portion of the channel
+    target in the HTTP/2 :path pseudo-header.  It always sends
+    :path = /package.Service/Method.  The OCF proxy needs the full path
+    (e.g. /v1/service/sandbox/package.Service/Method) to route the request.
+    This interceptor rewrites every outgoing RPC's method string to include
+    the prefix.
+    """
+
+    def __init__(self, path_prefix: str):
+        # Ensure the prefix starts with / and does not end with /
+        self._prefix = "/" + path_prefix.strip("/")
+
+    def _rewrite(self, client_call_details):
+        """Return a new ClientCallDetails with the rewritten method path."""
+        new_method = self._prefix + client_call_details.method
+        return _new_client_call_details(client_call_details, new_method)
+
+    def intercept_unary_unary(self, continuation, client_call_details, request):
+        return continuation(self._rewrite(client_call_details), request)
+
+    def intercept_unary_stream(self, continuation, client_call_details, request):
+        return continuation(self._rewrite(client_call_details), request)
+
+    def intercept_stream_unary(self, continuation, client_call_details, request_iterator):
+        return continuation(self._rewrite(client_call_details), request_iterator)
+
+    def intercept_stream_stream(self, continuation, client_call_details, request_iterator):
+        return continuation(self._rewrite(client_call_details), request_iterator)
+
+
+class _ClientCallDetails(
+    grpc.ClientCallDetails,
+):
+    """Concrete implementation of ClientCallDetails for rewriting."""
+
+    def __init__(self, method, timeout, metadata, credentials, wait_for_ready, compression):
+        self.method = method
+        self.timeout = timeout
+        self.metadata = metadata
+        self.credentials = credentials
+        self.wait_for_ready = wait_for_ready
+        self.compression = compression
+
+
+def _new_client_call_details(original, new_method):
+    return _ClientCallDetails(
+        method=new_method,
+        timeout=original.timeout,
+        metadata=original.metadata,
+        credentials=original.credentials,
+        wait_for_ready=original.wait_for_ready,
+        compression=original.compression,
+    )
+
+
+class SandboxClient:
+    """Client for interacting with the Agent Sandbox Orchestrator via gRPC."""
+
+    def __init__(self, host: Optional[str] = None, port: int = 50051, address: Optional[str] = None):
+        """
+        Initialize the SandboxClient.
+
+        Args:
+            host: The hostname or IP address of the orchestrator.
+            port: The port number of the orchestrator gRPC service.
+            address: Full address for proxy-based routing (e.g.
+                     ``localhost:8092/v1/service/sandbox``).  The path portion
+                     is extracted and prepended to each gRPC method via an
+                     interceptor so the OCF proxy can route the request.
+                     Overrides *host* and *port*.
+        """
+        if address:
+            # Strip scheme if the user passed one — gRPC channels don't use schemes.
+            addr = address
+            for scheme in ("http://", "https://"):
+                if addr.startswith(scheme):
+                    addr = addr[len(scheme):]
+                    break
+            # Split "host:port/path..." into the channel target and the proxy path.
+            # urlparse needs a scheme, so we add one temporarily.
+            parsed = urlparse(f"http://{addr}")
+            channel_target = f"{parsed.hostname}:{parsed.port or 80}"
+            proxy_path = parsed.path  # e.g. "/v1/service/sandbox"
+        elif host:
+            channel_target = f"{host}:{port}"
+            proxy_path = ""
+        else:
+            raise ValueError("Must provide either an address or a host")
+
+        self.address = channel_target
+        self.channel = grpc.insecure_channel(channel_target)
+
+        if proxy_path and proxy_path != "/":
+            interceptor = _OCFProxyInterceptor(proxy_path)
+            self.channel = grpc.intercept_channel(self.channel, interceptor)
+
+        self.stub = sandbox_pb2_grpc.SandboxServiceStub(self.channel)
+
+    def close(self):
+        """Close the gRPC channel."""
+        self.channel.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+
+    def start_sandbox(
+        self,
+        type: str,
+        image: str,
+        command: Optional[List[str]] = None,
+        memory_mb: int = 512,
+        cpu_cores: float = 1.0,
+    ) -> str:
+        """
+        Start a new sandbox.
+
+        Args:
+            type: The type of sandbox (e.g., "docker", "firecracker").
+            image: The image to use for the sandbox.
+            command: The command to run in the sandbox.
+            memory_mb: Memory limit in MB.
+            cpu_cores: CPU cores limit.
+
+        Returns:
+            The ID of the started sandbox.
+        """
+        request = sandbox_pb2.StartRequest(
+            type=type,
+            image=image,
+            command=command or [],
+            memory_mb=memory_mb,
+            cpu_cores=cpu_cores,
+        )
+        response = self.stub.StartSandbox(request)
+        return response.id
+
+    def stop_sandbox(self, sandbox_id: str) -> None:
+        """
+        Stop a running sandbox.
+
+        Args:
+            sandbox_id: The ID of the sandbox to stop.
+        """
+        request = sandbox_pb2.StopRequest(id=sandbox_id)
+        self.stub.StopSandbox(request)
+
+    def exec_command(self, sandbox_id: str, command: List[str]) -> sandbox_pb2.ExecResponse:
+        """
+        Execute a command in a running sandbox.
+
+        Args:
+            sandbox_id: The ID of the sandbox.
+            command: The command to execute.
+
+        Returns:
+            The execution response containing stdout, stderr, and exit code.
+        """
+        request = sandbox_pb2.ExecRequest(id=sandbox_id, command=command)
+        return self.stub.ExecCommand(request)
+
+    def get_status(self, sandbox_id: str) -> str:
+        """
+        Get the status of a sandbox.
+
+        Args:
+            sandbox_id: The ID of the sandbox.
+
+        Returns:
+            The status of the sandbox (e.g., "running", "stopped").
+        """
+        request = sandbox_pb2.StatusRequest(id=sandbox_id)
+        response = self.stub.GetStatus(request)
+        return response.status
+
+    def snapshot_sandbox(self, sandbox_id: str) -> dict:
+        """
+        Snapshot a running sandbox.
+
+        Args:
+            sandbox_id: The ID of the sandbox to snapshot.
+
+        Returns:
+            A dictionary containing the paths to the snapshot file and memory file.
+        """
+        request = sandbox_pb2.SnapshotRequest(id=sandbox_id)
+        response = self.stub.SnapshotSandbox(request)
+        return {
+            "snapshot_path": response.snapshot_path,
+            "mem_file_path": response.mem_file_path,
+        }
+
+    def resume_sandbox(self, sandbox_id: str) -> None:
+        """
+        Resume a paused or snapshotted sandbox.
+
+        Args:
+            sandbox_id: The ID of the sandbox to resume.
+        """
+        request = sandbox_pb2.ResumeRequest(id=sandbox_id)
+        self.stub.ResumeSandbox(request)
+