hyperbrowser 1.6.0__tar.gz → 1.8.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperbrowser
-Version: 1.6.0
+Version: 1.8.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
@@ -337,6 +380,42 @@ for event in connection.events():
     print(event)
 ```
 
+### Cache remote Dockerfile builds
+
+Use the public context fingerprint when deriving a cache name. It uses the same
+Dockerfile source selection and `.dockerignore` rules as remote packaging,
+including file contents, modes, paths, and symlinks. It ignores timestamps and
+does not compress or stage the context on disk.
+
+```python
+from hyperbrowser.build_context import docker_build_context_fingerprint
+
+fingerprint = docker_build_context_fingerprint("./app")
+# Include build options such as platform and image_init in your cache key too.
+image_name = f"app-{fingerprint[:32]}"
+build = client.sandboxes.build_image_from_dockerfile(
+    context_path="./app",
+    image_name=image_name,
+    expected_context_fingerprint=fingerprint,
+)
+```
+
+If the archived inputs differ from the fingerprint, the SDK raises
+`DockerBuildContextChangedError` before creating or uploading a build. Compute a
+fresh fingerprint and repeat the lookup/build operation. Use the same `dockerfile`
+and `force_full_context` selection when fingerprinting and building (the latter
+is named `remote_full_context` on the build method). The expected fingerprint is
+supported only for remote builds.
+
+Fingerprinting streams included files and performs blocking I/O. Async callers
+should use `await asyncio.to_thread(docker_build_context_fingerprint, "./app")`
+(Python 3.9+) or an executor. It does not resolve mutable base-image tags or
+network resources fetched by a Dockerfile; rebuild explicitly when those change.
+
+Image listings distinguish `ready` from `uploaded`: a completed team image can
+be ready to launch before its durability backup is uploaded. `ready` is `None`
+when talking to an older server. Keep the returned image ID to pin that revision.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

{hyperbrowser-1.6.0 → hyperbrowser-1.8.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
@@ -309,6 +352,42 @@ for event in connection.events():
     print(event)
 ```
 
+### Cache remote Dockerfile builds
+
+Use the public context fingerprint when deriving a cache name. It uses the same
+Dockerfile source selection and `.dockerignore` rules as remote packaging,
+including file contents, modes, paths, and symlinks. It ignores timestamps and
+does not compress or stage the context on disk.
+
+```python
+from hyperbrowser.build_context import docker_build_context_fingerprint
+
+fingerprint = docker_build_context_fingerprint("./app")
+# Include build options such as platform and image_init in your cache key too.
+image_name = f"app-{fingerprint[:32]}"
+build = client.sandboxes.build_image_from_dockerfile(
+    context_path="./app",
+    image_name=image_name,
+    expected_context_fingerprint=fingerprint,
+)
+```
+
+If the archived inputs differ from the fingerprint, the SDK raises
+`DockerBuildContextChangedError` before creating or uploading a build. Compute a
+fresh fingerprint and repeat the lookup/build operation. Use the same `dockerfile`
+and `force_full_context` selection when fingerprinting and building (the latter
+is named `remote_full_context` on the build method). The expected fingerprint is
+supported only for remote builds.
+
+Fingerprinting streams included files and performs blocking I/O. Async callers
+should use `await asyncio.to_thread(docker_build_context_fingerprint, "./app")`
+(Python 3.9+) or an executor. It does not resolve mutable base-image tags or
+network resources fetched by a Dockerfile; rebuild explicitly when those change.
+
+Image listings distinguish `ready` from `uploaded`: a completed team image can
+be ready to launch before its durability backup is uploaded. `ready` is `None`
+when talking to an older server. Keep the returned image ID to pin that revision.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

hyperbrowser-1.8.0/hyperbrowser/build_context.py

@@ -0,0 +1,8 @@
+"""Public helpers for identifying inputs to remote Dockerfile builds."""
+
+from .client.managers.sandboxes.image_build import (
+    DockerBuildContextChangedError,
+    docker_build_context_fingerprint,
+)
+
+__all__ = ["DockerBuildContextChangedError", "docker_build_context_fingerprint"]

{hyperbrowser-1.6.0 → hyperbrowser-1.8.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:
@@ -723,6 +725,7 @@ class SandboxManager:
         dockerfile,
         platform: str,
         remote_full_context: bool,
+        expected_context_fingerprint: Optional[str],
         image_init: Optional[Union[SandboxImageInitDict, SandboxImageInit]],
         image_config_user: Optional[str],
         builder_cpus: Optional[int],
@@ -739,6 +742,7 @@ class SandboxManager:
             context_path,
             dockerfile=dockerfile,
             force_full_context=remote_full_context,
+            expected_context_fingerprint=expected_context_fingerprint,
             temp_dir=temp_dir,
         )
         build_id = None
@@ -801,6 +805,7 @@ class SandboxManager:
         dockerfile="Dockerfile",
         remote: bool = True,
         remote_full_context: bool = False,
+        expected_context_fingerprint: Optional[str] = None,
         docker_tag: Optional[str] = None,
         platform: str = IMAGE_BUILD_SOURCE_PLATFORM,
         build_args: Optional[Dict[str, str]] = None,
@@ -827,6 +832,7 @@ class SandboxManager:
                 dockerfile=dockerfile,
                 platform=platform,
                 remote_full_context=remote_full_context,
+                expected_context_fingerprint=expected_context_fingerprint,
                 image_init=image_init,
                 image_config_user=image_config_user,
                 builder_cpus=builder_cpus,
@@ -838,6 +844,8 @@ class SandboxManager:
                 temp_dir=temp_dir,
                 upload_timeout=upload_timeout,
             )
+        if expected_context_fingerprint is not None:
+            raise ValueError("expected_context_fingerprint requires remote=True")
         tag = docker_tag or make_temp_docker_tag()
         remove_tag = docker_tag is None
         try:

{hyperbrowser-1.6.0 → hyperbrowser-1.8.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.8.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),
             )