Secure, Fast, and Extensible Sandbox runtime for AI agents.
# 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 asyncio
import json
import os
import threading
from datetime import datetime, timedelta, timezone
from typing import Any, cast
from unittest.mock import MagicMock, PropertyMock, patch
from docker.errors import APIError, DockerException, ImageNotFound, NotFound as DockerNotFound
import pytest
from fastapi import HTTPException, status
from pydantic import SecretStr, ValidationError
from opensandbox_server.config import (
AppConfig,
DockerConfig,
EGRESS_MODE_DNS,
EGRESS_MODE_DNS_NFT,
EgressConfig,
EgressUpstreamProxyConfig,
RuntimeConfig,
ServerConfig,
StorageConfig,
IngressConfig,
)
from opensandbox_server.extensions import ACCESS_RENEW_EXTEND_SECONDS_METADATA_KEY
from opensandbox_server.services.constants import (
EGRESS_MODE_ENV,
OTEL_EXPORTER_OTLP_ENDPOINT,
OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT,
OPENSANDBOX_EGRESS_SANDBOX_ID,
OPENSANDBOX_RUNTIME_MOUNT_PATH,
OPENSANDBOX_EGRESS_TOKEN,
)
from opensandbox_server.services.constants import (
SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY,
SANDBOX_EMBEDDING_PROXY_PORT_LABEL,
SANDBOX_EXPIRES_AT_LABEL,
SANDBOX_HTTP_PORT_LABEL,
SANDBOX_ID_LABEL,
SANDBOX_MANAGED_VOLUMES_LABEL,
SANDBOX_MANUAL_CLEANUP_LABEL,
SANDBOX_OSSFS_MOUNTS_LABEL,
SANDBOX_PLATFORM_ARCH_LABEL,
SANDBOX_PLATFORM_OS_LABEL,
SANDBOX_SNAPSHOT_ID_LABEL,
SandboxErrorCodes,
)
from opensandbox_server.services.docker import DockerSandboxService
from opensandbox_server.services.docker.metadata import DockerMetadataStore
from opensandbox_server.services.docker.runtime import SESSION_GATE_SOURCE_PATH
from opensandbox_server.services.helpers import (
parse_gpu_request,
parse_memory_limit,
parse_nano_cpus,
parse_timestamp,
)
from opensandbox_server.api.schema import (
CreateSandboxRequest,
CredentialProxyConfig,
Host,
IdlePolicy,
ImageSpec,
LifecycleHook,
ListSandboxesRequest,
NetworkPolicy,
OSSFS,
PaginationRequest,
PlatformSpec,
PVC,
ResourceLimits,
RenewSandboxExpirationRequest,
SandboxLifecycle,
Volume,
)
def _app_config() -> AppConfig:
return AppConfig(
server=ServerConfig(),
runtime=RuntimeConfig(type="docker", execd_image="ghcr.io/opensandbox/platform:latest"),
ingress=IngressConfig(mode="direct"),
)
@pytest.fixture(autouse=True)
def isolated_metadata_store(monkeypatch, tmp_path):
monkeypatch.setattr(
"opensandbox_server.services.docker.metadata.DEFAULT_STORE_DIR", tmp_path / "metadata"
)
def test_parse_memory_limit_handles_units():
assert parse_memory_limit("512Mi") == 512 * 1024 * 1024
assert parse_memory_limit("1G") == 1_000_000_000
assert parse_memory_limit("2gi") == 2 * 1024**3
assert parse_memory_limit("invalid") is None
def test_parse_nano_cpus():
assert parse_nano_cpus("500m") == 500_000_000
assert parse_nano_cpus("2") == 2_000_000_000
assert parse_nano_cpus("1.5") == 1_500_000_000
assert parse_nano_cpus("250.5m") == 250_500_000
assert parse_nano_cpus("bad") is None
@pytest.mark.parametrize(
"value", ["nan", "inf", "-inf", "1e10", "1e308", "1e309", "-1e309"]
)
def test_parse_nano_cpus_rejects_non_finite_and_overflow_values(value: str):
assert parse_nano_cpus(value) is None
def test_parse_gpu_request():
assert parse_gpu_request("1") == 1
assert parse_gpu_request("4") == 4
assert parse_gpu_request("all") == -1
assert parse_gpu_request("ALL") == -1
assert parse_gpu_request(None) is None
assert parse_gpu_request("") is None
assert parse_gpu_request("0") is None
assert parse_gpu_request("-1") is None
assert parse_gpu_request("bad") is None
def test_parse_timestamp_defaults_on_invalid():
ts = parse_timestamp("0001-01-01T00:00:00Z")
assert ts.tzinfo is not None
future = parse_timestamp("2024-01-01T00:00:00Z")
assert future.year == 2024
def test_env_allows_empty_string_and_skips_none():
DockerSandboxService(config=_app_config())
req = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={"FOO": "bar", "EMPTY": "", "NONE": None},
metadata={},
entrypoint=["python"],
)
env_dict = req.env or {}
environment = []
for key, value in env_dict.items():
if value is None:
continue
environment.append(f"{key}={value}")
assert "FOO=bar" in environment
assert "EMPTY=" in environment
assert all(not item.startswith("NONE=") for item in environment)
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_applies_security_defaults(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_host_config.return_value = {
"security_opt": ["no-new-privileges=true"],
"cap_drop": _app_config().docker.drop_capabilities,
"pids_limit": _app_config().docker.pids_limit,
}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value={
"44772": ("0.0.0.0", 40001),
"8080": ("0.0.0.0", 40002),
},
),
):
await service.create_sandbox(request)
host_config = mock_client.api.create_container.call_args.kwargs["host_config"]
assert "no-new-privileges=true" in host_config.get("security_opt", [])
assert host_config.get("cap_drop") == service.app_config.docker.drop_capabilities
assert host_config.get("pids_limit") == service.app_config.docker.pids_limit
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_unconfines_system_paths_for_bwrap_isolation(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_host_config.return_value = {
"MaskedPaths": ["/proc/kcore"],
"ReadonlyPaths": ["/proc/sys"],
}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
extensions={"bootstrap.execd.isolation": "enable"},
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value={
"44772": ("0.0.0.0", 40001),
"8080": ("0.0.0.0", 40002),
},
),
):
await service.create_sandbox(request)
host_config_kwargs = mock_client.api.create_host_config.call_args.kwargs
assert "SYS_ADMIN" in host_config_kwargs["cap_add"]
assert "apparmor=unconfined" in host_config_kwargs["security_opt"]
assert "seccomp=unconfined" in host_config_kwargs["security_opt"]
host_config = mock_client.api.create_container.call_args.kwargs["host_config"]
assert host_config["MaskedPaths"] == []
assert host_config["ReadonlyPaths"] == []
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_applies_config_sandbox_env_and_binds(mock_docker):
"""docker.sandbox_env / docker.sandbox_binds apply to every sandbox; request env wins."""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
config = _app_config()
config.docker = DockerConfig(
sandbox_env={
"NODE_EXTRA_CA_CERTS": "/etc/ssl/private-ca/root-ca.crt",
"SHARED": "config",
},
sandbox_binds=["/opt/certs/root-ca.crt:/etc/ssl/private-ca/root-ca.crt:ro"],
)
service = DockerSandboxService(config=config)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={"SHARED": "request"},
metadata={},
entrypoint=["python"],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value={
"44772": ("0.0.0.0", 40001),
"8080": ("0.0.0.0", 40002),
},
),
):
await service.create_sandbox(request)
environment = mock_client.api.create_container.call_args.kwargs["environment"]
assert "NODE_EXTRA_CA_CERTS=/etc/ssl/private-ca/root-ca.crt" in environment
assert "SHARED=request" in environment # request overrides the config default
assert "SHARED=config" not in environment
binds = mock_client.api.create_host_config.call_args.kwargs.get("binds")
assert binds == ["/opt/certs/root-ca.crt:/etc/ssl/private-ca/root-ca.crt:ro"]
@pytest.mark.asyncio
@pytest.mark.parametrize(
"limits, memory, cpu, gpu",
[
({"gpu": "2"}, None, None, 2),
({"memory": "512Mi", "cpu": "500m", "gpu": "all"}, 512 * 1024**2, 500_000_000, -1),
({"memory": "1G", "cpu": "1.5"}, 1_000_000_000, 1_500_000_000, None),
({}, None, None, None),
({"disk": "custom-value"}, None, None, None),
],
)
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_applies_resource_limits(mock_docker, limits, memory, cpu, gpu):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root=limits),
env={},
metadata={},
entrypoint=["python"],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value={
"44772": ("0.0.0.0", 40001),
"8080": ("0.0.0.0", 40002),
},
),
):
await service.create_sandbox(request)
create_host_config_kwargs = mock_client.api.create_host_config.call_args.kwargs
for key, expected in (("mem_limit", memory), ("nano_cpus", cpu)):
if expected is None:
assert key not in create_host_config_kwargs
else:
assert create_host_config_kwargs[key] == expected
device_requests = create_host_config_kwargs.get("device_requests")
if gpu is None:
assert "device_requests" not in create_host_config_kwargs
return
assert device_requests is not None
assert len(device_requests) == 1
# DeviceRequest is a dict subclass keyed with the Docker Engine's
# capitalized field names.
assert device_requests[0]["Count"] == gpu
assert device_requests[0]["Capabilities"] == [["gpu"]]
@pytest.mark.asyncio
@pytest.mark.parametrize(
"key, value",
[(key, value) for key in ("memory", "cpu", "gpu") for value in ("", " ", "0", "-1", "invalid")]
+ [("memory", "0Mi"), ("memory", "9" * 5000)]
+ [("cpu", value) for value in ("nan", "inf", "-inf", "1e10", "1e308", "1e309", "0.0000000001")]
+ [("gpu", "1.5")]
+ [(key, "x" * 5000) for key in ("cpu", "gpu")],
ids=lambda value: value if len(value) < 80 else "oversized-integer",
)
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_rejects_invalid_resource_limits_before_side_effects(mock_docker, key, value):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={key: value}),
entrypoint=["python"],
)
with (
patch.object(service, "_validate_volumes") as validate_volumes,
patch.object(service, "_ensure_image_available") as ensure_image,
patch.object(service, "_create_and_start_container") as create_container,
pytest.raises(HTTPException) as exc_info,
):
await service.create_sandbox(request)
assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
assert f"resourceLimits.{key}" in exc_info.value.detail["message"]
message = exc_info.value.detail["message"]
if len(value) > 80:
assert len(message) < 250
assert repr(value) not in message
assert value[:80] in message
assert f"{len(value)} characters" in message
else:
assert repr(value) in message
validate_volumes.assert_not_called()
ensure_image.assert_not_called()
create_container.assert_not_called()
mock_client.volumes.create.assert_not_called()
mock_client.api.create_container.assert_not_called()
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_without_gpu_omits_device_requests(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value={
"44772": ("0.0.0.0", 40001),
"8080": ("0.0.0.0", 40002),
},
),
):
await service.create_sandbox(request)
create_host_config_kwargs = mock_client.api.create_host_config.call_args.kwargs
assert "device_requests" not in create_host_config_kwargs
@pytest.mark.parametrize(
"runtime_exc, expected_status, expect_wrapped_error",
[
(
RuntimeError("tarfile error"),
status.HTTP_500_INTERNAL_SERVER_ERROR,
True,
),
(
HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail={"code": "CONFLICT", "message": "conflict error"},
),
status.HTTP_409_CONFLICT,
False,
),
],
)
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_prepare_runtime_failure_triggers_cleanup(
mock_docker, runtime_exc, expected_status, expect_wrapped_error
):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_container = MagicMock()
mock_client.containers.get.return_value = mock_container
mock_docker.from_env.return_value = mock_client
config = _app_config()
config.docker.network_mode = "bridge"
service = DockerSandboxService(config=config)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
bindings = {
"44772": ("0.0.0.0", 40001),
"8080": ("0.0.0.0", 40002),
}
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime", side_effect=runtime_exc),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value=bindings,
),
patch(
"opensandbox_server.services.docker.docker_service.release_port_bindings"
) as release_port_bindings,
):
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
mock_container.remove.assert_called_with(force=True)
release_port_bindings.assert_called_once_with(bindings)
assert exc.value.status_code == expected_status
if expect_wrapped_error:
assert str(runtime_exc) in str(exc.value.detail["message"])
else:
assert exc.value.detail["message"] == runtime_exc.detail["message"]
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_rejects_invalid_metadata(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={"Bad Key": "ok"}, # space is invalid for label key
entrypoint=["python"],
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_METADATA_LABEL
mock_client.containers.create.assert_not_called()
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_rejects_pool_ref_on_docker(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
entrypoint=["python"],
resourceLimits=ResourceLimits(root={}),
extensions={"poolRef": "my-pool"},
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == "SANDBOX::UNSUPPORTED_POOL_REF"
mock_client.containers.create.assert_not_called()
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_rejects_lifecycle_hooks_on_docker(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
entrypoint=["python"],
resourceLimits=ResourceLimits(root={}),
lifecycle=SandboxLifecycle(
preStart=LifecycleHook(command=["true"]),
),
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
mock_client.containers.create.assert_not_called()
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_rejects_timeout_above_configured_maximum(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
config = _app_config()
config.server.max_sandbox_timeout_seconds = 3600
service = DockerSandboxService(config=config)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=7200,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
assert "configured maximum of 3600s" in exc.value.detail["message"]
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_rejects_unsupported_platform(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
platform=PlatformSpec(os="darwin", arch="arm64"),
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
mock_client.containers.create.assert_not_called()
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_ensure_image_available_repulls_when_cached_platform_mismatch(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cached_image = MagicMock()
cached_image.attrs = {"Os": "linux", "Architecture": "amd64"}
mock_client.images.get.return_value = cached_image
service = DockerSandboxService(config=_app_config())
with patch.object(service, "_pull_image") as mock_pull:
service._ensure_image_available(
"python:3.11",
auth_config=None,
sandbox_id="sandbox-1",
platform=PlatformSpec(os="linux", arch="arm64"),
)
mock_pull.assert_called_once()
call = mock_pull.call_args
assert call.args[0] == "python:3.11"
assert call.args[3] is not None
assert call.args[3].os == "linux"
assert call.args[3].arch == "arm64"
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_ensure_image_available_repulls_when_platform_omitted_and_cached_arch_differs(
mock_docker,
):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cached_image = MagicMock()
cached_image.attrs = {"Os": "linux", "Architecture": "arm64"}
mock_client.images.get.return_value = cached_image
mock_client.info.return_value = {"OSType": "linux", "Architecture": "amd64"}
service = DockerSandboxService(config=_app_config())
with patch.object(service, "_pull_image") as mock_pull:
service._ensure_image_available(
"python:3.11",
auth_config=None,
sandbox_id="sandbox-default",
platform=None,
)
mock_pull.assert_called_once()
call = mock_pull.call_args
assert call.args[0] == "python:3.11"
assert call.args[3] is not None
assert call.args[3].os == "linux"
assert call.args[3].arch == "amd64"
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_ensure_image_available_does_not_repull_when_platform_omitted_and_cached_amd64(
mock_docker,
):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cached_image = MagicMock()
cached_image.attrs = {"Os": "linux", "Architecture": "amd64"}
mock_client.images.get.return_value = cached_image
# Docker daemon may report x86_64/aarch64 aliases; this should still match amd64.
mock_client.info.return_value = {"OSType": "linux", "Architecture": "x86_64"}
service = DockerSandboxService(config=_app_config())
with patch.object(service, "_pull_image") as mock_pull:
service._ensure_image_available(
"python:3.11",
auth_config=None,
sandbox_id="sandbox-default",
platform=None,
)
mock_pull.assert_not_called()
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_pull_image_passes_platform_to_docker_api(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
service._pull_image(
image_uri="python:3.11",
auth_config=None,
sandbox_id="sandbox-1",
platform=PlatformSpec(os="linux", arch="arm64"),
)
mock_client.images.pull.assert_called_once_with(
"python:3.11",
auth_config=None,
platform="linux/arm64",
)
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_pull_image_skips_platform_for_windows_profile(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
service._pull_image(
image_uri="dockurr/windows:latest",
auth_config=None,
sandbox_id="sandbox-win-1",
platform=PlatformSpec(os="windows", arch="amd64"),
)
mock_client.images.pull.assert_called_once_with(
"dockurr/windows:latest",
auth_config=None,
)
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_ensure_image_available_skips_windows_platform_mismatch_repull(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cached_image = MagicMock()
cached_image.attrs = {"Os": "linux", "Architecture": "amd64"}
mock_client.images.get.return_value = cached_image
mock_client.info.return_value = {"OSType": "linux", "Architecture": "amd64"}
service = DockerSandboxService(config=_app_config())
with patch.object(service, "_pull_image") as mock_pull:
service._ensure_image_available(
"dockurr/windows:latest",
auth_config=None,
sandbox_id="sandbox-win-1",
platform=PlatformSpec(os="windows", arch="amd64"),
)
mock_pull.assert_not_called()
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_fetch_execd_archive_caches_by_platform_key(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.info.return_value = {"OSType": "linux", "Architecture": "amd64"}
container_amd64 = MagicMock()
container_amd64.get_archive.return_value = ([b"amd64"], {})
container_arm64 = MagicMock()
container_arm64.get_archive.return_value = ([b"arm64"], {})
mock_client.containers.create.side_effect = [container_amd64, container_arm64]
service = DockerSandboxService(config=_app_config())
with patch.object(service, "_docker_operation"):
amd64_first = service._fetch_execd_archive(
platform=PlatformSpec(os="linux", arch="amd64")
)
amd64_second = service._fetch_execd_archive(
platform=PlatformSpec(os="linux", arch="amd64")
)
arm64_data = service._fetch_execd_archive(
platform=PlatformSpec(os="linux", arch="arm64")
)
assert amd64_first == b"amd64"
assert amd64_second == b"amd64"
assert arm64_data == b"arm64"
assert mock_client.containers.create.call_count == 2
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_fetch_execd_archive_passes_configured_network_mode(mock_docker):
"""The execd cache container must not fall back to the Docker API default (`bridge`).
Without an explicit network mode the Docker API attaches the cache container to `bridge`,
which fails wherever netavark cannot apply its ruleset (e.g. rootless podman in WSL2) even
though the sandbox itself is configured with a working mode such as `pasta`.
"""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.info.return_value = {"OSType": "linux", "Architecture": "amd64"}
container = MagicMock()
container.get_archive.return_value = ([b"payload"], {})
mock_client.containers.create.return_value = container
cfg = _app_config()
cfg.docker.network_mode = "pasta"
service = DockerSandboxService(config=cfg)
with patch.object(service, "_docker_operation"):
service._fetch_execd_archive()
assert mock_client.containers.create.call_args.kwargs["network_mode"] == "pasta"
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_fetch_execd_archive_applies_configured_security_profiles_and_runtime(mock_docker):
"""The execd cache container must honor the same security settings as sandbox containers.
It is created before any sandbox container. If it ignored ``[docker] seccomp_profile`` /
``apparmor_profile`` or ``[secure_runtime] docker_runtime``, a host whose default profile
blocks the execd image could not be fixed through configuration.
"""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.info.return_value = {"OSType": "linux", "Architecture": "amd64"}
container = MagicMock()
container.get_archive.return_value = ([b"payload"], {})
mock_client.containers.create.return_value = container
cfg = _app_config()
cfg.docker.seccomp_profile = "unconfined"
cfg.docker.apparmor_profile = "my-profile"
service = DockerSandboxService(config=cfg)
service.docker_runtime = "runsc"
with patch.object(service, "_docker_operation"):
service._fetch_execd_archive()
kwargs = mock_client.containers.create.call_args.kwargs
assert kwargs["security_opt"] == ["apparmor=my-profile", "seccomp=unconfined"]
assert kwargs["runtime"] == "runsc"
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_fetch_execd_archive_omits_security_opt_and_runtime_by_default(mock_docker):
"""Nothing configured means the Docker defaults are kept (backward compatible)."""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.info.return_value = {"OSType": "linux", "Architecture": "amd64"}
container = MagicMock()
container.get_archive.return_value = ([b"payload"], {})
mock_client.containers.create.return_value = container
service = DockerSandboxService(config=_app_config())
with patch.object(service, "_docker_operation"):
service._fetch_execd_archive()
kwargs = mock_client.containers.create.call_args.kwargs
assert "security_opt" not in kwargs
assert "runtime" not in kwargs
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_fetch_execd_archive_caches_session_gate_by_platform_key(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.info.return_value = {"OSType": "linux", "Architecture": "amd64"}
container = MagicMock()
def get_archive(path):
return ([f"archive:{path}".encode()], {})
container.get_archive.side_effect = get_archive
mock_client.containers.create.return_value = container
service = DockerSandboxService(config=_app_config())
with patch.object(service, "_ensure_image_available"), patch.object(
service, "_docker_operation"
):
service._fetch_execd_archive()
assert service._session_gate_archive_cache["default"] == (
f"archive:{SESSION_GATE_SOURCE_PATH}".encode()
)
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_fetch_execd_archive_allows_older_image_without_session_gate(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.info.return_value = {"OSType": "linux", "Architecture": "amd64"}
container = MagicMock()
def get_archive(path):
if path == SESSION_GATE_SOURCE_PATH:
raise DockerNotFound("session gate missing")
return ([f"archive:{path}".encode()], {})
container.get_archive.side_effect = get_archive
mock_client.containers.create.return_value = container
service = DockerSandboxService(config=_app_config())
with patch.object(service, "_ensure_image_available"), patch.object(
service, "_docker_operation"
):
assert service._fetch_execd_archive() == b"archive:/execd"
assert "default" not in service._session_gate_archive_cache
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_fetch_execd_archive_rejects_session_gate_read_failure(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.info.return_value = {"OSType": "linux", "Architecture": "amd64"}
container = MagicMock()
def get_archive(path):
if path == SESSION_GATE_SOURCE_PATH:
raise DockerException("session gate read failed")
return ([f"archive:{path}".encode()], {})
container.get_archive.side_effect = get_archive
mock_client.containers.create.return_value = container
service = DockerSandboxService(config=_app_config())
with patch.object(service, "_ensure_image_available"), patch.object(
service, "_docker_operation"
):
with pytest.raises(HTTPException) as exc_info:
service._fetch_execd_archive()
assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
assert exc_info.value.detail["code"] == SandboxErrorCodes.EXECD_DISTRIBUTION_FAILED
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_fetch_execd_archive_maps_platform_typeerror_to_invalid_parameter(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.containers.create.side_effect = TypeError("unexpected keyword argument 'platform'")
service = DockerSandboxService(config=_app_config())
with patch.object(service, "_ensure_image_available"):
with pytest.raises(HTTPException) as exc_info:
service._fetch_execd_archive(PlatformSpec(os="linux", arch="arm64"))
assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
assert "platform-aware container create" in exc_info.value.detail["message"]
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_requires_entrypoint(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
request.entrypoint = []
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_ENTRYPOINT
mock_client.containers.create.assert_not_called()
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_network_policy_rejected_on_host_mode(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "host"
cfg.egress = EgressConfig(image="egress:latest")
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
networkPolicy=NetworkPolicy(default_action="deny", egress=[]),
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_network_policy_requires_egress_image(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = None
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
networkPolicy=NetworkPolicy(default_action="deny", egress=[]),
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_container_runtime_network_modes_are_not_treated_as_user_defined(mock_docker):
"""`pasta` / `slirp4netns` / `none` are runtime network modes, not user-defined networks.
They must be passed through to the container runtime instead of being looked up as a
Docker network (podman has no `pasta` network driver and rejects a network with that
name), which is what makes them usable where bridge networking is unavailable.
"""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
for mode in ("pasta", "slirp4netns", "none"):
cfg = _app_config()
cfg.docker.network_mode = mode
service = DockerSandboxService(config=cfg)
assert service.network_mode == mode
assert service._is_user_defined_network() is False
service._validate_network_exists() # must not raise for runtime network modes
mock_client.networks.get.assert_not_called()
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_network_policy_rejects_container_runtime_network_modes(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
for mode in ("pasta", "slirp4netns", "none"):
cfg = _app_config()
cfg.docker.network_mode = mode
cfg.egress = EgressConfig(image="egress:latest")
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
networkPolicy=NetworkPolicy(default_action="deny", egress=[]),
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
assert mode in exc.value.detail["message"]
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_credential_proxy_requires_dns_nft_mode(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="egress:latest", mode="dns")
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
networkPolicy=NetworkPolicy(default_action="deny", egress=[]),
credentialProxy=CredentialProxyConfig(enabled=True),
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
assert "dns+nft" in exc.value.detail["message"]
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_egress_sidecar_injection_and_capabilities(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.side_effect = [
{"Id": "sidecar-id"},
{"Id": "main-id"},
]
mock_client.containers.get.side_effect = [MagicMock(id="sidecar-id"), MagicMock(id="main-id")]
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="egress:latest", readiness_timeout_seconds=75.5)
service = DockerSandboxService(config=cfg)
req = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
networkPolicy=NetworkPolicy(default_action="deny", egress=[]),
)
with (
patch("opensandbox_server.services.docker.docker_service.generate_egress_token", return_value="egress-token"),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value={
"44772": ("0.0.0.0", 44772),
"8080": ("0.0.0.0", 8080),
"18080": ("0.0.0.0", 18080),
},
),
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
patch.object(service, "_wait_for_egress_sidecar_ready") as wait_for_egress_ready,
):
await service.create_sandbox(req)
wait_for_egress_ready.assert_called_once()
assert wait_for_egress_ready.call_args.args[1:] == (18080, "egress-token")
assert wait_for_egress_ready.call_args.kwargs == {"timeout_seconds": 75.5}
assert len(mock_client.api.create_container.call_args_list) == 2
sidecar_call = mock_client.api.create_container.call_args_list[0]
main_call = mock_client.api.create_container.call_args_list[1]
sidecar_kwargs = sidecar_call.kwargs
main_kwargs = main_call.kwargs
assert "NET_ADMIN" in sidecar_kwargs["host_config"]["cap_add"]
assert "44772" in sidecar_kwargs["host_config"]["port_bindings"]
assert "8080" in sidecar_kwargs["host_config"]["port_bindings"]
assert main_kwargs["host_config"]["network_mode"] == "container:sidecar-id"
assert "NET_ADMIN" in set(main_kwargs["host_config"].get("cap_drop") or [])
assert "port_bindings" not in main_kwargs["host_config"]
labels = main_kwargs["labels"]
assert labels.get("opensandbox.io/embedding-proxy-port")
assert labels.get("opensandbox.io/http-port")
assert labels[SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY] == "egress-token"
sidecar_env = sidecar_kwargs["environment"]
assert f"{OPENSANDBOX_EGRESS_TOKEN}=egress-token" in sidecar_env
assert f"{EGRESS_MODE_ENV}={EGRESS_MODE_DNS}" in sidecar_env
assert f"{OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT}=true" not in sidecar_env
forwarded_env = main_kwargs["environment"]
assert f"{OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT}=true" not in forwarded_env
sandbox_id = main_kwargs["labels"][SANDBOX_ID_LABEL]
runtime_volume = f"opensandbox-runtime-{sandbox_id}"
mock_client.volumes.create.assert_called_once_with(
name=runtime_volume,
labels={SANDBOX_MANAGED_VOLUMES_LABEL: "server"},
)
sidecar_binds = sidecar_kwargs["host_config"].get("binds", [])
assert f"{runtime_volume}:{OPENSANDBOX_RUNTIME_MOUNT_PATH}:rw" in sidecar_binds
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_network_policy_enables_mitm_only_for_credential_proxy(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.side_effect = [
{"Id": "sidecar-id"},
{"Id": "main-id"},
]
mock_client.containers.get.side_effect = [MagicMock(id="sidecar-id"), MagicMock(id="main-id")]
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="egress:latest", mode="dns+nft")
service = DockerSandboxService(config=cfg)
req = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={"SSL_CERT_FILE": "/custom.pem"},
metadata={},
entrypoint=["python"],
networkPolicy=NetworkPolicy(default_action="deny", egress=[]),
credentialProxy=CredentialProxyConfig(enabled=True),
)
with (
patch("opensandbox_server.services.docker.docker_service.generate_egress_token", return_value="egress-token"),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value={
"44772": ("0.0.0.0", 44772),
"8080": ("0.0.0.0", 8080),
"18080": ("0.0.0.0", 18080),
},
),
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
patch.object(service, "_wait_for_egress_sidecar_ready"),
):
await service.create_sandbox(req)
sidecar_kwargs = mock_client.api.create_container.call_args_list[0].kwargs
main_kwargs = mock_client.api.create_container.call_args_list[1].kwargs
sidecar_env = sidecar_kwargs["environment"]
assert f"{OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT}=true" in sidecar_env
runtime_volume = "opensandbox-runtime-" + main_kwargs["labels"][SANDBOX_ID_LABEL]
expected_runtime_bind = f"{runtime_volume}:{OPENSANDBOX_RUNTIME_MOUNT_PATH}:rw"
assert sidecar_kwargs["host_config"]["binds"] == [expected_runtime_bind]
forwarded_env = main_kwargs["environment"]
assert "SSL_CERT_FILE=/custom.pem" in forwarded_env
assert f"{OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT}=true" in forwarded_env
assert expected_runtime_bind in main_kwargs["host_config"]["binds"]
assert json.loads(main_kwargs["labels"][SANDBOX_MANAGED_VOLUMES_LABEL]) == [
runtime_volume
]
mock_client.volumes.create.assert_called_once_with(
name=runtime_volume,
labels={SANDBOX_MANAGED_VOLUMES_LABEL: "server"},
)
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_mounts_upstream_proxy_ca_only_on_egress_sidecar(
mock_docker,
):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.side_effect = [
{"Id": "sidecar-id"},
{"Id": "main-id"},
]
mock_client.containers.get.side_effect = [
MagicMock(id="sidecar-id"),
MagicMock(id="main-id"),
]
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(
image="egress:latest",
mode=EGRESS_MODE_DNS_NFT,
upstream_proxy=EgressUpstreamProxyConfig(
url="https://proxy.local:8443",
ca_cert_path="/etc/ssl/private-ca/upstream.pem",
),
)
service = DockerSandboxService(config=cfg)
req = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
networkPolicy=NetworkPolicy(default_action="deny", egress=[]),
credentialProxy=CredentialProxyConfig(enabled=True),
)
with (
patch(
"opensandbox_server.services.docker.docker_service.generate_egress_token",
return_value="egress-token",
),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value={
"44772": ("0.0.0.0", 44772),
"8080": ("0.0.0.0", 8080),
"18080": ("0.0.0.0", 18080),
},
),
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
patch.object(service, "_wait_for_egress_sidecar_ready"),
):
await service.create_sandbox(req)
sidecar_kwargs = mock_client.api.create_container.call_args_list[0].kwargs
main_kwargs = mock_client.api.create_container.call_args_list[1].kwargs
ca_bind = (
"/etc/ssl/private-ca/upstream.pem"
":/etc/ssl/certs/opensandbox-upstream-extra-ca.pem:ro"
)
sidecar_env = sidecar_kwargs["environment"]
assert (
"OPENSANDBOX_EGRESS_MITMPROXY_UPSTREAM_EXTRA_CA="
"/etc/ssl/certs/opensandbox-upstream-extra-ca.pem" in sidecar_env
)
sidecar_binds = sidecar_kwargs["host_config"]["binds"]
runtime_volume = (
"opensandbox-runtime-" + main_kwargs["labels"][SANDBOX_ID_LABEL]
)
expected_runtime_bind = (
f"{runtime_volume}:{OPENSANDBOX_RUNTIME_MOUNT_PATH}:rw"
)
assert expected_runtime_bind in sidecar_binds
assert ca_bind in sidecar_binds
assert ca_bind.endswith(":ro")
main_binds = main_kwargs["host_config"].get("binds", [])
assert ca_bind not in main_binds
assert not any(
entry.startswith("OPENSANDBOX_EGRESS_MITMPROXY_UPSTREAM_EXTRA_CA")
for entry in main_kwargs["environment"]
)
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_egress_sidecar_omits_upstream_ca_bind_when_not_configured(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.return_value = {"Id": "sidecar-id"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(
image="egress:latest",
mode=EGRESS_MODE_DNS_NFT,
upstream_proxy=EgressUpstreamProxyConfig(
url="https://proxy.local:8443"
),
)
service = DockerSandboxService(config=cfg)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
service._start_egress_sidecar(
"sbx-abc123",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
)
sidecar_env = mock_client.api.create_container.call_args.kwargs["environment"]
assert not any(
entry.startswith("OPENSANDBOX_EGRESS_MITMPROXY_UPSTREAM_EXTRA_CA")
for entry in sidecar_env
)
sidecar_host_config = (
mock_client.api.create_host_config.call_args_list[0].kwargs
)
assert not any(
"opensandbox-upstream-extra-ca" in bind
for bind in sidecar_host_config.get("binds", [])
)
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_rejects_secure_access_on_docker_runtime(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
service = DockerSandboxService(config=cfg)
req = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
secureAccess=True,
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(req)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
assert "secureAccess is not supported when runtime.type='docker'" in exc.value.detail["message"]
mock_client.api.create_container.assert_not_called()
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_network_policy_rejected_on_user_defined_network(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "my-custom-net"
cfg.egress = EgressConfig(image="egress:latest")
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
networkPolicy=NetworkPolicy(default_action="deny", egress=[]),
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
assert "my-custom-net" in exc.value.detail["message"]
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_fails_when_user_defined_network_not_found(mock_docker):
from docker.errors import NotFound as DockerNotFound
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.networks.get.side_effect = DockerNotFound("network not found")
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "missing-net"
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
assert "missing-net" in exc.value.detail["message"]
assert "docker network create" in exc.value.detail["message"]
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_user_defined_network_uses_correct_network_mode(mock_docker):
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.networks.get.return_value = MagicMock() # network exists
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.return_value = {"Id": "main-id"}
mock_client.containers.get.return_value = MagicMock(id="main-id")
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "my-app-net"
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value={
"44772": ("0.0.0.0", 40001),
"8080": ("0.0.0.0", 40002),
},
),
):
await service.create_sandbox(request)
call_kwargs = mock_client.api.create_container.call_args.kwargs
assert call_kwargs["host_config"]["network_mode"] == "my-app-net"
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_validate_network_skipped_for_builtin_modes(mock_docker):
"""_validate_network_exists does NOT call the Docker API for host or bridge modes."""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
for mode in ("host", "bridge", "none"):
mock_client.networks.get.reset_mock()
cfg = _app_config()
cfg.docker.network_mode = mode
service = DockerSandboxService(config=cfg)
service._validate_network_exists()
mock_client.networks.get.assert_not_called()
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_egress_sidecar_cleanup_uses_api_remove_when_lookup_fails(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.return_value = {"Id": "sidecar-id"}
mock_client.containers.get.side_effect = DockerException("lookup failed")
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="egress:latest")
service = DockerSandboxService(config=cfg)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
with pytest.raises(HTTPException) as exc:
service._start_egress_sidecar(
"sandbox-id",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
)
detail = exc.value.detail
assert isinstance(detail, dict)
typed_detail = cast(dict[str, Any], detail)
assert exc.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
assert typed_detail["message"] == "Egress sidecar container failed to start."
mock_client.api.remove_container.assert_called_once_with("sidecar-id", force=True)
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_egress_sidecar_missing_id_preserves_specific_error(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.return_value = {}
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="egress:latest")
service = DockerSandboxService(config=cfg)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
with pytest.raises(HTTPException) as exc:
service._start_egress_sidecar(
"sandbox-id",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
)
detail = exc.value.detail
assert isinstance(detail, dict)
typed_detail = cast(dict[str, Any], detail)
assert exc.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
assert typed_detail["message"] == "Docker did not return an egress sidecar container ID."
mock_client.containers.get.assert_not_called()
mock_client.api.remove_container.assert_not_called()
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_egress_sidecar_cleanup_wraps_unexpected_lookup_error(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.return_value = {"Id": "sidecar-id"}
mock_client.containers.get.side_effect = RuntimeError("lookup failed")
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="egress:latest")
service = DockerSandboxService(config=cfg)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
with pytest.raises(HTTPException) as exc:
service._start_egress_sidecar(
"sandbox-id",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
)
detail = exc.value.detail
assert isinstance(detail, dict)
typed_detail = cast(dict[str, Any], detail)
assert exc.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
assert typed_detail["code"] == SandboxErrorCodes.CONTAINER_START_FAILED
assert typed_detail["message"] == "Egress sidecar container failed to start."
mock_client.api.remove_container.assert_called_once_with("sidecar-id", force=True)
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_egress_sidecar_host_config_sysctls_only_when_egress_disable_ipv6(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.return_value = {"Id": "sidecar-id"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="egress:latest", disable_ipv6=False)
service = DockerSandboxService(config=cfg)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
service._start_egress_sidecar(
"sandbox-id",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
)
hc_kwargs = mock_client.api.create_host_config.call_args.kwargs
assert "sysctls" not in hc_kwargs
cfg.egress = EgressConfig(image="egress:latest", disable_ipv6=True)
service2 = DockerSandboxService(config=cfg)
mock_client.api.create_host_config.reset_mock()
with (
patch.object(service2, "_ensure_image_available"),
patch.object(service2, "_docker_operation") as mock_op2,
):
mock_op2.return_value.__enter__.return_value = None
mock_op2.return_value.__exit__.return_value = None
service2._start_egress_sidecar(
"sandbox-id",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
)
hc2 = mock_client.api.create_host_config.call_args.kwargs
assert hc2["sysctls"]["net.ipv6.conf.all.disable_ipv6"] == 1
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_egress_sidecar_retries_without_ipv6_sysctls_when_daemon_rejects_them(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
def create_container_side_effect(**kwargs):
host_config = kwargs["host_config"]
if "sysctls" in host_config:
raise DockerException(
"open /proc/sys/net/ipv6/conf/all/disable_ipv6: no such file or directory"
)
return {"Id": "sidecar-id"}
mock_client.api.create_container.side_effect = create_container_side_effect
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="egress:latest", disable_ipv6=True)
service = DockerSandboxService(config=cfg)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
service._start_egress_sidecar(
"sandbox-id",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
)
first_create = mock_client.api.create_container.call_args_list[0].kwargs
second_create = mock_client.api.create_container.call_args_list[1].kwargs
assert first_create["host_config"]["sysctls"]["net.ipv6.conf.all.disable_ipv6"] == 1
assert "sysctls" not in second_create["host_config"]
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_egress_sidecar_injects_sandbox_id_env(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.return_value = {"Id": "sidecar-id"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="egress:latest", disable_ipv6=False)
service = DockerSandboxService(config=cfg)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
service._start_egress_sidecar(
"sbx-abc123",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
)
sidecar_env = mock_client.api.create_container.call_args.kwargs["environment"]
assert f"{OPENSANDBOX_EGRESS_SANDBOX_ID}=sbx-abc123" in sidecar_env
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_egress_sidecar_injects_otlp_endpoint_env_when_configured(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.return_value = {"Id": "sidecar-id"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(
image="egress:latest",
disable_ipv6=False,
otlp_endpoint="http://otel-collector.observability:4318",
)
service = DockerSandboxService(config=cfg)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
service._start_egress_sidecar(
"sbx-abc123",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
)
sidecar_env = mock_client.api.create_container.call_args.kwargs["environment"]
assert (
f"{OTEL_EXPORTER_OTLP_ENDPOINT}=http://otel-collector.observability:4318"
in sidecar_env
)
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_egress_sidecar_omits_otlp_endpoint_env_when_not_configured(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.return_value = {"Id": "sidecar-id"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="egress:latest", disable_ipv6=False)
service = DockerSandboxService(config=cfg)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
service._start_egress_sidecar(
"sbx-abc123",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
)
sidecar_env = mock_client.api.create_container.call_args.kwargs["environment"]
assert not any(
entry.startswith(f"{OTEL_EXPORTER_OTLP_ENDPOINT}=") for entry in sidecar_env
)
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_egress_sidecar_injects_upstream_proxy_env_when_configured(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.return_value = {"Id": "sidecar-id"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(
image="egress:latest",
mode=EGRESS_MODE_DNS_NFT,
disable_ipv6=False,
upstream_proxy=EgressUpstreamProxyConfig(
url="http://proxy.local:3128",
authorization=SecretStr("Basic dGVzdDp0ZXN0"),
),
)
service = DockerSandboxService(config=cfg)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
service._start_egress_sidecar(
"sbx-abc123",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
)
sidecar_env = mock_client.api.create_container.call_args.kwargs["environment"]
assert "OPENSANDBOX_EGRESS_UPSTREAM_PROXY=http://proxy.local:3128" in sidecar_env
assert (
"OPENSANDBOX_EGRESS_UPSTREAM_PROXY_AUTH=Basic dGVzdDp0ZXN0"
in sidecar_env
)
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_egress_sidecar_omits_upstream_proxy_env_when_not_configured(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.return_value = {"Id": "sidecar-id"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="egress:latest", disable_ipv6=False)
service = DockerSandboxService(config=cfg)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
service._start_egress_sidecar(
"sbx-abc123",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
)
sidecar_env = mock_client.api.create_container.call_args.kwargs["environment"]
assert not any(
entry.startswith("OPENSANDBOX_EGRESS_UPSTREAM_PROXY") for entry in sidecar_env
)
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_upstream_proxy_requires_transparent_mitm(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(
image="egress:latest",
mode=EGRESS_MODE_DNS_NFT,
upstream_proxy=EgressUpstreamProxyConfig(url="http://proxy.local:3128"),
)
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
networkPolicy=NetworkPolicy(default_action="deny", egress=[]),
)
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
assert "credentialProxy.enabled" in exc.value.detail["message"]
assert "OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT" in exc.value.detail["message"]
mock_client.api.create_container.assert_not_called()
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_egress_sidecar_normalizes_windows_port_bindings(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
def host_cfg_side_effect(**kwargs):
return kwargs
sidecar_container = MagicMock()
mock_client.api.create_host_config.side_effect = host_cfg_side_effect
mock_client.api.create_container.return_value = {"Id": "sidecar-id"}
mock_client.containers.get.return_value = sidecar_container
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="egress:latest", disable_ipv6=False)
service = DockerSandboxService(config=cfg)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
service._start_egress_sidecar(
"sandbox-id",
NetworkPolicy(defaultAction="deny", egress=[]),
egress_token="egress-token",
host_execd_port=44772,
host_http_port=8080,
extra_port_bindings={
"3389/tcp": ("0.0.0.0", 53389),
"3389/udp": ("0.0.0.0", 53390),
"8006/tcp": ("0.0.0.0", 58006),
},
)
hc_kwargs = mock_client.api.create_host_config.call_args.kwargs
assert "3389" in hc_kwargs["port_bindings"]
assert "3389/udp" in hc_kwargs["port_bindings"]
assert "8006" in hc_kwargs["port_bindings"]
sidecar_kwargs = mock_client.api.create_container.call_args.kwargs
assert "3389" in sidecar_kwargs["ports"]
assert "3389/udp" in sidecar_kwargs["ports"]
assert "8006" in sidecar_kwargs["ports"]
def _lifecycle_container(
container_id: str,
*,
running: bool,
paused: bool,
egress_expected: bool = False,
) -> MagicMock:
container = MagicMock()
container.id = container_id
labels = {}
if egress_expected:
labels[SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY] = "egress-token"
container.attrs = {
"Config": {"Labels": labels},
"State": {"Running": running, "Paused": paused},
}
return container
@pytest.mark.parametrize("failed_operation", ["kill", "remove"])
@pytest.mark.parametrize(
"docker_status, message, expected_status",
[
(409, "removal of container main-id is already in progress", 409),
(409, "container main-id is already being removed", 409),
(404, "No such container: main-id", 404),
(409, "unrelated daemon conflict", 500),
(500, "removal of container main-id is already in progress", 500),
],
)
def test_delete_sandbox_concurrent_outcomes(
tmp_path, failed_operation, docker_status, message, expected_status,
):
service = DockerSandboxService(config=_app_config())
service._metadata_store = DockerMetadataStore(tmp_path / "metadata")
expiration = datetime.now(timezone.utc) + timedelta(hours=1)
service._metadata_store.set_expiration("sandbox-id", expiration)
main = _lifecycle_container("main-id", running=True, paused=False)
error_type = DockerNotFound if docker_status == 404 else APIError
error = error_type(message, response=MagicMock(status_code=docker_status), explanation=message)
getattr(main, failed_operation).side_effect = error
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_cleanup_egress_sidecar") as cleanup_sidecar,
patch.object(service, "_remove_expiration_tracking") as remove_tracking,
patch.object(service, "_cleanup_windows_oem_volume") as cleanup_oem,
patch.object(service, "_release_ossfs_mounts") as release_mounts,
patch.object(service, "_cleanup_managed_volumes") as cleanup_volumes,
pytest.raises(HTTPException) as exc_info,
):
service.delete_sandbox("sandbox-id")
assert exc_info.value.status_code == expected_status
if expected_status == 404:
assert exc_info.value.detail == {
"code": SandboxErrorCodes.SANDBOX_NOT_FOUND,
"message": "Sandbox sandbox-id not found.",
}
cleanup_sidecar.assert_called_once_with("sandbox-id")
else:
assert exc_info.value.detail["code"] == SandboxErrorCodes.SANDBOX_DELETE_FAILED
assert exc_info.value.detail["message"]
cleanup_sidecar.assert_not_called()
if expected_status == 500:
assert str(error) in exc_info.value.detail["message"]
if failed_operation == "kill":
main.remove.assert_not_called()
remove_tracking.assert_not_called()
cleanup_oem.assert_not_called()
release_mounts.assert_not_called()
cleanup_volumes.assert_not_called()
assert service._metadata_store.get_expiration("sandbox-id") == expiration.isoformat()
@pytest.mark.parametrize("operation", ["pause", "resume"])
@pytest.mark.parametrize(
"docker_status, outcome, disappeared, expected_status",
[
(409, "state conflict", False, 409),
(409, "not running", False, 409),
(409, "not running", True, 404),
(404, "No such container: main-id", True, 404),
(409, "unrelated daemon conflict", False, 500),
(500, "state conflict", False, 500),
],
)
def test_pause_resume_sandbox_concurrent_outcomes(
operation, docker_status, outcome, disappeared, expected_status,
):
service = DockerSandboxService(config=_app_config())
resuming = operation == "resume"
main = _lifecycle_container("main-id", running=True, paused=resuming, egress_expected=True)
sidecar = _lifecycle_container("sidecar-id", running=True, paused=resuming)
if outcome == "state conflict":
message = "container main-id is not paused" if resuming else "container main-id is already paused"
elif outcome == "not running":
message = "container main-id is not running"
else:
message = outcome
error_type = DockerNotFound if docker_status == 404 else APIError
error = error_type(message, response=MagicMock(status_code=docker_status), explanation=message)
getattr(main, "unpause" if resuming else "pause").side_effect = error
missing = HTTPException(status_code=404, detail={
"code": SandboxErrorCodes.SANDBOX_NOT_FOUND,
"message": "Sandbox sandbox-id not found.",
})
lookup_results = [main, missing if disappeared else main]
with (
patch.object(service, "_get_container_by_sandbox_id", side_effect=lookup_results),
patch.object(service, "_get_egress_sidecars", return_value=[sidecar]),
patch.object(service._metadata_store, "set_transition") as set_transition,
pytest.raises(HTTPException) as exc_info,
):
getattr(service, f"{operation}_sandbox")("sandbox-id")
assert exc_info.value.status_code == expected_status
set_transition.assert_not_called()
if expected_status == 404:
assert exc_info.value.detail == missing.detail
elif expected_status == 409:
assert exc_info.value.detail == {
"code": SandboxErrorCodes.SANDBOX_NOT_PAUSED if resuming else SandboxErrorCodes.SANDBOX_NOT_RUNNING,
"message": f"Sandbox is not in a {'paused' if resuming else 'running'} state.",
}
else:
assert exc_info.value.detail == {
"code": SandboxErrorCodes.SANDBOX_RESUME_FAILED if resuming else SandboxErrorCodes.SANDBOX_PAUSE_FAILED,
"message": f"Failed to {operation} sandbox container: {error}",
}
if resuming:
main.unpause.assert_called_once_with()
# Keep the existing sidecar rollback even when the main failure maps to 409/404.
sidecar.unpause.assert_called_once_with()
sidecar.pause.assert_called_once_with()
else:
main.pause.assert_called_once_with()
sidecar.pause.assert_not_called()
main.unpause.assert_not_called()
@pytest.mark.parametrize("docker_status", [404, 409])
def test_resume_sandbox_race_with_failed_rollback_remains_500(docker_status):
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=True, egress_expected=True)
sidecar = _lifecycle_container("sidecar-id", running=True, paused=True)
error_type = DockerNotFound if docker_status == 404 else APIError
main.unpause.side_effect = error_type(
"resume raced", response=MagicMock(status_code=docker_status),
explanation="container main-id is not paused",
)
sidecar.pause.side_effect = DockerException("rollback failed")
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[sidecar]),
pytest.raises(HTTPException) as exc_info,
):
service.resume_sandbox("sandbox-id")
assert exc_info.value.status_code == 500
assert exc_info.value.detail["code"] == SandboxErrorCodes.SANDBOX_RESUME_FAILED
assert "rollback failed" in exc_info.value.detail["message"]
sidecar.pause.assert_called_once_with()
@pytest.mark.parametrize("operation", ["pause", "resume"])
@pytest.mark.parametrize("docker_status", [404, 409])
def test_pause_resume_sidecar_race_preserves_failure_and_rollback(operation, docker_status):
service = DockerSandboxService(config=_app_config())
resuming = operation == "resume"
main = _lifecycle_container("main-id", running=True, paused=resuming, egress_expected=True)
sidecar = _lifecycle_container("sidecar-id", running=True, paused=resuming)
error_type = DockerNotFound if docker_status == 404 else APIError
getattr(sidecar, "unpause" if resuming else "pause").side_effect = error_type(
"sidecar raced", response=MagicMock(status_code=docker_status),
explanation="container sidecar-id is not paused" if resuming else "container sidecar-id is already paused",
)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[sidecar]),
pytest.raises(HTTPException) as exc_info,
):
getattr(service, f"{operation}_sandbox")("sandbox-id")
assert exc_info.value.status_code == 500
assert exc_info.value.detail["code"] == (
SandboxErrorCodes.SANDBOX_RESUME_FAILED if resuming else SandboxErrorCodes.SANDBOX_PAUSE_FAILED
)
assert "egress sidecar" in exc_info.value.detail["message"]
if resuming:
main.unpause.assert_not_called()
else:
main.pause.assert_called_once_with()
main.unpause.assert_called_once_with()
@pytest.mark.parametrize("docker_status", [404, 409, 500])
def test_expire_sandbox_removal_race_retries_without_releasing_stale_mounts(tmp_path, docker_status):
service = DockerSandboxService(config=_app_config())
service._metadata_store = DockerMetadataStore(tmp_path / "metadata")
service._metadata_store.set_expiration("sandbox-id", datetime.now(timezone.utc) - timedelta(seconds=1))
main = _lifecycle_container("main-id", running=True, paused=False)
main.attrs["Config"]["Labels"][SANDBOX_OSSFS_MOUNTS_LABEL] = '["shared-mount"]'
error_type = DockerNotFound if docker_status == 404 else APIError
error = error_type(
"removal raced", response=MagicMock(status_code=docker_status),
explanation="removal of container main-id is already in progress",
)
main.remove.side_effect = error
if docker_status == 404:
main.kill.side_effect = error
missing = HTTPException(status_code=404, detail={
"code": SandboxErrorCodes.SANDBOX_NOT_FOUND,
"message": "Sandbox sandbox-id not found.",
})
with (
patch.object(service, "_get_container_by_sandbox_id", side_effect=[main, missing]),
patch.object(service, "_schedule_expiration") as schedule,
patch.object(service, "_cleanup_egress_sidecar") as cleanup_sidecar,
patch.object(service, "_release_ossfs_mounts") as release_mounts,
patch.object(service, "_cleanup_managed_volumes") as cleanup_volumes,
):
service._expire_sandbox("sandbox-id")
schedule.assert_called_once()
assert schedule.call_args.args[0] == "sandbox-id"
assert schedule.call_args.kwargs == {"update_expiration": False}
cleanup_sidecar.assert_not_called()
cleanup_volumes.assert_not_called()
assert service._metadata_store.get_expiration("sandbox-id") is not None
# A concurrent DELETE finished cleanup. Retry must re-read ownership.
service._expire_sandbox("sandbox-id")
cleanup_sidecar.assert_called_once_with("sandbox-id")
release_mounts.assert_not_called()
assert service._metadata_store.get_expiration("sandbox-id") is None
def test_pause_sandbox_pauses_main_before_egress_sidecar():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=False, egress_expected=True)
sidecar = _lifecycle_container("sidecar-id", running=True, paused=False)
events: list[str] = []
main.pause.side_effect = lambda: events.append("main.pause")
sidecar.pause.side_effect = lambda: events.append("sidecar.pause")
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[sidecar]),
):
service.pause_sandbox("sandbox-id")
assert events == ["main.pause", "sidecar.pause"]
def test_resume_sandbox_resumes_egress_sidecar_before_main():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=True, egress_expected=True)
sidecar = _lifecycle_container("sidecar-id", running=True, paused=True)
events: list[str] = []
sidecar.unpause.side_effect = lambda: events.append("sidecar.unpause")
main.unpause.side_effect = lambda: events.append("main.unpause")
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[sidecar]),
):
service.resume_sandbox("sandbox-id")
assert events == ["sidecar.unpause", "main.unpause"]
def test_pause_sandbox_without_egress_sidecar_preserves_main_only_behavior():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=False)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[]),
):
service.pause_sandbox("sandbox-id")
main.pause.assert_called_once_with()
def test_pause_sandbox_rejects_already_paused_main_without_mutating_containers():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=True, egress_expected=True)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars") as get_egress_sidecars,
pytest.raises(HTTPException) as exc_info,
):
service.pause_sandbox("sandbox-id")
assert exc_info.value.status_code == status.HTTP_409_CONFLICT
assert exc_info.value.detail["code"] == SandboxErrorCodes.SANDBOX_NOT_RUNNING
get_egress_sidecars.assert_not_called()
main.pause.assert_not_called()
def test_resume_sandbox_without_egress_sidecar_preserves_main_only_behavior():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=True)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[]),
):
service.resume_sandbox("sandbox-id")
main.unpause.assert_called_once_with()
def test_pause_sandbox_pauses_main_when_expected_egress_sidecar_is_missing():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=False, egress_expected=True)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[]),
pytest.raises(HTTPException) as exc_info,
):
service.pause_sandbox("sandbox-id")
assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
assert exc_info.value.detail["code"] == SandboxErrorCodes.SANDBOX_PAUSE_FAILED
assert "expected egress sidecar was not found" in exc_info.value.detail["message"]
main.pause.assert_called_once_with()
main.unpause.assert_not_called()
def test_resume_sandbox_fails_closed_when_expected_egress_sidecar_is_missing():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=True, egress_expected=True)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[]),
pytest.raises(HTTPException) as exc_info,
):
service.resume_sandbox("sandbox-id")
assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
assert exc_info.value.detail["code"] == SandboxErrorCodes.SANDBOX_RESUME_FAILED
assert "expected egress sidecar was not found" in exc_info.value.detail["message"]
main.unpause.assert_not_called()
def test_pause_sandbox_rolls_back_main_when_egress_sidecar_pause_fails():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=False, egress_expected=True)
sidecar = _lifecycle_container("sidecar-id", running=True, paused=False)
events: list[str] = []
main.pause.side_effect = lambda: events.append("main.pause")
main.unpause.side_effect = lambda: events.append("main.unpause")
def fail_sidecar_pause() -> None:
events.append("sidecar.pause")
raise DockerException("sidecar pause failed")
sidecar.pause.side_effect = fail_sidecar_pause
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[sidecar]),
pytest.raises(HTTPException) as exc_info,
):
service.pause_sandbox("sandbox-id")
assert exc_info.value.detail["code"] == SandboxErrorCodes.SANDBOX_PAUSE_FAILED
assert events == ["main.pause", "sidecar.pause", "main.unpause"]
def test_resume_sandbox_rolls_back_sidecar_when_main_resume_fails():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=True, egress_expected=True)
sidecar = _lifecycle_container("sidecar-id", running=True, paused=True)
events: list[str] = []
sidecar.unpause.side_effect = lambda: events.append("sidecar.unpause")
sidecar.pause.side_effect = lambda: events.append("sidecar.pause")
def fail_main_resume() -> None:
events.append("main.unpause")
raise DockerException("main resume failed")
main.unpause.side_effect = fail_main_resume
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[sidecar]),
pytest.raises(HTTPException) as exc_info,
):
service.resume_sandbox("sandbox-id")
assert exc_info.value.detail["code"] == SandboxErrorCodes.SANDBOX_RESUME_FAILED
assert events == ["sidecar.unpause", "main.unpause", "sidecar.pause"]
def test_pause_sandbox_does_not_mutate_when_egress_query_fails():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=False, egress_expected=True)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(
service,
"_get_egress_sidecars",
side_effect=DockerException("sidecar query failed"),
),
pytest.raises(HTTPException) as exc_info,
):
service.pause_sandbox("sandbox-id")
assert exc_info.value.detail["code"] == SandboxErrorCodes.SANDBOX_PAUSE_FAILED
main.pause.assert_not_called()
def test_resume_sandbox_does_not_mutate_when_egress_query_fails():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=True, egress_expected=True)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(
service,
"_get_egress_sidecars",
side_effect=DockerException("sidecar query failed"),
),
pytest.raises(HTTPException) as exc_info,
):
service.resume_sandbox("sandbox-id")
assert exc_info.value.detail["code"] == SandboxErrorCodes.SANDBOX_RESUME_FAILED
main.unpause.assert_not_called()
def test_pause_sandbox_skips_egress_sidecar_that_is_already_paused():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=False, egress_expected=True)
sidecar = _lifecycle_container("sidecar-id", running=True, paused=True)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[sidecar]),
):
service.pause_sandbox("sandbox-id")
main.pause.assert_called_once_with()
sidecar.pause.assert_not_called()
def test_resume_sandbox_skips_egress_sidecar_that_is_already_running():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main-id", running=True, paused=True, egress_expected=True)
sidecar = _lifecycle_container("sidecar-id", running=True, paused=False)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[sidecar]),
):
service.resume_sandbox("sandbox-id")
sidecar.unpause.assert_not_called()
main.unpause.assert_called_once_with()
def test_expire_cleans_sidecar():
service = DockerSandboxService(config=_app_config())
mock_container = MagicMock()
labels = {SANDBOX_PLATFORM_OS_LABEL: "windows"}
mock_container.attrs = {"State": {"Running": False}, "Config": {"Labels": labels}}
mock_container.kill = MagicMock()
mock_container.remove = MagicMock()
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=mock_container),
patch.object(service, "_remove_expiration_tracking") as mock_remove,
patch.object(service, "_cleanup_egress_sidecar") as mock_cleanup,
patch.object(service, "_cleanup_windows_oem_volume") as mock_cleanup_oem,
patch.object(service, "_docker_operation") as mock_op,
):
mock_op.return_value.__enter__.return_value = None
mock_op.return_value.__exit__.return_value = None
service._expire_sandbox("sandbox-id")
mock_cleanup.assert_called_once_with("sandbox-id")
mock_cleanup_oem.assert_called_once_with("sandbox-id", labels)
mock_remove.assert_called_once()
def test_restore_cleans_orphan_sidecar():
cfg = _app_config()
service = DockerSandboxService(config=cfg)
orphan_sidecar = MagicMock()
orphan_sidecar.attrs = {
"Config": {"Labels": {"opensandbox.io/egress-sidecar-for": "orphan-id"}}
}
with (
patch.object(service.docker_client.containers, "list", return_value=[orphan_sidecar]),
patch.object(service, "_get_container_by_sandbox_id") as mock_get,
patch.object(service, "_cleanup_egress_sidecar") as mock_cleanup,
):
mock_get.side_effect = HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail={})
service._restore_existing_sandboxes()
mock_cleanup.assert_called_once_with("orphan-id")
def test_expire_not_found_attempts_windows_oem_volume_cleanup():
service = DockerSandboxService(config=_app_config())
with (
patch.object(
service,
"_get_container_by_sandbox_id",
side_effect=HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail={}),
),
patch.object(service, "_remove_expiration_tracking") as mock_remove,
patch.object(service, "_cleanup_windows_oem_volume") as mock_cleanup_oem,
):
service._expire_sandbox("sandbox-missing")
mock_remove.assert_called_once_with("sandbox-missing")
mock_cleanup_oem.assert_called_once_with("sandbox-missing", None)
def test_expire_not_found_deletes_persisted_expiration_override(tmp_path):
service = DockerSandboxService(config=_app_config())
service._metadata_store = DockerMetadataStore(root=tmp_path / "metadata")
service._metadata_store.set_expiration("sandbox-missing", datetime(2030, 1, 1, tzinfo=timezone.utc))
with (
patch.object(
service,
"_get_container_by_sandbox_id",
side_effect=HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail={}),
),
patch.object(service, "_remove_expiration_tracking"),
patch.object(service, "_cleanup_windows_oem_volume"),
):
service._expire_sandbox("sandbox-missing")
assert service._metadata_store.get_expiration("sandbox-missing") is None
def test_prepare_creation_context_allows_manual_cleanup():
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
_, _, expires_at = service._prepare_creation_context(request)
assert expires_at is None
def test_build_labels_marks_manual_cleanup_without_expiration():
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={},
metadata={"team": "manual"},
entrypoint=["python"],
)
labels, _ = service._build_labels_and_env("sandbox-manual", request, None)
assert labels[SANDBOX_ID_LABEL] == "sandbox-manual"
assert labels[SANDBOX_MANUAL_CLEANUP_LABEL] == "true"
assert "opensandbox.io/expires-at" not in labels
def test_metadata_excludes_labels_inherited_from_the_image(tmp_path):
"""Docker merges image labels (e.g. nginx's ``maintainer``) into the
container's labels; only the keys the request set are metadata."""
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="nginx:latest"),
resourceLimits=ResourceLimits(root={}),
env={},
metadata={"team": "infra"},
entrypoint=["nginx"],
)
labels, _ = service._build_labels_and_env("sandbox-meta", request, None)
container_labels = {"maintainer": "NGINX Docker Maintainers", **labels}
store = DockerMetadataStore(root=tmp_path / "metadata")
assert store.get("sandbox-meta", container_labels) == {"team": "infra"}
def test_build_env_omits_execd_run_as_init_by_default():
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={"FOO": "bar"},
entrypoint=["python"],
)
_, environment = service._build_labels_and_env("sandbox-manual", request, None)
assert "FOO=bar" in environment
assert not any(e.startswith("EXECD_INIT=") for e in environment)
def test_build_env_injects_execd_run_as_init_when_enabled():
config = _app_config()
config.runtime.execd_run_as_init = True
service = DockerSandboxService(config=config)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={},
entrypoint=["python"],
)
_, environment = service._build_labels_and_env("sandbox-manual", request, None)
assert "EXECD_INIT=1" in environment
def test_build_labels_stores_renewal_policy_from_lifecycle():
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={},
entrypoint=["python"],
lifecycle=SandboxLifecycle(renewalPolicy={"extendSeconds": 3600}),
)
labels, _ = service._build_labels_and_env("sandbox-renew", request, None)
assert labels[ACCESS_RENEW_EXTEND_SECONDS_METADATA_KEY] == "3600"
def test_docker_create_accepts_renewal_policy_only_lifecycle():
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={},
entrypoint=["python"],
lifecycle=SandboxLifecycle(renewalPolicy={"extendSeconds": 3600}),
)
labels, _ = service._build_labels_and_env("sandbox-renew-only", request, None)
assert labels[ACCESS_RENEW_EXTEND_SECONDS_METADATA_KEY] == "3600"
def test_docker_create_rejects_lifecycle_hooks():
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={},
entrypoint=["python"],
lifecycle=SandboxLifecycle(preStart=LifecycleHook(command=["true"])),
)
with pytest.raises(HTTPException) as exc:
asyncio.run(service.create_sandbox(request))
assert exc.value.status_code == 400
assert "hooks" in exc.value.detail["message"]
def test_docker_create_rejects_idle_policy():
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={},
entrypoint=["python"],
lifecycle=SandboxLifecycle(
idlePolicy=IdlePolicy(idleTimeoutSeconds=300, onIdle="pause")
),
)
with pytest.raises(HTTPException) as exc:
asyncio.run(service.create_sandbox(request))
assert exc.value.status_code == 400
assert "idlePolicy" in exc.value.detail["message"]
def test_build_labels_stores_opensandbox_extensions():
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={},
entrypoint=["python"],
extensions={
"opensandbox.extensions.pool-ref": "my-pool",
"opensandbox.extensions.custom": "value",
},
)
labels, _ = service._build_labels_and_env("sandbox-ext2", request, None)
assert labels["opensandbox.io/extensions.pool-ref"] == "my-pool"
assert labels["opensandbox.io/extensions.custom"] == "value"
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_container_to_sandbox_returns_extensions(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
container = MagicMock()
container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "sandbox-ext",
"opensandbox.io/extensions.pool-ref": "my-pool",
"opensandbox.io/extensions.custom": "value",
"opensandbox.io/access-renew-extend-seconds": "1800",
},
"Cmd": ["python"],
"Image": "python:3.11",
},
"Created": "2025-01-01T00:00:00Z",
"State": {
"Status": "running",
"Running": True,
"FinishedAt": "0001-01-01T00:00:00Z",
"ExitCode": 0,
},
}
sandbox = service._container_to_sandbox(container)
assert sandbox.extensions == {
"opensandbox.extensions.pool-ref": "my-pool",
"opensandbox.extensions.custom": "value",
}
assert sandbox.metadata is None
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_container_to_sandbox_keeps_docker_times_with_trimmed_fraction(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
container = MagicMock()
container.attrs = {
"Config": {
"Labels": {SANDBOX_ID_LABEL: "sandbox-frac"},
"Cmd": ["python"],
"Image": "python:3.11",
},
"Created": "2025-01-01T00:00:00.12345Z",
"State": {
"Status": "exited",
"Running": False,
"FinishedAt": "2025-01-01T00:05:00.5Z",
"ExitCode": 0,
},
}
sandbox = service._container_to_sandbox(container)
assert sandbox.created_at == datetime(2025, 1, 1, 0, 0, 0, 123450, tzinfo=timezone.utc)
assert sandbox.status.last_transition_at == datetime(
2025, 1, 1, 0, 5, 0, 500000, tzinfo=timezone.utc
)
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_response_includes_extensions(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={},
entrypoint=["python"],
extensions={"opensandbox.extensions.test-key": "test-value"},
)
with patch.object(service, "_create_and_start_container") as mock_create:
mock_container = MagicMock()
mock_container.image = MagicMock(tags=["python:3.11"])
mock_create.return_value = mock_container
response = await service.create_sandbox(request)
assert response.extensions == {"opensandbox.extensions.test-key": "test-value"}
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_runs_docker_validation_off_the_event_loop(mock_docker):
"""Network and volume validation call the Docker API, which can block for
a long time; it must not run on the event loop thread."""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={},
entrypoint=["python"],
)
loop_thread = threading.get_ident()
validation_threads: list[int] = []
def record_thread(*_args):
validation_threads.append(threading.get_ident())
return {}, []
with (
patch.object(service, "_validate_network_exists", side_effect=record_thread),
patch.object(service, "_validate_volumes", side_effect=record_thread),
patch.object(service, "_create_and_start_container", return_value=MagicMock()),
):
await service.create_sandbox(request)
assert len(validation_threads) == 2
assert loop_thread not in validation_threads
def test_build_labels_store_platform_constraints():
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={},
entrypoint=["python"],
platform=PlatformSpec(os="linux", arch="arm64"),
)
labels, _ = service._build_labels_and_env("sandbox-platform", request, None)
assert labels[SANDBOX_PLATFORM_OS_LABEL] == "linux"
assert labels[SANDBOX_PLATFORM_ARCH_LABEL] == "arm64"
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_with_manual_cleanup_completes_full_create_path(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
env={"DEBUG": "1"},
metadata={"team": "manual"},
entrypoint=["python"],
)
with (
patch.object(service, "_create_and_start_container") as mock_create,
patch.object(service, "_schedule_expiration") as mock_schedule,
):
response = await service.create_sandbox(request)
assert response.expires_at is None
assert response.metadata == {"team": "manual"}
assert response.entrypoint == ["python"]
mock_create.assert_called_once()
mock_schedule.assert_not_called()
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_passes_platform_to_container_create(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
entrypoint=["python", "-c", "print('hello')"],
platform=PlatformSpec(os="linux", arch="arm64"),
)
with patch.object(service, "_create_and_start_container") as mock_create:
await service.create_sandbox(request)
called_args = mock_create.call_args.args
assert called_args[-1] is not None
assert called_args[-1].os == "linux"
assert called_args[-1].arch == "arm64"
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_response_keeps_platform_null_when_unconstrained(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
resourceLimits=ResourceLimits(root={}),
entrypoint=["python", "-c", "print('hello')"],
)
created_container = MagicMock()
created_container.image.attrs = {"Os": "linux", "Architecture": "amd64"}
with patch.object(
service,
"_create_and_start_container",
return_value=created_container,
):
response = await service.create_sandbox(request)
assert response.platform is None
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_create_and_start_container_uses_unconstrained_platform_for_execd(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
created_container = MagicMock()
created_container.image.attrs = {"Os": "linux", "Architecture": "arm64"}
mock_client.containers.get.return_value = created_container
service = DockerSandboxService(config=_app_config())
labels = {SANDBOX_ID_LABEL: "sandbox-1"}
with patch.object(service, "_prepare_sandbox_runtime") as mock_prepare:
service._create_and_start_container(
sandbox_id="sandbox-1",
image_uri="python:3.11",
bootstrap_command=["python", "-c", "print('hello')"],
labels=labels,
environment=[],
host_config_kwargs={},
exposed_ports=None,
platform=None,
)
passed_platform = mock_prepare.call_args.args[2]
assert passed_platform is not None
assert passed_platform.os == "linux"
assert passed_platform.arch == "arm64"
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_create_and_start_container_maps_platform_typeerror_to_invalid_parameter(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.side_effect = TypeError("unexpected keyword argument 'platform'")
service = DockerSandboxService(config=_app_config())
with pytest.raises(HTTPException) as exc_info:
service._create_and_start_container(
sandbox_id="sandbox-1",
image_uri="python:3.11",
bootstrap_command=["python", "-c", "print('hello')"],
labels={SANDBOX_ID_LABEL: "sandbox-1"},
environment=[],
host_config_kwargs={},
exposed_ports=None,
platform=PlatformSpec(os="linux", arch="arm64"),
)
assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
assert "platform-aware container create" in exc_info.value.detail["message"]
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_create_and_start_container_windows_profile_keeps_image_entrypoint(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
created_container = MagicMock()
# dockurr/windows image metadata is linux/*, but request platform is windows/*.
created_container.image.attrs = {"Os": "linux", "Architecture": "amd64"}
mock_client.containers.get.return_value = created_container
service = DockerSandboxService(config=_app_config())
with (
patch("opensandbox_server.services.docker.container_ops.fetch_execd_install_bat", return_value=b"script"),
patch("opensandbox_server.services.docker.container_ops.fetch_execd_windows_binary", return_value=b"exe"),
patch("opensandbox_server.services.docker.container_ops.install_windows_oem_scripts") as mock_install,
):
service._create_and_start_container(
sandbox_id="sandbox-win-1",
image_uri="dockurr/windows:latest",
bootstrap_command=["cmd", "/c", "echo ready"],
labels={SANDBOX_ID_LABEL: "sandbox-win-1"},
environment=[],
host_config_kwargs={},
exposed_ports=None,
platform=PlatformSpec(os="windows", arch="amd64"),
)
kwargs = mock_client.api.create_container.call_args.kwargs
assert "entrypoint" not in kwargs
assert "platform" not in kwargs
assert kwargs["command"] == ["cmd", "/c", "echo ready"]
mock_install.assert_called_once()
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_create_and_start_container_blanks_system_labels_inherited_from_image(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
# A snapshot image keeps every label of the sandbox it was committed from.
mock_client.images.get.return_value.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "source-sandbox",
SANDBOX_EXPIRES_AT_LABEL: "2026-01-01T00:00:00+00:00",
SANDBOX_HTTP_PORT_LABEL: "48891",
SANDBOX_MANAGED_VOLUMES_LABEL: '["source-volume"]',
SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY: "source-token",
"opensandbox.io/extensions.custom": "source-value",
"maintainer": "image-author",
}
}
}
created_container = MagicMock()
created_container.image.attrs = {"Os": "linux", "Architecture": "amd64"}
mock_client.containers.get.return_value = created_container
service = DockerSandboxService(config=_app_config())
labels = {
SANDBOX_ID_LABEL: "restored-sandbox",
SANDBOX_MANUAL_CLEANUP_LABEL: "true",
}
with patch.object(service, "_prepare_sandbox_runtime"):
service._create_and_start_container(
sandbox_id="restored-sandbox",
image_uri="opensandbox-snapshots:snap-1",
bootstrap_command=["sleep", "infinity"],
labels=labels,
environment=[],
host_config_kwargs={},
exposed_ports=None,
platform=None,
)
mock_client.images.get.assert_called_once_with("opensandbox-snapshots:snap-1")
assert mock_client.api.create_container.call_args.kwargs["labels"] == {
SANDBOX_ID_LABEL: "restored-sandbox",
SANDBOX_MANUAL_CLEANUP_LABEL: "true",
SANDBOX_EXPIRES_AT_LABEL: "",
SANDBOX_HTTP_PORT_LABEL: "",
SANDBOX_MANAGED_VOLUMES_LABEL: "",
SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY: "",
"opensandbox.io/extensions.custom": "",
}
assert labels == {
SANDBOX_ID_LABEL: "restored-sandbox",
SANDBOX_MANUAL_CLEANUP_LABEL: "true",
}
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_create_and_start_container_maps_image_label_inspect_failure(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.api.create_host_config.return_value = {}
mock_client.images.get.side_effect = DockerException("daemon unavailable")
service = DockerSandboxService(config=_app_config())
with pytest.raises(HTTPException) as exc_info:
service._create_and_start_container(
sandbox_id="sandbox-1",
image_uri="opensandbox-snapshots:snap-1",
bootstrap_command=["sleep", "infinity"],
labels={SANDBOX_ID_LABEL: "sandbox-1"},
environment=[],
host_config_kwargs={},
exposed_ports=None,
platform=None,
)
assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
assert exc_info.value.detail["code"] == SandboxErrorCodes.CONTAINER_START_FAILED
mock_client.api.create_container.assert_not_called()
def test_restore_existing_sandboxes_keeps_manual_cleanup_sandbox_with_blanked_expiration():
service = DockerSandboxService(config=_app_config())
container = MagicMock()
container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "restored-sandbox",
SANDBOX_MANUAL_CLEANUP_LABEL: "true",
SANDBOX_EXPIRES_AT_LABEL: "",
}
}
}
with (
patch.object(service.docker_client.containers, "list", return_value=[container]),
patch.object(service._metadata_store, "get_expiration", return_value=None),
patch.object(service, "_expire_sandbox") as mock_expire,
patch.object(service, "_schedule_expiration") as mock_schedule,
):
service._restore_existing_sandboxes()
mock_expire.assert_not_called()
mock_schedule.assert_not_called()
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_container_to_sandbox_ignores_blanked_system_labels(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
container = MagicMock()
container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "sandbox-1",
SANDBOX_MANUAL_CLEANUP_LABEL: "true",
SANDBOX_EXPIRES_AT_LABEL: "",
SANDBOX_SNAPSHOT_ID_LABEL: "",
"opensandbox.io/extensions.custom": "",
},
"Cmd": ["python"],
"Image": "python:3.11",
},
"Created": "2025-01-01T00:00:00Z",
"State": {
"Status": "running",
"Running": True,
"FinishedAt": "0001-01-01T00:00:00Z",
"ExitCode": 0,
},
}
with patch.object(service._metadata_store, "get_expiration", return_value=None):
sandbox = service._container_to_sandbox(container)
assert sandbox.expires_at is None
assert sandbox.snapshot_id is None
assert sandbox.image is not None
assert sandbox.image.uri == "python:3.11"
assert sandbox.extensions is None
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_create_and_start_container_windows_profile_skips_linux_runtime_injection(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
created_container = MagicMock()
created_container.image.attrs = {"Os": "linux", "Architecture": "amd64"}
mock_client.containers.get.return_value = created_container
service = DockerSandboxService(config=_app_config())
with (
patch.object(service, "_prepare_sandbox_runtime") as mock_prepare,
patch("opensandbox_server.services.docker.container_ops.fetch_execd_install_bat", return_value=b"script"),
patch("opensandbox_server.services.docker.container_ops.fetch_execd_windows_binary", return_value=b"exe"),
patch("opensandbox_server.services.docker.container_ops.install_windows_oem_scripts") as mock_install,
):
service._create_and_start_container(
sandbox_id="sandbox-win-2",
image_uri="dockurr/windows:latest",
bootstrap_command=["cmd", "/c", "echo ready"],
labels={SANDBOX_ID_LABEL: "sandbox-win-2"},
environment=[],
host_config_kwargs={},
exposed_ports=None,
platform=PlatformSpec(os="windows", arch="amd64"),
)
mock_prepare.assert_not_called()
mock_install.assert_called_once()
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_windows_profile_injects_runtime_defaults(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.runtime.execd_image = "ghcr.io/opensandbox/execd:v1.1.0"
cfg.docker.network_mode = "bridge"
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="dockurr/windows:latest"),
resourceLimits=ResourceLimits(root={}),
entrypoint=["cmd", "/c", "echo ready"],
platform=PlatformSpec(os="windows", arch="amd64"),
)
created_container = MagicMock()
created_container.image.attrs = {"Os": "windows", "Architecture": "amd64"}
with (
patch(
"opensandbox_server.services.docker.docker_service.validate_windows_runtime_prerequisites",
return_value=[],
),
patch.object(
service,
"_create_and_start_container",
return_value=created_container,
) as mock_create,
):
await service.create_sandbox(request)
host_config_kwargs = mock_create.call_args.args[5]
assert "/dev/kvm" in host_config_kwargs["devices"]
assert "/dev/net/tun" in host_config_kwargs["devices"]
assert "NET_ADMIN" in host_config_kwargs["cap_add"]
assert "NET_RAW" in host_config_kwargs["cap_add"]
assert not any(bind.endswith(":/storage:rw") for bind in host_config_kwargs["binds"])
assert any(bind.endswith(":/oem:rw") for bind in host_config_kwargs["binds"])
port_bindings = host_config_kwargs["port_bindings"]
assert "44772" in port_bindings
assert "8080" in port_bindings
assert "3389" in port_bindings
assert "3389/udp" in port_bindings
assert "8006" in port_bindings
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_windows_profile_does_not_require_download_url_override(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.runtime.execd_image = "ghcr.io/opensandbox/execd:latest"
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="dockurr/windows:latest"),
resourceLimits=ResourceLimits(root={}),
entrypoint=["cmd", "/c", "echo ready"],
platform=PlatformSpec(os="windows", arch="amd64"),
)
created_container = MagicMock()
created_container.image.attrs = {"Os": "windows", "Architecture": "amd64"}
with (
patch(
"opensandbox_server.services.docker.docker_service.validate_windows_runtime_prerequisites",
return_value=[],
),
patch.object(
service,
"_create_and_start_container",
return_value=created_container,
) as mock_create,
):
await service.create_sandbox(request)
mock_create.assert_called_once()
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_windows_profile_rejects_missing_runtime_devices(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.runtime.execd_image = "ghcr.io/opensandbox/execd:v1.1.0"
cfg.docker.network_mode = "bridge"
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="dockurr/windows:latest"),
resourceLimits=ResourceLimits(root={}),
entrypoint=["cmd", "/c", "echo ready"],
platform=PlatformSpec(os="windows", arch="amd64"),
)
with (
patch(
"opensandbox_server.services.docker.docker_service.validate_windows_runtime_prerequisites",
side_effect=HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail={
"code": SandboxErrorCodes.INVALID_PARAMETER,
"message": "Windows profile requires host devices to be present: /dev/kvm.",
},
),
),
patch.object(service, "_create_and_start_container") as mock_create,
pytest.raises(HTTPException) as exc_info,
):
await service.create_sandbox(request)
assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
assert "/dev/kvm" in exc_info.value.detail["message"]
mock_create.assert_not_called()
@pytest.mark.asyncio
@pytest.mark.parametrize(
"limits, field",
[
({"cpu": "1"}, "cpu"),
({"memory": "3 G"}, "memory"),
({"disk": "63G"}, "disk"),
({"memory": "invalid"}, "memory"),
],
)
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_windows_profile_rejects_invalid_resource_limits_before_side_effects(
mock_docker, limits, field
):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.runtime.execd_image = "ghcr.io/opensandbox/execd:v1.1.0"
cfg.docker.network_mode = "bridge"
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="dockurr/windows:latest"),
resourceLimits=ResourceLimits(root=limits),
entrypoint=["cmd", "/c", "echo ready"],
platform=PlatformSpec(os="windows", arch="amd64"),
)
with (
patch(
"opensandbox_server.services.docker.docker_service.validate_windows_runtime_prerequisites",
return_value=None,
),
patch.object(service, "_validate_volumes") as validate_volumes,
patch.object(service, "_ensure_image_available") as ensure_image,
patch.object(service, "_create_and_start_container") as mock_create,
pytest.raises(HTTPException) as exc_info,
):
await service.create_sandbox(request)
assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
assert f"resourceLimits.{field}" in exc_info.value.detail["message"]
validate_volumes.assert_not_called()
ensure_image.assert_not_called()
mock_client.volumes.create.assert_not_called()
mock_create.assert_not_called()
@pytest.mark.asyncio
@pytest.mark.parametrize("memory, expected_ram", [("8G", "8G"), ("4 G", "4G"), ("4096 Mi", "4G")])
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_windows_profile_accepts_dockur_demo_like_request(mock_docker, memory, expected_ram):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.runtime.execd_image = "ghcr.io/opensandbox/execd:v1.1.0"
cfg.docker.network_mode = "bridge"
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="dockurr/windows:latest"),
resourceLimits=ResourceLimits(
root={
"cpu": "4",
"memory": memory,
"disk": "64G",
}
),
env={"VERSION": "11"},
entrypoint=["cmd", "/c", "echo ready"],
platform=PlatformSpec(os="windows", arch="amd64"),
)
created_container = MagicMock()
created_container.image.attrs = {"Os": "windows", "Architecture": "amd64"}
with (
patch(
"opensandbox_server.services.docker.docker_service.validate_windows_runtime_prerequisites",
return_value=None,
),
patch.object(
service,
"_create_and_start_container",
return_value=created_container,
) as mock_create,
):
response = await service.create_sandbox(request)
forwarded_env = mock_create.call_args.args[4]
host_config_kwargs = mock_create.call_args.args[5]
assert "VERSION=11" in forwarded_env
assert "CPU_CORES=4" in forwarded_env
assert f"RAM_SIZE={expected_ram}" in forwarded_env
assert "DISK_SIZE=64G" in forwarded_env
assert "USER_PORTS=44772,8080,3389,8006" in forwarded_env
assert "mem_limit" not in host_config_kwargs
assert "nano_cpus" not in host_config_kwargs
assert "device_requests" not in host_config_kwargs
assert response.platform is not None
assert response.platform.os == "windows"
assert response.platform.arch == "amd64"
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_windows_profile_with_network_policy_maps_windows_ports(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.runtime.execd_image = "ghcr.io/opensandbox/execd:v1.1.0"
cfg.docker.network_mode = "bridge"
cfg.egress = EgressConfig(image="opensandbox/egress:latest")
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="dockurr/windows:latest"),
resourceLimits=ResourceLimits(
root={
"cpu": "4",
"memory": "8G",
"disk": "64G",
}
),
env={"VERSION": "11"},
entrypoint=["cmd", "/c", "echo ready"],
platform=PlatformSpec(os="windows", arch="amd64"),
networkPolicy=NetworkPolicy(default_action="deny", egress=[]),
)
created_container = MagicMock()
created_container.image.attrs = {"Os": "windows", "Architecture": "amd64"}
sidecar = MagicMock()
sidecar.id = "sidecar-123"
with (
patch(
"opensandbox_server.services.docker.docker_service.validate_windows_runtime_prerequisites",
return_value=None,
),
patch("opensandbox_server.services.docker.docker_service.generate_egress_token", return_value="egress-token"),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value={
"44772": ("0.0.0.0", 51664),
"8080": ("0.0.0.0", 48891),
"3389/tcp": ("0.0.0.0", 53389),
"3389/udp": ("0.0.0.0", 53390),
"8006/tcp": ("0.0.0.0", 58006),
},
),
patch.object(service, "_start_egress_sidecar", return_value=sidecar) as mock_start_sidecar,
patch.object(
service,
"_create_and_start_container",
return_value=created_container,
) as mock_create,
):
await service.create_sandbox(request)
_, start_kwargs = mock_start_sidecar.call_args
assert start_kwargs["host_execd_port"] == 51664
assert start_kwargs["host_http_port"] == 48891
assert start_kwargs["extra_port_bindings"] == {
"3389/tcp": ("0.0.0.0", 53389),
"3389/udp": ("0.0.0.0", 53390),
"8006/tcp": ("0.0.0.0", 58006),
}
forwarded_env = mock_create.call_args.args[4]
host_config_kwargs = mock_create.call_args.args[5]
forwarded_ports = mock_create.call_args.args[6]
labels = mock_create.call_args.args[3]
assert "USER_PORTS=44772,8080,3389,8006" in forwarded_env
assert host_config_kwargs["network_mode"] == "container:sidecar-123"
assert "NET_ADMIN" in set(host_config_kwargs.get("cap_add") or [])
assert "NET_ADMIN" not in set(host_config_kwargs.get("cap_drop") or [])
assert forwarded_ports is None
assert labels["opensandbox.io/embedding-proxy-port"] == "51664"
assert labels["opensandbox.io/http-port"] == "48891"
def test_restore_existing_sandboxes_ignores_manual_cleanup_without_warning():
service = DockerSandboxService(config=_app_config())
manual_container = MagicMock()
manual_container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "manual-id",
SANDBOX_MANUAL_CLEANUP_LABEL: "true",
}
}
}
with (
patch.object(service.docker_client.containers, "list", return_value=[manual_container]),
patch("opensandbox_server.services.docker.docker_service.logger.warning") as mock_warning,
patch.object(service, "_schedule_expiration") as mock_schedule,
):
service._restore_existing_sandboxes()
mock_schedule.assert_not_called()
mock_warning.assert_not_called()
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_container_snapshot_restore_reports_snapshot_id_without_image(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
container = MagicMock()
container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "sandbox-123",
SANDBOX_SNAPSHOT_ID_LABEL: "snap-001",
},
"Cmd": ["tail", "-f", "/dev/null"],
},
"Created": "2025-01-01T00:00:00Z",
"State": {
"Status": "running",
"Running": True,
"FinishedAt": "0001-01-01T00:00:00Z",
"ExitCode": 0,
},
}
sandbox = service._container_to_sandbox(container)
assert sandbox.snapshot_id == "snap-001"
assert sandbox.image is None
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_delete_sandbox_removes_windows_oem_volume(mock_docker):
mock_container = MagicMock()
mock_container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "sandbox-win-1",
SANDBOX_PLATFORM_OS_LABEL: "windows",
}
},
"State": {"Running": True},
}
mock_client = MagicMock()
mock_client.containers.list.return_value = [mock_container]
mock_client.containers.get.return_value = mock_container
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
service.delete_sandbox("sandbox-win-1")
mock_client.api.remove_volume.assert_called_once_with("opensandbox-win-oem-sandbox-win-1")
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_delete_sandbox_skips_oem_volume_cleanup_for_linux(mock_docker):
mock_container = MagicMock()
mock_container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "sandbox-linux-1",
SANDBOX_PLATFORM_OS_LABEL: "linux",
}
},
"State": {"Running": True},
}
mock_client = MagicMock()
mock_client.containers.list.return_value = [mock_container]
mock_client.containers.get.return_value = mock_container
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
service.delete_sandbox("sandbox-linux-1")
mock_client.api.remove_volume.assert_not_called()
def test_renew_expiration_rejects_manual_cleanup_sandbox():
service = DockerSandboxService(config=_app_config())
container = MagicMock()
container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "manual-id",
SANDBOX_MANUAL_CLEANUP_LABEL: "true",
}
}
}
request = MagicMock(expires_at=datetime.now(timezone.utc) + timedelta(hours=1))
with patch.object(service, "_get_container_by_sandbox_id", return_value=container):
with pytest.raises(HTTPException) as exc_info:
service.renew_expiration("manual-id", request)
assert exc_info.value.status_code == status.HTTP_409_CONFLICT
assert exc_info.value.detail["message"] == "Sandbox manual-id does not have automatic expiration enabled."
@pytest.mark.parametrize(
"delta_seconds",
[-600, 0, 600, 7200],
ids=["shorten", "unchanged", "extend", "above-create-limit"],
)
def test_renew_expiration_sets_future_timestamp_without_create_limit(tmp_path, delta_seconds):
config = _app_config()
config.server.max_sandbox_timeout_seconds = 3600
service = DockerSandboxService(config=config)
service._metadata_store = DockerMetadataStore(root=tmp_path / "metadata")
current_expiration = datetime.now(timezone.utc) + timedelta(minutes=30)
new_expiration = current_expiration + timedelta(seconds=delta_seconds)
container = MagicMock()
labels = {
SANDBOX_ID_LABEL: "sandbox-1",
SANDBOX_EXPIRES_AT_LABEL: current_expiration.isoformat(),
}
container.attrs = {"Config": {"Labels": labels}}
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=container),
patch.object(service, "_schedule_expiration") as mock_schedule,
patch.object(service, "_update_container_labels") as mock_update,
):
response = service.renew_expiration(
"sandbox-1", RenewSandboxExpirationRequest(expiresAt=new_expiration)
)
assert response.expires_at == new_expiration
mock_schedule.assert_called_once_with("sandbox-1", new_expiration)
mock_update.assert_called_once_with(container, labels)
assert labels[SANDBOX_EXPIRES_AT_LABEL] == new_expiration.isoformat()
assert service._metadata_store.get_expiration("sandbox-1") == new_expiration.isoformat()
def test_renew_expiration_persists_override_when_label_refresh_fails(tmp_path):
service = DockerSandboxService(config=_app_config())
service._metadata_store = DockerMetadataStore(root=tmp_path / "metadata")
container = MagicMock()
container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "sandbox-1",
SANDBOX_EXPIRES_AT_LABEL: datetime(2026, 7, 9, tzinfo=timezone.utc).isoformat(),
}
}
}
new_expiration = datetime.now(timezone.utc) + timedelta(hours=2)
request = RenewSandboxExpirationRequest(expiresAt=new_expiration)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=container),
patch.object(service, "_schedule_expiration") as mock_schedule,
patch.object(service, "_update_container_labels", side_effect=TypeError("labels unsupported")),
):
response = service.renew_expiration("sandbox-1", request)
mock_schedule.assert_called_once_with("sandbox-1", new_expiration)
assert response.expires_at == new_expiration
assert service._metadata_store.get_expiration("sandbox-1") == new_expiration.isoformat()
def test_get_tracked_expiration_prefers_persisted_override(tmp_path):
service = DockerSandboxService(config=_app_config())
service._metadata_store = DockerMetadataStore(root=tmp_path / "metadata")
persisted = datetime.now(timezone.utc) + timedelta(hours=3)
service._metadata_store.set_expiration("sandbox-1", persisted)
labels = {SANDBOX_EXPIRES_AT_LABEL: datetime(2026, 1, 1, tzinfo=timezone.utc).isoformat()}
assert service._get_tracked_expiration("sandbox-1", labels) == persisted
def test_restore_existing_sandboxes_prefers_persisted_expiration_override(tmp_path):
service = DockerSandboxService(config=_app_config())
service._metadata_store = DockerMetadataStore(root=tmp_path / "metadata")
persisted = datetime.now(timezone.utc) + timedelta(hours=1)
service._metadata_store.set_expiration("sandbox-1", persisted)
container = MagicMock()
container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "sandbox-1",
SANDBOX_EXPIRES_AT_LABEL: datetime(2026, 1, 1, tzinfo=timezone.utc).isoformat(),
}
}
}
with (
patch.object(service.docker_client.containers, "list", return_value=[container]),
patch.object(service, "_schedule_expiration") as mock_schedule,
):
service._restore_existing_sandboxes()
mock_schedule.assert_called_once_with("sandbox-1", persisted)
def test_expire_sandbox_renewed_reschedules_timer():
service = DockerSandboxService(config=_app_config())
current_expires = datetime.now(timezone.utc) + timedelta(minutes=10)
container = MagicMock()
container.attrs = {"Config": {"Labels": {SANDBOX_ID_LABEL: "sandbox-1"}}}
service._sandbox_expirations["sandbox-1"] = current_expires
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=container),
patch.object(service, "_schedule_expiration") as mock_schedule,
):
service._expire_sandbox("sandbox-1")
mock_schedule.assert_called_once_with("sandbox-1", current_expires, update_expiration=False)
container.kill.assert_not_called()
container.remove.assert_not_called()
@patch("opensandbox_server.services.docker.docker_service.docker")
class TestBuildVolumeBinds:
def test_none_volumes_returns_empty(self, mock_docker):
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
assert service._build_volume_binds(None) == []
def test_empty_volumes_returns_empty(self, mock_docker):
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
assert service._build_volume_binds([]) == []
def test_single_host_volume_rw(self, mock_docker):
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
volume = Volume(
name="workdir",
host=Host(path="/data/opensandbox/user-a"),
mount_path="/mnt/work",
read_only=False,
)
binds = service._build_volume_binds([volume])
assert binds == ["/data/opensandbox/user-a:/mnt/work:rw"]
def test_single_host_volume_ro(self, mock_docker):
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
volume = Volume(
name="workdir",
host=Host(path="/data/opensandbox/user-a"),
mount_path="/mnt/work",
read_only=True,
)
binds = service._build_volume_binds([volume])
assert binds == ["/data/opensandbox/user-a:/mnt/work:ro"]
def test_host_volume_with_subpath(self, mock_docker):
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
volume = Volume(
name="workdir",
host=Host(path="/data/opensandbox/user-a"),
mount_path="/mnt/work",
read_only=False,
sub_path="task-001",
)
binds = service._build_volume_binds([volume])
expected_host = os.path.normpath("/data/opensandbox/user-a/task-001")
assert binds == [f"{expected_host}:/mnt/work:rw"]
def test_multiple_host_volumes(self, mock_docker):
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
volumes = [
Volume(
name="workdir",
host=Host(path="/data/work"),
mount_path="/mnt/work",
read_only=False,
),
Volume(
name="data",
host=Host(path="/data/shared"),
mount_path="/mnt/data",
read_only=True,
),
]
binds = service._build_volume_binds(volumes)
assert len(binds) == 2
assert "/data/work:/mnt/work:rw" in binds
assert "/data/shared:/mnt/data:ro" in binds
def test_single_pvc_volume_rw(self, mock_docker):
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
volume = Volume(
name="shared-data",
pvc=PVC(claim_name="my-shared-volume"),
mount_path="/mnt/data",
read_only=False,
)
binds = service._build_volume_binds([volume])
assert binds == ["my-shared-volume:/mnt/data:rw"]
def test_single_pvc_volume_ro(self, mock_docker):
"""Single PVC volume with read-only (no subPath) should produce named volume bind string."""
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
volume = Volume(
name="models",
pvc=PVC(claim_name="shared-models-pvc"),
mount_path="/mnt/models",
read_only=True,
)
binds = service._build_volume_binds([volume])
assert binds == ["shared-models-pvc:/mnt/models:ro"]
def test_pvc_volume_with_subpath(self, mock_docker):
"""PVC volume with subPath should resolve via cached Mountpoint and produce bind mount."""
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
volume = Volume(
name="datasets",
pvc=PVC(claim_name="my-vol"),
mount_path="/mnt/train",
read_only=False,
sub_path="datasets/train",
)
cache = {
"my-vol": {
"Name": "my-vol",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-vol/_data",
}
}
binds = service._build_volume_binds([volume], pvc_inspect_cache=cache)
assert binds == ["/var/lib/docker/volumes/my-vol/_data/datasets/train:/mnt/train:rw"]
def test_pvc_volume_with_subpath_readonly(self, mock_docker):
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
volume = Volume(
name="datasets",
pvc=PVC(claim_name="my-vol"),
mount_path="/mnt/eval",
read_only=True,
sub_path="datasets/eval",
)
cache = {
"my-vol": {
"Name": "my-vol",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-vol/_data",
}
}
binds = service._build_volume_binds([volume], pvc_inspect_cache=cache)
assert binds == ["/var/lib/docker/volumes/my-vol/_data/datasets/eval:/mnt/eval:ro"]
def test_mixed_host_and_pvc_volumes(self, mock_docker):
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
volumes = [
Volume(
name="workdir",
host=Host(path="/data/work"),
mount_path="/mnt/work",
read_only=False,
),
Volume(
name="shared-data",
pvc=PVC(claim_name="my-shared-volume"),
mount_path="/mnt/data",
read_only=True,
),
]
binds = service._build_volume_binds(volumes)
assert len(binds) == 2
assert "/data/work:/mnt/work:rw" in binds
assert "my-shared-volume:/mnt/data:ro" in binds
def test_ossfs_volume_with_subpath(self, mock_docker):
"""OSSFS volume should resolve host path using subPath as OSS prefix."""
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
volume = Volume(
name="oss-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",
)
binds = service._build_volume_binds([volume])
assert binds == ["/mnt/ossfs/bucket-test-3/task-001:/mnt/data:rw"]
@patch("opensandbox_server.services.docker.docker_service.docker")
class TestDockerVolumeValidation:
@pytest.mark.parametrize("network_mode", ["host", "test-network"])
@pytest.mark.parametrize(
"name,mount_path,error_code",
[
("data", "/mnt/other", SandboxErrorCodes.DUPLICATE_VOLUME_NAME),
("other", "/mnt/data", SandboxErrorCodes.INVALID_MOUNT_PATH),
("other", "/mnt/data/", SandboxErrorCodes.INVALID_MOUNT_PATH),
("other", "/mnt/data/.", SandboxErrorCodes.INVALID_MOUNT_PATH),
("other", "/mnt/./data", SandboxErrorCodes.INVALID_MOUNT_PATH),
("other", "/mnt/cache/../data", SandboxErrorCodes.INVALID_MOUNT_PATH),
("other", "//mnt/data", SandboxErrorCodes.INVALID_MOUNT_PATH),
("other", "/", SandboxErrorCodes.INVALID_MOUNT_PATH),
("other", "//", SandboxErrorCodes.INVALID_MOUNT_PATH),
("other", "/.", SandboxErrorCodes.INVALID_MOUNT_PATH),
("other", "/mnt/..", SandboxErrorCodes.INVALID_MOUNT_PATH),
("other", "/\\", SandboxErrorCodes.INVALID_MOUNT_PATH),
("other", "/mnt/..\\", SandboxErrorCodes.INVALID_MOUNT_PATH),
],
)
@pytest.mark.asyncio
async def test_invalid_volumes_rejected_before_docker_calls(
self, mock_docker, name, mount_path, error_code, network_mode
):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.inspect_volume.return_value = {"Name": "shared-data"}
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.side_effect = DockerException("invalid mount destination")
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.docker.network_mode = network_mode
service = DockerSandboxService(config=cfg)
mock_client.reset_mock()
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
entrypoint=["python"],
volumes=[
Volume(
name="data",
pvc=PVC(claim_name="shared-data"),
mount_path="/mnt/data",
),
Volume(
name=name,
pvc=PVC(claim_name="shared-data"),
mount_path=mount_path,
),
],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
pytest.raises(HTTPException) as exc_info,
):
await service.create_sandbox(request)
assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc_info.value.detail["code"] == error_code
assert isinstance(exc_info.value.detail["message"], str)
mock_client.containers.create.assert_not_called()
mock_client.api.create_container.assert_not_called()
mock_client.api.inspect_volume.assert_not_called()
mock_client.api.create_volume.assert_not_called()
assert mock_client.mock_calls == []
@pytest.mark.parametrize(
"mount_path",
["/mnt/data/cache", "/mnt/other", "/tmp/opensandbox-execd", "/mnt\\data", "/mnt/data\\"],
)
@pytest.mark.asyncio
async def test_nested_and_repeated_source_mounts_allowed(self, mock_docker, mount_path):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.inspect_volume.return_value = {"Name": "shared-data"}
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
entrypoint=["python"],
volumes=[
Volume(
name="data",
pvc=PVC(claim_name="shared-data"),
mount_path="/mnt/data",
),
Volume(
name="other",
pvc=PVC(claim_name="shared-data"),
mount_path=mount_path,
),
],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
):
response = await service.create_sandbox(request)
assert response.status.state == "Running"
mock_client.api.create_container.assert_called_once()
assert mock_client.api.create_host_config.call_args.kwargs["binds"] == [
"shared-data:/mnt/data:rw",
f"shared-data:{mount_path}:rw",
]
@pytest.mark.asyncio
async def test_pvc_volume_not_found_rejected(self, mock_docker):
"""PVC backend with non-existent Docker named volume should be rejected when createIfNotExists is false."""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.inspect_volume.side_effect = DockerNotFound("volume not found")
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="models",
pvc=PVC(claim_name="nonexistent-volume", create_if_not_exists=False),
mount_path="/mnt/models",
read_only=True,
)
],
)
with pytest.raises(HTTPException) as exc_info:
await service.create_sandbox(request)
assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc_info.value.detail["code"] == SandboxErrorCodes.PVC_VOLUME_NOT_FOUND
@staticmethod
async def _create_with_failing_image_pull(mock_docker, remove_volume=None):
"""Create a sandbox whose image pull fails after an auto-created PVC volume.
Returns the raised exception, the pull error, and the volumes left behind.
"""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
volumes: dict[str, dict] = {}
def inspect_volume(name):
if name not in volumes:
raise DockerNotFound("volume not found")
return volumes[name]
def create_volume(name, labels):
volumes[name] = {"Name": name, "Labels": labels}
mock_client.api.inspect_volume.side_effect = inspect_volume
mock_client.api.create_volume.side_effect = create_volume
mock_client.api.remove_volume.side_effect = remove_volume or volumes.pop
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:does-not-exist"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="scratch",
pvc=PVC(claim_name="scratch", delete_on_sandbox_termination=True),
mount_path="/mnt/scratch",
)
],
)
pull_failed = HTTPException(status_code=500, detail="pull failed")
with patch.object(service, "_ensure_image_available", side_effect=pull_failed):
with pytest.raises(HTTPException) as exc_info:
await asyncio.wait_for(service.create_sandbox(request), timeout=5)
return exc_info.value, pull_failed, volumes
@pytest.mark.asyncio
async def test_auto_created_pvc_volume_removed_when_image_pull_fails(self, mock_docker):
"""A volume auto-created for the request is removed if creation fails before provisioning."""
raised, pull_failed, volumes = await self._create_with_failing_image_pull(mock_docker)
assert raised is pull_failed
assert "scratch" not in volumes
@pytest.mark.asyncio
async def test_create_failure_still_raised_when_volume_cleanup_fails(self, mock_docker):
"""A cleanup error must not swallow the create failure or leave the request hanging."""
def remove_volume(name):
raise RuntimeError("unexpected cleanup failure")
raised, pull_failed, _ = await self._create_with_failing_image_pull(
mock_docker, remove_volume=remove_volume
)
assert raised is pull_failed
def test_pvc_volume_auto_created_when_not_found(self, mock_docker):
"""PVC backend auto-creates Docker named volume when createIfNotExists is true (default)."""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
# First inspect fails (not found), then succeeds after create
mock_client.api.inspect_volume.side_effect = [
DockerNotFound("volume not found"),
{"Name": "my-volume", "Driver": "local", "Mountpoint": "/var/lib/docker/volumes/my-volume/_data"},
]
mock_client.api.create_volume.return_value = {}
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
service = DockerSandboxService(config=cfg)
volume = Volume(
name="data",
pvc=PVC(claim_name="my-volume"),
mount_path="/mnt/data",
read_only=False,
)
vol_info, auto_created = service._validate_pvc_volume(volume)
mock_client.api.create_volume.assert_called_once_with(
name="my-volume",
labels={"opensandbox.io/volume-managed-by": "server"},
)
assert vol_info["Name"] == "my-volume"
assert auto_created is True
def test_ossfs_inline_credentials_missing_rejected(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
with pytest.raises(ValidationError):
OSSFS(
bucket="bucket-test-3",
endpoint="oss-cn-hangzhou.aliyuncs.com",
access_key_id=None,
access_key_secret=None,
)
@pytest.mark.asyncio
async def test_ossfs_mount_failure_rejected(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="oss-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",
)
],
)
with patch("opensandbox_server.services.docker.ossfs_mixin.os.name", "posix"):
with patch("opensandbox_server.services.docker.ossfs_mixin.os.path.ismount", return_value=False):
with patch("opensandbox_server.services.docker.ossfs_mixin.os.makedirs"):
with patch("opensandbox_server.services.docker.ossfs_mixin.subprocess.run") as mock_run:
mock_run.return_value = MagicMock(returncode=1, stderr="mount failed")
with pytest.raises(HTTPException) as exc_info:
await service.create_sandbox(request)
assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
assert exc_info.value.detail["code"] == SandboxErrorCodes.OSSFS_MOUNT_FAILED
def test_ossfs_windows_host_not_supported(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
volume = Volume(
name="oss-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",
)
with patch("opensandbox_server.services.docker.ossfs_mixin.os.name", "nt"):
with pytest.raises(HTTPException) as exc_info:
service._validate_ossfs_volume(volume)
assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER
def test_ossfs_v1_mount_command_uses_o_options(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
volume = Volume(
name="oss-data",
ossfs=OSSFS(
bucket="bucket-test-3",
endpoint="oss-cn-hangzhou.aliyuncs.com",
version="1.0",
options=["allow_other", "umask=0022"],
access_key_id="AKIDEXAMPLE",
access_key_secret="SECRETEXAMPLE",
),
mount_path="/mnt/data",
sub_path="task-001",
)
backend_path = "/mnt/ossfs/bucket-test-3/task-001"
with patch("opensandbox_server.services.docker.ossfs_mixin.os.makedirs"):
with patch("opensandbox_server.services.docker.ossfs_mixin.subprocess.run") as mock_run:
mock_run.return_value = MagicMock(returncode=0, stderr="")
service._mount_ossfs_backend_path(volume, backend_path)
cmd = mock_run.call_args.args[0]
assert "bucket-test-3:/task-001" in cmd
assert "-o" in cmd
assert "allow_other" in cmd
assert "umask=0022" in cmd
assert "--allow_other" not in cmd
assert "sigv4" not in cmd
assert not any(str(part).startswith("region=") for part in cmd)
def test_ossfs_v2_mount_command_uses_config_file(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
volume = Volume(
name="oss-data",
ossfs=OSSFS(
bucket="bucket-test-3",
endpoint="oss-cn-hangzhou.aliyuncs.com",
version="2.0",
options=["allow_other", "umask=0022"],
access_key_id="AKIDEXAMPLE",
access_key_secret="SECRETEXAMPLE",
),
mount_path="/mnt/data",
sub_path="task-001",
)
backend_path = "/mnt/ossfs/bucket-test-3/task-001"
with patch("opensandbox_server.services.docker.ossfs_mixin.os.makedirs"):
with patch("opensandbox_server.services.docker.ossfs_mixin.subprocess.run") as mock_run:
mock_run.return_value = MagicMock(returncode=0, stderr="")
service._mount_ossfs_backend_path(volume, backend_path)
cmd = mock_run.call_args.args[0]
assert cmd[0] == "ossfs2"
assert cmd[1] == "mount"
assert cmd[2] == backend_path
assert cmd[3] == "-c"
assert cmd[4].endswith(".conf")
def test_ossfs_v2_config_contains_required_lines(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
volume = Volume(
name="oss-data",
ossfs=OSSFS(
bucket="bucket-test-3",
endpoint="oss-cn-hangzhou.aliyuncs.com",
version="2.0",
options=["allow_other", "umask=0022"],
access_key_id="AKIDEXAMPLE",
access_key_secret="SECRETEXAMPLE",
),
mount_path="/mnt/data",
sub_path="task-001",
)
conf_lines = service._build_ossfs_v2_config_lines(
volume=volume,
endpoint_url="http://oss-cn-hangzhou.aliyuncs.com",
prefix="task-001",
)
assert "--oss_endpoint=http://oss-cn-hangzhou.aliyuncs.com" in conf_lines
assert "--oss_bucket=bucket-test-3" in conf_lines
assert "--oss_access_key_id=AKIDEXAMPLE" in conf_lines
assert "--oss_access_key_secret=SECRETEXAMPLE" in conf_lines
assert "--oss_bucket_prefix=task-001/" in conf_lines
assert "--allow_other" in conf_lines
assert "--umask=0022" in conf_lines
@pytest.mark.asyncio
async def test_ossfs_volume_binds_passed_to_docker(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="oss-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=True,
sub_path="task-001",
)
],
)
with patch("opensandbox_server.services.docker.ossfs_mixin.os.name", "posix"):
with patch("opensandbox_server.services.docker.ossfs_mixin.os.path.ismount", return_value=False):
with patch("opensandbox_server.services.docker.ossfs_mixin.os.makedirs"):
with patch("opensandbox_server.services.docker.ossfs_mixin.subprocess.run") as mock_run:
mock_run.return_value = MagicMock(returncode=0, stderr="")
with patch.object(service, "_ensure_image_available"), patch.object(
service, "_prepare_sandbox_runtime"
):
response = await service.create_sandbox(request)
assert response.status.state == "Running"
assert mock_run.called
host_config_call = mock_client.api.create_host_config.call_args
binds = host_config_call.kwargs["binds"]
assert binds[0] == "/mnt/ossfs/bucket-test-3/task-001:/mnt/data:ro"
create_call = mock_client.api.create_container.call_args
labels = create_call.kwargs["labels"]
assert SANDBOX_OSSFS_MOUNTS_LABEL in labels
assert labels[SANDBOX_OSSFS_MOUNTS_LABEL] == '["/mnt/ossfs/bucket-test-3/task-001"]'
def test_prepare_ossfs_mounts_reuses_mount_key(self, mock_docker):
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
volumes = [
Volume(
name="oss-data-a",
ossfs=OSSFS(
bucket="bucket-test-3",
endpoint="oss-cn-hangzhou.aliyuncs.com",
access_key_id="AKIDEXAMPLE",
access_key_secret="SECRETEXAMPLE",
),
mount_path="/mnt/data-a",
sub_path="task-001",
),
Volume(
name="oss-data-b",
ossfs=OSSFS(
bucket="bucket-test-3",
endpoint="oss-cn-hangzhou.aliyuncs.com",
access_key_id="AKIDEXAMPLE",
access_key_secret="SECRETEXAMPLE",
),
mount_path="/mnt/data-b",
sub_path="task-001",
),
]
with patch("opensandbox_server.services.docker.ossfs_mixin.os.path.ismount", return_value=False):
with patch("opensandbox_server.services.docker.ossfs_mixin.os.makedirs"):
with patch("opensandbox_server.services.docker.ossfs_mixin.subprocess.run") as mock_run:
mock_run.return_value = MagicMock(returncode=0, stderr="")
mount_keys = service._prepare_ossfs_mounts(volumes)
mount_key = "/mnt/ossfs/bucket-test-3/task-001"
assert mount_keys == [mount_key]
assert service._ossfs_mount_ref_counts[mount_key] == 1
assert mock_run.call_count == 1
def test_prepare_ossfs_mounts_rolls_back_on_partial_failure(self, mock_docker):
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
volumes = [
Volume(
name="oss-data-a",
ossfs=OSSFS(
bucket="bucket-a",
endpoint="oss-cn-hangzhou.aliyuncs.com",
access_key_id="AKIDEXAMPLE",
access_key_secret="SECRETEXAMPLE",
),
mount_path="/mnt/data-a",
),
Volume(
name="oss-data-b",
ossfs=OSSFS(
bucket="bucket-b",
endpoint="oss-cn-hangzhou.aliyuncs.com",
access_key_id="AKIDEXAMPLE",
access_key_secret="SECRETEXAMPLE",
),
mount_path="/mnt/data-b",
),
]
mount_key_a = "/mnt/ossfs/bucket-a"
mount_key_b = "/mnt/ossfs/bucket-b"
with patch.object(
service,
"_ensure_ossfs_mounted",
side_effect=[mount_key_a, HTTPException(status_code=500, detail={"code": "E", "message": "boom"})],
) as ensure_mock:
with patch.object(service, "_release_ossfs_mounts") as release_mock:
with pytest.raises(HTTPException):
service._prepare_ossfs_mounts(volumes)
assert ensure_mock.call_count == 2
release_mock.assert_called_once_with([mount_key_a])
assert mount_key_b not in release_mock.call_args.args[0]
def test_delete_sandbox_releases_ossfs_mount(self, mock_docker):
mount_key = "/mnt/ossfs/bucket-test-3/task-001"
mock_container = MagicMock()
mock_container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "sandbox-1",
SANDBOX_OSSFS_MOUNTS_LABEL: f'["{mount_key}"]',
}
},
"State": {"Running": True},
}
mock_client = MagicMock()
mock_client.containers.list.return_value = [mock_container]
mock_client.containers.get.return_value = mock_container
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
service._ossfs_mount_ref_counts[mount_key] = 1
with patch("opensandbox_server.services.docker.ossfs_mixin.os.path.ismount", return_value=True):
with patch("opensandbox_server.services.docker.ossfs_mixin.subprocess.run") as mock_run:
mock_run.return_value = MagicMock(returncode=0, stderr="")
service.delete_sandbox("sandbox-1")
assert mount_key not in service._ossfs_mount_ref_counts
assert mock_run.called
def test_release_ossfs_mount_untracked_key_does_not_unmount(self, mock_docker):
mount_key = "/mnt/ossfs/bucket-test-3/task-001"
mock_docker.from_env.return_value = MagicMock()
service = DockerSandboxService(config=_app_config())
with patch("opensandbox_server.services.docker.ossfs_mixin.os.path.ismount", return_value=True):
with patch("opensandbox_server.services.docker.ossfs_mixin.subprocess.run") as mock_run:
service._release_ossfs_mount(mount_key)
mock_run.assert_not_called()
assert mount_key not in service._ossfs_mount_ref_counts
def test_restore_existing_sandboxes_rebuilds_ossfs_refs(self, mock_docker):
mount_key = "/mnt/ossfs/bucket-test-3/task-001"
expires_at = (datetime.now(timezone.utc) + timedelta(minutes=10)).isoformat()
container = MagicMock()
container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "sandbox-1",
SANDBOX_EXPIRES_AT_LABEL: expires_at,
SANDBOX_OSSFS_MOUNTS_LABEL: f'["{mount_key}"]',
}
},
"State": {"Running": True},
}
mock_client = MagicMock()
mock_client.containers.list.return_value = [container]
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
assert service._ossfs_mount_ref_counts[mount_key] == 1
def test_delete_one_sandbox_after_restart_keeps_shared_mount(self, mock_docker):
mount_key = "/mnt/ossfs/bucket-test-3/task-001"
expires_at = (datetime.now(timezone.utc) + timedelta(minutes=10)).isoformat()
container_a = MagicMock()
container_a.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "sandbox-a",
SANDBOX_EXPIRES_AT_LABEL: expires_at,
SANDBOX_OSSFS_MOUNTS_LABEL: f'["{mount_key}"]',
}
},
"State": {"Running": True},
}
container_b = MagicMock()
container_b.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "sandbox-b",
SANDBOX_EXPIRES_AT_LABEL: expires_at,
SANDBOX_OSSFS_MOUNTS_LABEL: f'["{mount_key}"]',
}
},
"State": {"Running": True},
}
mock_client = MagicMock()
mock_client.containers.list.return_value = [container_a, container_b]
mock_client.containers.get.side_effect = lambda name: {
"sandbox-sandbox-a": container_a,
"sandbox-sandbox-b": container_b,
}[name]
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
assert service._ossfs_mount_ref_counts[mount_key] == 2
with patch("opensandbox_server.services.docker.ossfs_mixin.os.path.ismount", return_value=True):
with patch("opensandbox_server.services.docker.ossfs_mixin.subprocess.run") as mock_run:
service.delete_sandbox("sandbox-a")
assert service._ossfs_mount_ref_counts[mount_key] == 1
mock_run.assert_not_called()
def test_restore_manual_cleanup_sandbox_rebuilds_ossfs_refs(self, mock_docker):
mount_key = "/mnt/ossfs/bucket-manual/data"
container = MagicMock()
container.attrs = {
"Config": {
"Labels": {
SANDBOX_ID_LABEL: "sandbox-manual",
SANDBOX_MANUAL_CLEANUP_LABEL: "true",
SANDBOX_OSSFS_MOUNTS_LABEL: f'["{mount_key}"]',
}
},
"State": {"Running": True},
}
mock_client = MagicMock()
mock_client.containers.list.return_value = [container]
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
assert service._ossfs_mount_ref_counts.get(mount_key) == 1
@pytest.mark.asyncio
async def test_pvc_volume_inspect_failure_returns_500(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.inspect_volume.side_effect = DockerException("connection error")
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="shared-data",
pvc=PVC(claim_name="my-volume"),
mount_path="/mnt/data",
)
],
)
with pytest.raises(HTTPException) as exc_info:
await service.create_sandbox(request)
assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
assert exc_info.value.detail["code"] == SandboxErrorCodes.PVC_VOLUME_INSPECT_FAILED
@pytest.mark.asyncio
async def test_pvc_volume_binds_passed_to_docker(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.inspect_volume.return_value = {"Name": "my-shared-volume"}
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="shared-data",
pvc=PVC(claim_name="my-shared-volume"),
mount_path="/mnt/data",
read_only=False,
)
],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
):
response = await service.create_sandbox(request)
assert response.status.state == "Running"
host_config_call = mock_client.api.create_host_config.call_args
assert "binds" in host_config_call.kwargs
binds = host_config_call.kwargs["binds"]
assert len(binds) == 1
assert binds[0] == "my-shared-volume:/mnt/data:rw"
@pytest.mark.asyncio
async def test_pvc_volume_readonly_binds_passed_to_docker(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.inspect_volume.return_value = {"Name": "shared-models"}
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="models",
pvc=PVC(claim_name="shared-models"),
mount_path="/mnt/models",
read_only=True,
)
],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
):
await service.create_sandbox(request)
host_config_call = mock_client.api.create_host_config.call_args
binds = host_config_call.kwargs["binds"]
assert binds[0] == "shared-models:/mnt/models:ro"
@pytest.mark.asyncio
@pytest.mark.parametrize("read_only", [False, True])
async def test_external_plugin_volume_without_subpath(self, mock_docker, read_only):
"""External drivers need neither a local Mountpoint nor server provisioning."""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.inspect_volume.return_value = {
"Name": "rclone-data",
"Driver": "rclone",
"Mountpoint": "",
}
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
entrypoint=["python"],
volumes=[
Volume(
name="remote-storage",
pvc=PVC(
claim_name="rclone-data",
create_if_not_exists=False,
# Even an explicit cleanup request must not own a pre-existing volume.
delete_on_sandbox_termination=True,
),
mount_path="/mnt/remote",
read_only=read_only,
),
],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
):
response = await service.create_sandbox(request)
assert response.status.state == "Running"
mode = "ro" if read_only else "rw"
assert mock_client.api.create_host_config.call_args.kwargs["binds"] == [
f"rclone-data:/mnt/remote:{mode}"
]
mock_client.api.create_volume.assert_not_called()
labels = mock_client.api.create_container.call_args.kwargs["labels"]
assert json.loads(labels.get(SANDBOX_MANAGED_VOLUMES_LABEL, "[]")) == []
@pytest.mark.asyncio
async def test_pvc_subpath_non_local_driver_rejected(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.inspect_volume.return_value = {
"Name": "cloud-vol",
"Driver": "nfs",
"Mountpoint": "",
}
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="data",
pvc=PVC(claim_name="cloud-vol"),
mount_path="/mnt/data",
sub_path="subdir",
)
],
)
with pytest.raises(HTTPException) as exc_info:
await service.create_sandbox(request)
assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc_info.value.detail["code"] == SandboxErrorCodes.PVC_SUBPATH_UNSUPPORTED_DRIVER
@pytest.mark.asyncio
async def test_pvc_subpath_symlink_escape_rejected(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.inspect_volume.return_value = {
"Name": "my-vol",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-vol/_data",
}
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="data",
pvc=PVC(claim_name="my-vol"),
mount_path="/mnt/data",
sub_path="datasets",
)
],
)
# Simulate: realpath resolves a symlink that escapes the mountpoint.
# datasets -> / inside the volume, so realpath(…/_data/datasets) = /
with patch("opensandbox_server.services.docker.docker_service.os.path.realpath") as mock_realpath:
mock_realpath.side_effect = lambda p, **kwargs: ("/" if p.endswith("datasets") else p)
with pytest.raises(HTTPException) as exc_info:
await service.create_sandbox(request)
assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_SUB_PATH
assert "symlink" in exc_info.value.detail["message"]
@pytest.mark.asyncio
async def test_pvc_subpath_binds_resolved_to_mountpoint(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.inspect_volume.return_value = {
"Name": "my-vol",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-vol/_data",
}
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="train-data",
pvc=PVC(claim_name="my-vol"),
mount_path="/mnt/train",
read_only=True,
sub_path="datasets/train",
)
],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
):
await service.create_sandbox(request)
host_config_call = mock_client.api.create_host_config.call_args
binds = host_config_call.kwargs["binds"]
assert len(binds) == 1
assert binds[0] == "/var/lib/docker/volumes/my-vol/_data/datasets/train:/mnt/train:ro"
@pytest.mark.asyncio
async def test_host_path_not_found_rejected(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.storage = StorageConfig(
allowed_host_paths=["/nonexistent/path/that/does/not/exist"]
)
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="workdir",
host=Host(path="/nonexistent/path/that/does/not/exist"),
mount_path="/mnt/work",
read_only=False,
)
],
)
with patch("opensandbox_server.services.docker.docker_service.os.makedirs", side_effect=PermissionError("denied")):
with pytest.raises(HTTPException) as exc_info:
await service.create_sandbox(request)
assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
assert exc_info.value.detail["code"] == SandboxErrorCodes.HOST_PATH_CREATE_FAILED
@pytest.mark.asyncio
async def test_host_path_not_in_allowlist_rejected(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
cfg.storage = StorageConfig(allowed_host_paths=["/data/opensandbox"])
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="workdir",
host=Host(path="/etc/passwd"),
mount_path="/mnt/work",
read_only=False,
)
],
)
with pytest.raises(HTTPException) as exc_info:
await service.create_sandbox(request)
assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST
assert exc_info.value.detail["code"] == SandboxErrorCodes.HOST_PATH_NOT_ALLOWED
@pytest.mark.asyncio
async def test_no_volumes_passes_validation(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
):
response = await service.create_sandbox(request)
assert response.status.state == "Running"
@pytest.mark.asyncio
async def test_host_volume_binds_passed_to_docker(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
import tempfile
with tempfile.TemporaryDirectory() as tmpdir:
cfg = _app_config()
cfg.storage = StorageConfig(allowed_host_paths=[tmpdir])
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="workdir",
host=Host(path=tmpdir),
mount_path="/mnt/work",
read_only=False,
)
],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
):
await service.create_sandbox(request)
host_config_call = mock_client.api.create_host_config.call_args
assert "binds" in host_config_call.kwargs
binds = host_config_call.kwargs["binds"]
assert len(binds) == 1
assert binds[0] == f"{tmpdir}:/mnt/work:rw"
@pytest.mark.asyncio
async def test_host_file_bind_passes_validation(self, mock_docker):
"""Existing host file should be allowed without mkdir."""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
import tempfile
with tempfile.NamedTemporaryFile(suffix=".iso") as iso_file:
cfg = _app_config()
cfg.storage = StorageConfig(allowed_host_paths=[iso_file.name])
service = DockerSandboxService(config=cfg)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="boot-iso",
host=Host(path=iso_file.name),
mount_path="/boot.iso",
read_only=True,
)
],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
):
await service.create_sandbox(request)
host_config_call = mock_client.api.create_host_config.call_args
binds = host_config_call.kwargs["binds"]
assert len(binds) == 1
assert binds[0] == f"{iso_file.name}:/boot.iso:ro"
@pytest.mark.asyncio
async def test_host_volume_with_subpath_resolved_correctly(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
import tempfile
with tempfile.TemporaryDirectory() as tmpdir:
cfg = _app_config()
cfg.storage = StorageConfig(allowed_host_paths=[tmpdir])
service = DockerSandboxService(config=cfg)
sub_dir = os.path.join(tmpdir, "task-001")
os.makedirs(sub_dir)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="workdir",
host=Host(path=tmpdir),
mount_path="/mnt/work",
read_only=True,
sub_path="task-001",
)
],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
):
await service.create_sandbox(request)
host_config_call = mock_client.api.create_host_config.call_args
binds = host_config_call.kwargs["binds"]
assert len(binds) == 1
assert binds[0] == f"{sub_dir}:/mnt/work:ro"
@pytest.mark.asyncio
async def test_host_volume_symlink_bypass_rejected(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
import tempfile
with tempfile.TemporaryDirectory() as tmpdir:
link_path = os.path.join(tmpdir, "escape")
os.symlink("/", link_path)
cfg = _app_config()
cfg.storage = StorageConfig(allowed_host_paths=[tmpdir])
service = DockerSandboxService(config=cfg)
# Request /tmpdir/escape/etc — lexical check passes (starts with
# tmpdir) but realpath resolves escape -> /, producing /etc which
# is outside the allowed prefix.
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="escape-vol",
host=Host(path=os.path.join(link_path, "etc")),
mount_path="/mnt/etc",
read_only=True,
)
],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
):
with pytest.raises(HTTPException) as exc_info:
await service.create_sandbox(request)
assert exc_info.value.status_code == 400
assert exc_info.value.detail["code"] == SandboxErrorCodes.HOST_PATH_NOT_ALLOWED
@pytest.mark.asyncio
async def test_host_subpath_auto_created(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
import tempfile
with tempfile.TemporaryDirectory() as tmpdir:
cfg = _app_config()
cfg.storage = StorageConfig(allowed_host_paths=[tmpdir])
service = DockerSandboxService(config=cfg)
sub = "auto-created-sub"
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="workdir",
host=Host(path=tmpdir),
mount_path="/mnt/work",
read_only=False,
sub_path=sub,
)
],
)
import os
resolved = os.path.join(tmpdir, sub)
assert not os.path.exists(resolved)
# create_sandbox will proceed past volume validation (subpath
# auto-created) but will fail later during container provisioning
# (mock doesn't cover the full flow). We only care that the
# directory was created — NOT that it raised HOST_PATH_CREATE_FAILED.
try:
await service.create_sandbox(request)
except HTTPException as e:
# If it's our own create-failed error, the auto-create didn't
# work — let the test fail explicitly.
if e.detail.get("code") == SandboxErrorCodes.HOST_PATH_CREATE_FAILED:
raise
except Exception:
pass # other provisioning errors are expected
assert os.path.isdir(resolved)
@pytest.mark.asyncio
async def test_empty_allowlist_rejects_host_path(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
cfg = _app_config()
assert cfg.storage.allowed_host_paths == []
service = DockerSandboxService(config=cfg)
import tempfile
with tempfile.TemporaryDirectory() as tmpdir:
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
volumes=[
Volume(
name="workdir",
host=Host(path=tmpdir),
mount_path="/mnt/work",
read_only=False,
)
],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
):
with pytest.raises(HTTPException) as exc_info:
await service.create_sandbox(request)
assert exc_info.value.status_code == 400
assert exc_info.value.detail["code"] == SandboxErrorCodes.HOST_PATH_NOT_ALLOWED
@pytest.mark.asyncio
async def test_no_volumes_omits_binds_from_host_config(self, mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.create_host_config.return_value = {}
mock_client.api.create_container.return_value = {"Id": "cid"}
mock_client.containers.get.return_value = MagicMock()
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_prepare_sandbox_runtime"),
):
await service.create_sandbox(request)
host_config_call = mock_client.api.create_host_config.call_args
assert "binds" not in host_config_call.kwargs
def test_docker_get_endpoint_rejects_expires():
from unittest.mock import patch
with patch("opensandbox_server.services.docker.docker_service.docker"):
cfg = _app_config()
cfg.docker.network_mode = "bridge"
service = DockerSandboxService(config=cfg)
with pytest.raises(HTTPException) as exc:
service.get_endpoint("sbx-001", 8080, expires=1000)
assert exc.value.status_code == status.HTTP_400_BAD_REQUEST
assert "not supported" in exc.value.detail["message"].lower()
# ============================================================================
# list_sandboxes: race-safety and full-fidelity semantics
# ============================================================================
def _list_summary(sandbox_id: str, *, labels: dict | None = None) -> dict:
"""Build the subset of a Docker low-level ``containers()`` summary that
``list_sandboxes`` reads (Id + Labels only)."""
merged_labels = {SANDBOX_ID_LABEL: sandbox_id, **(labels or {})}
return {"Id": f"cid-{sandbox_id}", "Labels": merged_labels}
def _mock_container(
sandbox_id: str,
*,
running: bool = True,
paused: bool = False,
restarting: bool = False,
docker_status: str = "running",
exit_code: int | None = None,
entrypoint: list[str] | None = None,
image: str = "python:3.11",
finished_at: str = "0001-01-01T00:00:00Z",
extra_labels: dict | None = None,
) -> MagicMock:
"""Build a MagicMock container matching what ``_container_to_sandbox``
expects to read from ``container.attrs``."""
labels = {SANDBOX_ID_LABEL: sandbox_id, **(extra_labels or {})}
container = MagicMock()
container.attrs = {
"Created": "2024-01-01T00:00:00Z",
"Config": {
"Image": image,
"Labels": labels,
"Cmd": entrypoint if entrypoint is not None else ["python", "-V"],
},
"State": {
"Status": docker_status,
"Running": running,
"Paused": paused,
"Restarting": restarting,
"ExitCode": exit_code,
"FinishedAt": finished_at,
},
}
container.status = docker_status
return container
@pytest.mark.asyncio
@pytest.mark.parametrize("timeout", [None, 120])
async def test_create_get_timestamp_consistency_preserves_ttl(timeout):
requested_at = datetime(2030, 1, 1, tzinfo=timezone.utc)
created_at = requested_at + timedelta(seconds=2, microseconds=123456)
container = _mock_container("timestamp-test")
container.attrs["Created"] = created_at.isoformat()
docker_client = MagicMock()
docker_client.containers.list.return_value = []
docker_client.containers.get.return_value = container
def create_container(sandbox_id, image, entrypoint, labels, *args, **kwargs):
container.attrs["Config"]["Labels"] = dict(labels)
return container
with (
patch("docker.from_env", return_value=docker_client),
patch("opensandbox_server.services.docker.docker_service.datetime", wraps=datetime) as clock,
):
clock.now.return_value = requested_at
service = DockerSandboxService(config=_app_config())
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"), timeout=timeout,
resourceLimits=ResourceLimits(root={}), entrypoint=["python"],
)
with (
patch.object(service, "generate_sandbox_id", return_value="timestamp-test"),
patch.object(service, "_ensure_image_available"),
patch.object(service, "_create_and_start_container", side_effect=create_container),
patch.object(service, "_schedule_expiration") as schedule,
):
created = await service.create_sandbox(request)
expected_expiration = requested_at + timedelta(seconds=timeout) if timeout else None
assert created.expires_at == expected_expiration
if timeout:
schedule.assert_called_once_with(created.id, expected_expiration)
else:
schedule.assert_not_called()
clock.now.return_value = requested_at + timedelta(seconds=10)
for _ in range(2):
fetched = service.get_sandbox(created.id)
assert created.created_at == fetched.created_at == requested_at
assert created.status.last_transition_at == fetched.status.last_transition_at == requested_at
assert fetched.expires_at == expected_expiration
reconstructed = DockerSandboxService(config=_app_config()).get_sandbox(created.id)
assert reconstructed.created_at == requested_at
assert reconstructed.expires_at == expected_expiration
@pytest.mark.parametrize("exit_code", [0, 137])
def test_pause_resume_transition_timestamps_survive_reconstruction(exit_code):
created_at = datetime(2030, 1, 1, tzinfo=timezone.utc)
expires_at = created_at + timedelta(hours=1)
container = _mock_container(
"timestamp-test", extra_labels={SANDBOX_EXPIRES_AT_LABEL: expires_at.isoformat()}
)
container.attrs["Created"] = created_at.isoformat()
state = container.attrs["State"]
container.pause.side_effect = lambda: state.update(Paused=True)
container.unpause.side_effect = lambda: state.update(Paused=False)
docker_client = MagicMock()
docker_client.containers.list.return_value = []
docker_client.containers.get.return_value = container
with (
patch("docker.from_env", return_value=docker_client),
patch("opensandbox_server.services.docker.docker_service.datetime", wraps=datetime) as clock,
):
service = DockerSandboxService(config=_app_config())
previous_transition = created_at
for step, expected_state in enumerate(["Paused", "Running", "Paused", "Running"], 1):
transitioned_at = created_at + timedelta(seconds=step * 10)
clock.now.return_value = transitioned_at
if expected_state == "Paused":
service.pause_sandbox("timestamp-test")
else:
service.resume_sandbox("timestamp-test")
clock.now.return_value += timedelta(seconds=1)
# Each new service must read the timestamp from disk, not process memory.
service = DockerSandboxService(config=_app_config())
for _ in range(2):
fetched = service.get_sandbox("timestamp-test")
assert fetched.status.state == expected_state
assert fetched.status.last_transition_at == transitioned_at > previous_transition
assert fetched.created_at == created_at
assert fetched.expires_at == expires_at
previous_transition = transitioned_at
finished_at = created_at + timedelta(minutes=1, microseconds=500000)
state.update(Running=False, Status="exited", ExitCode=exit_code, FinishedAt=finished_at.isoformat())
service = DockerSandboxService(config=_app_config())
terminated = service.get_sandbox("timestamp-test")
assert terminated.status.state == ("Terminated" if exit_code == 0 else "Failed")
assert terminated.status.last_transition_at == finished_at
assert terminated.created_at == created_at
assert terminated.expires_at == expires_at
service.delete_sandbox("timestamp-test")
assert not list(service._metadata_store._root.rglob("timestamp-test.json"))
@pytest.mark.parametrize("sidecar_missing", [False, True])
def test_pause_failure_timestamp_matches_actual_state(sidecar_missing):
paused_at = datetime(2030, 1, 1, tzinfo=timezone.utc)
rolled_back_at = paused_at + timedelta(seconds=1)
container = _mock_container(
"timestamp-test", extra_labels={SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY: "token"}
)
state = container.attrs["State"]
container.pause.side_effect = lambda: state.update(Paused=True)
container.unpause.side_effect = lambda: state.update(Paused=False)
sidecar = _lifecycle_container("sidecar", running=True, paused=False)
sidecar.pause.side_effect = DockerException("sidecar pause failed")
service = DockerSandboxService(config=_app_config())
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=container),
patch.object(service, "_get_egress_sidecars", return_value=[] if sidecar_missing else [sidecar]),
patch("opensandbox_server.services.docker.docker_service.datetime", wraps=datetime) as clock,
):
clock.now.side_effect = [paused_at, rolled_back_at]
with pytest.raises(HTTPException) as exc_info:
service.pause_sandbox("timestamp-test")
assert exc_info.value.status_code == 500
fetched = service.get_sandbox("timestamp-test")
assert fetched.status.state == ("Paused" if sidecar_missing else "Running")
assert fetched.status.last_transition_at == (paused_at if sidecar_missing else rolled_back_at)
@pytest.mark.parametrize("operation", ["pause", "resume"])
def test_transition_write_failure_preserves_successful_lifecycle(operation):
service = DockerSandboxService(config=_app_config())
resuming = operation == "resume"
main = _lifecycle_container("main", running=True, paused=resuming, egress_expected=True)
sidecar = _lifecycle_container("sidecar", running=True, paused=resuming)
for container in (main, sidecar):
container.pause.side_effect = lambda c=container: c.attrs["State"].update(Paused=True)
container.unpause.side_effect = lambda c=container: c.attrs["State"].update(Paused=False)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[sidecar]),
patch.object(service._metadata_store, "_write_file", side_effect=OSError("disk full")),
patch.object(service, "_raise_if_lifecycle_race") as map_race,
patch("opensandbox_server.services.docker.docker_service.logger.warning") as warning,
):
assert getattr(service, f"{operation}_sandbox")("sandbox-id") is None
for container in (main, sidecar):
assert container.attrs["State"] == {"Running": True, "Paused": not resuming}
getattr(container, "unpause" if resuming else "pause").assert_called_once_with()
getattr(container, "pause" if resuming else "unpause").assert_not_called()
map_race.assert_not_called()
transition_state = "Running" if resuming else "Paused"
warning.assert_called_once_with(
f"Failed to persist {transition_state} transition for sandbox sandbox-id: disk full"
)
@pytest.mark.parametrize("failed_state", ["Paused", "Running"])
def test_transition_write_failure_preserves_pause_rollback_error(failed_state):
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main", running=True, paused=False, egress_expected=True)
sidecar = _lifecycle_container("sidecar", running=True, paused=False)
failing_sidecar = _lifecycle_container("failing", running=True, paused=False)
for container in (main, sidecar):
container.pause.side_effect = lambda c=container: c.attrs["State"].update(Paused=True)
container.unpause.side_effect = lambda c=container: c.attrs["State"].update(Paused=False)
failing_sidecar.pause.side_effect = DockerException("sidecar pause failed")
write_file = service._metadata_store._write_file
def fail_transition_write(path, payload):
if payload["state"] == failed_state:
raise OSError("disk full")
write_file(path, payload)
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[sidecar, failing_sidecar]),
patch.object(service._metadata_store, "_write_file", side_effect=fail_transition_write),
patch.object(service, "_raise_if_lifecycle_race") as map_race,
patch("opensandbox_server.services.docker.docker_service.logger.warning") as warning,
pytest.raises(HTTPException) as exc_info,
):
service.pause_sandbox("sandbox-id")
assert exc_info.value.status_code == 500
assert exc_info.value.detail == {
"code": SandboxErrorCodes.SANDBOX_PAUSE_FAILED,
"message": "Failed to pause egress sidecar: sidecar pause failed",
}
assert isinstance(exc_info.value.__cause__, DockerException)
for container in (main, sidecar):
assert container.attrs["State"] == {"Running": True, "Paused": False}
container.pause.assert_called_once_with()
container.unpause.assert_called_once_with()
failing_sidecar.pause.assert_called_once_with()
map_race.assert_not_called()
warning.assert_any_call(
f"Failed to persist {failed_state} transition for sandbox sandbox-id: disk full"
)
def test_failed_pause_rollback_does_not_record_running_transition():
service = DockerSandboxService(config=_app_config())
main = _lifecycle_container("main", running=True, paused=False, egress_expected=True)
main.pause.side_effect = lambda: main.attrs["State"].update(Paused=True)
main.unpause.side_effect = DockerException("main rollback failed")
sidecar = _lifecycle_container("sidecar", running=True, paused=False)
sidecar.pause.side_effect = DockerException("sidecar pause failed")
with (
patch.object(service, "_get_container_by_sandbox_id", return_value=main),
patch.object(service, "_get_egress_sidecars", return_value=[sidecar]),
pytest.raises(HTTPException) as exc_info,
):
service.pause_sandbox("sandbox-id")
assert exc_info.value.status_code == 500
assert exc_info.value.detail == {
"code": SandboxErrorCodes.SANDBOX_PAUSE_FAILED,
"message": "Failed to pause egress sidecar: sidecar pause failed; rollback failed: main rollback failed",
}
assert main.attrs["State"]["Paused"] is True
assert service._metadata_store.get_transition_time("sandbox-id", "Paused") is not None
assert service._metadata_store.get_transition_time("sandbox-id", "Running") is None
def _run_lifecycle_interleaving(first_operation, second_operation, first_blocked, release_first):
second_checkpoint = threading.Event()
errors: list[Exception] = []
class ObservedLock:
"""Observe a waiting contender without sleeps or scheduler timing assumptions."""
def __init__(self):
self._lock = threading.Lock()
def __enter__(self):
if threading.current_thread() is second_thread and self._lock.locked():
second_checkpoint.set()
return self._lock.__enter__()
def __exit__(self, *args):
return self._lock.__exit__(*args)
def run(operation):
try:
operation()
except Exception as exc:
errors.append(exc)
def run_second():
run(second_operation)
# Without a lifecycle lock, let the contender finish before releasing
# the first operation to reproduce the stale write deterministically.
second_checkpoint.set()
first_thread = threading.Thread(target=run, args=(first_operation,), daemon=True)
second_thread = threading.Thread(target=run_second, daemon=True)
with patch("opensandbox_server.services.docker.docker_service.Lock", ObservedLock):
first_thread.start()
try:
assert first_blocked.wait(5), "First operation did not reach the test gate"
second_thread.start()
assert second_checkpoint.wait(5), "Contender neither waited for the lock nor finished"
finally:
release_first.set()
first_thread.join(5)
if second_thread.ident is not None:
second_thread.join(5)
assert not first_thread.is_alive() and not second_thread.is_alive()
assert not errors, errors
@pytest.mark.parametrize(
"operation, concurrent_operation",
[
("pause", "resume"),
("pause", "delete"),
("resume", "delete"),
("pause", "expire"),
("resume", "expire"),
("pause", "expire_missing"),
("resume", "expire_missing"),
],
)
def test_delayed_transition_write_is_ordered_with_lifecycle(operation, concurrent_operation):
service = DockerSandboxService(config=_app_config())
main = _mock_container("sandbox-id", paused=operation == "resume")
state = main.attrs["State"]
main.pause.side_effect = lambda: state.update(Paused=True)
main.unpause.side_effect = lambda: state.update(Paused=False)
first_blocked, release_first = threading.Event(), threading.Event()
events: list[str] = []
transition_times: dict[str, datetime] = {}
first_state = "Paused" if operation == "pause" else "Running"
set_transition = service._metadata_store.set_transition
delete_metadata = service._metadata_store.delete
def delayed_transition(sandbox_id, transition_state, transitioned_at):
transition_times[transition_state] = transitioned_at
if transition_state == first_state:
first_blocked.set()
assert release_first.wait(5)
set_transition(sandbox_id, transition_state, transitioned_at)
events.append(f"persist {transition_state}")
def lookup(sandbox_id):
if concurrent_operation == "expire_missing" and first_blocked.is_set():
raise HTTPException(status_code=404, detail={})
return main
def cleanup(sandbox_id):
delete_metadata(sandbox_id)
events.append("cleanup")
second_operation = (
service._expire_sandbox if concurrent_operation.startswith("expire")
else getattr(service, f"{concurrent_operation}_sandbox")
)
with (
patch.object(service, "_get_container_by_sandbox_id", side_effect=lookup),
patch.object(service, "_get_egress_sidecars", return_value=[]),
patch.object(service, "_cleanup_egress_sidecar"),
patch.object(service._metadata_store, "set_transition", side_effect=delayed_transition),
patch.object(service._metadata_store, "delete", side_effect=cleanup),
):
_run_lifecycle_interleaving(
lambda: getattr(service, f"{operation}_sandbox")("sandbox-id"),
lambda: second_operation("sandbox-id"),
first_blocked, release_first,
)
if concurrent_operation == "resume":
assert events == ["persist Paused", "persist Running"]
fetched = service.get_sandbox("sandbox-id")
assert fetched.status.state == "Running"
assert fetched.status.last_transition_at == transition_times["Running"]
else:
assert events == [f"persist {first_state}", "cleanup"]
assert not list(service._metadata_store._root.rglob("sandbox-id.json"))
if concurrent_operation == "expire_missing":
main.remove.assert_not_called()
else:
main.remove.assert_called_once_with(force=True)
@pytest.mark.parametrize("cleanup_operation", ["delete", "expire"])
@pytest.mark.parametrize("operation", ["pause", "resume"])
def test_transition_waits_for_cleanup_before_container_lookup(cleanup_operation, operation):
service = DockerSandboxService(config=_app_config())
main = _mock_container("sandbox-id", paused=operation == "resume")
first_blocked, release_first, removed = (
threading.Event(), threading.Event(), threading.Event()
)
outcomes: list[int | None] = []
def delayed_kill():
first_blocked.set()
assert release_first.wait(5)
main.attrs["State"]["Running"] = False
main.kill.side_effect = delayed_kill
main.remove.side_effect = lambda **kwargs: removed.set()
def lookup(sandbox_id):
if removed.is_set():
raise HTTPException(status_code=404, detail={})
return main
def transition():
try:
getattr(service, f"{operation}_sandbox")("sandbox-id")
except HTTPException as exc:
outcomes.append(exc.status_code)
else:
outcomes.append(None)
cleanup = service.delete_sandbox if cleanup_operation == "delete" else service._expire_sandbox
with (
patch.object(service, "_get_container_by_sandbox_id", side_effect=lookup),
patch.object(service, "_get_egress_sidecars", return_value=[]),
patch.object(service, "_cleanup_egress_sidecar"),
patch.object(service._metadata_store, "set_transition") as set_transition,
):
_run_lifecycle_interleaving(
lambda: cleanup("sandbox-id"), transition, first_blocked, release_first,
)
assert outcomes == [404]
main.pause.assert_not_called()
main.unpause.assert_not_called()
set_transition.assert_not_called()
assert not list(service._metadata_store._root.rglob("sandbox-id.json"))
def test_delayed_transition_does_not_block_another_sandbox():
service = DockerSandboxService(config=_app_config())
containers = {sandbox_id: _mock_container(sandbox_id) for sandbox_id in ("first", "second")}
for container in containers.values():
container.pause.side_effect = lambda c=container: c.attrs["State"].update(Paused=True)
first_blocked, release_first = threading.Event(), threading.Event()
events: list[str] = []
set_transition = service._metadata_store.set_transition
def delayed_transition(sandbox_id, state, transitioned_at):
if sandbox_id == "first":
first_blocked.set()
assert release_first.wait(5)
set_transition(sandbox_id, state, transitioned_at)
events.append(sandbox_id)
with (
patch.object(service, "_get_container_by_sandbox_id", side_effect=containers.__getitem__),
patch.object(service, "_get_egress_sidecars", return_value=[]),
patch.object(service._metadata_store, "set_transition", side_effect=delayed_transition),
):
_run_lifecycle_interleaving(
lambda: service.pause_sandbox("first"),
lambda: service.pause_sandbox("second"),
first_blocked, release_first,
)
assert events == ["second", "first"]
for sandbox_id, container in containers.items():
assert container.attrs["State"]["Paused"] is True
assert service._metadata_store.get_transition_time(sandbox_id, "Paused") is not None
def _wire_list_mocks(mock_client: MagicMock, containers: list[MagicMock]) -> None:
"""Wire ``api.containers`` (summary) + ``containers.get`` (inspect) so
that list_sandboxes' two-step discovery returns the given containers."""
summaries = [_list_summary(c.attrs["Config"]["Labels"][SANDBOX_ID_LABEL]) for c in containers]
mock_client.api.containers.return_value = summaries
by_id = {s["Id"]: c for s, c in zip(summaries, containers)}
def _get(container_id):
if container_id in by_id:
return by_id[container_id]
raise DockerNotFound(f"no such container: {container_id}")
mock_client.containers.get.side_effect = _get
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_list_sandboxes_uses_low_level_summary_endpoint(mock_docker):
"""list_sandboxes discovers IDs via the low-level engine endpoint so a
concurrent deletion mid-listing can be handled explicitly (see
test_list_sandboxes_skips_concurrently_deleted_sandbox)."""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
_wire_list_mocks(mock_client, [_mock_container("sbx-1", entrypoint=["python", "app.py"])])
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
response = service.list_sandboxes(
ListSandboxesRequest(pagination=PaginationRequest(page=1, page_size=50))
)
call_kwargs = mock_client.api.containers.call_args.kwargs
assert call_kwargs["all"] is True
assert call_kwargs["filters"] == {"label": [SANDBOX_ID_LABEL]}
assert response.pagination.total_items == 1
item = response.items[0]
assert item.id == "sbx-1"
assert item.status.state == "Running"
# Full fidelity: entrypoint from Config.Cmd, image from Config.Image.
assert item.entrypoint == ["python", "app.py"]
assert item.image is not None
assert item.image.uri == "python:3.11"
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_list_sandboxes_skips_concurrently_deleted_sandbox(mock_docker):
"""Regression: a container removed between list summary and follow-up
inspect must be silently skipped, not fail the whole request with 500.
The pre-fix path used ``docker_client.containers.list(filters=...)``
which raises inside docker-py when the second-stage inspect 404s.
"""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
alive = _mock_container("sbx-alive", running=True)
mock_client.api.containers.return_value = [
_list_summary("sbx-alive"),
_list_summary("sbx-gone"),
]
def _get(container_id):
if container_id == "cid-sbx-alive":
return alive
raise DockerNotFound(f"no such container: {container_id}")
mock_client.containers.get.side_effect = _get
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
response = service.list_sandboxes(
ListSandboxesRequest(pagination=PaginationRequest(page=1, page_size=50))
)
ids = {item.id for item in response.items}
assert ids == {"sbx-alive"}
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_list_sandboxes_reports_image_of_container_whose_image_was_removed(mock_docker):
"""An image can be removed (``docker rmi -f``) while a container still
uses it. Listing must not look the image up: that raises ImageNotFound
and fails the whole request. The image comes from the container config.
"""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
container = _mock_container("sbx-1", image="python:3.11")
type(container).image = PropertyMock(side_effect=ImageNotFound("no such image"))
_wire_list_mocks(mock_client, [container])
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
response = service.list_sandboxes(
ListSandboxesRequest(pagination=PaginationRequest(page=1, page_size=50))
)
(item,) = response.items
assert item.image is not None
assert item.image.uri == "python:3.11"
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_list_sandboxes_preserves_failed_and_terminated_states(mock_docker):
"""list_sandboxes must distinguish successful exits (Terminated) from
non-zero exits (Failed) so that ``filter.state == ['Failed']`` does not
silently drop failed sandboxes.
"""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
_wire_list_mocks(
mock_client,
[
_mock_container(
"sbx-terminated",
running=False,
docker_status="exited",
exit_code=0,
),
_mock_container(
"sbx-failed",
running=False,
docker_status="exited",
exit_code=137,
),
],
)
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
response = service.list_sandboxes(
ListSandboxesRequest(pagination=PaginationRequest(page=1, page_size=50))
)
got = {item.id: (item.status.state, item.status.reason) for item in response.items}
assert got == {
"sbx-terminated": ("Terminated", "CONTAINER_EXITED"),
"sbx-failed": ("Failed", "CONTAINER_EXITED_ERROR"),
}
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_list_sandboxes_wraps_docker_exception(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_client.api.containers.side_effect = DockerException("boom")
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
with pytest.raises(HTTPException) as exc:
service.list_sandboxes(
ListSandboxesRequest(pagination=PaginationRequest(page=1, page_size=50))
)
assert exc.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
assert exc.value.detail["code"] == SandboxErrorCodes.CONTAINER_QUERY_FAILED
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_get_container_by_sandbox_id_uses_deterministic_name(
mock_docker: MagicMock,
) -> None:
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
container = MagicMock()
container.attrs = {
"Config": {"Labels": {SANDBOX_ID_LABEL: "sbx-current"}},
}
mock_client.containers.get.reset_mock()
mock_client.containers.list.reset_mock()
mock_client.containers.get.return_value = container
result = service._get_container_by_sandbox_id("sbx-current")
assert result is container
mock_client.containers.get.assert_called_once_with("sandbox-sbx-current")
mock_client.containers.list.assert_not_called()
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_get_container_by_sandbox_id_falls_back_to_label_lookup(
mock_docker: MagicMock,
) -> None:
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
legacy_container = MagicMock()
mock_client.containers.list.reset_mock()
mock_client.containers.get.side_effect = DockerNotFound("no deterministic name")
mock_client.containers.list.return_value = [legacy_container]
result = service._get_container_by_sandbox_id("sbx-legacy")
assert result is legacy_container
mock_client.containers.get.assert_called_once_with("sandbox-sbx-legacy")
mock_client.containers.list.assert_called_once_with(
all=True,
filters={"label": f"{SANDBOX_ID_LABEL}=sbx-legacy"},
)
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_get_container_by_sandbox_id_falls_back_when_name_has_wrong_label(
mock_docker: MagicMock,
) -> None:
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
named_container = MagicMock()
named_container.attrs = {
"Config": {"Labels": {SANDBOX_ID_LABEL: "another-sandbox"}},
}
labelled_container = MagicMock()
mock_client.containers.list.reset_mock()
mock_client.containers.get.return_value = named_container
mock_client.containers.list.return_value = [labelled_container]
result = service._get_container_by_sandbox_id("sbx-collision")
assert result is labelled_container
mock_client.containers.list.assert_called_once_with(
all=True,
filters={"label": f"{SANDBOX_ID_LABEL}=sbx-collision"},
)
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_get_container_by_sandbox_id_maps_empty_fallback_to_404(
mock_docker: MagicMock,
) -> None:
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
mock_client.containers.get.side_effect = DockerNotFound("no deterministic name")
with pytest.raises(HTTPException) as exc:
service._get_container_by_sandbox_id("sbx-missing")
assert exc.value.status_code == status.HTTP_404_NOT_FOUND
assert exc.value.detail["code"] == SandboxErrorCodes.SANDBOX_NOT_FOUND
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_get_container_by_sandbox_id_maps_notfound_to_404(
mock_docker: MagicMock,
) -> None:
"""Concurrent deletion of a single container must yield 404, not 500."""
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
mock_client.containers.get.side_effect = DockerNotFound("no deterministic name")
mock_client.containers.list.side_effect = DockerNotFound("no such container")
with pytest.raises(HTTPException) as exc:
service._get_container_by_sandbox_id("sbx-vanished")
assert exc.value.status_code == status.HTTP_404_NOT_FOUND
assert exc.value.detail["code"] == SandboxErrorCodes.SANDBOX_NOT_FOUND
@patch("opensandbox_server.services.docker.docker_service.docker")
def test_get_container_by_sandbox_id_maps_docker_error_to_500(
mock_docker: MagicMock,
) -> None:
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
service = DockerSandboxService(config=_app_config())
mock_client.containers.list.reset_mock()
mock_client.containers.get.side_effect = DockerException("daemon unavailable")
with pytest.raises(HTTPException) as exc:
service._get_container_by_sandbox_id("sbx-error")
assert exc.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
assert exc.value.detail["code"] == SandboxErrorCodes.CONTAINER_QUERY_FAILED
mock_client.containers.list.assert_not_called()
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_retries_on_host_port_publish_error(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
config = _app_config()
config.docker.network_mode = "bridge"
service = DockerSandboxService(config=config)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
first_bindings = {
"44772": ("0.0.0.0", 41077),
"8080": ("0.0.0.0", 41078),
}
second_bindings = {
"44772": ("0.0.0.0", 42001),
"8080": ("0.0.0.0", 42002),
}
port_error = HTTPException(
status_code=500,
detail={
"code": SandboxErrorCodes.CONTAINER_START_FAILED,
"message": (
"Failed to create or start container: 500 Server Error for "
"http+docker://localhost/v1.55/containers/.../start: Internal Server Error "
'("failed to set up container networking: driver failed programming external connectivity '
'on endpoint sandbox-1: Bind for 0.0.0.0:41077 failed: port is already allocated")'
),
},
)
mock_container = MagicMock()
mock_container.id = "test-container-id"
mock_container.attrs = {"Config": {"Image": "python:3.11"}}
calls = []
def mock_create_and_start(
sandbox_id,
image_uri,
bootstrap_command,
labels,
environment,
host_config_kwargs,
container_exposed_ports,
platform,
unconfine_system_paths=False,
):
calls.append((dict(labels), dict(host_config_kwargs)))
if len(calls) == 1:
raise port_error
return mock_container
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_create_and_start_container", side_effect=mock_create_and_start),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
side_effect=[first_bindings, second_bindings],
),
patch(
"opensandbox_server.services.docker.docker_service.release_port_bindings"
) as mock_release,
):
resp = await service.create_sandbox(request)
assert resp.status.state == "Running"
assert len(calls) == 2
assert calls[0][0][SANDBOX_EMBEDDING_PROXY_PORT_LABEL] == "41077"
assert calls[0][0][SANDBOX_HTTP_PORT_LABEL] == "41078"
assert calls[0][1]["port_bindings"]["44772"] == ("0.0.0.0", 41077)
assert calls[0][1]["port_bindings"]["8080"] == ("0.0.0.0", 41078)
assert calls[1][0][SANDBOX_EMBEDDING_PROXY_PORT_LABEL] == "42001"
assert calls[1][0][SANDBOX_HTTP_PORT_LABEL] == "42002"
assert calls[1][1]["port_bindings"]["44772"] == ("0.0.0.0", 42001)
assert calls[1][1]["port_bindings"]["8080"] == ("0.0.0.0", 42002)
# First bindings released when retrying, second released in finally
assert mock_release.call_count == 2
mock_release.assert_any_call(first_bindings)
mock_release.assert_any_call(second_bindings)
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_raises_after_exhausting_port_retries(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
config = _app_config()
config.docker.network_mode = "bridge"
service = DockerSandboxService(config=config)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
port_error = HTTPException(
status_code=500,
detail={
"code": SandboxErrorCodes.CONTAINER_START_FAILED,
"message": "Failed to create or start container: ports are not available: bind: forbidden",
},
)
attempt_count = 0
def mock_create_and_start(*args, **kwargs):
nonlocal attempt_count
attempt_count += 1
raise port_error
bindings = {
"44772": ("0.0.0.0", 41077),
"8080": ("0.0.0.0", 41078),
}
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_create_and_start_container", side_effect=mock_create_and_start),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value=bindings,
),
patch(
"opensandbox_server.services.docker.docker_service.release_port_bindings"
) as mock_release,
):
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == 500
assert attempt_count == 3 # MAX_PORT_PUBLISH_ATTEMPTS
assert mock_release.call_count == 3
@pytest.mark.asyncio
@patch("opensandbox_server.services.docker.docker_service.docker")
async def test_create_sandbox_does_not_retry_on_non_port_error(mock_docker):
mock_client = MagicMock()
mock_client.containers.list.return_value = []
mock_docker.from_env.return_value = mock_client
config = _app_config()
config.docker.network_mode = "bridge"
service = DockerSandboxService(config=config)
request = CreateSandboxRequest(
image=ImageSpec(uri="python:3.11"),
timeout=120,
resourceLimits=ResourceLimits(root={}),
env={},
metadata={},
entrypoint=["python"],
)
generic_error = HTTPException(
status_code=500,
detail={
"code": SandboxErrorCodes.CONTAINER_START_FAILED,
"message": "Failed to create or start container: repository python not found",
},
)
attempt_count = 0
def mock_create_and_start(*args, **kwargs):
nonlocal attempt_count
attempt_count += 1
raise generic_error
bindings = {
"44772": ("0.0.0.0", 41077),
"8080": ("0.0.0.0", 41078),
}
with (
patch.object(service, "_ensure_image_available"),
patch.object(service, "_create_and_start_container", side_effect=mock_create_and_start),
patch(
"opensandbox_server.services.docker.docker_service.allocate_port_bindings",
return_value=bindings,
),
patch(
"opensandbox_server.services.docker.docker_service.release_port_bindings"
) as mock_release,
):
with pytest.raises(HTTPException) as exc:
await service.create_sandbox(request)
assert exc.value.status_code == 500
assert attempt_count == 1
mock_release.assert_called_once_with(bindings)
@pytest.mark.parametrize("failed_operation", [None, "kill", "remove"])
def test_delete_preserves_dependencies_until_application_removal(tmp_path, failed_operation):
docker_client = MagicMock()
docker_client.containers.list.return_value = []
with patch("docker.from_env", return_value=docker_client):
service = DockerSandboxService(config=_app_config())
service._metadata_store = DockerMetadataStore(tmp_path / "metadata")
sandbox_id = "short-stop-regression"
expiration = datetime.now(timezone.utc) + timedelta(hours=1)
service._metadata_store.set_expiration(sandbox_id, expiration)
application, sidecar = MagicMock(), MagicMock()
application.attrs = {"Config": {"Labels": {SANDBOX_ID_LABEL: sandbox_id}}}
docker_client.containers.get.return_value = application
docker_client.containers.list.return_value = [sidecar]
operations = []
application.kill.side_effect = lambda: operations.append("kill app")
application.remove.side_effect = lambda **kwargs: operations.append("remove app")
sidecar.stop.side_effect = lambda **kwargs: operations.append("stop sidecar")
sidecar.remove.side_effect = lambda **kwargs: operations.append("remove sidecar")
if failed_operation:
getattr(application, failed_operation).side_effect = DockerException("application operation failed")
with pytest.raises(HTTPException) as error:
service.delete_sandbox(sandbox_id)
assert error.value.status_code == 500
sidecar.stop.assert_not_called()
sidecar.remove.assert_not_called()
assert service._metadata_store.get_expiration(sandbox_id) == expiration.isoformat()
else:
service.delete_sandbox(sandbox_id)
assert operations == ["kill app", "remove app", "stop sidecar", "remove sidecar"]
sidecar.stop.assert_called_once_with(timeout=9)
assert service._metadata_store.get_expiration(sandbox_id) is None