Skip to content

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

42.0 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.

import pytest
from pydantic import ValidationError

from opensandbox_server.api.schema import (
    CreateSandboxRequest,
    CreateSnapshotRequest,
    CredentialProxyConfig,
    Host,
    ImageSpec,
    ListSnapshotsRequest,
    LifecycleHook,
    NetworkPolicy,
    NetworkRule,
    OSSFS,
    PaginationInfo,
    PaginationRequest,
    PeriodicLifecycleHook,
    PlatformSpec,
    PVC,
    RenewalPolicy,
    ResourceLimits,
    SandboxLifecycle,
    Snapshot,
    SnapshotFilter,
    SnapshotStatus,
    Volume,
)
from opensandbox_server.constants import OPENSANDBOX_LIFECYCLE


class TestSandboxLifecycle:

    def test_create_request_parses_lifecycle_aliases(self):
        request = CreateSandboxRequest.model_validate(
            {
                "image": {"uri": "python:3.11"},
                "entrypoint": ["python"],
                "resourceLimits": {},
                "lifecycle": {
                    "preStart": {
                        "command": ["/opt/hooks/restore.sh"],
                        "timeoutSeconds": 30,
                    },
                    "periodic": [
                        {
                            "name": " checkpoint ",
                            "schedule": " */5 * * * * ",
                            "command": ["/opt/hooks/checkpoint.sh"],
                        }
                    ],
                },
            }
        )

        assert request.lifecycle is not None
        assert request.lifecycle.pre_start is not None
        assert request.lifecycle.pre_start.timeout_seconds == 30
        assert request.lifecycle.periodic is not None
        assert request.lifecycle.periodic[0].name == "checkpoint"
        assert request.lifecycle.periodic[0].schedule == "*/5 * * * *"

    def test_create_request_rejects_reserved_lifecycle_env(self):
        with pytest.raises(ValidationError, match="is reserved"):
            CreateSandboxRequest(
                image=ImageSpec(uri="python:3.11"),
                entrypoint=["python"],
                resourceLimits=ResourceLimits(root={}),
                env={OPENSANDBOX_LIFECYCLE: "{}"},
            )

    def test_create_request_rejects_lifecycle_with_pool_ref(self):
        # OSEP-0024: lifecycle hooks conflict with pool mode, but the
        # hooks-free idlePolicy container is allowed through.
        with pytest.raises(
            ValidationError,
            match="lifecycle hooks cannot be used together with poolRef",
        ):
            CreateSandboxRequest(
                extensions={"poolRef": "default/pool"},
                lifecycle=SandboxLifecycle(
                    preStart=LifecycleHook(command=["true"]),
                ),
            )

        request = CreateSandboxRequest(
            extensions={"poolRef": "default/pool"},
            lifecycle=SandboxLifecycle(idlePolicy={"idleTimeoutSeconds": 300, "onIdle": "pause"}),
        )
        assert request.lifecycle is not None
        assert request.lifecycle.idle_policy is not None

    @pytest.mark.parametrize(
        ("hook", "expected"),
        [
            (LifecycleHook(command=["true"], timeoutSeconds=10800), 10800),
            (
                PeriodicLifecycleHook(
                    name="sync",
                    schedule="@hourly",
                    command=["true"],
                    timeoutSeconds=300,
                ),
                300,
            ),
        ],
    )
    def test_lifecycle_accepts_maximum_timeout(self, hook, expected):
        assert hook.timeout_seconds == expected

    @pytest.mark.parametrize(
        ("payload", "maximum"),
        [
            ({"preStart": {"command": ["true"], "timeoutSeconds": 10801}}, 10800),
            (
                {
                    "periodic": [
                        {
                            "name": "sync",
                            "schedule": "@hourly",
                            "command": ["true"],
                            "timeoutSeconds": 301,
                        }
                    ]
                },
                300,
            ),
        ],
    )
    def test_lifecycle_rejects_timeout_above_maximum(self, payload, maximum):
        with pytest.raises(ValidationError, match=f"less than or equal to {maximum}"):
            SandboxLifecycle.model_validate(payload)

    @pytest.mark.parametrize("duplicate_name", ["sync", " sync "])
    def test_lifecycle_rejects_duplicate_periodic_names(self, duplicate_name):
        with pytest.raises(ValidationError, match="names must be unique"):
            SandboxLifecycle.model_validate(
                {
                    "periodic": [
                        {"name": "sync", "schedule": "@hourly", "command": ["true"]},
                        {"name": duplicate_name, "schedule": "@daily", "command": ["true"]},
                    ]
                }
            )

    @pytest.mark.parametrize(
        ("payload", "message"),
        [
            ({"preStart": {"command": [" "]}}, "command must not be empty"),
            (
                {"periodic": [{"name": " ", "schedule": "@hourly", "command": ["true"]}]},
                "name must not be blank",
            ),
            (
                {"periodic": [{"name": "sync", "schedule": "\t", "command": ["true"]}]},
                "schedule must not be blank",
            ),
            (
                {"periodic": [{"name": "sync", "schedule": "@hourly", "command": [" "]}]},
                "command must not be empty",
            ),
        ],
    )
    def test_lifecycle_rejects_blank_required_values(self, payload, message):
        with pytest.raises(ValidationError, match=message):
            SandboxLifecycle.model_validate(payload)


class TestRenewalPolicy:
    """lifecycle.renewalPolicy (OSEP-0009) supersedes the deprecated
    extensions["access.renew.extend.seconds"] key."""

    def test_parses_alias(self):
        lifecycle = SandboxLifecycle.model_validate(
            {"renewalPolicy": {"extendSeconds": 3600}}
        )
        assert lifecycle.renewal_policy is not None
        assert lifecycle.renewal_policy.extend_seconds == 3600

    def test_serialization_uses_aliases(self):
        lifecycle = SandboxLifecycle(renewalPolicy={"extendSeconds": 3600})
        payload = lifecycle.model_dump(by_alias=True, exclude_none=True)
        assert payload == {"renewalPolicy": {"extendSeconds": 3600}}

    @pytest.mark.parametrize("value", [299, 86401])
    def test_rejects_out_of_bounds(self, value):
        with pytest.raises(ValidationError):
            RenewalPolicy(extendSeconds=value)

    def test_rejects_unknown_fields(self):
        with pytest.raises(ValidationError):
            RenewalPolicy.model_validate({"extendSeconds": 3600, "onAccess": "renew"})

    def test_lifecycle_rejects_unknown_fields(self):
        with pytest.raises(ValidationError):
            SandboxLifecycle.model_validate({"renewal": {"extendSeconds": 3600}})

    def test_pool_ref_allows_renewal_policy(self):
        # renewalPolicy is control-plane state, not a hook: it may accompany
        # extensions.poolRef like idlePolicy.
        request = CreateSandboxRequest(
            extensions={"poolRef": "default/pool"},
            lifecycle=SandboxLifecycle(renewalPolicy={"extendSeconds": 3600}),
        )
        assert request.lifecycle is not None
        assert request.lifecycle.renewal_policy is not None

    def test_template_mode_allows_renewal_policy_at_schema_level(self):
        # Template mode rejects workload-shaping fields only; the fsb backend
        # enforces its own renew-on-access rejection after routing.
        request = CreateSandboxRequest.model_validate(
            {
                "templateId": "tpl-1",
                "timeout": 600,
                "lifecycle": {"renewalPolicy": {"extendSeconds": 3600}},
            }
        )
        assert request.lifecycle is not None
        assert request.lifecycle.renewal_policy is not None


class TestHost:

    def test_valid_path(self):
        backend = Host(path="/data/opensandbox")
        assert backend.path == "/data/opensandbox"

    def test_valid_windows_path(self):
        backend = Host(path=r"D:\sandbox-mnt\ReMe")
        assert backend.path == r"D:\sandbox-mnt\ReMe"

    def test_path_required(self):
        with pytest.raises(ValidationError) as exc_info:
            Host()  # type: ignore
        errors = exc_info.value.errors()
        assert any(e["loc"] == ("path",) for e in errors)

    def test_serialization(self):
        backend = Host(path="/data/opensandbox")
        data = backend.model_dump()
        assert data == {"path": "/data/opensandbox"}

    def test_deserialization(self):
        data = {"path": "/data/opensandbox"}
        backend = Host.model_validate(data)
        assert backend.path == "/data/opensandbox"


class TestPVC:

    def test_valid_claim_name(self):
        backend = PVC(claim_name="my-pvc")
        assert backend.claim_name == "my-pvc"

    def test_claim_name_alias(self):
        data = {"claimName": "my-pvc"}
        backend = PVC.model_validate(data)
        assert backend.claim_name == "my-pvc"

    def test_serialization_uses_alias(self):
        backend = PVC(claim_name="my-pvc")
        data = backend.model_dump(by_alias=True, exclude_none=True)
        assert data == {
            "claimName": "my-pvc",
            "createIfNotExists": True,
            "deleteOnSandboxTermination": False,
        }

    def test_serialization_with_provisioning_hints(self):
        backend = PVC(
            claim_name="my-pvc",
            storage_class="ssd",
            storage="5Gi",
            access_modes=["ReadWriteOnce"],
        )
        data = backend.model_dump(by_alias=True, exclude_none=True)
        assert data == {
            "claimName": "my-pvc",
            "createIfNotExists": True,
            "deleteOnSandboxTermination": False,
            "storageClass": "ssd",
            "storage": "5Gi",
            "accessModes": ["ReadWriteOnce"],
        }

    def test_claim_name_required(self):
        with pytest.raises(ValidationError) as exc_info:
            PVC()  # type: ignore
        errors = exc_info.value.errors()
        assert any("claim_name" in str(e["loc"]) or "claimName" in str(e["loc"]) for e in errors)


class TestOSSFS:

    def test_valid_ossfs(self):
        backend = OSSFS(
            bucket="bucket-test-3",
            endpoint="oss-cn-hangzhou.aliyuncs.com",
            version="2.0",
            options=["allow_other"],
            access_key_id="AKIDEXAMPLE",
            access_key_secret="SECRETEXAMPLE",
        )
        assert backend.bucket == "bucket-test-3"
        assert backend.version == "2.0"
        assert backend.access_key_id == "AKIDEXAMPLE"

    def test_default_ossfs_version_is_2_0(self):
        backend = OSSFS(
            bucket="bucket-test-3",
            endpoint="oss-cn-hangzhou.aliyuncs.com",
            access_key_id="AKIDEXAMPLE",
            access_key_secret="SECRETEXAMPLE",
        )
        assert backend.version == "2.0"

    def test_inline_credentials_required(self):
        with pytest.raises(ValidationError):
            OSSFS(  # type: ignore
                bucket="bucket-test-3",
                endpoint="oss-cn-hangzhou.aliyuncs.com",
            )


class TestVolume:

    def test_valid_host_volume(self):
        volume = Volume(
            name="workdir",
            host=Host(path="/data/opensandbox"),
            mount_path="/mnt/work",
            read_only=False,
        )
        assert volume.name == "workdir"
        assert volume.host is not None
        assert volume.host.path == "/data/opensandbox"
        assert volume.mount_path == "/mnt/work"
        assert volume.read_only is False
        assert volume.pvc is None
        assert volume.sub_path is None

    def test_valid_pvc_volume(self):
        volume = Volume(
            name="models",
            pvc=PVC(claim_name="shared-models-pvc"),
            mount_path="/mnt/models",
            read_only=True,
        )
        assert volume.name == "models"
        assert volume.pvc is not None
        assert volume.pvc.claim_name == "shared-models-pvc"
        assert volume.mount_path == "/mnt/models"
        assert volume.read_only is True
        assert volume.host is None

    def test_valid_volume_with_subpath(self):
        volume = Volume(
            name="workdir",
            host=Host(path="/data/opensandbox"),
            mount_path="/mnt/work",
            read_only=False,
            sub_path="task-001",
        )
        assert volume.sub_path == "task-001"

    def test_valid_ossfs_volume(self):
        volume = Volume(
            name="data",
            ossfs=OSSFS(
                bucket="bucket-test-3",
                endpoint="oss-cn-hangzhou.aliyuncs.com",
                    access_key_id="AKIDEXAMPLE",
                access_key_secret="SECRETEXAMPLE",
            ),
            mount_path="/mnt/data",
            sub_path="task-001",
        )
        assert volume.ossfs is not None
        assert volume.ossfs.access_key_id == "AKIDEXAMPLE"
        assert volume.sub_path == "task-001"

    def test_no_backend_raises(self):
        with pytest.raises(ValidationError) as exc_info:
            Volume(
                name="workdir",
                mount_path="/mnt/work",
                read_only=False,
            )
        error_message = str(exc_info.value)
        assert "backend" in error_message.lower()

    def test_multiple_backends_raises(self):
        with pytest.raises(ValidationError) as exc_info:
            Volume(
                name="workdir",
                host=Host(path="/data/opensandbox"),
                pvc=PVC(claim_name="my-pvc"),
                mount_path="/mnt/work",
                read_only=False,
            )
        error_message = str(exc_info.value)
        assert "backend" in error_message.lower()

    def test_serialization_host_volume(self):
        volume = Volume(
            name="workdir",
            host=Host(path="/data/opensandbox"),
            mount_path="/mnt/work",
            read_only=False,
            sub_path="task-001",
        )
        data = volume.model_dump(by_alias=True, exclude_none=True)
        assert data == {
            "name": "workdir",
            "host": {"path": "/data/opensandbox"},
            "mountPath": "/mnt/work",
            "readOnly": False,
            "subPath": "task-001",
        }

    def test_serialization_pvc_volume(self):
        volume = Volume(
            name="models",
            pvc=PVC(claim_name="shared-models-pvc"),
            mount_path="/mnt/models",
            read_only=True,
        )
        data = volume.model_dump(by_alias=True, exclude_none=True)
        assert data == {
            "name": "models",
            "pvc": {
                "claimName": "shared-models-pvc",
                "createIfNotExists": True,
                "deleteOnSandboxTermination": False,
            },
            "mountPath": "/mnt/models",
            "readOnly": True,
        }

    def test_deserialization_host_volume(self):
        data = {
            "name": "workdir",
            "host": {"path": "/data/opensandbox"},
            "mountPath": "/mnt/work",
            "readOnly": False,
            "subPath": "task-001",
        }
        volume = Volume.model_validate(data)
        assert volume.name == "workdir"
        assert volume.host is not None
        assert volume.host.path == "/data/opensandbox"
        assert volume.mount_path == "/mnt/work"
        assert volume.read_only is False
        assert volume.sub_path == "task-001"


class TestSnapshots:

    def test_create_snapshot_request_accepts_optional_name(self):
        request = CreateSnapshotRequest(name="checkpoint-before-import")
        assert request.name == "checkpoint-before-import"

    def test_snapshot_serialization_uses_aliases(self):
        snapshot = Snapshot(
            id="snap-001",
            sandboxId="sbx-001",
            name="checkpoint-before-import",
            status=SnapshotStatus(state="Ready"),
            createdAt="2026-04-22T00:00:00Z",
        )
        data = snapshot.model_dump(by_alias=True, exclude_none=True)
        assert data["sandboxId"] == "sbx-001"
        assert data["createdAt"] == snapshot.created_at
        assert data["status"] == {"state": "Ready"}

    def test_list_snapshots_request_supports_alias_filter(self):
        request = ListSnapshotsRequest(
            filter=SnapshotFilter(
                sandboxId="sbx-001",
                name="toolchain:python@rev-1",
                state=["Ready"],
            ),
            pagination=PaginationRequest(page=2, pageSize=50),
        )
        assert request.filter.sandbox_id == "sbx-001"
        assert request.filter.name == "toolchain:python@rev-1"
        assert request.pagination is not None
        assert request.pagination.page_size == 50

    def test_pagination_info_serializes_aliases(self):
        pagination = PaginationInfo(
            page=1,
            pageSize=20,
            totalItems=3,
            totalPages=1,
            hasNextPage=False,
        )
        data = pagination.model_dump(by_alias=True)
        assert data == {
            "page": 1,
            "pageSize": 20,
            "totalItems": 3,
            "totalPages": 1,
            "hasNextPage": False,
        }


class TestCreateSandboxRequestSnapshotCompat:

    def test_accepts_snapshot_id_without_entrypoint(self):
        request = CreateSandboxRequest(
            snapshotId="snap-001",
            resourceLimits=ResourceLimits(root={"cpu": "500m"}),
        )
        assert request.snapshot_id == "snap-001"
        assert request.image is None
        assert request.entrypoint is None

    def test_accepts_snapshot_id_with_entrypoint(self):
        request = CreateSandboxRequest(
            snapshotId="snap-001",
            resourceLimits=ResourceLimits(root={"cpu": "500m"}),
            entrypoint=["python", "app.py"],
        )
        assert request.snapshot_id == "snap-001"
        assert request.entrypoint == ["python", "app.py"]

    def test_treats_blank_image_uri_as_missing_image(self):
        request = CreateSandboxRequest(
            image=ImageSpec(uri="   "),
            snapshotId="snap-001",
            resourceLimits=ResourceLimits(root={"cpu": "500m"}),
        )
        assert request.image is None
        assert request.snapshot_id == "snap-001"

    def test_rejects_when_both_image_and_snapshot_missing(self):
        with pytest.raises(ValidationError):
            CreateSandboxRequest(
                resourceLimits=ResourceLimits(root={"cpu": "500m"}),
            )

    def test_deserialization_pvc_volume(self):
        data = {
            "name": "models",
            "pvc": {"claimName": "shared-models-pvc"},
            "mountPath": "/mnt/models",
            "readOnly": True,
        }
        volume = Volume.model_validate(data)
        assert volume.name == "models"
        assert volume.pvc is not None
        assert volume.pvc.claim_name == "shared-models-pvc"
        assert volume.mount_path == "/mnt/models"
        assert volume.read_only is True

    def test_serialization_ossfs_volume(self):
        volume = Volume(
            name="data",
            ossfs=OSSFS(
                bucket="bucket-test-3",
                endpoint="oss-cn-hangzhou.aliyuncs.com",
                    access_key_id="AKIDEXAMPLE",
                access_key_secret="SECRETEXAMPLE",
            ),
            mount_path="/mnt/data",
            read_only=False,
            sub_path="task-001",
        )
        data = volume.model_dump(by_alias=True, exclude_none=True)
        assert data["ossfs"]["bucket"] == "bucket-test-3"
        assert data["ossfs"]["accessKeyId"] == "AKIDEXAMPLE"
        assert data["subPath"] == "task-001"


class TestCreateSandboxRequestWithVolumes:

    def test_request_without_timeout_uses_manual_cleanup(self):
        request = CreateSandboxRequest(
            image=ImageSpec(uri="python:3.11"),
            resource_limits=ResourceLimits({"cpu": "500m", "memory": "512Mi"}),
            entrypoint=["python", "-c", "print('hello')"],
        )
        assert request.timeout is None

    def test_request_without_volumes(self):
        request = CreateSandboxRequest(
            image=ImageSpec(uri="python:3.11"),
            timeout=3600,
            resource_limits=ResourceLimits({"cpu": "500m", "memory": "512Mi"}),
            entrypoint=["python", "-c", "print('hello')"],
        )
        assert request.volumes is None
        assert request.secure_access is False

    def test_request_with_secure_access(self):
        request = CreateSandboxRequest.model_validate(
            {
                "image": {"uri": "python:3.11"},
                "timeout": 3600,
                "resourceLimits": {"cpu": "500m", "memory": "512Mi"},
                "entrypoint": ["python", "-c", "print('hello')"],
                "secureAccess": True,
            }
        )
        assert request.secure_access is True

        data = request.model_dump(by_alias=True, exclude_none=True)
        assert data["secureAccess"] is True

    def test_request_with_credential_proxy_enabled(self):
        request = CreateSandboxRequest.model_validate(
            {
                "image": {"uri": "python:3.11"},
                "timeout": 3600,
                "resourceLimits": {"cpu": "500m", "memory": "512Mi"},
                "entrypoint": ["python", "-c", "print('hello')"],
                "networkPolicy": {"defaultAction": "deny", "egress": []},
                "credentialProxy": {"enabled": True},
            }
        )
        assert request.credential_proxy == CredentialProxyConfig(enabled=True)

        data = request.model_dump(by_alias=True, exclude_none=True)
        assert data["credentialProxy"] == {"enabled": True}

    def test_credential_proxy_requires_network_policy(self):
        with pytest.raises(ValidationError) as exc_info:
            CreateSandboxRequest.model_validate(
                {
                    "image": {"uri": "python:3.11"},
                    "timeout": 3600,
                    "resourceLimits": {"cpu": "500m", "memory": "512Mi"},
                    "entrypoint": ["python", "-c", "print('hello')"],
                    "credentialProxy": {"enabled": True},
                }
            )
        assert "credentialProxy.enabled requires networkPolicy" in str(exc_info.value)

    def test_credential_proxy_allows_default_allow_policy_for_compatibility(self):
        request = CreateSandboxRequest.model_validate(
            {
                "image": {"uri": "python:3.11"},
                "timeout": 3600,
                "resourceLimits": {"cpu": "500m", "memory": "512Mi"},
                "entrypoint": ["python", "-c", "print('hello')"],
                "networkPolicy": {"defaultAction": "allow", "egress": []},
                "credentialProxy": {"enabled": True},
            }
        )
        assert request.network_policy.default_action == "allow"

    def test_request_with_empty_volumes(self):
        request = CreateSandboxRequest(
            image=ImageSpec(uri="python:3.11"),
            timeout=3600,
            resource_limits=ResourceLimits({"cpu": "500m", "memory": "512Mi"}),
            entrypoint=["python", "-c", "print('hello')"],
            volumes=[],
        )
        assert request.volumes == []

    def test_request_with_host_volume(self):
        request = CreateSandboxRequest(
            image=ImageSpec(uri="python:3.11"),
            timeout=3600,
            resource_limits=ResourceLimits({"cpu": "500m", "memory": "512Mi"}),
            entrypoint=["python", "-c", "print('hello')"],
            volumes=[
                Volume(
                    name="workdir",
                    host=Host(path="/data/opensandbox"),
                    mount_path="/mnt/work",
                    read_only=False,
                )
            ],
        )
        assert request.volumes is not None
        assert len(request.volumes) == 1
        assert request.volumes[0].name == "workdir"

    def test_request_with_pvc_volume(self):
        request = CreateSandboxRequest(
            image=ImageSpec(uri="python:3.11"),
            timeout=3600,
            resource_limits=ResourceLimits({"cpu": "500m", "memory": "512Mi"}),
            entrypoint=["python", "-c", "print('hello')"],
            volumes=[
                Volume(
                    name="models",
                    pvc=PVC(claim_name="shared-models-pvc"),
                    mount_path="/mnt/models",
                    read_only=True,
                )
            ],
        )
        assert request.volumes is not None
        assert len(request.volumes) == 1
        assert request.volumes[0].pvc is not None
        assert request.volumes[0].pvc.claim_name == "shared-models-pvc"

    def test_request_with_multiple_volumes(self):
        request = CreateSandboxRequest(
            image=ImageSpec(uri="python:3.11"),
            timeout=3600,
            resource_limits=ResourceLimits({"cpu": "500m", "memory": "512Mi"}),
            entrypoint=["python", "-c", "print('hello')"],
            volumes=[
                Volume(
                    name="workdir",
                    host=Host(path="/data/opensandbox"),
                    mount_path="/mnt/work",
                    read_only=False,
                ),
                Volume(
                    name="models",
                    pvc=PVC(claim_name="shared-models-pvc"),
                    mount_path="/mnt/models",
                    read_only=True,
                ),
            ],
        )
        assert request.volumes is not None
        assert len(request.volumes) == 2

    def test_request_with_platform(self):
        request = CreateSandboxRequest(
            image=ImageSpec(uri="python:3.11"),
            timeout=3600,
            platform=PlatformSpec(os="linux", arch="arm64"),
            resource_limits=ResourceLimits({"cpu": "500m", "memory": "512Mi"}),
            entrypoint=["python", "-c", "print('hello')"],
        )
        assert request.platform is not None
        assert request.platform.os == "linux"
        assert request.platform.arch == "arm64"

    def test_serialization_with_volumes(self):
        request = CreateSandboxRequest(
            image=ImageSpec(uri="python:3.11"),
            timeout=3600,
            resource_limits=ResourceLimits({"cpu": "500m", "memory": "512Mi"}),
            entrypoint=["python", "-c", "print('hello')"],
            volumes=[
                Volume(
                    name="workdir",
                    host=Host(path="/data/opensandbox"),
                    mount_path="/mnt/work",
                    read_only=False,
                    sub_path="task-001",
                )
            ],
        )
        data = request.model_dump(by_alias=True, exclude_none=True)
        assert "volumes" in data
        assert len(data["volumes"]) == 1
        assert data["volumes"][0]["name"] == "workdir"
        assert data["volumes"][0]["mountPath"] == "/mnt/work"
        assert data["volumes"][0]["readOnly"] is False
        assert data["volumes"][0]["subPath"] == "task-001"

    def test_deserialization_with_volumes(self):
        data = {
            "image": {"uri": "python:3.11"},
            "timeout": 3600,
            "resourceLimits": {"cpu": "500m", "memory": "512Mi"},
            "entrypoint": ["python", "-c", "print('hello')"],
            "volumes": [
                {
                    "name": "workdir",
                    "host": {"path": "/data/opensandbox"},
                    "mountPath": "/mnt/work",
                    "readOnly": False,
                    "subPath": "task-001",
                },
                {
                    "name": "models",
                    "pvc": {"claimName": "shared-models-pvc"},
                    "mountPath": "/mnt/models",
                    "readOnly": True,
                },
            ],
        }
        request = CreateSandboxRequest.model_validate(data)
        assert request.volumes is not None
        assert len(request.volumes) == 2

        assert request.volumes[0].name == "workdir"
        assert request.volumes[0].host is not None
        assert request.volumes[0].host.path == "/data/opensandbox"
        assert request.volumes[0].mount_path == "/mnt/work"
        assert request.volumes[0].read_only is False
        assert request.volumes[0].sub_path == "task-001"

        assert request.volumes[1].name == "models"
        assert request.volumes[1].pvc is not None
        assert request.volumes[1].pvc.claim_name == "shared-models-pvc"
        assert request.volumes[1].mount_path == "/mnt/models"
        assert request.volumes[1].read_only is True

    def test_deserialization_with_platform(self):
        data = {
            "image": {"uri": "python:3.11"},
            "platform": {"os": "linux", "arch": "amd64"},
            "timeout": 3600,
            "resourceLimits": {"cpu": "500m", "memory": "512Mi"},
            "entrypoint": ["python", "-c", "print('hello')"],
        }
        request = CreateSandboxRequest.model_validate(data)
        assert request.platform is not None
        assert request.platform.os == "linux"
        assert request.platform.arch == "amd64"

    def test_request_rejects_zero_timeout(self):
        with pytest.raises(ValidationError):
            CreateSandboxRequest(
                image=ImageSpec(uri="python:3.11"),
                timeout=0,
                resource_limits=ResourceLimits({"cpu": "500m"}),
                entrypoint=["python", "-c", "print('hello')"],
            )

    def test_request_allows_timeout_above_previous_hardcoded_limit(self):
        request = CreateSandboxRequest(
            image=ImageSpec(uri="python:3.11"),
            timeout=172800,
            resource_limits=ResourceLimits({"cpu": "500m", "memory": "512Mi"}),
            entrypoint=["python", "-c", "print('hello')"],
        )

        assert request.timeout == 172800


class TestCreateSandboxRequestPoolMode:
    """Tests for pool mode (extensions.poolRef) validation."""

    def test_pool_mode_accepts_only_pool_ref(self):
        """Happy path: poolRef only, no image/entrypoint/resourceLimits required."""
        request = CreateSandboxRequest(
            extensions={"poolRef": "my-pool"},
        )
        assert request.image is None
        assert request.entrypoint is None
        assert request.resource_limits is None
        assert request.extensions["poolRef"] == "my-pool"

    def test_pool_mode_accepts_pool_ref_with_optional_fields(self):
        """poolRef with optional env/metadata/timeout should be valid."""
        request = CreateSandboxRequest(
            extensions={"poolRef": "my-pool"},
            env={"KEY": "value"},
            metadata={"team": "test"},
            timeout=600,
        )
        assert request.extensions["poolRef"] == "my-pool"
        assert request.env == {"KEY": "value"}

    def test_pool_mode_rejects_snapshot_id_with_pool_ref(self):
        with pytest.raises(ValidationError) as exc_info:
            CreateSandboxRequest(
                snapshotId="snap-001",
                extensions={"poolRef": "my-pool"},
            )
        errors = exc_info.value.errors()
        assert any("snapshotId" in str(e) and "poolRef" in str(e) for e in errors)

    def test_pool_mode_parses_credential_proxy_for_service_validation(self):
        """The service returns the documented 400 instead of a parsing-time 422."""
        request = CreateSandboxRequest(
            extensions={"poolRef": "my-pool"},
            credentialProxy=CredentialProxyConfig(enabled=True),
        )
        assert request.credential_proxy is not None
        assert request.credential_proxy.enabled is True

    def test_pool_mode_parses_network_policy_for_service_validation(self):
        """The service returns the documented 400 instead of a parsing-time 422."""
        request = CreateSandboxRequest(
            extensions={"poolRef": "my-pool"},
            networkPolicy={"defaultAction": "deny", "egress": []},
        )
        assert request.network_policy is not None

    def test_resource_limits_required_without_pool_ref(self):
        """Without poolRef, resourceLimits is still required (image mode)."""
        with pytest.raises(ValidationError):
            CreateSandboxRequest(
                image=ImageSpec(uri="python:3.11"),
                entrypoint=["python"],
            )

    def test_pool_mode_normalizes_blank_snapshot_id(self):
        req = CreateSandboxRequest(
            extensions={"poolRef": "my-pool"},
            snapshotId="   ",
        )
        assert req.snapshot_id is None

    def test_pool_mode_ignores_blank_pool_ref(self):
        with pytest.raises(ValidationError):
            CreateSandboxRequest(
                extensions={"poolRef": "   "},
            )


class TestNetworkPolicy:
    @pytest.mark.parametrize(
        "payload",
        [
            {"egress": [{"action": "allow", "target": "10.0.0.0/8", "port": [443]}]},
            {"egres": []},
        ],
    )
    def test_rejects_unknown_fields(self, payload):
        with pytest.raises(ValidationError, match="Extra inputs are not permitted"):
            NetworkPolicy.model_validate(payload)

    @pytest.mark.parametrize("action", ["allow", "deny"])
    def test_round_trips_valid_policy(self, action):
        payload = {
            "defaultAction": action,
            "egress": [
                {"action": action, "target": "*.example.com"},
                {"action": action, "target": "10.0.0.0/8", "ports": [22, 443]},
                {"action": action, "ports": [25]},
            ],
        }
        policy = NetworkPolicy.model_validate(payload)
        assert policy.model_dump(by_alias=True, exclude_none=True) == payload

    def test_preserves_omitted_defaults(self):
        policy = NetworkPolicy()
        assert policy.default_action is None
        assert policy.egress == []
        assert policy.model_dump(by_alias=True, exclude_none=True) == {"egress": []}

    def test_preserves_default_action_field_name(self):
        policy = NetworkPolicy.model_validate({"default_action": "deny"})
        assert policy.model_dump(by_alias=True, exclude_none=True) == {
            "defaultAction": "deny", "egress": [],
        }


class TestNetworkRule:
    """NetworkRule.target became optional so a rule can be scoped by `ports`
    alone; these guard the target/ports combinations the API is meant to
    accept or reject, and that pass-through to the egress sidecar (see
    server/opensandbox_server/services/{docker/networking,k8s/egress_helper}.py,
    which serialize with exclude_none=True) drops unset fields instead of
    sending literal nulls.
    """

    def test_requires_target_or_ports(self):
        with pytest.raises(ValidationError):
            NetworkRule.model_validate({"action": "allow"})

    def test_rejects_more_than_256_ports(self):
        with pytest.raises(ValidationError):
            NetworkRule.model_validate({"action": "allow", "ports": list(range(1, 258))})

    def test_accepts_exactly_256_ports(self):
        rule = NetworkRule.model_validate({"action": "allow", "ports": list(range(1, 257))})
        assert len(rule.ports) == 256

    def test_port_only_rule_omits_target(self):
        rule = NetworkRule.model_validate({"action": "deny", "ports": [25]})
        assert rule.target is None
        assert rule.ports == [25]

    def test_target_with_ports(self):
        rule = NetworkRule.model_validate({"action": "allow", "target": "10.0.0.5", "ports": [22, 80]})
        assert rule.target == "10.0.0.5"
        assert rule.ports == [22, 80]

    def test_cidr_target_with_ports(self):
        rule = NetworkRule.model_validate({"action": "deny", "target": "10.0.0.0/8", "ports": [22]})
        assert rule.target == "10.0.0.0/8"

    def test_ipv6_target_with_ports(self):
        rule = NetworkRule.model_validate({"action": "allow", "target": "2001:db8::1", "ports": [443]})
        assert rule.target == "2001:db8::1"

    def test_rejects_domain_target_with_ports(self):
        """Regression: the sidecar (policy.go normalizePolicy) rejects
        domain+ports, but the server validator did not mirror it, so an
        invalid request would pass the API and only fail once Docker/K8s
        started the egress sidecar with it — surfacing as a sandbox creation
        failure instead of a clean 422 from the create-sandbox request."""
        with pytest.raises(ValidationError):
            NetworkRule.model_validate({"action": "allow", "target": "example.com", "ports": [443]})

    def test_rejects_wildcard_domain_target_with_ports(self):
        with pytest.raises(ValidationError):
            NetworkRule.model_validate({"action": "allow", "target": "*.example.com", "ports": [443]})

    def test_rejects_out_of_range_ports(self):
        for bad_port in (0, -1, 65536):
            with pytest.raises(ValidationError):
                NetworkRule.model_validate({"action": "allow", "ports": [bad_port]})

    def test_rejects_duplicate_ports(self):
        with pytest.raises(ValidationError):
            NetworkRule.model_validate({"action": "allow", "ports": [443, 443]})

    def test_rejects_empty_ports_list(self):
        """The specs declare minItems: 1 on ports; an empty list must not be
        silently treated as unset, or clients could widen a rule's scope by
        mistake (an allow rule for a target would apply to every port)."""
        with pytest.raises(ValidationError):
            NetworkRule.model_validate({"action": "allow", "target": "10.0.0.5", "ports": []})
        with pytest.raises(ValidationError):
            NetworkRule.model_validate({"action": "allow", "ports": []})

    def test_rejects_netmask_cidr_with_ports(self):
        """Regression: `10.0.0.0/255.0.0.0` parses via ipaddress.ip_network but
        Go's netip.ParsePrefix rejects netmask notation, so the sidecar would
        classify it as a domain target and fail startup with a confusing
        "ports are not supported for domain targets" error."""
        with pytest.raises(ValidationError):
            NetworkRule.model_validate({"action": "allow", "target": "10.0.0.0/255.0.0.0", "ports": [22]})

    def test_netmask_cidr_without_ports_still_accepted(self):
        """Netmask notation is not port-scoped: it reaches the sidecar as a
        domain rule, which both layers accept (evaluated as a literal string
        by the DNS layer, like any other non-IP target)."""
        rule = NetworkRule.model_validate({"action": "allow", "target": "10.0.0.0/255.0.0.0"})
        assert rule.target == "10.0.0.0/255.0.0.0"

    def test_target_is_trimmed_like_the_sidecar(self):
        """policy.go trims the target before classifying; the server must too,
        or " 10.0.0.5" would be classified as a domain and rejected with a
        confusing domain+ports error. The trimmed value is what gets stored
        and serialized."""
        rule = NetworkRule.model_validate({"action": "allow", "target": "  10.0.0.5  ", "ports": [22]})
        assert rule.target == "10.0.0.5"

    def test_whitespace_target_counts_as_omitted(self):
        """A whitespace-only target trims to empty, mirroring the sidecar:
        with ports it degrades to a port-only rule; without ports it is
        rejected like a rule with no target and no ports."""
        rule = NetworkRule.model_validate({"action": "deny", "target": "   ", "ports": [25]})
        assert rule.target is None
        assert rule.ports == [25]
        with pytest.raises(ValidationError):
            NetworkRule.model_validate({"action": "allow", "target": "   "})

    def test_domain_only_rule_still_requires_target(self):
        rule = NetworkRule.model_validate({"action": "allow", "target": "example.com"})
        assert rule.target == "example.com"
        assert rule.ports is None

    def test_serialization_omits_unset_target_and_ports(self):
        rule = NetworkRule.model_validate({"action": "allow", "target": "example.com"})
        assert rule.model_dump(by_alias=True, exclude_none=True) == {
            "action": "allow",
            "target": "example.com",
        }

    def test_network_policy_round_trips_port_only_rule(self):
        policy = NetworkPolicy.model_validate(
            {"defaultAction": "deny", "egress": [{"action": "deny", "ports": [25]}]}
        )
        dumped = policy.model_dump(by_alias=True, exclude_none=True)
        assert dumped["egress"] == [{"action": "deny", "ports": [25]}]


class TestNetworkRuleReadModifyWriteAndClassification:
    """Review follow-ups: the sidecar marshals port-only rules as
    "target": "" (no omitempty), so the schema must accept blank targets on
    input (GET → PUT round-trip), and its IP/CIDR classification must match
    Go's netip for the shapes the sidecar will re-classify.
    """

    def test_blank_target_with_ports_round_trips(self):
        rule = NetworkRule.model_validate({"action": "deny", "target": "", "ports": [25]})
        assert rule.target is None
        assert rule.ports == [25]
        assert NetworkPolicy.model_validate(
            {"defaultAction": "deny", "egress": [{"action": "deny", "target": "", "ports": [25]}]}
        ).model_dump(by_alias=True, exclude_none=True)["egress"] == [{"action": "deny", "ports": [25]}]

    def test_blank_target_without_ports_rejected(self):
        with pytest.raises(ValidationError):
            NetworkRule.model_validate({"action": "allow", "target": ""})

    def test_zoned_ipv6_prefix_with_ports_rejected(self):
        """netip.ParsePrefix rejects scoped prefixes; the sidecar would see a
        domain and fail at provisioning with a confusing error."""
        with pytest.raises(ValidationError):
            NetworkRule.model_validate({"action": "allow", "target": "fe80::1%eth0/64", "ports": [22]})

    def test_zoned_ipv6_address_with_ports_accepted(self):
        """Bare zoned addresses parse in both netip.ParseAddr and ipaddress."""
        rule = NetworkRule.model_validate({"action": "allow", "target": "fe80::1%eth0", "ports": [22]})
        assert rule.target == "fe80::1%eth0"