hyperbrowser 1.6.0__tar.gz → 1.7.0__tar.gz

{hyperbrowser-1.6.0 → hyperbrowser-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperbrowser
-Version: 1.6.0
+Version: 1.7.0
 Summary: Python SDK for hyperbrowser
 License: MIT
 License-File: LICENSE
@@ -323,6 +323,49 @@ sandbox.files.write(
 )
 ```
 
+### Run commands and collect output
+
+`sandbox.exec()` and `sandbox.processes.start()` stream command output from the
+receiver as soon as execution starts. The SDK collects stdout and stderr in
+memory, so a completed result is not limited to the receiver's replay buffer.
+This requires a receiver supporting streaming `POST /sandbox/processes`; roll
+out the receiver before upgrading the SDK.
+
+```python
+result = sandbox.exec("make test", max_output_bytes=128 * 1024 * 1024)
+print(result.stdout, result.stderr, result.exit_code)
+
+process = sandbox.processes.start("make test")
+try:
+    for event in process.stream():
+        if event.type == "stdout":
+            print(event.data, end="")
+    result = process.wait()
+finally:
+    process.disconnect()
+```
+
+The combined output limit defaults to 64 MiB per command and can be adjusted
+with `max_output_bytes`. Exceeding it raises `output_limit_exceeded`. A broken
+stream, missing output, or receiver truncation raises `incomplete_output`.
+These errors include the process ID and do not automatically rerun the command.
+
+Process streams use a separate 60-second read-idle timeout once response headers
+arrive. Output and the receiver's 15-second heartbeats reset this timeout, so quiet
+commands can run longer than the client's ordinary HTTP timeout. That ordinary
+timeout still applies to connection setup and waiting for response headers.
+
+`start()` returns after the process starts and collects in the background.
+`wait(timeout_sec=...)` limits the local wait; collection continues after a wait
+timeout. The timeout passed to `start()` or `exec()` limits command execution.
+A local wait timeout raises `TimeoutError` (`asyncio.TimeoutError` in the async API).
+`disconnect()` stops collection and leaves the command running. Use `kill()` to
+stop it. Reattaching with `get()` can retrieve only retained receiver output;
+`wait()` raises if that output has been truncated.
+
+The async API has the same behavior: await `exec()`, `start()`, `wait()`, and
+`disconnect()`, and use `async for` with `stream()`.
+
 ### Resume terminal output after reconnect
 
 ```python

{hyperbrowser-1.6.0 → hyperbrowser-1.7.0}/README.md

@@ -295,6 +295,49 @@ sandbox.files.write(
 )
 ```
 
+### Run commands and collect output
+
+`sandbox.exec()` and `sandbox.processes.start()` stream command output from the
+receiver as soon as execution starts. The SDK collects stdout and stderr in
+memory, so a completed result is not limited to the receiver's replay buffer.
+This requires a receiver supporting streaming `POST /sandbox/processes`; roll
+out the receiver before upgrading the SDK.
+
+```python
+result = sandbox.exec("make test", max_output_bytes=128 * 1024 * 1024)
+print(result.stdout, result.stderr, result.exit_code)
+
+process = sandbox.processes.start("make test")
+try:
+    for event in process.stream():
+        if event.type == "stdout":
+            print(event.data, end="")
+    result = process.wait()
+finally:
+    process.disconnect()
+```
+
+The combined output limit defaults to 64 MiB per command and can be adjusted
+with `max_output_bytes`. Exceeding it raises `output_limit_exceeded`. A broken
+stream, missing output, or receiver truncation raises `incomplete_output`.
+These errors include the process ID and do not automatically rerun the command.
+
+Process streams use a separate 60-second read-idle timeout once response headers
+arrive. Output and the receiver's 15-second heartbeats reset this timeout, so quiet
+commands can run longer than the client's ordinary HTTP timeout. That ordinary
+timeout still applies to connection setup and waiting for response headers.
+
+`start()` returns after the process starts and collects in the background.
+`wait(timeout_sec=...)` limits the local wait; collection continues after a wait
+timeout. The timeout passed to `start()` or `exec()` limits command execution.
+A local wait timeout raises `TimeoutError` (`asyncio.TimeoutError` in the async API).
+`disconnect()` stops collection and leaves the command running. Use `kill()` to
+stop it. Reattaching with `get()` can retrieve only retained receiver output;
+`wait()` raises if that output has been truncated.
+
+The async API has the same behavior: await `exec()`, `start()`, `wait()`, and
+`disconnect()`, and use `async for` with `stream()`.
+
 ### Resume terminal output after reconnect
 
 ```python

{hyperbrowser-1.6.0 → hyperbrowser-1.7.0}/hyperbrowser/client/managers/async_manager/sandbox.py

@@ -307,6 +307,7 @@ class SandboxHandle:
         timeout_ms: Optional[int] = None,
         timeout_sec: Optional[int] = None,
         run_as: Optional[str] = None,
+        max_output_bytes: int = 64 * 1024 * 1024,
     ):
         return await self.processes.exec(
             input,
@@ -315,6 +316,7 @@ class SandboxHandle:
             timeout_ms=timeout_ms,
             timeout_sec=timeout_sec,
             run_as=run_as,
+            max_output_bytes=max_output_bytes,
         )
 
     async def get_process(self, process_id: str) -> SandboxProcessHandle:

{hyperbrowser-1.6.0 → hyperbrowser-1.7.0}/hyperbrowser/client/managers/async_manager/sandboxes/sandbox_processes.py

@@ -1,3 +1,4 @@
+import asyncio
 import base64
 from typing import AsyncIterator, Dict, Optional, Union
 
@@ -16,6 +17,11 @@ from .....types import (
     SandboxProcessStdinParams as SandboxProcessStdinParamsDict,
 )
 from ...sandboxes.shared import _normalize_exec_params
+from ...sandboxes.process_output import (
+    DEFAULT_MAX_PROCESS_OUTPUT_BYTES,
+    ProcessOutput,
+    validate_output_limit,
+)
 from .sandbox_transport import RuntimeTransport
 
 DEFAULT_PROCESS_KILL_WAIT_SECONDS = 5.0
@@ -25,6 +31,10 @@ class SandboxProcessHandle:
     def __init__(self, transport: RuntimeTransport, summary: SandboxProcessSummary):
         self._transport = transport
         self._summary = summary
+        self._output = None
+        self._collector = None
+        self._events = None
+        self._changed = asyncio.Event()
 
     @property
     def id(self) -> str:
@@ -50,6 +60,15 @@ class SandboxProcessHandle:
         timeout_ms: Optional[int] = None,
         timeout_sec: Optional[int] = None,
     ) -> SandboxProcessResult:
+        if self._collector is not None:
+            timeout = None
+            if timeout_sec is not None and timeout_sec > 0:
+                timeout = timeout_sec
+            elif timeout_ms is not None and timeout_ms > 0:
+                timeout = timeout_ms / 1000
+            if not self._collector.done():
+                await asyncio.wait_for(asyncio.shield(self._collector), timeout)
+            return self._collected_result()
         payload = await self._transport.request_json(
             f"/sandbox/processes/{self.id}/wait",
             method="POST",
@@ -60,6 +79,10 @@ class SandboxProcessHandle:
             headers={"content-type": "application/json"},
         )
         result = SandboxProcessResult(**payload["result"])
+        if result.output_truncated:
+            raise ProcessOutput(self.id, 0).failure(
+                "Retained process output is incomplete; collect output from process start"
+            )
         self._summary = SandboxProcessSummary(
             id=result.id,
             status=result.status,
@@ -133,6 +156,21 @@ class SandboxProcessHandle:
         )
 
     async def stream(self, from_seq: Optional[int] = None) -> AsyncIterator[object]:
+        if self._output is not None:
+            index = 0
+            while True:
+                self._changed.clear()
+                while index < len(self._output.events):
+                    event = self._output.events[index]
+                    index += 1
+                    if from_seq is None or event.seq >= from_seq:
+                        yield event
+                if self._collector.done():
+                    yield SandboxProcessExitEvent(
+                        type="exit", result=self._collected_result()
+                    )
+                    return
+                await self._changed.wait()
         params = {"from_seq": from_seq} if from_seq and from_seq > 0 else None
         async for event in self._transport.stream_sse(
             f"/sandbox/processes/{self.id}/stream",
@@ -153,6 +191,70 @@ class SandboxProcessHandle:
                     result=SandboxProcessResult(**data),
                 )
 
+    def _collected_result(self) -> SandboxProcessResult:
+        if self._output.error is not None:
+            raise self._output.error
+        if self._output.result is None:
+            raise self._output.failure(
+                "Command stream ended before its completion event"
+            )
+        result = self._output.result
+        self._summary = self._summary.model_copy(
+            update={
+                "status": result.status,
+                "exit_code": result.exit_code,
+                "completed_at": result.completed_at,
+            }
+        )
+        return result
+
+    async def _collect(self) -> None:
+        try:
+            async for event in self._events:
+                self._output.consume(event)
+                self._changed.set()
+                if self._output.result is not None:
+                    return
+            self._output.error = self._output.failure(
+                "Command stream ended before its completion event"
+            )
+        except asyncio.CancelledError:
+            if self._output.result is None:
+                self._output.error = self._output.failure(
+                    "Command output collection disconnected"
+                )
+        except Exception as error:
+            self._output.error = (
+                self._output.failure(str(error))
+                if not hasattr(error, "code")
+                else error
+            )
+        finally:
+            try:
+                await self._events.aclose()
+            except Exception as error:
+                if self._output.result is None and self._output.error is None:
+                    self._output.error = self._output.failure(str(error))
+            finally:
+                self._changed.set()
+
+    async def disconnect(self) -> None:
+        """Stop collecting output; the detached command continues running."""
+        if self._collector is not None and not self._collector.done():
+            if self._output.result is None and self._output.error is None:
+                self._output.error = self._output.failure(
+                    "Command output collection disconnected"
+                )
+            self._collector.cancel()
+            try:
+                await self._collector
+            except asyncio.CancelledError:
+                pass
+            finally:
+                # Cancellation may happen before the collector gets its first turn.
+                await self._events.aclose()
+                self._changed.set()
+
     async def result(self) -> SandboxProcessResult:
         return await self.wait()
 
@@ -170,22 +272,21 @@ class SandboxProcessesApi:
         timeout_ms: Optional[int] = None,
         timeout_sec: Optional[int] = None,
         run_as: Optional[str] = None,
+        max_output_bytes: int = DEFAULT_MAX_PROCESS_OUTPUT_BYTES,
     ) -> SandboxProcessResult:
-        params = _normalize_exec_params(
+        handle = await self.start(
             input,
             cwd=cwd,
             env=env,
             timeout_ms=timeout_ms,
             timeout_sec=timeout_sec,
             run_as=run_as,
+            max_output_bytes=max_output_bytes,
         )
-        payload = await self._transport.request_json(
-            "/sandbox/exec",
-            method="POST",
-            json_body=dump_request(params, SandboxExecParams),
-            headers={"content-type": "application/json"},
-        )
-        return SandboxProcessResult(**payload["result"])
+        try:
+            return await handle.wait()
+        finally:
+            await handle.disconnect()
 
     async def start(
         self,
@@ -196,7 +297,9 @@ class SandboxProcessesApi:
         timeout_ms: Optional[int] = None,
         timeout_sec: Optional[int] = None,
         run_as: Optional[str] = None,
+        max_output_bytes: int = DEFAULT_MAX_PROCESS_OUTPUT_BYTES,
     ) -> SandboxProcessHandle:
+        validate_output_limit(max_output_bytes)
         params = _normalize_exec_params(
             input,
             cwd=cwd,
@@ -205,16 +308,25 @@ class SandboxProcessesApi:
             timeout_sec=timeout_sec,
             run_as=run_as,
         )
-        payload = await self._transport.request_json(
+        events = self._transport.stream_sse(
             "/sandbox/processes",
             method="POST",
             json_body=dump_request(params, SandboxExecParams),
-            headers={"content-type": "application/json"},
-        )
-        return SandboxProcessHandle(
-            self._transport,
-            SandboxProcessSummary(**payload["process"]),
         )
+        try:
+            started = await events.__anext__()
+            if started["event"] != "started":
+                raise RuntimeError("Expected process start event")
+            handle = SandboxProcessHandle(
+                self._transport, SandboxProcessSummary(**started["data"])
+            )
+        except BaseException:
+            await events.aclose()
+            raise
+        handle._events = events
+        handle._output = ProcessOutput(handle.id, max_output_bytes)
+        handle._collector = asyncio.create_task(handle._collect())
+        return handle
 
     async def get(self, process_id: str) -> SandboxProcessHandle:
         payload = await self._transport.request_json(f"/sandbox/processes/{process_id}")

{hyperbrowser-1.6.0 → hyperbrowser-1.7.0}/hyperbrowser/client/managers/async_manager/sandboxes/sandbox_transport.py

@@ -3,6 +3,7 @@ from typing import Any, AsyncIterator, Dict, Optional
 
 import httpx
 
+from .....exceptions import HyperbrowserError
 from .....sandbox_common import (
     RuntimeConnection,
     build_headers,
@@ -12,7 +13,11 @@ from .....sandbox_common import (
     request_context,
     resolve_runtime_transport_target,
 )
-from ...sandboxes.shared import _build_query_path, _is_replayable_http_content
+from ...sandboxes.shared import (
+    PROCESS_STREAM_IDLE_TIMEOUT_SECONDS,
+    _build_query_path,
+    _is_replayable_http_content,
+)
 
 
 class RuntimeTransport:
@@ -83,9 +88,16 @@ class RuntimeTransport:
             await client.aclose()
 
     async def stream_sse(
-        self, path: str, params: Optional[Dict[str, object]] = None
+        self,
+        path: str,
+        params: Optional[Dict[str, object]] = None,
+        *,
+        method: str = "GET",
+        json_body: Optional[Dict[str, object]] = None,
     ) -> AsyncIterator[Dict[str, object]]:
-        client, response = await self._open_stream(path, params=params)
+        client, response = await self._open_stream(
+            path, params=params, method=method, json_body=json_body
+        )
         event_name = "message"
         event_id = None
         data_lines = []
@@ -115,6 +127,8 @@ class RuntimeTransport:
 
         try:
             async for line in response.aiter_lines():
+                # HTTPX < 0.24 includes line terminators in aiter_lines().
+                line = line.rstrip("\r\n")
                 if line == "":
                     event = flush_event()
                     if event is not None:
@@ -194,18 +208,45 @@ class RuntimeTransport:
         *,
         params: Optional[Dict[str, object]] = None,
         allow_refresh: bool = True,
+        method: str = "GET",
+        json_body: Optional[Dict[str, object]] = None,
     ):
         connection = await self._resolve_connection(False)
-        client, response = await self._send_stream(connection, path, params=params)
+        client, response = await self._send_stream(
+            connection, path, params=params, method=method, json_body=json_body
+        )
         if response.status_code == 401 and allow_refresh:
             await response.aclose()
             await client.aclose()
             refreshed = await self._resolve_connection(True)
-            client, response = await self._send_stream(refreshed, path, params=params)
+            client, response = await self._send_stream(
+                refreshed, path, params=params, method=method, json_body=json_body
+            )
 
-        if not response.is_success:
-            await response.aread()
-        ensure_response_ok(response, "runtime")
+        try:
+            if not response.is_success:
+                await response.aread()
+            ensure_response_ok(response, "runtime")
+            if method == "POST" and "text/event-stream" not in response.headers.get(
+                "content-type", ""
+            ):
+                raise HyperbrowserError(
+                    "Receiver does not support streaming command start; update the receiver. The command may have started; do not retry it automatically.",
+                    code="streaming_not_supported",
+                    service="runtime",
+                )
+            if "text/event-stream" in response.headers.get("content-type", ""):
+                # HTTPX passes this timeout extension through to body reads.
+                # Change it before reading the body, after response headers have
+                # arrived under the ordinary request timeout. Heartbeats reset
+                # this idle timeout independently of the command's deadline.
+                response.request.extensions["timeout"]["read"] = (
+                    PROCESS_STREAM_IDLE_TIMEOUT_SECONDS
+                )
+        except BaseException:
+            await response.aclose()
+            await client.aclose()
+            raise
         return client, response
 
     async def _open_binary_stream(
@@ -320,6 +361,8 @@ class RuntimeTransport:
         path: str,
         *,
         params: Optional[Dict[str, object]],
+        method: str = "GET",
+        json_body: Optional[Dict[str, object]] = None,
     ):
         request_path = _build_query_path(path, params)
         target = resolve_runtime_transport_target(
@@ -335,7 +378,9 @@ class RuntimeTransport:
         client = httpx.AsyncClient(timeout=self._timeout)
 
         try:
-            request = client.build_request("GET", target.url, headers=headers)
+            request = client.build_request(
+                method, target.url, headers=headers, json=json_body
+            )
             response = await client.send(request, stream=True)
             return client, response
         except BaseException as error:
@@ -344,5 +389,5 @@ class RuntimeTransport:
                 error,
                 "runtime",
                 "Unknown runtime request error",
-                request_context("GET", path),
+                request_context(method, path),
             )

hyperbrowser-1.7.0/hyperbrowser/client/managers/sandboxes/process_output.py

@@ -0,0 +1,88 @@
+"""Collection and validation of the receiver's command event stream."""
+
+import base64
+import codecs
+from typing import Dict, List, Optional
+
+from ....exceptions import HyperbrowserError
+from ....models.sandbox import SandboxProcessOutputEvent, SandboxProcessResult
+
+DEFAULT_MAX_PROCESS_OUTPUT_BYTES = 64 * 1024 * 1024
+
+
+class ProcessOutput:
+    def __init__(self, process_id: str, max_bytes: int):
+        self.process_id = process_id
+        self.max_bytes = max_bytes
+        self.size = 0
+        self.seq = 0
+        self.events: List[SandboxProcessOutputEvent] = []
+        self.result: Optional[SandboxProcessResult] = None
+        self.error: Optional[BaseException] = None
+        self._chunks: Dict[str, List[str]] = {"stdout": [], "stderr": []}
+        self._decoders = {
+            stream: codecs.getincrementaldecoder("utf-8")(errors="replace")
+            for stream in ("stdout", "stderr", "system")
+        }
+
+    def failure(
+        self, message: str, code: str = "incomplete_output"
+    ) -> HyperbrowserError:
+        return HyperbrowserError(
+            message,
+            code=code,
+            service="runtime",
+            details={"process_id": self.process_id, "last_seq": self.seq},
+        )
+
+    def consume(self, event) -> None:
+        kind, data = event["event"], event["data"]
+        if kind == "output":
+            if data["seq"] != self.seq + 1:
+                raise self.failure("Command output contains a sequence gap")
+            stream = data["stream"]
+            if stream not in self._decoders:
+                raise self.failure("Unknown command output stream")
+            raw = (
+                base64.b64decode(data["data"], validate=True)
+                if data.get("encoding") == "base64"
+                else data["data"].encode("utf-8")
+            )
+            self.size += len(raw)
+            if self.size > self.max_bytes:
+                raise self.failure(
+                    "Command output exceeds max_output_bytes; increase the collection limit or disconnect a detached process",
+                    "output_limit_exceeded",
+                )
+            self.seq = data["seq"]
+            text = self._decoders[stream].decode(raw)
+            self._chunks["stdout" if stream == "stdout" else "stderr"].append(text)
+            self.events.append(
+                SandboxProcessOutputEvent(
+                    type=stream,
+                    seq=self.seq,
+                    data=text,
+                    timestamp=data["timestamp"],
+                )
+            )
+        elif kind == "done":
+            if data.get("last_seq") != self.seq or data.get("output_truncated", False):
+                raise self.failure("Receiver reported incomplete command output")
+            for stream, decoder in self._decoders.items():
+                self._chunks["stdout" if stream == "stdout" else "stderr"].append(
+                    decoder.decode(b"", final=True)
+                )
+            result = dict(data)
+            result["stdout"] = "".join(self._chunks["stdout"])
+            result["stderr"] = "".join(self._chunks["stderr"])
+            self.result = SandboxProcessResult(**result)
+        elif kind == "error":
+            raise self.failure(
+                str(data.get("error", "Command stream failed")),
+                data.get("code", "incomplete_output"),
+            )
+
+
+def validate_output_limit(value: int) -> None:
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ValueError("max_output_bytes must be a positive integer")

{hyperbrowser-1.6.0 → hyperbrowser-1.7.0}/hyperbrowser/client/managers/sandboxes/shared.py

@@ -27,6 +27,8 @@ from ....types import (
 )
 
 DEFAULT_WATCH_TIMEOUT_MS = 60_000
+# The receiver sends process SSE keepalives every 15 seconds.
+PROCESS_STREAM_IDLE_TIMEOUT_SECONDS = 60.0
 SHELL_SAFE_TOKEN_PATTERN = re.compile(r"^[A-Za-z0-9_@%+=:,./-]+$")
 
 

{hyperbrowser-1.6.0 → hyperbrowser-1.7.0}/hyperbrowser/client/managers/sync_manager/sandbox.py

@@ -299,6 +299,7 @@ class SandboxHandle:
         timeout_ms: Optional[int] = None,
         timeout_sec: Optional[int] = None,
         run_as: Optional[str] = None,
+        max_output_bytes: int = 64 * 1024 * 1024,
     ):
         return self.processes.exec(
             input,
@@ -307,6 +308,7 @@ class SandboxHandle:
             timeout_ms=timeout_ms,
             timeout_sec=timeout_sec,
             run_as=run_as,
+            max_output_bytes=max_output_bytes,
         )
 
     def get_process(self, process_id: str) -> SandboxProcessHandle: