Merge pull request #64 from hyperbrowserai/update-sandbox

update python sdk sandbox

Author: Dingway98

README.md

@@ -100,6 +100,118 @@ def main():
 # Run the asyncio event loop
 main()
 ```
+
+## Sandboxes
+
+The sync and async clients expose the same sandbox APIs through `client.sandboxes`.
+
+### Create a sandbox with pre-exposed ports
+
+```python
+from hyperbrowser import Hyperbrowser
+from hyperbrowser.models import CreateSandboxParams, SandboxExposeParams
+
+client = Hyperbrowser(api_key="test-key")
+sandbox = client.sandboxes.create(
+    CreateSandboxParams(
+        image_name="node",
+        exposed_ports=[SandboxExposeParams(port=3000, auth=True)],
+    )
+)
+
+print(sandbox.exposed_ports[0].browser_url)
+sandbox.stop()
+client.close()
+```
+
+### List sandboxes with filters
+
+```python
+from hyperbrowser import Hyperbrowser
+from hyperbrowser.models import SandboxListParams
+
+client = Hyperbrowser(api_key="test-key")
+result = client.sandboxes.list(
+    SandboxListParams(
+        status="active",
+        search="sandbox",
+        start=1711929600000,
+        end=1712016000000,
+        limit=20,
+    )
+)
+
+for sandbox in result.sandboxes:
+    print(sandbox.id, sandbox.status)
+```
+
+### List snapshots for a specific image
+
+```python
+from hyperbrowser import Hyperbrowser
+from hyperbrowser.models import SandboxSnapshotListParams
+
+client = Hyperbrowser(api_key="test-key")
+snapshots = client.sandboxes.list_snapshots(
+    SandboxSnapshotListParams(image_name="node", status="created", limit=10)
+)
+```
+
+### Expose and unexpose ports
+
+```python
+from hyperbrowser import Hyperbrowser
+from hyperbrowser.models import CreateSandboxParams, SandboxExposeParams
+
+client = Hyperbrowser(api_key="test-key")
+sandbox = client.sandboxes.create(CreateSandboxParams(image_name="node"))
+
+result = sandbox.expose(SandboxExposeParams(port=8080, auth=True))
+print(result.url, result.browser_url)
+
+sandbox.unexpose(8080)
+```
+
+### Batch file writes with per-file options
+
+```python
+from hyperbrowser import Hyperbrowser
+from hyperbrowser.models import CreateSandboxParams, SandboxFileWriteEntry
+
+client = Hyperbrowser(api_key="test-key")
+sandbox = client.sandboxes.create(CreateSandboxParams(image_name="node"))
+
+sandbox.files.write(
+    [
+        SandboxFileWriteEntry(
+            path="/tmp/config.json",
+            data='{"debug":true}\n',
+            append=True,
+            mode="600",
+        ),
+        SandboxFileWriteEntry(
+            path="/tmp/blob.bin",
+            data=b"\x00\x01\x02",
+        ),
+    ]
+)
+```
+
+### Resume terminal output after reconnect
+
+```python
+from hyperbrowser import Hyperbrowser
+from hyperbrowser.models import CreateSandboxParams, SandboxTerminalCreateParams
+
+client = Hyperbrowser(api_key="test-key")
+sandbox = client.sandboxes.create(CreateSandboxParams(image_name="node"))
+terminal = sandbox.terminal.create(SandboxTerminalCreateParams(command="bash"))
+
+connection = terminal.attach(cursor=10)
+for event in connection.events():
+    print(event)
+```
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

hyperbrowser/client/managers/async_manager/sandbox.py

@@ -15,6 +15,7 @@
     SandboxRuntimeSession,
     SandboxSnapshotListParams,
     SandboxSnapshotListResponse,
+    SandboxUnexposeResult,
     StartSandboxFromSnapshotParams,
 )
 from ....models.session import BasicResponse
@@ -113,6 +114,10 @@ def token_expires_at(self):
     def session_url(self) -> str:
         return self._detail.session_url
 
+    @property
+    def exposed_ports(self):
+        return self._detail.exposed_ports
+
     def to_dict(self):
         return self._detail.model_dump()
 
@@ -152,7 +157,27 @@ async def create_memory_snapshot(
     async def expose(self, params: SandboxExposeParams) -> SandboxExposeResult:
         if not isinstance(params, SandboxExposeParams):
             raise TypeError("params must be a SandboxExposeParams instance")
-        return await self._service.expose(self.id, params, runtime=self.runtime)
+        result = await self._service.expose(self.id, params, runtime=self.runtime)
+        exposed_ports = [
+            port for port in self._detail.exposed_ports if port.port != result.port
+        ]
+        exposed_ports.append(result)
+        exposed_ports.sort(key=lambda port: port.port)
+        self._detail = self._detail.model_copy(update={"exposed_ports": exposed_ports})
+        return result
+
+    async def unexpose(self, port: int) -> SandboxUnexposeResult:
+        result = await self._service.unexpose(self.id, port)
+        self._detail = self._detail.model_copy(
+            update={
+                "exposed_ports": [
+                    exposed_port
+                    for exposed_port in self._detail.exposed_ports
+                    if exposed_port.port != port
+                ]
+            }
+        )
+        return result
 
     def get_exposed_url(self, port: int) -> str:
         return _build_sandbox_exposed_url(self.runtime, port)
@@ -372,11 +397,17 @@ async def expose(
             data=params.model_dump(exclude_none=True, by_alias=True),
         )
         target_runtime = runtime or (await self.get_detail(sandbox_id)).runtime
-        return SandboxExposeResult(
-            port=payload["port"],
-            auth=payload["auth"],
-            url=_build_sandbox_exposed_url(target_runtime, payload["port"]),
+        if "url" not in payload:
+            payload["url"] = _build_sandbox_exposed_url(target_runtime, payload["port"])
+        return SandboxExposeResult(**payload)
+
+    async def unexpose(self, sandbox_id: str, port: int) -> SandboxUnexposeResult:
+        payload = await self._request(
+            "POST",
+            f"/sandbox/{sandbox_id}/unexpose",
+            data={"port": port},
         )
+        return SandboxUnexposeResult(**payload)
 
     async def _create_detail(self, params: CreateSandboxParams) -> SandboxDetail:
         payload = await self._request(

hyperbrowser/client/managers/async_manager/sandboxes/sandbox_files.py

@@ -32,6 +32,7 @@
 from .....sandbox_common import build_headers, to_websocket_transport_target
 from ...sandboxes.shared import (
     DEFAULT_WATCH_TIMEOUT_MS,
+    _encode_batch_write_entry,
     _copy_model,
     _encode_write_data,
     _normalize_event_type,
@@ -371,12 +372,7 @@ async def write(
         for entry in path_or_files:
             if not isinstance(entry, SandboxFileWriteEntry):
                 raise TypeError("files must contain SandboxFileWriteEntry instances")
-            encoded_files.append(
-                {
-                    "path": entry.path,
-                    **_encode_write_data(entry.data),
-                }
-            )
+            encoded_files.append(_encode_batch_write_entry(entry))
 
         payload = await self._transport.request_json(
             "/sandbox/files/write",

hyperbrowser/client/managers/async_manager/sandboxes/sandbox_terminal.py

@@ -2,6 +2,7 @@
 import json
 import socket
 from typing import AsyncIterator, Dict, Optional, Union
+from urllib.parse import urlencode
 
 from websockets.asyncio.client import connect as async_ws_connect
 from websockets.exceptions import ConnectionClosed
@@ -160,11 +161,20 @@ async def resize(self, rows: int, cols: int) -> SandboxTerminalStatus:
         self._status = _normalize_terminal_status(payload["pty"])
         return self.current
 
-    async def attach(self) -> SandboxTerminalConnection:
+    async def attach(
+        self,
+        cursor: Optional[int] = None,
+    ) -> SandboxTerminalConnection:
         connection = await self._get_connection_info()
+        query = urlencode(
+            [
+                ("sessionId", connection.sandbox_id),
+                *([("cursor", str(cursor))] if cursor is not None else []),
+            ]
+        )
         target = to_websocket_transport_target(
             connection.base_url,
-            f"/sandbox/pty/{self.id}/ws?sessionId={connection.sandbox_id}",
+            f"/sandbox/pty/{self.id}/ws?{query}",
             self._runtime_proxy_override,
         )
         headers = build_headers(connection.token, host_header=target.host_header)

hyperbrowser/client/managers/sandboxes/shared.py

@@ -7,6 +7,7 @@
 from ....exceptions import HyperbrowserError
 from ....models.sandbox import (
     SandboxFileInfo,
+    SandboxFileWriteEntry,
     SandboxFileWriteInfo,
     SandboxTerminalStatus,
 )
@@ -27,7 +28,7 @@ def _build_sandbox_exposed_url(runtime, port: int) -> str:
     parsed = urlsplit(runtime.base_url)
     hostname = parsed.hostname
     if not hostname:
-        return runtime.base_url.rstrip("/")
+        return runtime.base_url
 
     exposed_host = f"{port}-{hostname}"
     netloc = exposed_host
@@ -39,9 +40,9 @@ def _build_sandbox_exposed_url(runtime, port: int) -> str:
             credentials = f"{credentials}:{parsed.password}"
         netloc = f"{credentials}@{netloc}"
 
-    return urlunsplit(
-        (parsed.scheme, netloc, parsed.path, parsed.query, parsed.fragment)
-    ).rstrip("/")
+    path = parsed.path or "/"
+
+    return urlunsplit((parsed.scheme, netloc, path, parsed.query, parsed.fragment))
 
 
 def _expires_within_buffer(expires_at: Optional[datetime]) -> bool:
@@ -188,6 +189,32 @@ def _encode_write_data(data: Union[str, bytes, bytearray]) -> Dict[str, str]:
     }
 
 
+def _encode_batch_write_entry(entry: SandboxFileWriteEntry) -> Dict[str, object]:
+    if isinstance(entry.data, str):
+        encoding = entry.encoding or "utf8"
+        if encoding not in {"utf8", "base64"}:
+            raise ValueError("encoding should be one of: utf8, base64")
+        payload: Dict[str, object] = {
+            "path": entry.path,
+            "data": entry.data,
+            "encoding": encoding,
+        }
+    else:
+        if entry.encoding not in {None, "base64"}:
+            raise ValueError("encoding must be base64 when data is bytes")
+        payload = {
+            "path": entry.path,
+            "data": base64.b64encode(bytes(entry.data)).decode("ascii"),
+            "encoding": "base64",
+        }
+
+    if entry.append is not None:
+        payload["append"] = entry.append
+    if entry.mode is not None:
+        payload["mode"] = entry.mode
+    return payload
+
+
 def _normalize_terminal_output_chunk(entry: Dict[str, object]) -> Dict[str, object]:
     raw = base64.b64decode(entry["data"])
     return {

hyperbrowser/client/managers/sync_manager/sandbox.py

@@ -15,6 +15,7 @@
     SandboxRuntimeSession,
     SandboxSnapshotListParams,
     SandboxSnapshotListResponse,
+    SandboxUnexposeResult,
     StartSandboxFromSnapshotParams,
 )
 from ....models.session import BasicResponse
@@ -113,6 +114,10 @@ def token_expires_at(self):
     def session_url(self) -> str:
         return self._detail.session_url
 
+    @property
+    def exposed_ports(self):
+        return self._detail.exposed_ports
+
     def to_dict(self):
         return self._detail.model_dump()
 
@@ -152,7 +157,27 @@ def create_memory_snapshot(
     def expose(self, params: SandboxExposeParams) -> SandboxExposeResult:
         if not isinstance(params, SandboxExposeParams):
             raise TypeError("params must be a SandboxExposeParams instance")
-        return self._service.expose(self.id, params, runtime=self.runtime)
+        result = self._service.expose(self.id, params, runtime=self.runtime)
+        exposed_ports = [
+            port for port in self._detail.exposed_ports if port.port != result.port
+        ]
+        exposed_ports.append(result)
+        exposed_ports.sort(key=lambda port: port.port)
+        self._detail = self._detail.model_copy(update={"exposed_ports": exposed_ports})
+        return result
+
+    def unexpose(self, port: int) -> SandboxUnexposeResult:
+        result = self._service.unexpose(self.id, port)
+        self._detail = self._detail.model_copy(
+            update={
+                "exposed_ports": [
+                    exposed_port
+                    for exposed_port in self._detail.exposed_ports
+                    if exposed_port.port != port
+                ]
+            }
+        )
+        return result
 
     def get_exposed_url(self, port: int) -> str:
         return _build_sandbox_exposed_url(self.runtime, port)
@@ -372,11 +397,17 @@ def expose(
             data=params.model_dump(exclude_none=True, by_alias=True),
         )
         target_runtime = runtime or self.get_detail(sandbox_id).runtime
-        return SandboxExposeResult(
-            port=payload["port"],
-            auth=payload["auth"],
-            url=_build_sandbox_exposed_url(target_runtime, payload["port"]),
+        if "url" not in payload:
+            payload["url"] = _build_sandbox_exposed_url(target_runtime, payload["port"])
+        return SandboxExposeResult(**payload)
+
+    def unexpose(self, sandbox_id: str, port: int) -> SandboxUnexposeResult:
+        payload = self._request(
+            "POST",
+            f"/sandbox/{sandbox_id}/unexpose",
+            data={"port": port},
         )
+        return SandboxUnexposeResult(**payload)
 
     def _create_detail(self, params: CreateSandboxParams) -> SandboxDetail:
         payload = self._request(

hyperbrowser/client/managers/sync_manager/sandboxes/sandbox_files.py

@@ -31,6 +31,7 @@
 from .....sandbox_common import build_headers, to_websocket_transport_target
 from ...sandboxes.shared import (
     DEFAULT_WATCH_TIMEOUT_MS,
+    _encode_batch_write_entry,
     _copy_model,
     _encode_write_data,
     _normalize_event_type,
@@ -352,12 +353,7 @@ def write(
         for entry in path_or_files:
             if not isinstance(entry, SandboxFileWriteEntry):
                 raise TypeError("files must contain SandboxFileWriteEntry instances")
-            encoded_files.append(
-                {
-                    "path": entry.path,
-                    **_encode_write_data(entry.data),
-                }
-            )
+            encoded_files.append(_encode_batch_write_entry(entry))
 
         payload = self._transport.request_json(
             "/sandbox/files/write",