hyperbrowser 1.8.0__tar.gz → 1.9.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperbrowser
-Version: 1.8.0
+Version: 1.9.0
 Summary: Python SDK for hyperbrowser
 License: MIT
 License-File: LICENSE
@@ -416,6 +416,56 @@ 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.
 
+### Reuse an image or join a build
+
+`get_or_build_image` provides the same operation on sync and async clients. Give
+it either a remote Dockerfile context or a local Docker image. It derives a name
+from the input identity and image initialization options, reuses a ready team
+image, or submits a build and joins a compatible concurrent build automatically.
+The optional prefix is a namespace, not a fixed image alias: different inputs
+produce different names under the same prefix.
+
+```python
+resolved = client.sandboxes.get_or_build_image(
+    context_path="./app",  # alternatively: docker_image="local/app:latest"
+    image_name_prefix="my-app",
+    wait_timeout=3600,
+)
+print(resolved.outcome)  # "reused", "joined", or "created"
+sandbox = client.sandboxes.create({
+    "image_name": resolved.image_name,
+    "image_id": resolved.image_id,
+})
+```
+
+With `wait=False`, a submitted/joined build is returned as `resolved.build`;
+`image_id` is populated only when ready. `find_ready_image(name)` exposes the
+exact-name lookup separately. Older servers fall back to uploaded-image reuse.
+The public `hyperbrowser.image_builds.image_build_name` helper lets integrations
+derive the same name from an existing context fingerprint or Docker image digest.
+Passing `expected_context_fingerprint` or `expected_image_digest` avoids repeating
+identity discovery; supply a fresh identity for each resolution request. Changes
+between identity discovery and packaging are rejected instead of published under
+the wrong name. Local Docker images must already be available in the daemon.
+
+Automatic local-image identity discovery requires a Docker CLI and Engine
+supporting **API 1.49 or newer (Docker 28.1+)** for platform-specific inspection.
+Upgrade Docker and check for an older `DOCKER_API_VERSION` override if the helper
+reports this requirement. Remote Dockerfile builds do not require local Docker.
+The existing explicit-name import method retains its inspection fallback.
+
+`force_build=True` skips ready-image lookup but still joins matching active builds
+and permits existing layer/artifact caches. Use it to refresh mutable base tags or
+external Dockerfile downloads. Joining does not change an existing builder's
+resources. Lookup and creation use separate API calls; if another build completes
+between them, an additional revision can be submitted.
+
+Each caller owns its polling timeout. Canceling that wait does not cancel an
+accepted backend build. Uploads have a separate inactivity allowance
+(`upload_timeout=600` by default), not a total upload-duration limit. The existing
+`build_image_from_dockerfile` and `build_image_from_docker_image` methods retain
+their explicit-name behavior and continue to report build conflicts directly.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

{hyperbrowser-1.8.0 → hyperbrowser-1.9.0}/README.md

@@ -388,6 +388,56 @@ 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.
 
+### Reuse an image or join a build
+
+`get_or_build_image` provides the same operation on sync and async clients. Give
+it either a remote Dockerfile context or a local Docker image. It derives a name
+from the input identity and image initialization options, reuses a ready team
+image, or submits a build and joins a compatible concurrent build automatically.
+The optional prefix is a namespace, not a fixed image alias: different inputs
+produce different names under the same prefix.
+
+```python
+resolved = client.sandboxes.get_or_build_image(
+    context_path="./app",  # alternatively: docker_image="local/app:latest"
+    image_name_prefix="my-app",
+    wait_timeout=3600,
+)
+print(resolved.outcome)  # "reused", "joined", or "created"
+sandbox = client.sandboxes.create({
+    "image_name": resolved.image_name,
+    "image_id": resolved.image_id,
+})
+```
+
+With `wait=False`, a submitted/joined build is returned as `resolved.build`;
+`image_id` is populated only when ready. `find_ready_image(name)` exposes the
+exact-name lookup separately. Older servers fall back to uploaded-image reuse.
+The public `hyperbrowser.image_builds.image_build_name` helper lets integrations
+derive the same name from an existing context fingerprint or Docker image digest.
+Passing `expected_context_fingerprint` or `expected_image_digest` avoids repeating
+identity discovery; supply a fresh identity for each resolution request. Changes
+between identity discovery and packaging are rejected instead of published under
+the wrong name. Local Docker images must already be available in the daemon.
+
+Automatic local-image identity discovery requires a Docker CLI and Engine
+supporting **API 1.49 or newer (Docker 28.1+)** for platform-specific inspection.
+Upgrade Docker and check for an older `DOCKER_API_VERSION` override if the helper
+reports this requirement. Remote Dockerfile builds do not require local Docker.
+The existing explicit-name import method retains its inspection fallback.
+
+`force_build=True` skips ready-image lookup but still joins matching active builds
+and permits existing layer/artifact caches. Use it to refresh mutable base tags or
+external Dockerfile downloads. Joining does not change an existing builder's
+resources. Lookup and creation use separate API calls; if another build completes
+between them, an additional revision can be submitted.
+
+Each caller owns its polling timeout. Canceling that wait does not cancel an
+accepted backend build. Uploads have a separate inactivity allowance
+(`upload_timeout=600` by default), not a total upload-duration limit. The existing
+`build_image_from_dockerfile` and `build_image_from_docker_image` methods retain
+their explicit-name behavior and continue to report build conflicts directly.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

{hyperbrowser-1.8.0 → hyperbrowser-1.9.0}/hyperbrowser/client/managers/async_manager/sandbox.py

@@ -1,6 +1,7 @@
 import asyncio
 import functools
 import time
+from pathlib import Path
 from typing import Dict, Optional, Union
 
 from ..._request import coerce_request, dump_request
@@ -15,6 +16,8 @@ from ....models.sandbox import (
     SandboxExposeParams,
     SandboxExposeResult,
     SandboxImageBuild,
+    SandboxImageBuildResolution,
+    SandboxImageSummary,
     SandboxImageBuildCreateResult,
     SandboxDockerImageReuseResult,
     SandboxImageBuildListParams,
@@ -63,6 +66,11 @@ from ....sandbox_common import (
     parse_json_response,
     should_retry_get,
 )
+from ..sandboxes.image_resolution import (
+    image_build_name,
+    matching_image_build,
+    completed_image_id,
+)
 from ..sandboxes.shared import (
     _build_sandbox_exposed_url,
     _copy_model,
@@ -70,6 +78,8 @@ from ..sandboxes.shared import (
 )
 from ..sandboxes.image_build import (
     IMAGE_BUILD_SOURCE_PLATFORM,
+    docker_build_context_fingerprint,
+    docker_image_digest,
     build_docker_image_from_dockerfile,
     is_terminal_image_build_status,
     make_temp_docker_tag,
@@ -459,6 +469,159 @@ class SandboxManager:
         )
         return SandboxImageListResponse(**payload)
 
+    async def find_ready_image(self, image_name: str) -> Optional[SandboxImageSummary]:
+        """Find an exact ready team image, including revisions awaiting backup."""
+        page = 1
+        while True:
+            response = await self.list_images(
+                SandboxImageListParams(
+                    search=image_name, sources=["team"], page=page, limit=100
+                )
+            )
+            for image in response.images:
+                if image.image_name == image_name and (
+                    image.uploaded or getattr(image, "ready", False)
+                ):
+                    return image
+            if len(response.images) < 100:
+                return None
+            if response.total_count is not None and page * 100 >= response.total_count:
+                return None
+            page += 1
+
+    async def get_or_build_image(
+        self,
+        *,
+        context_path: Optional[Union[str, Path]] = None,
+        docker_image: Optional[str] = None,
+        image_name_prefix: str = "hb",
+        dockerfile: str = "Dockerfile",
+        platform: str = IMAGE_BUILD_SOURCE_PLATFORM,
+        remote_full_context: bool = False,
+        expected_context_fingerprint: Optional[str] = None,
+        expected_image_digest: Optional[str] = None,
+        image_init: Optional[Union[SandboxImageInitDict, SandboxImageInit]] = None,
+        image_config_user: Optional[str] = None,
+        builder_cpus: Optional[int] = None,
+        builder_memory_mib: Optional[int] = None,
+        builder_scratch_mib: Optional[int] = None,
+        force_build: bool = False,
+        wait: bool = True,
+        poll_interval: float = 3.0,
+        wait_timeout: Optional[float] = 35 * 60,
+        upload_timeout: Optional[float] = 600,
+        temp_dir: Optional[str] = None,
+    ) -> SandboxImageBuildResolution:
+        """Reuse, join, or build content-derived remote Dockerfile/image inputs.
+
+        Supply exactly one of context_path or docker_image. Names include source
+        contents, platform and image initialization overrides. force_build skips
+        ready-image lookup, but joins matching active builds and retains builder
+        layer/artifact caches. Canceling polling never cancels the backend build.
+        wait_timeout applies to this caller's polling, independently of uploads.
+        This composes existing APIs; lookup plus creation is not server-atomic.
+        """
+        platform = platform.strip().lower()
+        if platform != "linux/amd64":
+            raise ValueError("Image builds require platform='linux/amd64'")
+        if (context_path is None) == (docker_image is None):
+            raise ValueError("Supply exactly one of context_path or docker_image")
+        if context_path is not None:
+            if expected_image_digest is not None:
+                raise ValueError("expected_image_digest requires docker_image")
+            fingerprint = expected_context_fingerprint
+            if fingerprint is None:
+                fingerprint = await _run_blocking(
+                    docker_build_context_fingerprint,
+                    context_path,
+                    dockerfile=dockerfile,
+                    force_full_context=remote_full_context,
+                )
+            source = "dockerfile"
+            input_format = "dockerfile_context_manifest_v1"
+        else:
+            if (
+                expected_context_fingerprint is not None
+                or remote_full_context
+                or dockerfile != "Dockerfile"
+            ):
+                raise ValueError("Dockerfile context options require context_path")
+            fingerprint = expected_image_digest
+            if fingerprint is None:
+                fingerprint = await _run_blocking(
+                    docker_image_digest, docker_image, platform=platform
+                )
+            source = "prebuilt"
+            input_format = "docker_image_manifest_v1"
+        image_name = image_build_name(
+            source=source,
+            fingerprint=fingerprint,
+            name_prefix=image_name_prefix,
+            platform=platform,
+            image_init=image_init,
+            image_config_user=image_config_user,
+        )
+        if not force_build:
+            image = await self.find_ready_image(image_name)
+            if image is not None:
+                return SandboxImageBuildResolution(
+                    outcome="reused",
+                    image_name=image_name,
+                    image_id=image.id,
+                )
+        common = dict(
+            image_name=image_name,
+            platform=platform,
+            image_init=image_init,
+            image_config_user=image_config_user,
+            builder_cpus=builder_cpus,
+            builder_memory_mib=builder_memory_mib,
+            builder_scratch_mib=builder_scratch_mib,
+            wait=False,
+            upload_timeout=upload_timeout,
+            temp_dir=temp_dir,
+        )
+        common = {
+            key: value
+            for key, value in common.items()
+            if not (key.startswith("builder_") and value is None)
+        }
+        outcome = "created"
+        try:
+            if context_path is not None:
+                build = await self.build_image_from_dockerfile(
+                    context_path=context_path,
+                    dockerfile=dockerfile,
+                    remote=True,
+                    remote_full_context=remote_full_context,
+                    expected_context_fingerprint=fingerprint,
+                    **common,
+                )
+            else:
+                build = await self.build_image_from_docker_image(
+                    docker_image=docker_image,
+                    expected_image_digest=fingerprint,
+                    **common,
+                )
+        except HyperbrowserError as error:
+            existing = matching_image_build(error, image_name, input_format)
+            if existing is None:
+                raise
+            build = existing
+            outcome = "joined"
+        if wait and build.status != "completed":
+            build = await self.wait_for_image_build(
+                build.id,
+                poll_interval=poll_interval,
+                timeout=wait_timeout,
+            )
+        return SandboxImageBuildResolution(
+            outcome=outcome,
+            image_name=image_name,
+            image_id=completed_image_id(build),
+            build=build,
+        )
+
     async def list_snapshots(
         self,
         params: Optional[
@@ -582,6 +745,7 @@ class SandboxManager:
         *,
         docker_image: str,
         image_name: str,
+        expected_image_digest: Optional[str] = None,
         platform: str = IMAGE_BUILD_SOURCE_PLATFORM,
         image_init: Optional[Union[SandboxImageInitDict, SandboxImageInit]] = None,
         image_config_user: Optional[str] = None,
@@ -600,6 +764,14 @@ class SandboxManager:
             platform=platform,
         )
         try:
+            if (
+                expected_image_digest is not None
+                and source.image_digest != expected_image_digest.lower()
+            ):
+                raise RuntimeError(
+                    "Docker image changed after its cache identity was computed. "
+                    "Retry with a fresh image digest."
+                )
             explicit_image_init = (
                 coerce_request(image_init, SandboxImageInit, name="image_init")
                 if image_init is not None

{hyperbrowser-1.8.0 → hyperbrowser-1.9.0}/hyperbrowser/client/managers/sandboxes/image_build.py

@@ -443,6 +443,27 @@ def package_docker_build_context_manifest(
         raise
 
 
+def docker_image_digest(
+    docker_image: str, *, platform: str = IMAGE_BUILD_SOURCE_PLATFORM
+) -> str:
+    """Inspect platform identity with Docker API 1.49+, without temporary resources."""
+    try:
+        inspection = _inspect_docker_image(docker_image, platform)
+    except RuntimeError as error:
+        message = str(error)
+        if (
+            '"--platform" requires API version' in message
+            or "unknown flag: --platform" in message
+        ):
+            raise RuntimeError(
+                "Local Docker image imports require a Docker CLI and Engine "
+                "supporting API 1.49 or newer (Docker 28.1+). Upgrade Docker "
+                "or remove an older DOCKER_API_VERSION override."
+            ) from error
+        raise
+    return _normalize_sha256_digest(inspection.get("Id"))
+
+
 def prepare_docker_image_manifest_source(
     docker_image: str,
     *,

hyperbrowser-1.9.0/hyperbrowser/client/managers/sandboxes/image_resolution.py

@@ -0,0 +1,103 @@
+"""Shared identity and validation for opt-in image resolution."""
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping
+from typing import Literal, Optional, Union
+
+from ....exceptions import HyperbrowserError
+from ....models.sandbox import SandboxImageBuild, SandboxImageInit
+from ....types import SandboxImageInit as SandboxImageInitDict
+from ..._request import coerce_request
+
+
+def image_build_name(
+    *,
+    source: Literal["dockerfile", "prebuilt"],
+    fingerprint: str,
+    name_prefix: str = "hb",
+    platform: str = "linux/amd64",
+    image_init: Optional[Union[SandboxImageInitDict, SandboxImageInit]] = None,
+    image_config_user: Optional[str] = None,
+) -> str:
+    """Name an immutable input identity without packaging or uploading it.
+
+    Fingerprints identify effective Dockerfile contexts or platform-specific
+    Docker image digests. Builder resources and wait policies do not change the
+    image contents and are excluded. Mutable external inputs (base tags, network
+    downloads) require an explicit force_build to request another build.
+    """
+    platform = platform.strip().lower()
+    if not re.fullmatch(r"[a-z0-9]+/[a-z0-9]+(?:/[a-z0-9]+)?", platform):
+        raise ValueError("platform must be an OCI platform such as 'linux/amd64'")
+    if not re.fullmatch(r"[A-Za-z0-9_-]{1,21}", name_prefix):
+        raise ValueError("image_name_prefix must be 1-21 letters, digits, '_' or '-'")
+    if source == "prebuilt":
+        fingerprint = fingerprint.lower()
+        if not re.fullmatch(r"sha256:[0-9a-f]{64}", fingerprint):
+            raise ValueError("expected_image_digest must be a sha256: Docker digest")
+        payload = "docker_image\0{}\0platform\0{}".format(fingerprint, platform)
+    elif source == "dockerfile":
+        if not re.fullmatch(r"[0-9a-f]{64}", fingerprint):
+            raise ValueError(
+                "expected_context_fingerprint must be a SHA-256 hex digest"
+            )
+        payload = "dockerfile-context-v3\0{}\0platform\0{}".format(
+            fingerprint, platform
+        )
+    else:
+        raise ValueError("source must be 'dockerfile' or 'prebuilt'")
+    options = {}
+    if image_init is not None:
+        normalized = coerce_request(image_init, SandboxImageInit, name="image_init")
+        initialization = normalized.model_dump(by_alias=True, exclude_none=True)
+        if initialization:
+            options["imageInit"] = initialization
+    if image_config_user is not None:
+        options["imageConfigUser"] = image_config_user.strip()
+    if options:
+        payload += "\0options\0" + json.dumps(
+            options, sort_keys=True, separators=(",", ":")
+        )
+    digest = hashlib.blake2b(payload.encode(), digest_size=8).hexdigest()
+    name = "{}__{}__{}__{}".format(
+        name_prefix, source, digest, platform.replace("/", "-")
+    )
+    if len(name) > 64:
+        raise ValueError(
+            "image_name_prefix and platform produce a name longer than 64 characters"
+        )
+    return name
+
+
+def matching_image_build(
+    error: HyperbrowserError, image_name: str, input_format: str
+) -> Optional[SandboxImageBuild]:
+    if error.status_code != 409 or error.code != "image_build_in_progress":
+        return None
+    if not isinstance(error.details, Mapping):
+        return None
+    data = error.details.get("build")
+    if not isinstance(data, Mapping):
+        return None
+    metadata = data.get("metadata")
+    if not isinstance(metadata, Mapping) or metadata.get("inputFormat") != input_format:
+        return None
+    if metadata.get("sourcePlatform", "linux/amd64") != "linux/amd64":
+        return None
+    try:
+        build = SandboxImageBuild(**dict(data))
+    except (TypeError, ValueError):
+        return None
+    if not build.id or build.image_name != image_name:
+        return None
+    return build
+
+
+def completed_image_id(build: SandboxImageBuild) -> Optional[str]:
+    if build.status != "completed":
+        return None
+    if not build.image_id:
+        raise RuntimeError("Completed image build did not return an image ID")
+    return build.image_id

{hyperbrowser-1.8.0 → hyperbrowser-1.9.0}/hyperbrowser/client/managers/sync_manager/sandbox.py

@@ -1,4 +1,5 @@
 import time
+from pathlib import Path
 from typing import Dict, Optional, Union
 
 from ..._request import coerce_request, dump_request
@@ -13,6 +14,8 @@ from ....models.sandbox import (
     SandboxExposeParams,
     SandboxExposeResult,
     SandboxImageBuild,
+    SandboxImageBuildResolution,
+    SandboxImageSummary,
     SandboxImageBuildCreateResult,
     SandboxDockerImageReuseResult,
     SandboxImageBuildListParams,
@@ -61,6 +64,11 @@ from ....sandbox_common import (
     parse_json_response,
     should_retry_get,
 )
+from ..sandboxes.image_resolution import (
+    image_build_name,
+    matching_image_build,
+    completed_image_id,
+)
 from ..sandboxes.shared import (
     _build_sandbox_exposed_url,
     _copy_model,
@@ -68,6 +76,8 @@ from ..sandboxes.shared import (
 )
 from ..sandboxes.image_build import (
     IMAGE_BUILD_SOURCE_PLATFORM,
+    docker_build_context_fingerprint,
+    docker_image_digest,
     build_docker_image_from_dockerfile,
     is_terminal_image_build_status,
     make_temp_docker_tag,
@@ -451,6 +461,156 @@ class SandboxManager:
         )
         return SandboxImageListResponse(**payload)
 
+    def find_ready_image(self, image_name: str) -> Optional[SandboxImageSummary]:
+        """Find an exact ready team image, including revisions awaiting backup."""
+        page = 1
+        while True:
+            response = self.list_images(
+                SandboxImageListParams(
+                    search=image_name, sources=["team"], page=page, limit=100
+                )
+            )
+            for image in response.images:
+                if image.image_name == image_name and (
+                    image.uploaded or getattr(image, "ready", False)
+                ):
+                    return image
+            if len(response.images) < 100:
+                return None
+            if response.total_count is not None and page * 100 >= response.total_count:
+                return None
+            page += 1
+
+    def get_or_build_image(
+        self,
+        *,
+        context_path: Optional[Union[str, Path]] = None,
+        docker_image: Optional[str] = None,
+        image_name_prefix: str = "hb",
+        dockerfile: str = "Dockerfile",
+        platform: str = IMAGE_BUILD_SOURCE_PLATFORM,
+        remote_full_context: bool = False,
+        expected_context_fingerprint: Optional[str] = None,
+        expected_image_digest: Optional[str] = None,
+        image_init: Optional[Union[SandboxImageInitDict, SandboxImageInit]] = None,
+        image_config_user: Optional[str] = None,
+        builder_cpus: Optional[int] = None,
+        builder_memory_mib: Optional[int] = None,
+        builder_scratch_mib: Optional[int] = None,
+        force_build: bool = False,
+        wait: bool = True,
+        poll_interval: float = 3.0,
+        wait_timeout: Optional[float] = 35 * 60,
+        upload_timeout: Optional[float] = 600,
+        temp_dir: Optional[str] = None,
+    ) -> SandboxImageBuildResolution:
+        """Reuse, join, or build content-derived remote Dockerfile/image inputs.
+
+        Supply exactly one of context_path or docker_image. Names include source
+        contents, platform and image initialization overrides. force_build skips
+        ready-image lookup, but joins matching active builds and retains builder
+        layer/artifact caches. Canceling polling never cancels the backend build.
+        wait_timeout applies to this caller's polling, independently of uploads.
+        This composes existing APIs; lookup plus creation is not server-atomic.
+        """
+        platform = platform.strip().lower()
+        if platform != "linux/amd64":
+            raise ValueError("Image builds require platform='linux/amd64'")
+        if (context_path is None) == (docker_image is None):
+            raise ValueError("Supply exactly one of context_path or docker_image")
+        if context_path is not None:
+            if expected_image_digest is not None:
+                raise ValueError("expected_image_digest requires docker_image")
+            fingerprint = expected_context_fingerprint
+            if fingerprint is None:
+                fingerprint = docker_build_context_fingerprint(
+                    context_path,
+                    dockerfile=dockerfile,
+                    force_full_context=remote_full_context,
+                )
+            source = "dockerfile"
+            input_format = "dockerfile_context_manifest_v1"
+        else:
+            if (
+                expected_context_fingerprint is not None
+                or remote_full_context
+                or dockerfile != "Dockerfile"
+            ):
+                raise ValueError("Dockerfile context options require context_path")
+            fingerprint = expected_image_digest
+            if fingerprint is None:
+                fingerprint = docker_image_digest(docker_image, platform=platform)
+            source = "prebuilt"
+            input_format = "docker_image_manifest_v1"
+        image_name = image_build_name(
+            source=source,
+            fingerprint=fingerprint,
+            name_prefix=image_name_prefix,
+            platform=platform,
+            image_init=image_init,
+            image_config_user=image_config_user,
+        )
+        if not force_build:
+            image = self.find_ready_image(image_name)
+            if image is not None:
+                return SandboxImageBuildResolution(
+                    outcome="reused",
+                    image_name=image_name,
+                    image_id=image.id,
+                )
+        common = dict(
+            image_name=image_name,
+            platform=platform,
+            image_init=image_init,
+            image_config_user=image_config_user,
+            builder_cpus=builder_cpus,
+            builder_memory_mib=builder_memory_mib,
+            builder_scratch_mib=builder_scratch_mib,
+            wait=False,
+            upload_timeout=upload_timeout,
+            temp_dir=temp_dir,
+        )
+        common = {
+            key: value
+            for key, value in common.items()
+            if not (key.startswith("builder_") and value is None)
+        }
+        outcome = "created"
+        try:
+            if context_path is not None:
+                build = self.build_image_from_dockerfile(
+                    context_path=context_path,
+                    dockerfile=dockerfile,
+                    remote=True,
+                    remote_full_context=remote_full_context,
+                    expected_context_fingerprint=fingerprint,
+                    **common,
+                )
+            else:
+                build = self.build_image_from_docker_image(
+                    docker_image=docker_image,
+                    expected_image_digest=fingerprint,
+                    **common,
+                )
+        except HyperbrowserError as error:
+            existing = matching_image_build(error, image_name, input_format)
+            if existing is None:
+                raise
+            build = existing
+            outcome = "joined"
+        if wait and build.status != "completed":
+            build = self.wait_for_image_build(
+                build.id,
+                poll_interval=poll_interval,
+                timeout=wait_timeout,
+            )
+        return SandboxImageBuildResolution(
+            outcome=outcome,
+            image_name=image_name,
+            image_id=completed_image_id(build),
+            build=build,
+        )
+
     def list_snapshots(
         self,
         params: Optional[
@@ -574,6 +734,7 @@ class SandboxManager:
         *,
         docker_image: str,
         image_name: str,
+        expected_image_digest: Optional[str] = None,
         platform: str = IMAGE_BUILD_SOURCE_PLATFORM,
         image_init: Optional[Union[SandboxImageInitDict, SandboxImageInit]] = None,
         image_config_user: Optional[str] = None,
@@ -591,6 +752,14 @@ class SandboxManager:
             platform=platform,
         )
         try:
+            if (
+                expected_image_digest is not None
+                and source.image_digest != expected_image_digest.lower()
+            ):
+                raise RuntimeError(
+                    "Docker image changed after its cache identity was computed. "
+                    "Retry with a fresh image digest."
+                )
             explicit_image_init = (
                 coerce_request(image_init, SandboxImageInit, name="image_init")
                 if image_init is not None

hyperbrowser-1.9.0/hyperbrowser/image_builds.py

@@ -0,0 +1,5 @@
+"""Content-derived image names for build-or-wait workflows."""
+
+from .client.managers.sandboxes.image_resolution import image_build_name
+
+__all__ = ["image_build_name"]

{hyperbrowser-1.8.0 → hyperbrowser-1.9.0}/hyperbrowser/models/__init__.py

@@ -364,6 +364,7 @@ from .sandbox import (
     CompleteSandboxImageBuildParams,
     SandboxImageBuildUpload,
     SandboxImageBuild,
+    SandboxImageBuildResolution,
     SandboxImageBuildCreateResult,
     SandboxDockerImageReuseResult,
     SandboxImageBuildListParams,
@@ -695,6 +696,7 @@ __all__ = [
     "CompleteSandboxImageBuildParams",
     "SandboxImageBuildUpload",
     "SandboxImageBuild",
+    "SandboxImageBuildResolution",
     "SandboxImageBuildCreateResult",
     "SandboxDockerImageReuseResult",
     "SandboxImageBuildListParams",

{hyperbrowser-1.8.0 → hyperbrowser-1.9.0}/hyperbrowser/models/sandbox.py

@@ -523,6 +523,19 @@ class SandboxImageBuild(SandboxBaseModel):
         return _parse_optional_datetime(value)
 
 
+class SandboxImageBuildResolution(SandboxBaseModel):
+    """The result of resolving content-derived image inputs.
+
+    image_id is populated only for a ready image. With wait=False, build
+    identifies the submitted or joined build, which the caller can poll later.
+    """
+
+    outcome: Literal["reused", "joined", "created"]
+    image_name: str
+    image_id: Optional[str] = None
+    build: Optional[SandboxImageBuild] = None
+
+
 class SandboxImageBuildCreateResult(SandboxBaseModel):
     build: SandboxImageBuild
     upload: Optional[SandboxImageBuildUpload] = None

{hyperbrowser-1.8.0 → hyperbrowser-1.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "hyperbrowser"
-version = "1.8.0"
+version = "1.9.0"
 description = "Python SDK for hyperbrowser"
 authors = ["Nikhil Shahi <nshahi1998@gmail.com>"]
 license = "MIT"