opensandbox 0.1.8.dev0__tar.gz → 0.1.8.dev2__tar.gz

{opensandbox-0.1.8.dev0 → opensandbox-0.1.8.dev2}/.gitignore

@@ -274,3 +274,5 @@ kubernetes/test/kind/gvisor/runsc
 kubernetes/test/kind/gvisor/containerd-shim-runsc-v1
 bin/
 obj/
+
+.qoder/

{opensandbox-0.1.8.dev0 → opensandbox-0.1.8.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensandbox
-Version: 0.1.8.dev0
+Version: 0.1.8.dev2
 Summary: OpenSandbox Python SDK - Secure, isolated execution environments
 Project-URL: Homepage, https://open-sandbox.ai
 Project-URL: Repository, https://github.com/alibaba/OpenSandbox
@@ -420,8 +420,9 @@ The store does not create or close Redis clients.
 ```python
 import redis
 
-from opensandbox import PoolCreationSpec, RedisPoolStateStore, SandboxPoolSync
+from opensandbox import PoolCreationSpec, SandboxPoolSync
 from opensandbox.config import ConnectionConfigSync
+from opensandbox.pool_redis import RedisPoolStateStore
 
 redis_client = redis.Redis.from_url(
     "redis://user:password@redis.example.com:6379/0",
@@ -453,9 +454,9 @@ Notes:
   lock owner and is not the pool identifier.
 - All nodes sharing one pool must use the same creation and warmup definition. If
   that definition changes, use a new `pool_name` or `key_prefix` and drain the old pool.
-- `resize(max_idle)` can be called from any node. The new idle target is stored in
-  the shared state store and the current primary applies replenish or shrink work
-  during reconcile.
+- `resize(max_idle)` can be called from any node. The call returns after the new
+  idle target is stored in the shared state store; the current primary applies
+  replenish or shrink work during periodic reconcile.
 - Use `resize(0)` and wait for `snapshot().idle_count == 0` to drain a distributed
   idle buffer. `release_all_idle()` is only a best-effort cleanup pass in distributed
   mode because another primary may put new idle sandboxes concurrently unless the

{opensandbox-0.1.8.dev0 → opensandbox-0.1.8.dev2}/README.md

@@ -187,8 +187,9 @@ The store does not create or close Redis clients.
 ```python
 import redis
 
-from opensandbox import PoolCreationSpec, RedisPoolStateStore, SandboxPoolSync
+from opensandbox import PoolCreationSpec, SandboxPoolSync
 from opensandbox.config import ConnectionConfigSync
+from opensandbox.pool_redis import RedisPoolStateStore
 
 redis_client = redis.Redis.from_url(
     "redis://user:password@redis.example.com:6379/0",
@@ -220,9 +221,9 @@ Notes:
   lock owner and is not the pool identifier.
 - All nodes sharing one pool must use the same creation and warmup definition. If
   that definition changes, use a new `pool_name` or `key_prefix` and drain the old pool.
-- `resize(max_idle)` can be called from any node. The new idle target is stored in
-  the shared state store and the current primary applies replenish or shrink work
-  during reconcile.
+- `resize(max_idle)` can be called from any node. The call returns after the new
+  idle target is stored in the shared state store; the current primary applies
+  replenish or shrink work during periodic reconcile.
 - Use `resize(0)` and wait for `snapshot().idle_count == 0` to drain a distributed
   idle buffer. `release_all_idle()` is only a best-effort cleanup pass in distributed
   mode because another primary may put new idle sandboxes concurrently unless the

{opensandbox-0.1.8.dev0 → opensandbox-0.1.8.dev2}/pyproject.toml

@@ -142,6 +142,7 @@ branch = true
 
 [dependency-groups]
 dev = [
+    "redis>=5.0,<6.0",
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
     "pytest-cov>=4.0.0",

{opensandbox-0.1.8.dev0 → opensandbox-0.1.8.dev2}/src/opensandbox/__init__.py

@@ -102,12 +102,10 @@ from importlib.metadata import version as _pkg_version
 from opensandbox.manager import SandboxManager
 from opensandbox.pool import (
     AcquirePolicy,
-    AsyncRedisPoolStateStore,
     AsyncSandboxPool,
     InMemoryAsyncPoolStateStore,
     InMemoryPoolStateStore,
     PoolCreationSpec,
-    RedisPoolStateStore,
     SandboxPool,
     SandboxPoolAsync,
 )
@@ -133,6 +131,4 @@ __all__ = [
     "PoolCreationSpec",
     "InMemoryAsyncPoolStateStore",
     "InMemoryPoolStateStore",
-    "AsyncRedisPoolStateStore",
-    "RedisPoolStateStore",
 ]

{opensandbox-0.1.8.dev0 → opensandbox-0.1.8.dev2}/src/opensandbox/adapters/converter/exception_converter.py

@@ -234,8 +234,11 @@ def _parse_error_body(body: Any) -> SandboxError | None:
                     message=body,
                 )
 
-        # Extract code and message from dict
+        # FastAPI HTTPException bodies are commonly wrapped as {"detail": {"code": ..., "message": ...}}.
         if isinstance(body, dict):
+            if isinstance(body.get("detail"), dict):
+                body = body["detail"]
+
             code: str | None = body.get("code")
             message: str | None = body.get("message")
 

{opensandbox-0.1.8.dev0 → opensandbox-0.1.8.dev2}/src/opensandbox/adapters/converter/response_handler.py

@@ -28,7 +28,7 @@ import logging
 from http import HTTPStatus
 from typing import Any, TypeVar
 
-from opensandbox.exceptions import SandboxApiException
+from opensandbox.exceptions import SandboxApiException, SandboxError
 
 logger = logging.getLogger(__name__)
 
@@ -118,17 +118,27 @@ def handle_api_error(response_obj: Any, operation_name: str = "API call") -> Non
 
     if status_code >= 300:
         error_message = f"{operation_name} failed: HTTP {status_code}"
+        sandbox_error: SandboxError | None = None
 
         if hasattr(response_obj, "parsed") and response_obj.parsed is not None:
-            if hasattr(response_obj.parsed, "message"):
-                error_message = (
-                    f"{operation_name} failed: {response_obj.parsed.message}"
+            parsed = response_obj.parsed
+            parsed_code = getattr(parsed, "code", None)
+            parsed_message = getattr(parsed, "message", None)
+
+            if parsed_message:
+                error_message = f"{operation_name} failed: {parsed_message}"
+            elif parsed_code:
+                error_message = f"{operation_name} failed: {parsed_code}"
+
+            if parsed_code:
+                sandbox_error = SandboxError(
+                    code=str(parsed_code),
+                    message=str(parsed_message or ""),
                 )
-            elif hasattr(response_obj.parsed, "code"):
-                error_message = f"{operation_name} failed: {response_obj.parsed.code}"
 
         raise SandboxApiException(
             message=error_message,
             status_code=status_code,
             request_id=request_id,
+            error=sandbox_error,
         )

{opensandbox-0.1.8.dev0 → opensandbox-0.1.8.dev2}/src/opensandbox/api/lifecycle/api/snapshots/delete_snapshots_snapshot_id.py

@@ -91,8 +91,13 @@ def sync_detailed(
 ) -> Response[Any | ErrorResponse]:
     """Delete a snapshot
 
-     Delete a persistent sandbox snapshot by id. Snapshots that are still being created cannot be
-    deleted.
+     Delete a persistent sandbox snapshot by id. Snapshots that are still
+    being created cannot be deleted.
+
+    For Kubernetes-backed snapshots, deletion removes OpenSandbox metadata
+    and Kubernetes coordination resources, but does not guarantee removal
+    of pushed OCI images from the configured registry. Use registry
+    retention or garbage collection policies for image lifecycle cleanup.
 
     Args:
         snapshot_id (str):
@@ -123,8 +128,13 @@ def sync(
 ) -> Any | ErrorResponse | None:
     """Delete a snapshot
 
-     Delete a persistent sandbox snapshot by id. Snapshots that are still being created cannot be
-    deleted.
+     Delete a persistent sandbox snapshot by id. Snapshots that are still
+    being created cannot be deleted.
+
+    For Kubernetes-backed snapshots, deletion removes OpenSandbox metadata
+    and Kubernetes coordination resources, but does not guarantee removal
+    of pushed OCI images from the configured registry. Use registry
+    retention or garbage collection policies for image lifecycle cleanup.
 
     Args:
         snapshot_id (str):
@@ -150,8 +160,13 @@ async def asyncio_detailed(
 ) -> Response[Any | ErrorResponse]:
     """Delete a snapshot
 
-     Delete a persistent sandbox snapshot by id. Snapshots that are still being created cannot be
-    deleted.
+     Delete a persistent sandbox snapshot by id. Snapshots that are still
+    being created cannot be deleted.
+
+    For Kubernetes-backed snapshots, deletion removes OpenSandbox metadata
+    and Kubernetes coordination resources, but does not guarantee removal
+    of pushed OCI images from the configured registry. Use registry
+    retention or garbage collection policies for image lifecycle cleanup.
 
     Args:
         snapshot_id (str):
@@ -180,8 +195,13 @@ async def asyncio(
 ) -> Any | ErrorResponse | None:
     """Delete a snapshot
 
-     Delete a persistent sandbox snapshot by id. Snapshots that are still being created cannot be
-    deleted.
+     Delete a persistent sandbox snapshot by id. Snapshots that are still
+    being created cannot be deleted.
+
+    For Kubernetes-backed snapshots, deletion removes OpenSandbox metadata
+    and Kubernetes coordination resources, but does not guarantee removal
+    of pushed OCI images from the configured registry. Use registry
+    retention or garbage collection policies for image lifecycle cleanup.
 
     Args:
         snapshot_id (str):

{opensandbox-0.1.8.dev0 → opensandbox-0.1.8.dev2}/src/opensandbox/api/lifecycle/api/snapshots/post_sandboxes_sandbox_id_snapshots.py

@@ -115,8 +115,10 @@ def sync_detailed(
     """Create a snapshot from a sandbox
 
      Create a persistent point-in-time snapshot from the sandbox's current state.
-    The returned snapshot id identifies the created artifact. Snapshot creation may
-    temporarily pause the sandbox while the runtime captures provider-supported state.
+    The source sandbox must be `Running`. The returned snapshot id identifies
+    the created artifact. Snapshot creation may temporarily pause the sandbox
+    while the runtime captures provider-supported state, then the source
+    sandbox continues running.
 
     Args:
         sandbox_id (str):
@@ -151,8 +153,10 @@ def sync(
     """Create a snapshot from a sandbox
 
      Create a persistent point-in-time snapshot from the sandbox's current state.
-    The returned snapshot id identifies the created artifact. Snapshot creation may
-    temporarily pause the sandbox while the runtime captures provider-supported state.
+    The source sandbox must be `Running`. The returned snapshot id identifies
+    the created artifact. Snapshot creation may temporarily pause the sandbox
+    while the runtime captures provider-supported state, then the source
+    sandbox continues running.
 
     Args:
         sandbox_id (str):
@@ -182,8 +186,10 @@ async def asyncio_detailed(
     """Create a snapshot from a sandbox
 
      Create a persistent point-in-time snapshot from the sandbox's current state.
-    The returned snapshot id identifies the created artifact. Snapshot creation may
-    temporarily pause the sandbox while the runtime captures provider-supported state.
+    The source sandbox must be `Running`. The returned snapshot id identifies
+    the created artifact. Snapshot creation may temporarily pause the sandbox
+    while the runtime captures provider-supported state, then the source
+    sandbox continues running.
 
     Args:
         sandbox_id (str):
@@ -216,8 +222,10 @@ async def asyncio(
     """Create a snapshot from a sandbox
 
      Create a persistent point-in-time snapshot from the sandbox's current state.
-    The returned snapshot id identifies the created artifact. Snapshot creation may
-    temporarily pause the sandbox while the runtime captures provider-supported state.
+    The source sandbox must be `Running`. The returned snapshot id identifies
+    the created artifact. Snapshot creation may temporarily pause the sandbox
+    while the runtime captures provider-supported state, then the source
+    sandbox continues running.
 
     Args:
         sandbox_id (str):

{opensandbox-0.1.8.dev0 → opensandbox-0.1.8.dev2}/src/opensandbox/async_redis_pool_store.py

@@ -20,17 +20,26 @@ from __future__ import annotations
 import base64
 from collections.abc import Awaitable, Callable
 from datetime import datetime, timedelta, timezone
-from typing import Any, TypeVar
+from typing import Any, TypeVar, cast
 
 from opensandbox.exceptions import PoolStateStoreUnavailableException
 from opensandbox.pool_types import IdleEntry, StoreCounters
 from opensandbox.redis_pool_store import (
+    _REQUIRED_REDIS_METHODS,
+    Redis,
     RedisPoolStateStore,
     _decode,
     _millis,
     _validate_owner_and_ttl,
 )
 
+try:
+    from redis.asyncio import Redis as AsyncRedis
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        'Install opensandbox[pool-redis] to use opensandbox.pool_redis'
+    ) from exc
+
 T = TypeVar("T")
 
 
@@ -39,7 +48,8 @@ class AsyncRedisPoolStateStore:
 
     DEFAULT_KEY_PREFIX = RedisPoolStateStore.DEFAULT_KEY_PREFIX
 
-    def __init__(self, redis: Any, key_prefix: str = DEFAULT_KEY_PREFIX) -> None:
+    def __init__(self, redis: AsyncRedis, key_prefix: str = DEFAULT_KEY_PREFIX) -> None:
+        _validate_async_redis_client(redis)
         self._redis = redis
         self._key_prefix = key_prefix
         self._default_idle_ttl = timedelta(hours=24)
@@ -48,11 +58,14 @@ class AsyncRedisPoolStateStore:
         result = await self._execute(
             "try_take_idle",
             pool_name,
-            lambda: self._redis.eval(
-                RedisPoolStateStore._TAKE_IDLE_SCRIPT,
-                2,
-                self._idle_list_key(pool_name),
-                self._idle_expires_key(pool_name),
+            lambda: cast(
+                Awaitable[Any],
+                self._redis.eval(
+                    RedisPoolStateStore._TAKE_IDLE_SCRIPT,
+                    2,
+                    self._idle_list_key(pool_name),
+                    self._idle_expires_key(pool_name),
+                ),
             ),
         )
         return _decode(result) if result is not None else None
@@ -64,13 +77,16 @@ class AsyncRedisPoolStateStore:
         await self._execute(
             "put_idle",
             pool_name,
-            lambda: self._redis.eval(
-                RedisPoolStateStore._PUT_IDLE_SCRIPT,
-                2,
-                self._idle_list_key(pool_name),
-                self._idle_expires_key(pool_name),
-                sandbox_id,
-                str(ttl_millis),
+            lambda: cast(
+                Awaitable[Any],
+                self._redis.eval(
+                    RedisPoolStateStore._PUT_IDLE_SCRIPT,
+                    2,
+                    self._idle_list_key(pool_name),
+                    self._idle_expires_key(pool_name),
+                    sandbox_id,
+                    str(ttl_millis),
+                ),
             ),
         )
 
@@ -79,8 +95,14 @@ class AsyncRedisPoolStateStore:
             "remove_idle",
             pool_name,
             lambda: _gather_tuple(
-                self._redis.hdel(self._idle_expires_key(pool_name), sandbox_id),
-                self._redis.lrem(self._idle_list_key(pool_name), 0, sandbox_id),
+                cast(
+                    Awaitable[Any],
+                    self._redis.hdel(self._idle_expires_key(pool_name), sandbox_id),
+                ),
+                cast(
+                    Awaitable[Any],
+                    self._redis.lrem(self._idle_list_key(pool_name), 0, sandbox_id),
+                ),
             ),
         )
 
@@ -109,12 +131,15 @@ class AsyncRedisPoolStateStore:
         result = await self._execute(
             "renew_primary_lock",
             pool_name,
-            lambda: self._redis.eval(
-                RedisPoolStateStore._RENEW_LOCK_SCRIPT,
-                1,
-                self._primary_lock_key(pool_name),
-                owner_id,
-                str(max(1, _millis(ttl))),
+            lambda: cast(
+                Awaitable[Any],
+                self._redis.eval(
+                    RedisPoolStateStore._RENEW_LOCK_SCRIPT,
+                    1,
+                    self._primary_lock_key(pool_name),
+                    owner_id,
+                    str(max(1, _millis(ttl))),
+                ),
             ),
         )
         return result == 1 or result == b"1"
@@ -123,11 +148,14 @@ class AsyncRedisPoolStateStore:
         await self._execute(
             "release_primary_lock",
             pool_name,
-            lambda: self._redis.eval(
-                RedisPoolStateStore._RELEASE_LOCK_SCRIPT,
-                1,
-                self._primary_lock_key(pool_name),
-                owner_id,
+            lambda: cast(
+                Awaitable[Any],
+                self._redis.eval(
+                    RedisPoolStateStore._RELEASE_LOCK_SCRIPT,
+                    1,
+                    self._primary_lock_key(pool_name),
+                    owner_id,
+                ),
             ),
         )
 
@@ -135,35 +163,52 @@ class AsyncRedisPoolStateStore:
         await self._execute(
             "reap_expired_idle",
             pool_name,
-            lambda: self._redis.eval(
-                RedisPoolStateStore._REAP_EXPIRED_SCRIPT,
-                2,
-                self._idle_list_key(pool_name),
-                self._idle_expires_key(pool_name),
+            lambda: cast(
+                Awaitable[Any],
+                self._redis.eval(
+                    RedisPoolStateStore._REAP_EXPIRED_SCRIPT,
+                    2,
+                    self._idle_list_key(pool_name),
+                    self._idle_expires_key(pool_name),
+                ),
             ),
         )
 
     async def snapshot_counters(self, pool_name: str) -> StoreCounters:
         async def op() -> StoreCounters:
-            await self.reap_expired_idle(pool_name, datetime.now(timezone.utc))
+            idle_count = cast(
+                int,
+                await cast(
+                    Awaitable[Any],
+                    self._redis.hlen(self._idle_expires_key(pool_name)),
+                ),
+            )
             return StoreCounters(
-                idle_count=int(await self._redis.hlen(self._idle_expires_key(pool_name)))
+                idle_count=idle_count
             )
 
         return await self._execute("snapshot_counters", pool_name, op)
 
     async def snapshot_idle_entries(self, pool_name: str) -> list[IdleEntry]:
         async def op() -> list[IdleEntry]:
-            await self.reap_expired_idle(pool_name, datetime.now(timezone.utc))
-            ids = [
-                _decode(v)
-                for v in await self._redis.lrange(self._idle_list_key(pool_name), 0, -1)
-            ]
+            raw_ids = cast(
+                list[Any],
+                await cast(
+                    Awaitable[Any],
+                    self._redis.lrange(self._idle_list_key(pool_name), 0, -1),
+                ),
+            )
+            ids = [_decode(v) for v in raw_ids]
+            raw_expires_by_id = cast(
+                dict[Any, Any],
+                await cast(
+                    Awaitable[Any],
+                    self._redis.hgetall(self._idle_expires_key(pool_name)),
+                ),
+            )
             expires_by_id = {
                 _decode(k): _decode(v)
-                for k, v in (
-                    await self._redis.hgetall(self._idle_expires_key(pool_name))
-                ).items()
+                for k, v in raw_expires_by_id.items()
             }
             entries: list[IdleEntry] = []
             for sandbox_id in ids:
@@ -267,3 +312,17 @@ async def _gather_tuple(*awaitables: Awaitable[Any]) -> tuple[Any, ...]:
     import asyncio
 
     return tuple(await asyncio.gather(*awaitables))
+
+
+def _validate_async_redis_client(redis: Any) -> None:
+    if isinstance(redis, Redis) or not isinstance(redis, AsyncRedis):
+        raise TypeError(
+            "AsyncRedisPoolStateStore requires a redis.asyncio.Redis client; "
+            "use RedisPoolStateStore for redis.Redis"
+        )
+    for method_name in _REQUIRED_REDIS_METHODS:
+        method = getattr(redis, method_name, None)
+        if not callable(method):
+            raise TypeError(
+                f"AsyncRedisPoolStateStore requires a Redis client with callable {method_name}()"
+            )

{opensandbox-0.1.8.dev0 → opensandbox-0.1.8.dev2}/src/opensandbox/pool.py

@@ -17,7 +17,6 @@
 
 from opensandbox._async_pool_store import InMemoryAsyncPoolStateStore
 from opensandbox._pool_store import InMemoryPoolStateStore
-from opensandbox.async_redis_pool_store import AsyncRedisPoolStateStore
 from opensandbox.pool_async import AsyncSandboxPool, SandboxPoolAsync
 from opensandbox.pool_types import (
     AcquirePolicy,
@@ -32,7 +31,6 @@ from opensandbox.pool_types import (
     PoolStateStore,
     StoreCounters,
 )
-from opensandbox.redis_pool_store import RedisPoolStateStore
 from opensandbox.sync.pool import SandboxPoolSync
 
 SandboxPool = SandboxPoolSync
@@ -41,7 +39,6 @@ __all__ = [
     "AcquirePolicy",
     "AsyncPoolConfig",
     "AsyncPoolStateStore",
-    "AsyncRedisPoolStateStore",
     "AsyncSandboxPool",
     "IdleEntry",
     "InMemoryAsyncPoolStateStore",
@@ -52,7 +49,6 @@ __all__ = [
     "PoolSnapshot",
     "PoolState",
     "PoolStateStore",
-    "RedisPoolStateStore",
     "SandboxPoolAsync",
     "SandboxPool",
     "SandboxPoolSync",

{opensandbox-0.1.8.dev0 → opensandbox-0.1.8.dev2}/src/opensandbox/pool_async.py

@@ -135,10 +135,9 @@ class SandboxPoolAsync:
                 await self._state_store.set_idle_entry_ttl(
                     self._config.pool_name, self._config.idle_timeout
                 )
-                if await self._state_store.get_max_idle(self._config.pool_name) is None:
-                    await self._state_store.set_max_idle(
-                        self._config.pool_name, self._config.max_idle
-                    )
+                await self._state_store.set_max_idle(
+                    self._config.pool_name, self._config.max_idle
+                )
                 stop_event = asyncio.Event()
                 self._stop_event = stop_event
                 self._lifecycle_state = PoolLifecycleState.RUNNING
@@ -220,11 +219,6 @@ class SandboxPoolAsync:
             raise ValueError("max_idle must be >= 0")
         await self._state_store.set_max_idle(self._config.pool_name, max_idle)
         self._current_max_idle = max_idle
-        if self._lifecycle_state == PoolLifecycleState.RUNNING:
-            asyncio.create_task(
-                self._run_reconcile_tick(),
-                name=f"sandbox-pool-resize-{self._config.pool_name}",
-            )
 
     async def release_all_idle(self) -> int:
         pool_name = self._config.pool_name
@@ -434,7 +428,14 @@ class SandboxPoolAsync:
             skip_health_check=self._config.acquire_skip_health_check,
         )
         if sandbox_timeout is not None:
-            await sandbox.renew(sandbox_timeout)
+            try:
+                await sandbox.renew(sandbox_timeout)
+            except BaseException:
+                try:
+                    await sandbox.kill()
+                finally:
+                    await sandbox.close()
+                raise
         return sandbox
 
     async def _resolve_max_idle(self) -> int:

opensandbox-0.1.8.dev2/src/opensandbox/pool_redis.py

@@ -0,0 +1,27 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# 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.
+#
+"""Redis-backed sandbox pool state stores.
+
+Install ``opensandbox[pool-redis]`` and pass a caller-managed redis-py client.
+"""
+
+from opensandbox.async_redis_pool_store import AsyncRedisPoolStateStore
+from opensandbox.redis_pool_store import RedisPoolStateStore
+
+__all__ = [
+    "AsyncRedisPoolStateStore",
+    "RedisPoolStateStore",
+]