opensandbox 0.1.8.dev1__tar.gz → 0.1.8.dev2__tar.gz

{opensandbox-0.1.8.dev1 → 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.dev1 → opensandbox-0.1.8.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensandbox
-Version: 0.1.8.dev1
+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",

{opensandbox-0.1.8.dev1 → 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",

{opensandbox-0.1.8.dev1 → 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.dev1 → 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.dev1 → 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.dev1 → 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.dev1 → 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.dev1 → 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.dev1 → opensandbox-0.1.8.dev2}/src/opensandbox/pool_async.py

@@ -428,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",
+]

{opensandbox-0.1.8.dev1 → opensandbox-0.1.8.dev2}/src/opensandbox/redis_pool_store.py

@@ -19,11 +19,29 @@ from __future__ import annotations
 
 import base64
 from datetime import datetime, timedelta, timezone
-from typing import Any
+from typing import Any, cast
 
 from opensandbox.exceptions import PoolStateStoreUnavailableException
 from opensandbox.pool_types import IdleEntry, StoreCounters
 
+try:
+    from redis import Redis
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        'Install opensandbox[pool-redis] to use opensandbox.pool_redis'
+    ) from exc
+
+_REQUIRED_REDIS_METHODS = (
+    "eval",
+    "get",
+    "set",
+    "hdel",
+    "lrem",
+    "hlen",
+    "lrange",
+    "hgetall",
+)
+
 
 class RedisPoolStateStore:
     """Distributed pool store backed by a caller-managed Redis client."""
@@ -91,7 +109,8 @@ end
 return 1
 """
 
-    def __init__(self, redis: Any, key_prefix: str = DEFAULT_KEY_PREFIX) -> None:
+    def __init__(self, redis: Redis, key_prefix: str = DEFAULT_KEY_PREFIX) -> None:
+        _validate_sync_redis_client(redis)
         self._redis = redis
         self._key_prefix = key_prefix
         self._default_idle_ttl = timedelta(hours=24)
@@ -195,18 +214,25 @@ return 1
 
     def snapshot_counters(self, pool_name: str) -> StoreCounters:
         def op() -> StoreCounters:
-            self.reap_expired_idle(pool_name, datetime.now(timezone.utc))
-            return StoreCounters(idle_count=int(self._redis.hlen(self._idle_expires_key(pool_name))))
+            idle_count = cast(int, self._redis.hlen(self._idle_expires_key(pool_name)))
+            return StoreCounters(idle_count=idle_count)
 
         return self._execute("snapshot_counters", pool_name, op)
 
     def snapshot_idle_entries(self, pool_name: str) -> list[IdleEntry]:
         def op() -> list[IdleEntry]:
-            self.reap_expired_idle(pool_name, datetime.now(timezone.utc))
-            ids = [_decode(v) for v in self._redis.lrange(self._idle_list_key(pool_name), 0, -1)]
+            raw_ids = cast(
+                list[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],
+                self._redis.hgetall(self._idle_expires_key(pool_name)),
+            )
             expires_by_id = {
                 _decode(k): _decode(v)
-                for k, v in 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:
@@ -317,3 +343,17 @@ def _validate_owner_and_ttl(owner_id: str, ttl: timedelta) -> None:
         raise ValueError("owner_id must not be blank")
     if ttl.total_seconds() <= 0:
         raise ValueError("ttl must be positive")
+
+
+def _validate_sync_redis_client(redis: Any) -> None:
+    if not isinstance(redis, Redis):
+        raise TypeError(
+            "RedisPoolStateStore requires a redis.Redis client; "
+            "use AsyncRedisPoolStateStore for redis.asyncio.Redis"
+        )
+    for method_name in _REQUIRED_REDIS_METHODS:
+        method = getattr(redis, method_name, None)
+        if not callable(method):
+            raise TypeError(
+                f"RedisPoolStateStore requires a Redis client with callable {method_name}()"
+            )

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

@@ -410,7 +410,14 @@ class SandboxPoolSync:
             skip_health_check=self._config.acquire_skip_health_check,
         )
         if sandbox_timeout is not None:
-            sandbox.renew(sandbox_timeout)
+            try:
+                sandbox.renew(sandbox_timeout)
+            except BaseException:
+                try:
+                    sandbox.kill()
+                finally:
+                    sandbox.close()
+                raise
         return sandbox
 
     def _resolve_max_idle(self) -> int: