hyperbrowser 1.2.2__tar.gz → 1.3.0__tar.gz

{hyperbrowser-1.2.2 → hyperbrowser-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperbrowser
-Version: 1.2.2
+Version: 1.3.0
 Summary: Python SDK for hyperbrowser
 License: MIT
 License-File: LICENSE
@@ -250,6 +250,7 @@ sandbox = client.sandboxes.create(
 )
 
 sandbox.stop()
+client.volumes.delete(same_volume.id)
 client.close()
 ```
 

{hyperbrowser-1.2.2 → hyperbrowser-1.3.0}/README.md

@@ -223,6 +223,7 @@ sandbox = client.sandboxes.create(
 )
 
 sandbox.stop()
+client.volumes.delete(same_volume.id)
 client.close()
 ```
 

{hyperbrowser-1.2.2 → hyperbrowser-1.3.0}/hyperbrowser/client/managers/async_manager/sandbox.py

@@ -9,12 +9,14 @@ from ....models.sandbox import (
     CompleteSandboxImageBuildParams,
     CreateSandboxParams,
     CreateSandboxImageBuildParams,
+    ReuseSandboxDockerImageParams,
     SandboxDetail,
     SandboxExecParams,
     SandboxExposeParams,
     SandboxExposeResult,
     SandboxImageBuild,
     SandboxImageBuildCreateResult,
+    SandboxDockerImageReuseResult,
     SandboxImageBuildListParams,
     SandboxImageBuildListResponse,
     SandboxImageListParams,
@@ -39,6 +41,7 @@ from ....models.session import BasicResponse
 from ....types import (
     CompleteSandboxImageBuildParams as CompleteSandboxImageBuildParamsDict,
     CreateSandboxImageBuildParams as CreateSandboxImageBuildParamsDict,
+    ReuseSandboxDockerImageParams as ReuseSandboxDockerImageParamsDict,
     CreateSandboxParams as CreateSandboxParamsDict,
     SandboxExecParams as SandboxExecParamsDict,
     SandboxExposeParams as SandboxExposeParamsDict,
@@ -67,9 +70,12 @@ from ..sandboxes.image_build import (
     build_docker_image_from_dockerfile,
     is_terminal_image_build_status,
     make_temp_docker_tag,
-    package_docker_image,
+    merge_image_init,
+    package_docker_build_context_manifest,
+    package_docker_image_manifest,
+    prepare_docker_image_manifest_source,
     remove_docker_image,
-    upload_image_build_artifact,
+    upload_missing_image_build_artifacts,
 )
 from .sandboxes.sandbox_files import (
     DEFAULT_WATCH_TIMEOUT_MS,
@@ -494,6 +500,20 @@ class SandboxManager:
         payload = await self._request("GET", f"/images/builds/{build_id}")
         return SandboxImageBuild(**payload["build"])
 
+    async def reuse_docker_image(
+        self,
+        params: Union[
+            ReuseSandboxDockerImageParamsDict,
+            ReuseSandboxDockerImageParams,
+        ],
+    ) -> SandboxDockerImageReuseResult:
+        payload = await self._request(
+            "POST",
+            "/images/builds/reuse",
+            data=dump_request(params, ReuseSandboxDockerImageParams),
+        )
+        return SandboxDockerImageReuseResult(**payload)
+
     async def complete_image_build(
         self,
         build_id: str,
@@ -566,18 +586,158 @@ class SandboxManager:
         temp_dir: Optional[str] = None,
         upload_timeout: Optional[float] = None,
     ) -> SandboxImageBuild:
-        artifact = await _run_blocking(
-            package_docker_image,
+        source = await _run_blocking(
+            prepare_docker_image_manifest_source,
             docker_image,
             platform=platform,
+        )
+        try:
+            explicit_image_init = (
+                coerce_request(image_init, SandboxImageInit, name="image_init")
+                if image_init is not None
+                else None
+            )
+            normalized_image_init = merge_image_init(
+                source.image_init,
+                explicit_image_init,
+            )
+            normalized_image_config_user = (
+                image_config_user
+                if image_config_user is not None
+                else source.image_config_user
+            )
+            try:
+                reused = await self.reuse_docker_image(
+                    ReuseSandboxDockerImageParams(
+                        image_name=image_name,
+                        source_image_digest=source.image_digest,
+                        source_platform=platform,
+                        image_config_user=normalized_image_config_user,
+                        image_init=normalized_image_init,
+                    )
+                )
+            except HyperbrowserError as error:
+                if error.status_code != 404:
+                    raise
+                reused = None
+            if reused is not None and reused.hit:
+                if reused.build is None:
+                    raise RuntimeError(
+                        "exact image cache response is missing its completed build"
+                    )
+                return reused.build
+
+            packaged = await _run_blocking(
+                package_docker_image_manifest,
+                docker_image,
+                source.image_digest,
+                source.config,
+                platform=platform,
+                temp_dir=temp_dir,
+            )
+            build_id = None
+            build_started = False
+            try:
+                artifact = packaged.artifact
+                create_result = await self.create_image_build(
+                    CreateSandboxImageBuildParams(
+                        image_name=image_name,
+                        input_sha256=artifact.sha256_hex,
+                        input_size_bytes=artifact.size_bytes,
+                        input_format=artifact.input_format,
+                        source_platform=artifact.source_platform,
+                        image_config_user=normalized_image_config_user,
+                        image_init=normalized_image_init,
+                        docker_image_manifest=packaged.manifest,
+                    )
+                )
+                build_id = create_result.build.id
+                await _run_blocking(
+                    upload_missing_image_build_artifacts,
+                    create_result.uploads,
+                    packaged.layers,
+                    label="Docker image layer",
+                    timeout=upload_timeout,
+                )
+                build = await self._complete_image_build_resilient(
+                    build_id,
+                    artifact,
+                )
+                build_started = True
+                if wait:
+                    return await self.wait_for_image_build(
+                        build.id,
+                        poll_interval=poll_interval,
+                        timeout=wait_timeout,
+                    )
+                return build
+            except Exception:
+                if build_id is not None and not build_started:
+                    try:
+                        await self.cancel_image_build(build_id)
+                    except Exception:
+                        pass
+                raise
+            finally:
+                await _run_blocking(packaged.cleanup)
+        finally:
+            await _run_blocking(source.cleanup)
+
+    async def _complete_image_build_resilient(
+        self,
+        build_id: str,
+        artifact,
+    ) -> SandboxImageBuild:
+        params = CompleteSandboxImageBuildParams(
+            input_sha256=artifact.sha256_hex,
+            input_size_bytes=artifact.size_bytes,
+            input_format=artifact.input_format,
+        )
+        try:
+            return await self.complete_image_build(build_id, params)
+        except HyperbrowserError as exc:
+            if exc.status_code != 409:
+                raise
+            if "already in progress" in str(exc).lower():
+                return await self.get_image_build(build_id)
+            current = await self.get_image_build(build_id)
+            if current.status not in ("awaiting_upload", "upload_verified"):
+                raise
+            await asyncio.sleep(2)
+            return await self.complete_image_build(build_id, params)
+
+    async def _build_image_from_remote_dockerfile(
+        self,
+        *,
+        context_path,
+        image_name: str,
+        dockerfile,
+        platform: str,
+        remote_full_context: bool,
+        image_init: Optional[Union[SandboxImageInitDict, SandboxImageInit]],
+        image_config_user: Optional[str],
+        wait: bool,
+        poll_interval: float,
+        wait_timeout: Optional[float],
+        temp_dir: Optional[str],
+        upload_timeout: Optional[float],
+    ) -> SandboxImageBuild:
+        packaged = await _run_blocking(
+            package_docker_build_context_manifest,
+            context_path,
+            dockerfile=dockerfile,
+            force_full_context=remote_full_context,
             temp_dir=temp_dir,
         )
+        build_id = None
+        build_started = False
         try:
             normalized_image_init = (
                 coerce_request(image_init, SandboxImageInit, name="image_init")
                 if image_init is not None
-                else artifact.image_init
+                else None
             )
+            artifact = packaged.artifact
             create_result = await self.create_image_build(
                 CreateSandboxImageBuildParams(
                     image_name=image_name,
@@ -585,28 +745,22 @@ class SandboxManager:
                     input_size_bytes=artifact.size_bytes,
                     input_format=artifact.input_format,
                     source_platform=artifact.source_platform,
-                    image_config_user=(
-                        image_config_user
-                        if image_config_user is not None
-                        else artifact.image_config_user
-                    ),
+                    dockerfile_path=packaged.manifest.dockerfile_path,
+                    image_config_user=image_config_user,
                     image_init=normalized_image_init,
+                    context_manifest=packaged.manifest,
                 )
             )
+            build_id = create_result.build.id
             await _run_blocking(
-                upload_image_build_artifact,
-                create_result.upload,
-                artifact.path,
+                upload_missing_image_build_artifacts,
+                create_result.uploads,
+                packaged.bundles,
+                label="build context bundle",
                 timeout=upload_timeout,
             )
-            build = await self.complete_image_build(
-                create_result.build.id,
-                CompleteSandboxImageBuildParams(
-                    input_sha256=artifact.sha256_hex,
-                    input_size_bytes=artifact.size_bytes,
-                    input_format=artifact.input_format,
-                ),
-            )
+            build = await self._complete_image_build_resilient(build_id, artifact)
+            build_started = True
             if wait:
                 return await self.wait_for_image_build(
                     build.id,
@@ -614,8 +768,15 @@ class SandboxManager:
                     timeout=wait_timeout,
                 )
             return build
+        except Exception:
+            if build_id is not None and not build_started:
+                try:
+                    await self.cancel_image_build(build_id)
+                except Exception:
+                    pass
+            raise
         finally:
-            artifact.cleanup()
+            await _run_blocking(packaged.cleanup)
 
     async def build_image_from_dockerfile(
         self,
@@ -623,6 +784,8 @@ class SandboxManager:
         context_path,
         image_name: str,
         dockerfile="Dockerfile",
+        remote: bool = True,
+        remote_full_context: bool = False,
         docker_tag: Optional[str] = None,
         platform: str = IMAGE_BUILD_SOURCE_PLATFORM,
         build_args: Optional[Dict[str, str]] = None,
@@ -634,6 +797,26 @@ class SandboxManager:
         temp_dir: Optional[str] = None,
         upload_timeout: Optional[float] = None,
     ) -> SandboxImageBuild:
+        if remote:
+            if docker_tag is not None or build_args:
+                raise ValueError(
+                    "docker_tag and build_args require remote=False; remote "
+                    "Dockerfile builds send the build context to Hyperbrowser"
+                )
+            return await self._build_image_from_remote_dockerfile(
+                context_path=context_path,
+                image_name=image_name,
+                dockerfile=dockerfile,
+                platform=platform,
+                remote_full_context=remote_full_context,
+                image_init=image_init,
+                image_config_user=image_config_user,
+                wait=wait,
+                poll_interval=poll_interval,
+                wait_timeout=wait_timeout,
+                temp_dir=temp_dir,
+                upload_timeout=upload_timeout,
+            )
         tag = docker_tag or make_temp_docker_tag()
         remove_tag = docker_tag is None
         try:

{hyperbrowser-1.2.2 → hyperbrowser-1.3.0}/hyperbrowser/client/managers/async_manager/volume.py

@@ -4,6 +4,7 @@ from hyperbrowser.client._request import dump_request
 from hyperbrowser.models.volume import (
     CreateVolumeParams,
     Volume,
+    VolumeDeleteResult,
     VolumeListParams,
     VolumeListResponse,
 )
@@ -43,3 +44,10 @@ class VolumeManager:
             self._client._build_url(f"/volume/{volume_id}")
         )
         return Volume(**response.data)
+
+    async def delete(self, volume_id: str) -> VolumeDeleteResult:
+        """Delete a volume by id or name. Ambiguous names and active mounts return 409."""
+        response = await self._client.transport.delete(
+            self._client._build_url(f"/volume/{volume_id}")
+        )
+        return VolumeDeleteResult(**response.data)

hyperbrowser-1.3.0/hyperbrowser/client/managers/sandboxes/dockerfile_analysis.py

@@ -0,0 +1,293 @@
+"""Conservative Dockerfile analysis for remote build context selection.
+
+This module intentionally does not try to execute or fully reproduce the
+BuildKit Dockerfile frontend. It recognizes the context-consuming syntax the
+SDK can analyze safely and requests a full context for anything ambiguous.
+That keeps sparse uploads an optimization rather than a correctness
+requirement.
+"""
+
+import json
+import re
+import shlex
+from typing import Dict, List, Optional, Tuple
+
+
+_KNOWN_INSTRUCTIONS = frozenset(
+    {
+        "ADD",
+        "ARG",
+        "CMD",
+        "COPY",
+        "ENTRYPOINT",
+        "ENV",
+        "EXPOSE",
+        "FROM",
+        "HEALTHCHECK",
+        "LABEL",
+        "MAINTAINER",
+        "ONBUILD",
+        "RUN",
+        "SHELL",
+        "STOPSIGNAL",
+        "USER",
+        "VOLUME",
+        "WORKDIR",
+    }
+)
+_KNOWN_RUN_FLAGS = frozenset({"device", "mount", "network", "security"})
+_INSTRUCTION_PATTERN = re.compile(r"^([A-Za-z]+)(?:[ \t]+(.*))?$")
+_DIRECTIVE_PATTERN = re.compile(
+    r"(?im)^\s*#\s*(?P<name>escape|syntax)\s*=\s*(?P<value>\S+)"
+)
+_FLAG_NAME_PATTERN = re.compile(r"^[a-z][a-z0-9-]*$")
+_SCP_GIT_SOURCE_PATTERN = re.compile(r"^git@[^:/\s]+:.+")
+
+
+class _AnalysisFallback(Exception):
+    def __init__(self, reason: str):
+        super().__init__(reason)
+        self.reason = reason
+
+
+class _DockerfileSourceAnalyzer:
+    def __init__(self, data: bytes):
+        self._data = data
+
+    def analyze(self) -> Tuple[List[List[str]], str]:
+        try:
+            text = self._data.decode("utf-8")
+        except UnicodeDecodeError:
+            return [], "dockerfile_parse_failed"
+
+        try:
+            self._validate_parser_directives(text)
+            # Heredocs are valid BuildKit syntax, but treating the entire
+            # Dockerfile as full context is safer than partially parsing them.
+            if "<<" in text:
+                raise _AnalysisFallback("dockerfile_instruction_parse_failed")
+            logical_lines = self._logical_lines(text)
+            return self._analyze_lines(logical_lines), ""
+        except _AnalysisFallback as exc:
+            return [], exc.reason
+
+    @staticmethod
+    def _validate_parser_directives(text: str) -> None:
+        for match in _DIRECTIVE_PATTERN.finditer(text):
+            name = match.group("name").lower()
+            value = match.group("value")
+            if name == "escape" and value != "\\":
+                raise _AnalysisFallback("dockerfile_parse_failed")
+            if name == "syntax" and not _is_official_dockerfile_frontend(value):
+                raise _AnalysisFallback("custom_dockerfile_frontend")
+
+    @staticmethod
+    def _logical_lines(text: str) -> List[str]:
+        logical_lines = []
+        parts: List[str] = []
+        for raw_line in text.splitlines():
+            stripped = raw_line.strip()
+            if not parts and (not stripped or stripped.startswith("#")):
+                continue
+            if parts and (not stripped or stripped.startswith("#")):
+                # BuildKit has nuanced rules for comments and empty lines in a
+                # continuation. Full context is the safe answer here.
+                raise _AnalysisFallback("dockerfile_parse_failed")
+            if stripped.endswith("\\"):
+                parts.append(stripped[:-1].rstrip())
+                continue
+            parts.append(stripped)
+            logical_lines.append(" ".join(parts))
+            parts = []
+        if parts:
+            raise _AnalysisFallback("dockerfile_parse_failed")
+        return logical_lines
+
+    def _analyze_lines(self, logical_lines: List[str]) -> List[List[str]]:
+        groups = []
+        for line in logical_lines:
+            instruction, body = _parse_instruction(line)
+            if instruction not in _KNOWN_INSTRUCTIONS:
+                raise _AnalysisFallback("dockerfile_instruction_parse_failed")
+            if instruction in ("COPY", "ADD"):
+                group = self._analyze_copy_or_add(instruction, body)
+                if group:
+                    groups.append(group)
+            elif instruction == "RUN":
+                groups.extend(self._analyze_run(body))
+        return groups
+
+    @staticmethod
+    def _analyze_copy_or_add(instruction: str, body: str) -> List[str]:
+        try:
+            flags, values = _parse_copy_add_values(body)
+        except (ValueError, json.JSONDecodeError):
+            raise _AnalysisFallback("dockerfile_instruction_parse_failed")
+
+        if instruction == "COPY" and "from" in flags:
+            return []
+
+        local_sources = []
+        for source in values[:-1]:
+            if "$" in source or "\x00" in source:
+                reason = (
+                    "copy_source_requires_expansion"
+                    if instruction == "COPY"
+                    else "add_source_requires_expansion"
+                )
+                raise _AnalysisFallback(reason)
+            if "\\" in source:
+                # A backslash is a path character on Unix but a separator on
+                # Windows. Full context keeps selection platform-independent.
+                raise _AnalysisFallback("dockerfile_source_path")
+            if instruction == "ADD" and _is_remote_add_source(source):
+                continue
+            if _source_has_pattern(source):
+                # Python glob semantics differ from Go filepath.Match for
+                # dotfiles, character classes, and recursive patterns.
+                raise _AnalysisFallback("dockerfile_source_pattern")
+            local_sources.append(source)
+        return local_sources
+
+    @staticmethod
+    def _analyze_run(body: str) -> List[List[str]]:
+        try:
+            flags, _ = _split_leading_flags(body)
+        except ValueError:
+            raise _AnalysisFallback("run_mount_parse_failed")
+
+        groups = []
+        for name, value in flags:
+            if name not in _KNOWN_RUN_FLAGS:
+                raise _AnalysisFallback("dockerfile_instruction_parse_failed")
+            if name != "mount":
+                continue
+            if not value or any(character in value for character in ('"', "'")):
+                raise _AnalysisFallback("run_mount_parse_failed")
+            options = _parse_mount_options(value)
+            if options.get("type", "bind") != "bind" or options.get("from"):
+                continue
+            source = options.get("source") or options.get("src") or "."
+            if "$" in source or "\x00" in source:
+                raise _AnalysisFallback("run_bind_source_requires_expansion")
+            groups.append([source])
+        return groups
+
+
+def analyze_dockerfile_sources(data: bytes) -> Tuple[List[List[str]], str]:
+    """Return local source groups or a reason to upload the full context."""
+
+    return _DockerfileSourceAnalyzer(data).analyze()
+
+
+def _parse_instruction(line: str) -> Tuple[str, str]:
+    match = _INSTRUCTION_PATTERN.fullmatch(line)
+    if match is None:
+        raise _AnalysisFallback("dockerfile_parse_failed")
+    return match.group(1).upper(), match.group(2) or ""
+
+
+def _parse_copy_add_values(body: str) -> Tuple[Dict[str, str], List[str]]:
+    parsed_flags, remaining = _split_leading_flags(body)
+    flags = dict(parsed_flags)
+    if remaining.startswith("["):
+        values = json.loads(remaining)
+        if not isinstance(values, list) or not all(
+            isinstance(value, str) for value in values
+        ):
+            raise ValueError("invalid JSON COPY/ADD")
+    else:
+        if "\\" in remaining:
+            # BuildKit's shell-form COPY/ADD word splitting is not POSIX shlex.
+            # Backslash-containing forms use the full context rather than risk
+            # selecting a different set of sources.
+            raise ValueError("escaped shell COPY/ADD requires full context")
+        values = shlex.split(remaining, posix=True)
+    if len(values) < 2:
+        raise ValueError("COPY/ADD is missing source or destination")
+    return flags, values
+
+
+def _split_leading_flags(body: str) -> Tuple[List[Tuple[str, str]], str]:
+    flags = []
+    remaining = body.lstrip()
+    while remaining.startswith("--"):
+        raw_token, remaining = _take_word(remaining)
+        decoded = shlex.split(raw_token, posix=True)
+        if len(decoded) != 1 or not decoded[0].startswith("--"):
+            raise ValueError("invalid Dockerfile instruction flag")
+        key, has_value, value = decoded[0][2:].partition("=")
+        key = key.lower()
+        if not _FLAG_NAME_PATTERN.fullmatch(key):
+            raise ValueError("invalid Dockerfile instruction flag")
+        if key == "mount" and any(character in raw_token for character in ('"', "'")):
+            # BuildKit parses mount values as CSV after Dockerfile word
+            # processing. Quoted CSV values are deliberately outside the
+            # subset implemented here.
+            raise ValueError("quoted RUN mount requires full context")
+        flags.append((key, value if has_value else ""))
+        remaining = remaining.lstrip()
+    return flags, remaining
+
+
+def _take_word(value: str) -> Tuple[str, str]:
+    quote: Optional[str] = None
+    escaped = False
+    for index, character in enumerate(value):
+        if escaped:
+            escaped = False
+            continue
+        if character == "\\" and quote != "'":
+            escaped = True
+            continue
+        if quote is not None:
+            if character == quote:
+                quote = None
+            continue
+        if character in ('"', "'"):
+            quote = character
+        elif character.isspace():
+            return value[:index], value[index:]
+    if quote is not None or escaped:
+        raise ValueError("unterminated Dockerfile instruction word")
+    return value, ""
+
+
+def _parse_mount_options(value: str) -> Dict[str, str]:
+    options = {}
+    for field in value.split(","):
+        key, has_value, option_value = field.partition("=")
+        key = key.strip().lower()
+        if not key:
+            raise _AnalysisFallback("run_mount_parse_failed")
+        options[key] = option_value.strip() if has_value else ""
+    return options
+
+
+def _source_has_pattern(source: str) -> bool:
+    return any(character in source for character in ("*", "?", "["))
+
+
+def _is_official_dockerfile_frontend(reference: str) -> bool:
+    normalized = reference.strip()
+    if normalized.startswith("docker-image://"):
+        normalized = normalized[len("docker-image://") :]
+    normalized = normalized.split("@", 1)[0]
+    last_slash = normalized.rfind("/")
+    last_colon = normalized.rfind(":")
+    if last_colon > last_slash:
+        normalized = normalized[:last_colon]
+    return normalized in {
+        "docker/dockerfile",
+        "docker.io/docker/dockerfile",
+        "index.docker.io/docker/dockerfile",
+        "docker/dockerfile-upstream",
+        "docker.io/docker/dockerfile-upstream",
+        "index.docker.io/docker/dockerfile-upstream",
+    }
+
+
+def _is_remote_add_source(source: str) -> bool:
+    if _SCP_GIT_SOURCE_PATTERN.match(source):
+        return True
+    return source.startswith(("http://", "https://", "git://", "ssh://"))