Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

36.4 KB
Raw Blame
#
# Copyright 2025 The OpenSandbox Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
from __future__ import annotations

from datetime import datetime, timedelta

import pytest
from httpx import HTTPStatusError, Request, Response
from pydantic import ValidationError

from opensandbox.adapters.converter.command_execution import (
    build_run_in_session_request_body,
    resolve_run_in_session_timeout,
)
from opensandbox.adapters.converter.exception_converter import (
    ExceptionConverter,
    parse_sandbox_error,
)
from opensandbox.adapters.converter.execution_converter import (
    ExecutionConverter,
)
from opensandbox.adapters.converter.filesystem_model_converter import (
    FilesystemModelConverter,
)
from opensandbox.adapters.converter.metrics_model_converter import (
    MetricsModelConverter,
)
from opensandbox.adapters.converter.response_handler import (
    handle_api_error,
    require_parsed,
)
from opensandbox.adapters.converter.sandbox_model_converter import (
    SandboxModelConverter,
)
from opensandbox.api.lifecycle.errors import UnexpectedStatus
from opensandbox.exceptions import (
    InvalidArgumentException,
    SandboxApiException,
    SandboxInternalException,
    SandboxRateLimitException,
)
from opensandbox.models.execd import RunCommandOpts
from opensandbox.models.sandboxes import (
    CredentialProxyConfig,
    LifecycleHook,
    NetworkPolicy,
    NetworkRule,
    PeriodicLifecycleHook,
    PlatformSpec,
    SandboxImageSpec,
    SandboxLifecycle,
)


def test_parse_sandbox_error_from_json_bytes() -> None:
    err = parse_sandbox_error(b'{"code":"X","message":"m"}')
    assert err is not None
    assert err.code == "X"
    assert err.message == "m"


def test_parse_sandbox_error_from_plain_text_string() -> None:
    err = parse_sandbox_error("not-json")
    assert err is not None
    assert err.code == "UNEXPECTED_RESPONSE"
    assert err.message == "not-json"


def test_parse_sandbox_error_from_invalid_utf8_bytes_fallback_message() -> None:
    err = parse_sandbox_error(b"\xff\xfe")
    assert err is not None
    assert err.code == "UNEXPECTED_RESPONSE"
    assert err.message is not None
    assert "\ufffd" in err.message


def test_handle_api_error_raises_with_parsed_message() -> None:
    class Parsed:
        code = "BAD_REQUEST"
        message = "bad request"

    class Resp:
        status_code = 400
        parsed = Parsed()
        headers = {"X-Request-ID": "req-123"}

    with pytest.raises(SandboxApiException) as ei:
        handle_api_error(Resp(), "Op")
    assert "bad request" in str(ei.value)
    assert ei.value.request_id == "req-123"
    assert ei.value.error.code == "BAD_REQUEST"
    assert ei.value.error.message == "bad request"


def test_handle_api_error_noop_on_success() -> None:
    class Resp:
        status_code = 200
        parsed = None

    handle_api_error(Resp(), "Op")


def test_handle_api_error_raises_rate_limit_on_429() -> None:
    from opensandbox.exceptions import SandboxRateLimitException

    class Resp:
        status_code = 429
        parsed = None
        headers = {"X-Request-ID": "req-abc", "Retry-After": "12"}

    with pytest.raises(SandboxRateLimitException) as ei:
        handle_api_error(Resp(), "Op")
    assert ei.value.status_code == 429
    assert ei.value.retry_after == timedelta(seconds=12)
    assert ei.value.request_id == "req-abc"
    # 429 is a transient class; is_retryable is machine-checkable.
    assert ei.value.is_retryable is True
    # Backward-compatible: still catchable as SandboxApiException.
    assert isinstance(ei.value, SandboxApiException)


def test_handle_api_error_sets_is_retryable_by_status() -> None:
    from opensandbox.exceptions import SandboxApiException

    # 502/503 are transient -> is_retryable True; 500/4xx -> False.
    for code, expected in [(502, True), (503, True), (500, False), (404, False)]:

        class Resp:
            status_code = code
            parsed = None
            headers: dict[str, str] = {}

        with pytest.raises(SandboxApiException) as ei:
            handle_api_error(Resp(), "Op")
        assert ei.value.is_retryable is expected, f"status {code}"


def test_to_sandbox_exception_connection_is_retryable() -> None:
    import httpx

    from opensandbox.adapters.converter.exception_converter import (
        ExceptionConverter,
    )
    from opensandbox.exceptions import SandboxConnectionException

    mapped = ExceptionConverter.to_sandbox_exception(
        httpx.ConnectError("dns down")
    )
    assert isinstance(mapped, SandboxConnectionException)
    assert mapped.is_retryable is True


def test_handle_api_error_rate_limit_without_retry_after_header() -> None:
    from opensandbox.exceptions import SandboxRateLimitException

    class Resp:
        status_code = 429
        parsed = None
        headers: dict[str, str] = {}

    with pytest.raises(SandboxRateLimitException) as ei:
        handle_api_error(Resp(), "Op")
    assert ei.value.retry_after is None


def test_handle_api_error_attaches_raw_response_body() -> None:
    body = b'{"whatever": "server text"}'

    class Resp:
        status_code = 500
        parsed = None
        headers: dict[str, str] = {}
        content = body

    with pytest.raises(SandboxApiException) as ei:
        handle_api_error(Resp(), "Op")
    # Raw body preserved untruncated on the exception.
    assert ei.value.response_body == body
    # And spliced into str() so logs surface the server's own message.
    assert "server text" in str(ei.value)


def test_handle_api_error_rate_limit_preserves_raw_body_when_unparsed() -> None:
    from opensandbox.exceptions import SandboxRateLimitException

    body = b"quota exhausted for tenant foo"

    class Resp:
        status_code = 429
        parsed = None
        headers: dict[str, str] = {"Retry-After": "5"}
        content = body

    with pytest.raises(SandboxRateLimitException) as ei:
        handle_api_error(Resp(), "Acquire")
    assert ei.value.response_body == body
    assert ei.value.retry_after == timedelta(seconds=5)
    assert "quota exhausted for tenant foo" in str(ei.value)


def test_handle_api_error_truncates_long_raw_body_in_message() -> None:
    body = b"x" * 2000

    class Resp:
        status_code = 502
        parsed = None
        headers: dict[str, str] = {}
        content = body

    with pytest.raises(SandboxApiException) as ei:
        handle_api_error(Resp(), "Op")
    # Full body still available on the exception field.
    assert ei.value.response_body == body
    # str() is truncated with an ellipsis marker.
    assert "…" in str(ei.value)
    assert len(str(ei.value)) < 1500


def test_handle_api_error_prefers_parsed_message_over_raw_body() -> None:
    class Parsed:
        code = "BAD_REQUEST"
        message = "structured message"

    class Resp:
        status_code = 400
        parsed = Parsed()
        headers: dict[str, str] = {}
        content = b"{unparsed raw body}"

    with pytest.raises(SandboxApiException) as ei:
        handle_api_error(Resp(), "Op")
    # Structured message wins; raw body is not spliced.
    assert "structured message" in str(ei.value)
    assert "unparsed raw body" not in str(ei.value)
    # But the raw body is still attached for callers that want it.
    assert ei.value.response_body == b"{unparsed raw body}"


def test_build_api_exception_from_httpx_maps_429_to_rate_limit() -> None:
    from opensandbox.adapters.converter.response_handler import (
        build_api_exception_from_httpx,
    )
    from opensandbox.exceptions import SandboxRateLimitException

    class Resp:
        status_code = 429
        headers = {"Retry-After": "3", "X-Request-ID": "req-xyz"}
        content = b'{"code":"QUOTA","message":"too many"}'

    exc = build_api_exception_from_httpx(Resp(), "Isolated create")
    assert isinstance(exc, SandboxRateLimitException)
    assert exc.status_code == 429
    assert exc.retry_after == timedelta(seconds=3)
    assert exc.request_id == "req-xyz"
    assert exc.response_body == b'{"code":"QUOTA","message":"too many"}'
    assert "too many" in str(exc)


def test_build_api_exception_from_httpx_500_is_api_exception() -> None:
    from opensandbox.adapters.converter.response_handler import (
        build_api_exception_from_httpx,
    )
    from opensandbox.exceptions import (
        SandboxApiException,
        SandboxRateLimitException,
    )

    class Resp:
        status_code = 500
        headers: dict[str, str] = {}
        content = b"internal explosion"

    exc = build_api_exception_from_httpx(Resp(), "Isolated attach")
    assert isinstance(exc, SandboxApiException)
    assert not isinstance(exc, SandboxRateLimitException)
    assert exc.response_body == b"internal explosion"
    assert "internal explosion" in str(exc)


def test_exception_converter_maps_read_timeout_to_timeout_exception() -> None:
    import httpx

    from opensandbox.adapters.converter.exception_converter import ExceptionConverter
    from opensandbox.exceptions import SandboxTimeoutException

    exc = ExceptionConverter.to_sandbox_exception(httpx.ReadTimeout("slow"))
    assert isinstance(exc, SandboxTimeoutException)
    assert "slow" in str(exc)


def test_exception_converter_maps_connect_error_to_connection_exception() -> None:
    import httpx

    from opensandbox.adapters.converter.exception_converter import ExceptionConverter
    from opensandbox.exceptions import SandboxConnectionException

    exc = ExceptionConverter.to_sandbox_exception(httpx.ConnectError("boom"))
    assert isinstance(exc, SandboxConnectionException)
    assert "boom" in str(exc)


def test_exception_converter_maps_connect_timeout_to_connection_exception() -> None:
    import httpx

    from opensandbox.adapters.converter.exception_converter import ExceptionConverter
    from opensandbox.exceptions import (
        SandboxConnectionException,
        SandboxTimeoutException,
    )

    exc = ExceptionConverter.to_sandbox_exception(httpx.ConnectTimeout("dial"))
    # ConnectTimeout is dispatched to Connection, not Timeout, because
    # it happens before any bytes are on the wire.
    assert isinstance(exc, SandboxConnectionException)
    assert not isinstance(exc, SandboxTimeoutException)


def test_exception_converter_maps_unexpected_status_429_to_rate_limit() -> None:
    from opensandbox.adapters.converter.exception_converter import ExceptionConverter
    from opensandbox.api.execd.errors import UnexpectedStatus
    from opensandbox.exceptions import SandboxRateLimitException

    exc = ExceptionConverter.to_sandbox_exception(
        UnexpectedStatus(status_code=429, content=b'{"code":"QUOTA"}')
    )
    assert isinstance(exc, SandboxRateLimitException)
    assert exc.status_code == 429
    assert exc.response_body == b'{"code":"QUOTA"}'


def test_exception_converter_maps_httpx_status_error_429_to_rate_limit() -> None:
    import httpx

    from opensandbox.adapters.converter.exception_converter import ExceptionConverter
    from opensandbox.exceptions import SandboxRateLimitException

    response = httpx.Response(
        status_code=429,
        headers={"Retry-After": "7", "X-Request-ID": "req-1"},
        content=b'{"code":"QUOTA"}',
        request=httpx.Request("GET", "http://x"),
    )
    err = httpx.HTTPStatusError("429", request=response.request, response=response)
    exc = ExceptionConverter.to_sandbox_exception(err)
    assert isinstance(exc, SandboxRateLimitException)
    assert exc.retry_after == timedelta(seconds=7)
    assert exc.request_id == "req-1"


def test_require_parsed_includes_request_id_on_invalid_payload() -> None:
    class Resp:
        status_code = 200
        parsed = None
        headers = {"x-request-id": "req-456"}

    with pytest.raises(SandboxApiException) as ei:
        require_parsed(Resp(), expected_type=str, operation_name="Op")
    assert ei.value.request_id == "req-456"


def test_exception_converter_maps_common_types() -> None:
    se = ExceptionConverter.to_sandbox_exception(ValueError("x"))
    assert isinstance(se, InvalidArgumentException)

    se2 = ExceptionConverter.to_sandbox_exception(OSError("x"))
    assert isinstance(se2, SandboxInternalException)


def test_exception_converter_maps_generated_unexpected_status_to_api_exception() -> (
    None
):
    err = UnexpectedStatus(400, b'{"code":"X","message":"bad"}')

    converted = ExceptionConverter.to_sandbox_exception(err)

    assert isinstance(converted, SandboxApiException)
    assert converted.status_code == 400
    assert converted.error is not None
    assert converted.error.code == "X"


def test_exception_converter_splices_unstructured_body_into_message() -> None:
    body = b'{"error": "invalid parameter"}'  # JSON without code/message envelope
    err = UnexpectedStatus(400, body)

    converted = ExceptionConverter.to_sandbox_exception(err)

    assert isinstance(converted, SandboxApiException)
    assert converted.status_code == 400
    # The raw body is spliced into str()/message so logs show the server reason.
    assert '{"error": "invalid parameter"}' in str(converted)
    # Full body still available on the exception field.
    assert converted.response_body == body


def test_exception_converter_splices_plain_text_body_into_message() -> None:
    body = b"cursor must be positive"
    err = UnexpectedStatus(400, body)

    converted = ExceptionConverter.to_sandbox_exception(err)

    assert isinstance(converted, SandboxApiException)
    assert "cursor must be positive" in str(converted)
    assert converted.response_body == body


def test_exception_converter_maps_unstructured_429_body_into_message() -> None:
    body = b"quota exhausted for tenant foo"
    err = UnexpectedStatus(429, body)

    converted = ExceptionConverter.to_sandbox_exception(err)

    assert isinstance(converted, SandboxRateLimitException)
    assert "quota exhausted for tenant foo" in str(converted)
    assert converted.response_body == body


def test_exception_converter_truncates_long_unstructured_body_in_message() -> None:
    body = b"x" * 2000
    err = UnexpectedStatus(502, body)

    converted = ExceptionConverter.to_sandbox_exception(err)

    assert isinstance(converted, SandboxApiException)
    assert converted.response_body == body
    assert "…" in str(converted)
    assert len(str(converted)) < 1500


def test_exception_converter_preserves_structured_code_without_message() -> None:
    err = UnexpectedStatus(429, b'{"code":"QUOTA"}')

    converted = ExceptionConverter.to_sandbox_exception(err)

    assert isinstance(converted, SandboxRateLimitException)
    # Structured code is preserved even when the body has no message field.
    assert converted.error is not None
    assert converted.error.code == "QUOTA"


def test_exception_converter_maps_httpx_status_error_to_api_exception() -> None:
    request = Request("GET", "https://example.test")
    response = Response(
        502, request=request, content=b'{"code":"UPSTREAM","message":"gateway"}'
    )
    err = HTTPStatusError("bad gateway", request=request, response=response)

    converted = ExceptionConverter.to_sandbox_exception(err)

    assert isinstance(converted, SandboxApiException)
    assert converted.status_code == 502
    assert converted.error is not None
    assert converted.error.code == "UPSTREAM"


def test_execution_converter_to_api_run_command_request() -> None:
    from opensandbox.api.execd.types import UNSET

    api = ExecutionConverter.to_api_run_command_request("echo hi", RunCommandOpts())
    d = api.to_dict()
    assert d["command"] == "echo hi"
    assert "cwd" not in d

    api2 = ExecutionConverter.to_api_run_command_request(
        "echo hi",
        RunCommandOpts(working_directory="/tmp"),
    )
    d2 = api2.to_dict()
    assert d2["cwd"] == "/tmp"
    # background defaults to False in domain opts; when False we omit it from the API request.
    assert d2.get("background", UNSET) is UNSET

    from datetime import timedelta

    api3 = ExecutionConverter.to_api_run_command_request(
        "sleep 10",
        RunCommandOpts(timeout=timedelta(seconds=60)),
    )
    d3 = api3.to_dict()
    assert d3["command"] == "sleep 10"
    assert d3["timeout"] == 60_000
    # timeout omitted when not set (backward compat)
    assert (
        "timeout"
        not in ExecutionConverter.to_api_run_command_request(
            "x", RunCommandOpts()
        ).to_dict()
    )

    api4 = ExecutionConverter.to_api_run_command_request(
        "id",
        RunCommandOpts(
            uid=1000,
            gid=1000,
            envs={"APP_ENV": "test", "LOG_LEVEL": "debug"},
        ),
    )
    d4 = api4.to_dict()
    assert d4["uid"] == 1000
    assert d4["gid"] == 1000
    assert d4["envs"] == {"APP_ENV": "test", "LOG_LEVEL": "debug"}
    assert "cwd" not in d4


    argv = ["tool", "", "a b", "$HOME", "x'y", "中文"]
    native = ExecutionConverter.to_api_run_command_request(
        argv, RunCommandOpts(background=True, working_directory="$DIR", envs={"DIR": "/tmp"})
    ).to_dict()
    assert native == {"argv": argv, "background": True, "cwd": "$DIR", "envs": {"DIR": "/tmp"}}
    for invalid in ([], [""], ["tool", "\0"], ["tool", None], ("tool", "arg"), None, 123):
        with pytest.raises(InvalidArgumentException):
            ExecutionConverter.to_api_run_command_request(invalid, RunCommandOpts())

    # Shell-sensitive values (a literal "$HOME", an embedded space, a single
    # quote, a trailing empty string) travel in `argv` untouched.
    literal_argv = ["python3", "-c", "import sys; print(sys.argv[1:])", "a b", "$HOME", "x'y", ""]
    literal_request = ExecutionConverter.to_api_run_command_request(
        literal_argv, RunCommandOpts()
    ).to_dict()
    assert literal_request == {"argv": literal_argv}


@pytest.mark.parametrize(
    ("microseconds", "expected"),
    [
        (None, None),
        (0, 0),
        (1, 1),
        (500, 1),
        (900, 1),
        (999, 1),
        (1000, 1),
        (1001, 2),
        (1200, 2),
        (1_001_000, 1001),
        (2_007_000, 2007),
        (60_000_000, 60_000),
    ],
)
def test_execution_converter_rounds_timeout_up_to_milliseconds(
    microseconds: int | None, expected: int | None
) -> None:
    timeout = timedelta(microseconds=microseconds) if microseconds is not None else None
    request = ExecutionConverter.to_api_run_command_request(
        "sleep 10", RunCommandOpts(timeout=timeout)
    ).to_dict()

    if expected is None:
        assert "timeout" not in request
    else:
        assert request["timeout"] == expected


@pytest.mark.parametrize(
    ("microseconds", "expected"),
    [
        (None, None),
        (0, 0),
        (1, 1),
        (500, 1),
        (900, 1),
        (999, 1),
        (1000, 1),
        (1001, 2),
        (1200, 2),
        (1_001_000, 1001),
        (2_007_000, 2007),
        (60_000_000, 60_000),
    ],
)
def test_run_in_session_converter_rounds_timeout_up_to_milliseconds(
    microseconds: int | None, expected: int | None
) -> None:
    timeout = timedelta(microseconds=microseconds) if microseconds is not None else None
    timeout_ms = resolve_run_in_session_timeout(timeout)
    assert timeout_ms == expected
    request = build_run_in_session_request_body("sleep 10", None, timeout_ms).to_dict()

    if expected is None:
        assert "timeout" not in request
    else:
        assert request["timeout"] == expected


@pytest.mark.parametrize("microseconds", [-1, -999, -1000])
def test_execution_converter_rejects_negative_timeout(microseconds: int) -> None:
    with pytest.raises(InvalidArgumentException, match="^timeout must be positive"):
        ExecutionConverter.to_api_run_command_request(
            "sleep 10", RunCommandOpts(timeout=timedelta(microseconds=microseconds))
        )


@pytest.mark.parametrize("microseconds", [-1, -999, -1000])
def test_run_in_session_converter_rejects_negative_timeout(microseconds: int) -> None:
    with pytest.raises(InvalidArgumentException, match="^timeout must not be negative"):
        resolve_run_in_session_timeout(timedelta(microseconds=microseconds))


def test_run_command_opts_validates_gid_requires_uid() -> None:
    with pytest.raises(ValueError, match="uid is required when gid is provided"):
        RunCommandOpts(gid=1000)


def test_filesystem_and_metrics_converters() -> None:
    from datetime import datetime, timezone

    from opensandbox.api.execd.models import FileInfo, Metrics

    fi = FileInfo(
        path="/a",
        mode=644,
        owner="u",
        group="g",
        size=1,
        modified_at=datetime(2025, 1, 1, tzinfo=timezone.utc),
        created_at=datetime(2025, 1, 1, tzinfo=timezone.utc),
    )
    entry = FilesystemModelConverter.to_entry_info(fi)
    assert entry.path == "/a"

    api_metrics = Metrics(
        cpu_count=1.0,
        cpu_used_pct=2.0,
        mem_total_mib=3.0,
        mem_used_mib=4.0,
        timestamp=5,
    )
    m = MetricsModelConverter.to_sandbox_metrics(api_metrics)
    assert m.cpu_used_percentage == 2.0


def test_sandbox_model_converter_to_api_create_request_and_renew_tz() -> None:
    from datetime import timezone

    spec = SandboxImageSpec("python:3.11")
    req = SandboxModelConverter.to_api_create_sandbox_request(
        spec=spec,
        entrypoint=["/bin/sh"],
        env={},
        metadata={},
        timeout=timedelta(seconds=3),
        resource={"cpu": "100m"},
        platform=PlatformSpec(os="linux", arch="arm64"),
        network_policy=NetworkPolicy(
            defaultAction="deny",
            egress=[NetworkRule(action="allow", target="pypi.org")],
        ),
        extensions={},
        volumes=None,
        credential_proxy=CredentialProxyConfig(enabled=True),
        lifecycle=SandboxLifecycle(
            preStart=LifecycleHook(
                command=["/opt/hooks/restore.sh"],
                timeoutSeconds=30,
            ),
            periodic=[
                PeriodicLifecycleHook(
                    name="checkpoint",
                    schedule="@hourly",
                    command=["/opt/hooks/checkpoint.sh"],
                )
            ],
        ),
    )
    d = req.to_dict()
    assert d["image"]["uri"] == "python:3.11"
    assert d["timeout"] == 3
    assert "env" not in d
    assert "metadata" not in d
    assert d["platform"] == {"os": "linux", "arch": "arm64"}
    assert d["networkPolicy"]["defaultAction"] == "deny"
    assert d["networkPolicy"]["egress"] == [{"action": "allow", "target": "pypi.org"}]
    assert d["credentialProxy"] == {"enabled": True}
    assert d["lifecycle"] == {
        "preStart": {
            "command": ["/opt/hooks/restore.sh"],
            "timeoutSeconds": 30,
        },
        "periodic": [
            {
                "name": "checkpoint",
                "schedule": "@hourly",
                "command": ["/opt/hooks/checkpoint.sh"],
            }
        ],
    }

    renew = SandboxModelConverter.to_api_renew_request(datetime(2025, 1, 1))
    assert renew.expires_at.tzinfo is timezone.utc


def test_sandbox_model_converter_serializes_port_scoped_rules() -> None:
    """A domain-only rule, an IP+ports rule, and a target-less port-only rule
    must all round-trip to the wire shape the egress sidecar expects: the
    port-only rule's `target` key must be entirely absent (not null), since
    the generated client uses its own UNSET sentinel to mean "omit this key".
    """
    req = SandboxModelConverter.to_api_create_sandbox_request(
        spec=SandboxImageSpec("python:3.11"),
        entrypoint=["/bin/sh"],
        env={},
        metadata={},
        timeout=None,
        resource={},
        platform=None,
        network_policy=NetworkPolicy(
            defaultAction="deny",
            egress=[
                NetworkRule(action="allow", target="pypi.org"),
                NetworkRule(action="allow", target="10.0.0.5", ports=[22, 80]),
                NetworkRule(action="deny", ports=[25]),
            ],
        ),
        extensions={},
        volumes=None,
    )
    d = req.to_dict()
    assert d["networkPolicy"]["egress"] == [
        {"action": "allow", "target": "pypi.org"},
        {"action": "allow", "target": "10.0.0.5", "ports": [22, 80]},
        {"action": "deny", "ports": [25]},
    ]

    # Round-trip back through the reverse converter (as done for GET /policy
    # responses) must reconstruct the same domain rules, target=None for the
    # port-only rule instead of the generated client's UNSET sentinel.
    from opensandbox.api.lifecycle.models.network_policy import (
        NetworkPolicy as ApiNetworkPolicy,
    )

    api_policy = ApiNetworkPolicy.from_dict(d["networkPolicy"])
    roundtripped = SandboxModelConverter.to_sandbox_network_policy(api_policy)
    assert roundtripped.egress[2].target is None
    assert roundtripped.egress[2].ports == [25]


def test_network_rule_requires_target_or_ports() -> None:
    with pytest.raises(ValidationError):
        NetworkRule(action="allow")


def test_network_rule_read_back_tolerates_sidecar_blank_target() -> None:
    """The sidecar marshals target without omitempty, so a port-only rule
    reads back as {"target": "", "ports": [25]}; the domain model must parse
    it (blank => omitted) instead of raising a blank-target error."""
    rule = NetworkRule.model_validate({"action": "deny", "target": "", "ports": [25]})
    assert rule.target is None
    assert rule.ports == [25]


def test_network_rule_rejects_more_than_256_ports() -> None:
    with pytest.raises(ValidationError):
        NetworkRule(action="allow", ports=list(range(1, 258)))


def test_network_rule_rejects_invalid_ports() -> None:
    for bad_ports in ([0], [65536], [443, 443], []):
        with pytest.raises(ValidationError):
            NetworkRule(action="allow", target="10.0.0.5", ports=bad_ports)


def test_network_rule_rejects_domain_target_with_ports() -> None:
    """The sidecar rejects domain+ports (DNS-layer rules have no port
    dimension); surfacing that as a local ValidationError beats a 4xx after
    the sandbox create request is already in flight."""
    for target in ("example.com", "*.example.com", "10.0.0.0/255.0.0.0"):
        with pytest.raises(ValidationError):
            NetworkRule(action="allow", target=target, ports=[443])


def test_sandbox_model_converter_omits_empty_lifecycle() -> None:
    req = SandboxModelConverter.to_api_create_sandbox_request(
        spec=SandboxImageSpec("python:3.11"),
        entrypoint=["python"],
        env={},
        metadata={},
        timeout=None,
        resource={},
        platform=None,
        network_policy=None,
        extensions={},
        volumes=None,
        lifecycle=SandboxLifecycle(),
    )

    assert "lifecycle" not in req.to_dict()

    req = SandboxModelConverter.to_api_create_sandbox_request(
        spec=SandboxImageSpec("python:3.11"),
        entrypoint=["python"],
        env={},
        metadata={},
        timeout=None,
        resource={},
        platform=None,
        network_policy=None,
        extensions={},
        volumes=None,
        lifecycle=SandboxLifecycle(
            preStart=LifecycleHook(command=["true"]),
            periodic=[],
        ),
    )

    assert req.to_dict()["lifecycle"] == {"preStart": {"command": ["true"]}}


def test_platform_spec_accepts_windows() -> None:
    platform = PlatformSpec(os="windows", arch="amd64")
    assert platform.os == "windows"
    assert platform.arch == "amd64"


def test_sandbox_model_converter_preserves_null_timeout_for_manual_cleanup() -> None:
    req = SandboxModelConverter.to_api_create_sandbox_request(
        spec=SandboxImageSpec("python:3.11"),
        entrypoint=["/bin/sh"],
        env={},
        metadata={},
        timeout=None,
        resource={"cpu": "100m"},
        platform=None,
        network_policy=None,
        extensions={},
        volumes=None,
    )

    dumped = req.to_dict()
    assert dumped["timeout"] is None


def test_sandbox_model_converter_snapshot_restore_request() -> None:
    req = SandboxModelConverter.to_api_create_sandbox_request(
        spec=None,
        entrypoint=None,
        env={},
        metadata={},
        timeout=None,
        resource={"cpu": "100m"},
        platform=None,
        network_policy=None,
        extensions={},
        volumes=None,
        snapshot_id="snap-123",
    )

    dumped = req.to_dict()
    assert dumped["snapshotId"] == "snap-123"
    assert "image" not in dumped
    assert "entrypoint" not in dumped

def test_sandbox_model_converter_to_api_volume_skips_unset_fields() -> None:
    from opensandbox.api.lifecycle.types import UNSET
    from opensandbox.models.sandboxes import Volume

    # Inject UNSET into backend fields (bypassing Pydantic validation) to
    # simulate a domain Volume carrying Unset values from an API round-trip.
    volume = Volume.model_construct(
        name="workdir",
        mount_path="/mnt/work",
        read_only=False,
        host=UNSET,
        pvc=UNSET,
        ossfs=UNSET,
        sub_path=UNSET,
    )

    api_volume = SandboxModelConverter.to_api_volume(volume)
    dumped = api_volume.to_dict()
    assert dumped == {"name": "workdir", "mountPath": "/mnt/work", "readOnly": False}
    assert "host" not in dumped
    assert "pvc" not in dumped
    assert "ossfs" not in dumped
    assert "subPath" not in dumped

def test_sandbox_model_converter_to_api_volume_maps_backends() -> None:
    from opensandbox.models.sandboxes import OSSFS, PVC, Host, Volume

    volume = Volume(
        name="workdir",
        host=Host(path="/data/opensandbox"),
        mount_path="/mnt/work",
        sub_path="sub",
    )
    dumped = SandboxModelConverter.to_api_volume(volume).to_dict()
    assert dumped["host"] == {"path": "/data/opensandbox"}
    assert dumped["subPath"] == "sub"
    assert "pvc" not in dumped
    assert "ossfs" not in dumped

    pvc_volume = Volume(
        name="models",
        pvc=PVC(claim_name="shared-models-pvc"),
        mount_path="/mnt/models",
        read_only=True,
    )
    pvc_dumped = SandboxModelConverter.to_api_volume(pvc_volume).to_dict()
    assert pvc_dumped["pvc"]["claimName"] == "shared-models-pvc"
    assert pvc_dumped["readOnly"] is True

    ossfs_volume = Volume(
        name="oss", ossfs=OSSFS(
            bucket="b",
            endpoint="oss-cn-hangzhou.aliyuncs.com",
            accessKeyId="ak",
            accessKeySecret="sk",
        ),
        mount_path="/mnt/oss",
    )
    ossfs_dumped = SandboxModelConverter.to_api_volume(ossfs_volume).to_dict()
    assert ossfs_dumped["ossfs"]["bucket"] == "b"

def test_sandbox_model_converter_maps_platform_from_create_response() -> None:
    from opensandbox.api.lifecycle.models.create_sandbox_response import (
        CreateSandboxResponse,
    )
    from opensandbox.api.lifecycle.models.create_sandbox_response_extensions import (
        CreateSandboxResponseExtensions,
    )
    from opensandbox.api.lifecycle.models.platform_spec import (
        PlatformSpec as ApiPlatformSpec,
    )
    from opensandbox.api.lifecycle.models.sandbox_status import SandboxStatus

    api_response = CreateSandboxResponse(
        id="sbx-1",
        status=SandboxStatus(state="Running"),
        platform=ApiPlatformSpec(os="linux", arch="arm64"),
        extensions=CreateSandboxResponseExtensions.from_dict(
            {"opensandbox.extensions.custom-label": "中文数据"}
        ),
        created_at=datetime(2025, 1, 1),
        entrypoint=["/bin/sh"],
    )

    converted = SandboxModelConverter.to_sandbox_create_response(api_response)
    assert converted.platform is not None
    assert converted.platform.arch == "arm64"
    assert converted.extensions == {"opensandbox.extensions.custom-label": "中文数据"}


def test_sandbox_model_converter_preserves_missing_metadata_default() -> None:
    from opensandbox.api.lifecycle.models.sandbox import Sandbox
    from opensandbox.api.lifecycle.models.sandbox_status import SandboxStatus

    api_sandbox = Sandbox(
        id="sbx-1",
        status=SandboxStatus(state="Running"),
        created_at=datetime(2025, 1, 1),
        entrypoint=["/bin/sh"],
    )

    converted = SandboxModelConverter.to_sandbox_info(api_sandbox)
    assert converted.metadata == {}
    assert converted.extensions is None
    assert converted.allocation is None


def test_sandbox_model_converter_maps_allocation() -> None:
    from opensandbox.api.lifecycle.models.allocation_summary import AllocationSummary
    from opensandbox.api.lifecycle.models.allocation_summary_mode import (
        AllocationSummaryMode,
    )
    from opensandbox.api.lifecycle.models.allocation_summary_state import (
        AllocationSummaryState,
    )
    from opensandbox.api.lifecycle.models.sandbox import Sandbox
    from opensandbox.api.lifecycle.models.sandbox_status import SandboxStatus

    api_sandbox = Sandbox(
        id="sbx-1",
        status=SandboxStatus(state="Running"),
        created_at=datetime(2025, 1, 1),
        entrypoint=["/bin/sh"],
        allocation=AllocationSummary(
            mode=AllocationSummaryMode.POOL,
            pool_ref="default/python",
            state=AllocationSummaryState.ALLOCATED,
        ),
    )

    converted = SandboxModelConverter.to_sandbox_info(api_sandbox)
    assert converted.allocation is not None
    assert converted.allocation.mode == "pool"
    assert converted.allocation.pool_ref == "default/python"
    assert converted.allocation.state == "allocated"


def test_sandbox_model_converter_maps_allocation_for_list_results() -> None:
    from opensandbox.api.lifecycle.models.allocation_summary import AllocationSummary
    from opensandbox.api.lifecycle.models.allocation_summary_mode import (
        AllocationSummaryMode,
    )
    from opensandbox.api.lifecycle.models.allocation_summary_state import (
        AllocationSummaryState,
    )
    from opensandbox.api.lifecycle.models.list_sandboxes_response import (
        ListSandboxesResponse,
    )
    from opensandbox.api.lifecycle.models.pagination_info import PaginationInfo
    from opensandbox.api.lifecycle.models.sandbox import Sandbox
    from opensandbox.api.lifecycle.models.sandbox_status import SandboxStatus

    api_response = ListSandboxesResponse(
        items=[
            Sandbox(
                id="sbx-1",
                status=SandboxStatus(state="Running"),
                created_at=datetime(2025, 1, 1),
                entrypoint=["/bin/sh"],
                allocation=AllocationSummary(
                    mode=AllocationSummaryMode.POOL,
                    pool_ref="default/python",
                    state=AllocationSummaryState.ALLOCATED,
                ),
            )
        ],
        pagination=PaginationInfo(
            page=1,
            page_size=10,
            total_items=1,
            total_pages=1,
            has_next_page=False,
        ),
    )

    converted = SandboxModelConverter.to_paged_sandbox_infos(api_response)
    assert converted.sandbox_infos[0].allocation is not None
    assert converted.sandbox_infos[0].allocation.pool_ref == "default/python"


def test_sandbox_model_converter_supports_windows_platform_request() -> None:
    req = SandboxModelConverter.to_api_create_sandbox_request(
        spec=SandboxImageSpec("dockurr/windows:latest"),
        entrypoint=["cmd", "/c", "echo hi"],
        env={},
        metadata={},
        timeout=timedelta(seconds=3),
        resource={"cpu": "2", "memory": "4G"},
        platform=PlatformSpec(os="windows", arch="amd64"),
        network_policy=None,
        extensions={},
        volumes=None,
    )
    dumped = req.to_dict()
    assert dumped["platform"] == {"os": "windows", "arch": "amd64"}


def test_network_rule_trims_target_before_classification() -> None:
    """The sidecar trims before classifying; " 10.0.0.5" with ports must be
    an IP locally too, not a misleading domain+ports rejection."""
    rule = NetworkRule(action="allow", target="  10.0.0.5  ", ports=[22])
    assert rule.target == "10.0.0.5"
    with pytest.raises(ValidationError):
        NetworkRule(action="allow", target="  example.com  ", ports=[443])


def test_network_rule_scoped_ipv6_prefix_with_ports_rejected() -> None:
    """netip.ParsePrefix rejects scoped prefixes while Python's ipaddress
    accepts them; the SDK must mirror the sidecar or a valid-looking rule
    dies remotely as a domain+ports 400."""
    with pytest.raises(ValidationError):
        NetworkRule(action="allow", target="fe80::1%eth0/64", ports=[22])
    rule = NetworkRule(action="allow", target="fe80::1%eth0", ports=[22])
    assert rule.target == "fe80::1%eth0"