From d45c49734f53685967b412d5bcd0d91879738222 Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 11:05:10 +0800 Subject: [PATCH 01/15] feat(lifecycle): support manual cleanup sandboxes --- docs/manual-cleanup-refactor-guide.md | 536 ++++++++++++++++++ sdks/sandbox/csharp/README.md | 19 +- sdks/sandbox/csharp/README_zh.md | 18 +- .../OpenSandbox/Adapters/SandboxesAdapter.cs | 13 +- .../src/OpenSandbox/Models/Sandboxes.cs | 6 +- .../sandbox/csharp/src/OpenSandbox/Options.cs | 5 + .../sandbox/csharp/src/OpenSandbox/Sandbox.cs | 2 +- .../SandboxesAdapterTests.cs | 63 ++ sdks/sandbox/javascript/README.md | 12 +- sdks/sandbox/javascript/README_zh.md | 15 + .../src/adapters/sandboxesAdapter.ts | 11 +- sdks/sandbox/javascript/src/api/lifecycle.ts | 33 +- .../javascript/src/models/sandboxes.ts | 8 +- sdks/sandbox/javascript/src/sandbox.ts | 13 +- sdks/sandbox/kotlin/README.md | 11 + sdks/sandbox/kotlin/README_zh.md | 11 + .../alibaba/opensandbox/sandbox/Sandbox.kt | 13 +- .../domain/models/sandboxes/SandboxModels.kt | 4 +- .../sandbox/domain/services/Sandboxes.kt | 4 +- .../converter/SandboxModelConverter.kt | 4 +- .../adapters/service/SandboxesAdapter.kt | 2 +- .../adapters/service/SandboxesAdapterTest.kt | 62 ++ sdks/sandbox/python/README.md | 11 + sdks/sandbox/python/README_zh.md | 11 + .../converter/sandbox_model_converter.py | 8 +- .../opensandbox/adapters/sandboxes_adapter.py | 2 +- .../models/create_sandbox_request.py | 10 +- .../models/create_sandbox_response.py | 9 +- .../api/lifecycle/models/sandbox.py | 9 +- .../src/opensandbox/models/sandboxes.py | 6 +- .../sandbox/python/src/opensandbox/sandbox.py | 9 +- .../src/opensandbox/services/sandbox.py | 4 +- .../sync/adapters/sandboxes_adapter.py | 2 +- .../python/src/opensandbox/sync/sandbox.py | 9 +- .../src/opensandbox/sync/services/sandbox.py | 4 +- .../test_converters_and_error_handling.py | 17 + .../python/tests/test_models_stability.py | 14 + .../test_sandbox_service_adapter_lifecycle.py | 29 + server/README.md | 21 +- server/example.config.toml | 2 + server/src/api/lifecycle.py | 3 - server/src/api/schema.py | 23 +- server/src/config.py | 8 + server/src/services/constants.py | 2 + server/src/services/docker.py | 62 +- server/src/services/k8s/kubernetes_service.py | 31 +- server/src/services/k8s/workload_provider.py | 9 + server/src/services/validators.py | 27 + server/tests/k8s/test_kubernetes_service.py | 45 ++ server/tests/test_config.py | 7 + server/tests/test_docker_service.py | 139 ++++- server/tests/test_routes.py | 15 +- server/tests/test_routes_create_delete.py | 38 ++ server/tests/test_routes_list_sandboxes.py | 44 ++ server/tests/test_routes_renew_expiration.py | 31 + server/tests/test_schema.py | 30 + server/tests/test_validators.py | 17 + specs/sandbox-lifecycle.yml | 40 +- .../OpenSandbox.E2ETests/SandboxE2ETests.cs | 26 + .../opensandbox/e2e/SandboxE2ETest.java | 25 + .../javascript/tests/test_sandbox_e2e.test.ts | 22 + tests/python/tests/test_sandbox_e2e.py | 19 + tests/python/tests/test_sandbox_e2e_sync.py | 19 + 63 files changed, 1596 insertions(+), 128 deletions(-) create mode 100644 docs/manual-cleanup-refactor-guide.md diff --git a/docs/manual-cleanup-refactor-guide.md b/docs/manual-cleanup-refactor-guide.md new file mode 100644 index 00000000..35ce9245 --- /dev/null +++ b/docs/manual-cleanup-refactor-guide.md @@ -0,0 +1,536 @@ +# Manual Cleanup Refactor Guide + +## Background + +GitHub issue: `alibaba/OpenSandbox#442` + +Issue summary: + +- Support non-expiring sandboxes +- Let callers manage cleanup explicitly +- Keep existing TTL-based behavior for current users +- Work across Docker and Kubernetes runtimes where supported + +Current implementation does not support this. TTL is a hard requirement in: + +- API request/response models +- Docker runtime scheduling and restore logic +- Kubernetes workload creation and renew flows + +This document captures the recommended refactor direction before implementation starts. + +## Refactor Goal + +Introduce a manual cleanup mode without adding a new top-level mode field for now. + +Chosen semantic: + +- `timeout` present: sandbox uses TTL behavior +- `timeout` omitted or `null`: sandbox uses manual cleanup behavior + +Non-goals for this refactor: + +- Do not support magic values like `timeout=0` or `timeout=-1` +- Do not redesign the lifecycle API beyond what is required for manual cleanup +- Do not overload `renew_expiration` to switch a sandbox from manual mode back to TTL mode + +## Compatibility and Rollout + +This refactor is compatible through a controlled upgrade path, not through strict protocol backward compatibility. + +Important compatibility fact: + +- Once manual cleanup is enabled in an environment, lifecycle responses may contain `expiresAt=null` +- Older SDKs that assume `expiresAt` is always a timestamp may fail when they call `create`, `get`, or `list` +- Existing TTL-based callers are unaffected as long as they do not encounter manual-cleanup sandboxes + +Recommended rollout order: + +1. Upgrade all SDKs/clients that read lifecycle API responses +2. Upgrade the server +3. Only then start creating sandboxes with `timeout` omitted or `null` + +Operational rule: + +- Do not create manual-cleanup sandboxes in a shared environment until all readers of the lifecycle API have been upgraded + +This should be called out explicitly in release notes and upgrade documentation. + +## Why This Approach + +Compared with adding `expirationMode`, using `timeout: Optional[int]` is the smallest compatible change that still maps cleanly to the feature request. + +Advantages: + +- Smaller API and SDK surface change +- Easier migration from the current TTL-only model +- Preserves current behavior for existing clients that already send `timeout` + +Tradeoffs: + +- Mode becomes implicit rather than explicit +- `timeout == null` can mean either deliberate manual mode or missing input +- Future expansion beyond `ttl/manual` may require a second API refactor + +For the current scope, these tradeoffs are acceptable. + +## Current State + +### API layer + +TTL is currently mandatory. + +Relevant files: + +- `server/src/api/schema.py` +- `specs/sandbox-lifecycle.yml` + +Current constraints: + +- `CreateSandboxRequest.timeout` is required and bounded to `60-86400` +- `CreateSandboxResponse.expiresAt` is required +- `Sandbox.expiresAt` is required +- `RenewSandboxExpirationRequest.expiresAt` is required and assumes the sandbox already has TTL semantics + +### Docker runtime + +Relevant file: + +- `server/src/services/docker.py` + +Current behavior: + +- Creation always computes `expires_at = created_at + timeout` +- Creation always schedules expiration via in-process timer +- Existing sandboxes are restored from the expiration label on server startup +- Sandbox read/list responses always expose `expiresAt` +- `renew_expiration()` only supports extending TTL + +### Kubernetes runtime + +Relevant files: + +- `server/src/services/k8s/kubernetes_service.py` +- `server/src/services/k8s/batchsandbox_provider.py` +- `server/src/services/k8s/agent_sandbox_provider.py` + +Current behavior: + +- Creation always computes `expires_at = created_at + timeout` +- BatchSandbox writes `spec.expireTime` +- agent-sandbox writes `spec.shutdownTime` +- `renew_expiration()` patches those fields +- Sandbox read/list responses expose `expiresAt` + +## Target API Semantics + +### Create request + +`CreateSandboxRequest.timeout` should become optional. + +Rules: + +- `timeout` omitted or `null` means manual cleanup mode +- `timeout` present means TTL mode +- If present, `timeout` must still satisfy `60 <= timeout <= 86400` +- `timeout=0` and `timeout<0` remain invalid + +Suggested request examples: + +TTL mode: + +```json +{ + "image": { "uri": "python:3.11" }, + "timeout": 3600, + "resourceLimits": {}, + "entrypoint": ["sleep", "infinity"] +} +``` + +Manual cleanup mode: + +```json +{ + "image": { "uri": "python:3.11" }, + "resourceLimits": {}, + "entrypoint": ["sleep", "infinity"] +} +``` + +### Response models + +`expiresAt` should become nullable in: + +- `CreateSandboxResponse` +- `Sandbox` + +Rules: + +- TTL sandbox: `expiresAt` contains an RFC 3339 timestamp +- Manual sandbox: `expiresAt` is `null` + +### Renew expiration API + +Do not use `renew_expiration` as a mode switch. + +Recommended behavior: + +- TTL sandbox: renew works as it does today +- Manual sandbox: renew fails clearly + +Recommended response: + +- `409 Conflict` preferred +- `400 Bad Request` acceptable if existing error handling makes that much simpler + +Recommended error message: + +- `"Sandbox does not have automatic expiration enabled."` + +## Implementation Strategy + +## 1. API and schema updates + +Files to update: + +- `server/src/api/schema.py` +- `specs/sandbox-lifecycle.yml` + +Required changes: + +- Make `CreateSandboxRequest.timeout` optional +- Make `CreateSandboxResponse.expiresAt` optional +- Make `Sandbox.expiresAt` optional +- Update field descriptions to document manual cleanup behavior +- Update request/response examples in the OpenAPI spec + +Recommended validation rule: + +- No custom mode field +- Validation only enforces bounds when `timeout` is not `None` + +## 2. Docker runtime refactor + +File to update: + +- `server/src/services/docker.py` + +### Target behavior + +For manual sandboxes: + +- No expiration timestamp is computed +- No expiration label is written +- A dedicated runtime marker should be written (for example `opensandbox.io/manual-cleanup=true`) +- No expiration timer is scheduled +- Sandbox survives server restart without restoration warnings +- Read/list responses return `expiresAt=None` + +### Concrete refactor points + +#### Creation context + +Current logic: + +- `_prepare_creation_context()` always returns a concrete `expires_at` + +Target logic: + +- Return `expires_at: Optional[datetime]` +- `None` when `request.timeout is None` + +#### Label building + +Current logic: + +- Expiration label is assumed to exist + +Target logic: + +- Only write `SANDBOX_EXPIRES_AT_LABEL` when `expires_at is not None` +- Write a dedicated manual-cleanup label/annotation when `expires_at is None` + +#### Provisioning + +Current logic: + +- `_provision_sandbox()` always schedules expiration + +Target logic: + +- Only call `_schedule_expiration()` when `expires_at is not None` + +#### Sandbox reconstruction + +Current logic: + +- `_container_to_sandbox()` falls back to a concrete `expires_at` + +Target logic: + +- Manual sandbox should produce `expiresAt=None` +- Avoid fallback behavior that fabricates an expiration timestamp from `created_at` + +#### Restore path + +Current logic: + +- `_restore_existing_sandboxes()` warns when a sandbox is missing the expiration label + +Target logic: + +- Missing expiration label should only be treated as valid when the manual-cleanup marker is present +- Continue warning on sandboxes that have neither an expiration label nor a manual-cleanup marker +- Only restore timers for TTL sandboxes that actually carry expiration metadata + +#### Renew path + +Current logic: + +- `renew_expiration()` assumes every sandbox has TTL enabled + +Target logic: + +- Reject renewal if the manual-cleanup marker is present +- Continue treating "missing expiration metadata without manual marker" as malformed state rather than silently converting it to manual mode + +## 3. Kubernetes service refactor + +Files to update: + +- `server/src/services/k8s/kubernetes_service.py` +- `server/src/services/k8s/workload_provider.py` +- `server/src/services/k8s/batchsandbox_provider.py` +- `server/src/services/k8s/agent_sandbox_provider.py` + +### Key risk + +Kubernetes support depends on the underlying CRDs. + +Open question: + +- Can BatchSandbox omit `spec.expireTime`? +- Can agent-sandbox omit `spec.shutdownTime`? + +This must be confirmed before claiming end-to-end support. + +### Recommended capability design + +Add a provider capability check: + +- `supports_manual_cleanup() -> bool` + +Persist the chosen mode on workload metadata as well: + +- TTL sandbox: keep expiration field populated +- Manual sandbox: omit expiration field and write a provider-neutral marker (label or annotation) + +Rationale: + +- Docker can support manual cleanup immediately +- Kubernetes providers may differ based on CRD semantics +- The server should fail clearly when the selected provider cannot represent a non-expiring sandbox + +### Service-layer behavior + +In `KubernetesSandboxService.create_sandbox()`: + +- Compute `expires_at: Optional[datetime]` +- If `request.timeout is None` and provider does not support manual cleanup, fail early with a clear message + +Suggested message: + +- `"Manual cleanup mode is not supported by the current Kubernetes workload provider."` + +### BatchSandbox provider behavior + +If supported by the CRD: + +- Make `expires_at` optional in provider interfaces +- Omit `spec.expireTime` when `expires_at is None` +- `get_expiration()` should return `None` when the field is absent +- `update_expiration()` should reject manual sandboxes instead of silently enabling TTL + +If not supported by the CRD: + +- Return `False` from `supports_manual_cleanup()` +- Keep current `expireTime` behavior unchanged + +### agent-sandbox provider behavior + +If supported by the CRD: + +- Make `expires_at` optional in provider interfaces +- Omit `spec.shutdownTime` when `expires_at is None` +- `get_expiration()` should return `None` when the field is absent +- `update_expiration()` should reject manual sandboxes + +If not supported by the CRD: + +- Return `False` from `supports_manual_cleanup()` +- Keep current `shutdownTime` behavior unchanged + +## 4. Interface changes + +Files likely affected: + +- `server/src/services/sandbox_service.py` +- `server/src/services/k8s/workload_provider.py` + +Required updates: + +- Any method signature currently assuming `expires_at: datetime` should be reviewed +- Provider creation/update/get-expiration flows should allow `Optional[datetime]` where needed +- Abstract service docs should describe manual cleanup semantics + +## Error Handling Guidance + +Recommended failure cases: + +### Unsupported runtime/provider + +Case: + +- User omits `timeout` +- Provider cannot represent non-expiring sandbox + +Response: + +- HTTP 400 + +Message: + +- `"Manual cleanup mode is not supported by the current runtime/provider."` + +### Renew called for manual sandbox + +Response: + +- HTTP 409 preferred + +Message: + +- `"Sandbox does not have automatic expiration enabled."` + +### Invalid timeout values + +Keep current behavior: + +- Reject `timeout=0` +- Reject negative values +- Reject values above max bound + +## Compatibility Plan + +This refactor should preserve backward compatibility for current users. + +Expected compatibility behavior: + +- Existing clients sending `timeout` continue to work unchanged +- Existing responses for TTL sandboxes remain unchanged +- New manual-cleanup behavior is opt-in via omission of `timeout` + +Compatibility caveat: + +- Any generated SDKs may need regeneration because `timeout` and `expiresAt` types change from required to optional +- Cross-SDK request shapes do not need to be byte-for-byte identical if language constraints differ. In particular, the + C# SDK may use an explicit `ManualCleanup` flag instead of `timeout=null` so it can keep "unset means use default TTL" + distinct from "explicitly request manual cleanup". + +## Testing Plan + +### API/schema tests + +Files likely affected: + +- `server/tests/test_schema.py` +- route tests covering create/get/list/renew + +Add coverage for: + +- Create request without `timeout` +- Create request with valid `timeout` +- Reject `timeout=0` +- Create response with `expiresAt=null` +- Sandbox model with `expiresAt=null` + +### Docker tests + +File likely affected: + +- `server/tests/test_docker_service.py` + +Add coverage for: + +- Manual sandbox creation does not schedule expiration +- Manual sandbox creation does not write expiration label +- Manual sandbox get/list returns `expiresAt=None` +- Server restart restore path ignores manual sandboxes without warning +- Renew expiration on manual sandbox fails clearly +- TTL sandbox behavior remains unchanged + +### Kubernetes service tests + +Files likely affected: + +- `server/tests/k8s/test_kubernetes_service.py` +- `server/tests/k8s/test_batchsandbox_provider.py` +- `server/tests/k8s/test_agent_sandbox_provider.py` + +Add coverage for: + +- Manual mode rejected when provider capability is false +- Manual mode omits expiration fields when provider capability is true +- Manual mode writes the runtime marker when provider capability is true +- `get_expiration()` returns `None` when expiration field is absent +- Renew expiration fails for manual sandboxes +- TTL sandbox behavior remains unchanged + +### Spec/SDK validation + +Follow-up checks: + +- Regenerate or validate OpenAPI docs if needed +- Verify generated SDKs handle optional `timeout` and nullable `expiresAt` + +## Suggested Implementation Order + +1. Update schema models in `server/src/api/schema.py` +2. Update OpenAPI spec in `specs/sandbox-lifecycle.yml` +3. Refactor Docker runtime to support `expires_at: Optional[datetime]` +4. Add Kubernetes provider capability plumbing +5. Implement Kubernetes manual mode only where confirmed supported +6. Add and update tests +7. Regenerate SDK/spec artifacts if required by repo workflow + +## Open Questions Before Coding + +These should be resolved early in the branch: + +1. Does BatchSandbox allow `spec.expireTime` to be omitted? +2. Does agent-sandbox allow `spec.shutdownTime` to be omitted? +3. Should renew-on-manual return `400` or `409`? +4. Should list/get expose any explicit hint that a sandbox is manual, or is `expiresAt=null` sufficient? + +Recommended implementation default for questions 1 and 2 until confirmed: + +- Return `False` from `supports_manual_cleanup()` for both Kubernetes providers +- Enable Kubernetes manual mode only after CRD behavior is verified by tests or upstream documentation + +Recommended answer for question 4: + +- `expiresAt=null` is sufficient for the first iteration + +## Summary + +The smallest practical refactor is: + +- Make `timeout` optional +- Treat missing `timeout` as manual cleanup mode +- Make `expiresAt` nullable +- Support manual mode in Docker immediately +- Gate Kubernetes support behind provider capability and CRD validation +- Keep `renew_expiration()` TTL-only + +This preserves current behavior while creating a clear path to non-expiring sandboxes with limited API churn. diff --git a/sdks/sandbox/csharp/README.md b/sdks/sandbox/csharp/README.md index 6c52c1dc..83549ca1 100644 --- a/sdks/sandbox/csharp/README.md +++ b/sdks/sandbox/csharp/README.md @@ -68,7 +68,7 @@ Manage the sandbox lifecycle, including renewal, pausing, and resuming. var info = await sandbox.GetInfoAsync(); Console.WriteLine($"State: {info.Status.State}"); Console.WriteLine($"Created: {info.CreatedAt}"); -Console.WriteLine($"Expires: {info.ExpiresAt}"); +Console.WriteLine($"Expires: {info.ExpiresAt}"); // null when manual cleanup mode is used await sandbox.PauseAsync(); @@ -79,6 +79,23 @@ var resumed = await sandbox.ResumeAsync(); await resumed.RenewAsync(30 * 60); ``` +Create a non-expiring sandbox by setting `ManualCleanup = true`: + +```csharp +var manual = await Sandbox.CreateAsync(new SandboxCreateOptions +{ + ConnectionConfig = config, + Image = "ubuntu", + ManualCleanup = true, +}); +``` + +Note: unlike the Python, JavaScript, and Kotlin SDKs, the C# SDK uses an explicit +`ManualCleanup` flag instead of `TimeoutSeconds = null`. This is intentional: +`int?` in the current options model cannot reliably distinguish "unset, use the +default TTL" from "explicitly request manual cleanup" without making the default +creation path ambiguous. + ### Connect to an Existing Sandbox Use `ConnectAsync` when you already have a sandbox ID and need a new SDK instance bound to it. diff --git a/sdks/sandbox/csharp/README_zh.md b/sdks/sandbox/csharp/README_zh.md index d6fd82d6..49ad63f8 100644 --- a/sdks/sandbox/csharp/README_zh.md +++ b/sdks/sandbox/csharp/README_zh.md @@ -68,7 +68,7 @@ catch (SandboxException ex) var info = await sandbox.GetInfoAsync(); Console.WriteLine($"状态: {info.Status.State}"); Console.WriteLine($"创建时间: {info.CreatedAt}"); -Console.WriteLine($"过期时间: {info.ExpiresAt}"); +Console.WriteLine($"过期时间: {info.ExpiresAt}"); // 使用手动清理模式时为 null await sandbox.PauseAsync(); @@ -79,6 +79,22 @@ var resumed = await sandbox.ResumeAsync(); await resumed.RenewAsync(30 * 60); ``` +通过设置 `ManualCleanup = true` 创建一个不会自动过期的沙箱： + +```csharp +var manual = await Sandbox.CreateAsync(new SandboxCreateOptions +{ + ConnectionConfig = config, + Image = "ubuntu", + ManualCleanup = true, +}); +``` + +注意：与 Python、JavaScript、Kotlin SDK 不同，C# SDK 使用显式的 +`ManualCleanup` 开关，而不是 `TimeoutSeconds = null`。这是有意的设计， +因为在当前的 options 模型里，`int?` 不能稳定地区分“未设置，沿用默认 TTL” +和“显式请求手动清理”。 + ### 2. 自定义健康检查 定义自定义逻辑来确定沙箱是否就绪/健康。 diff --git a/sdks/sandbox/csharp/src/OpenSandbox/Adapters/SandboxesAdapter.cs b/sdks/sandbox/csharp/src/OpenSandbox/Adapters/SandboxesAdapter.cs index 00682e00..4896ce61 100644 --- a/sdks/sandbox/csharp/src/OpenSandbox/Adapters/SandboxesAdapter.cs +++ b/sdks/sandbox/csharp/src/OpenSandbox/Adapters/SandboxesAdapter.cs @@ -167,6 +167,11 @@ private static DateTime ParseIsoDate(string fieldName, JsonElement element) return date.ToUniversalTime(); } + private static DateTime? ParseOptionalIsoDate(string fieldName, JsonElement element) + { + return element.ValueKind == JsonValueKind.Null ? null : ParseIsoDate(fieldName, element); + } + private static SandboxInfo ParseSandboxInfo(JsonElement element) { var status = element.GetProperty("status"); @@ -193,7 +198,9 @@ private static SandboxInfo ParseSandboxInfo(JsonElement element) Message = status.TryGetProperty("message", out var message) ? message.GetString() : null }, CreatedAt = ParseIsoDate("createdAt", element.GetProperty("createdAt")), - ExpiresAt = ParseIsoDate("expiresAt", element.GetProperty("expiresAt")) + ExpiresAt = element.TryGetProperty("expiresAt", out var expiresAtElement) + ? ParseOptionalIsoDate("expiresAt", expiresAtElement) + : null }; } @@ -214,7 +221,9 @@ private static CreateSandboxResponse ParseCreateSandboxResponse(JsonElement elem ? metadata.EnumerateObject().ToDictionary(p => p.Name, p => p.Value.GetString() ?? string.Empty) : null, CreatedAt = ParseIsoDate("createdAt", element.GetProperty("createdAt")), - ExpiresAt = ParseIsoDate("expiresAt", element.GetProperty("expiresAt")), + ExpiresAt = element.TryGetProperty("expiresAt", out var expiresAtElement) + ? ParseOptionalIsoDate("expiresAt", expiresAtElement) + : null, Entrypoint = element.GetProperty("entrypoint").EnumerateArray().Select(e => e.GetString() ?? string.Empty).ToList() }; } diff --git a/sdks/sandbox/csharp/src/OpenSandbox/Models/Sandboxes.cs b/sdks/sandbox/csharp/src/OpenSandbox/Models/Sandboxes.cs index 1fb9817c..0f5db81b 100644 --- a/sdks/sandbox/csharp/src/OpenSandbox/Models/Sandboxes.cs +++ b/sdks/sandbox/csharp/src/OpenSandbox/Models/Sandboxes.cs @@ -249,7 +249,7 @@ public class SandboxInfo /// Gets or sets the sandbox expiration time. /// [JsonPropertyName("expiresAt")] - public required DateTime ExpiresAt { get; set; } + public DateTime? ExpiresAt { get; set; } } /// @@ -273,7 +273,7 @@ public class CreateSandboxRequest /// Gets or sets the timeout in seconds. /// [JsonPropertyName("timeout")] - public required int Timeout { get; set; } + public int? Timeout { get; set; } /// /// Gets or sets the resource limits. @@ -339,7 +339,7 @@ public class CreateSandboxResponse /// Gets or sets the sandbox expiration time. /// [JsonPropertyName("expiresAt")] - public required DateTime ExpiresAt { get; set; } + public DateTime? ExpiresAt { get; set; } /// /// Gets or sets the sandbox creation time. diff --git a/sdks/sandbox/csharp/src/OpenSandbox/Options.cs b/sdks/sandbox/csharp/src/OpenSandbox/Options.cs index eeb86b54..8d255cf0 100644 --- a/sdks/sandbox/csharp/src/OpenSandbox/Options.cs +++ b/sdks/sandbox/csharp/src/OpenSandbox/Options.cs @@ -90,6 +90,11 @@ public class SandboxCreateOptions /// public int? TimeoutSeconds { get; set; } + /// + /// Gets or sets whether the sandbox should disable automatic expiration and require explicit cleanup. + /// + public bool ManualCleanup { get; set; } + /// /// Gets or sets whether to skip health checks during creation. /// diff --git a/sdks/sandbox/csharp/src/OpenSandbox/Sandbox.cs b/sdks/sandbox/csharp/src/OpenSandbox/Sandbox.cs index 14b02ed6..a8eab9fc 100644 --- a/sdks/sandbox/csharp/src/OpenSandbox/Sandbox.cs +++ b/sdks/sandbox/csharp/src/OpenSandbox/Sandbox.cs @@ -151,7 +151,7 @@ public static async Task CreateAsync( Auth = options.ImageAuth }, Entrypoint = options.Entrypoint ?? Constants.DefaultEntrypoint, - Timeout = options.TimeoutSeconds ?? Constants.DefaultTimeoutSeconds, + Timeout = options.ManualCleanup ? null : options.TimeoutSeconds ?? Constants.DefaultTimeoutSeconds, ResourceLimits = options.Resource ?? Constants.DefaultResourceLimits, Env = options.Env, Metadata = options.Metadata, diff --git a/sdks/sandbox/csharp/tests/OpenSandbox.Tests/SandboxesAdapterTests.cs b/sdks/sandbox/csharp/tests/OpenSandbox.Tests/SandboxesAdapterTests.cs index 6bbeed03..894234e1 100644 --- a/sdks/sandbox/csharp/tests/OpenSandbox.Tests/SandboxesAdapterTests.cs +++ b/sdks/sandbox/csharp/tests/OpenSandbox.Tests/SandboxesAdapterTests.cs @@ -17,6 +17,7 @@ using FluentAssertions; using OpenSandbox.Adapters; using OpenSandbox.Internal; +using OpenSandbox.Models; using Xunit; namespace OpenSandbox.Tests; @@ -58,6 +59,56 @@ public async Task GetSandboxEndpointAsync_ShouldDefaultUseServerProxyToFalse() handler.LastRequestUri!.Query.Should().Contain("use_server_proxy=false"); } + [Fact] + public async Task GetSandboxAsync_ShouldTreatMissingExpiresAtAsNull() + { + var payload = """ + { + "id": "sbx-1", + "image": { "uri": "python:3.11" }, + "entrypoint": ["python"], + "status": { "state": "Running" }, + "createdAt": "2026-03-14T12:00:00Z" + } + """; + var adapter = CreateAdapterWithJsonResponse(payload); + + SandboxInfo sandbox = await adapter.GetSandboxAsync("sbx-1"); + + sandbox.ExpiresAt.Should().BeNull(); + } + + [Fact] + public async Task CreateSandboxAsync_ShouldTreatMissingExpiresAtAsNull() + { + var payload = """ + { + "id": "sbx-2", + "status": { "state": "Pending" }, + "createdAt": "2026-03-14T12:00:00Z", + "entrypoint": ["python"] + } + """; + var adapter = CreateAdapterWithJsonResponse(payload); + + CreateSandboxResponse response = await adapter.CreateSandboxAsync(new CreateSandboxRequest + { + Image = new ImageSpec { Uri = "python:3.11" }, + ResourceLimits = new Dictionary(), + Entrypoint = new List { "python" } + }); + + response.ExpiresAt.Should().BeNull(); + } + + private static SandboxesAdapter CreateAdapterWithJsonResponse(string payload) + { + var handler = new StaticJsonHandler(payload); + var client = new HttpClient(handler); + var wrapper = new HttpClientWrapper(client, "http://localhost:8080/v1"); + return new SandboxesAdapter(wrapper); + } + private sealed class CaptureHandler : HttpMessageHandler { public Uri? LastRequestUri { get; private set; } @@ -73,4 +124,16 @@ protected override Task SendAsync(HttpRequestMessage reques return Task.FromResult(response); } } + + private sealed class StaticJsonHandler(string payload) : HttpMessageHandler + { + protected override Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken) + { + var response = new HttpResponseMessage(HttpStatusCode.OK) + { + Content = new StringContent(payload, Encoding.UTF8, "application/json") + }; + return Task.FromResult(response); + } + } } diff --git a/sdks/sandbox/javascript/README.md b/sdks/sandbox/javascript/README.md index 49b93a81..13ceee73 100644 --- a/sdks/sandbox/javascript/README.md +++ b/sdks/sandbox/javascript/README.md @@ -74,7 +74,7 @@ Manage the sandbox lifecycle, including renewal, pausing, and resuming. const info = await sandbox.getInfo(); console.log("State:", info.status.state); console.log("Created:", info.createdAt); -console.log("Expires:", info.expiresAt); +console.log("Expires:", info.expiresAt); // null when manual cleanup mode is used await sandbox.pause(); @@ -85,6 +85,16 @@ const resumed = await sandbox.resume(); await resumed.renew(30 * 60); ``` +Create a non-expiring sandbox by passing `timeoutSeconds: null`: + +```ts +const manual = await Sandbox.create({ + connectionConfig: config, + image: "ubuntu", + timeoutSeconds: null, +}); +``` + ### 2. Custom Health Check Define custom logic to determine whether the sandbox is ready/healthy. This overrides the default ping check used during readiness checks. diff --git a/sdks/sandbox/javascript/README_zh.md b/sdks/sandbox/javascript/README_zh.md index a9d7192f..c6293881 100644 --- a/sdks/sandbox/javascript/README_zh.md +++ b/sdks/sandbox/javascript/README_zh.md @@ -80,6 +80,21 @@ const resumed = await sandbox.resume(); // renew：expiresAt = now + timeoutSeconds await resumed.renew(30 * 60); + +// 获取当前状态 +const info = await resumed.getInfo(); +console.log("状态:", info.status.state); +console.log("过期时间:", info.expiresAt); // 使用手动清理模式时为 null +``` + +通过传入 `timeoutSeconds: null` 创建一个不会自动过期的沙箱： + +```ts +const manual = await Sandbox.create({ + connectionConfig: config, + image: "ubuntu", + timeoutSeconds: null, +}); ``` ### 2. 自定义健康检查 diff --git a/sdks/sandbox/javascript/src/adapters/sandboxesAdapter.ts b/sdks/sandbox/javascript/src/adapters/sandboxesAdapter.ts index 4df9bc29..4d0984aa 100644 --- a/sdks/sandbox/javascript/src/adapters/sandboxesAdapter.ts +++ b/sdks/sandbox/javascript/src/adapters/sandboxesAdapter.ts @@ -69,11 +69,16 @@ export class SandboxesAdapter implements Sandboxes { return d; } + private parseOptionalIsoDate(field: string, v: unknown): Date | null { + if (v == null) return null; + return this.parseIsoDate(field, v); + } + private mapSandboxInfo(raw: ApiGetSandboxOk): SandboxInfo { return { ...(raw ?? {}), createdAt: this.parseIsoDate("createdAt", raw?.createdAt), - expiresAt: this.parseIsoDate("expiresAt", raw?.expiresAt), + expiresAt: this.parseOptionalIsoDate("expiresAt", raw?.expiresAt), } as SandboxInfo; } @@ -91,7 +96,7 @@ export class SandboxesAdapter implements Sandboxes { return { ...(raw ?? {}), createdAt: this.parseIsoDate("createdAt", raw?.createdAt), - expiresAt: this.parseIsoDate("expiresAt", raw?.expiresAt), + expiresAt: this.parseOptionalIsoDate("expiresAt", raw?.expiresAt), } as CreateSandboxResponse; } @@ -188,4 +193,4 @@ export class SandboxesAdapter implements Sandboxes { } return ok as unknown as Endpoint; } -} \ No newline at end of file +} diff --git a/sdks/sandbox/javascript/src/api/lifecycle.ts b/sdks/sandbox/javascript/src/api/lifecycle.ts index 571eac18..6e819bcc 100644 --- a/sdks/sandbox/javascript/src/api/lifecycle.ts +++ b/sdks/sandbox/javascript/src/api/lifecycle.ts @@ -468,11 +468,8 @@ export interface components { metadata?: { [key: string]: string; }; - /** - * Format: date-time - * @description Timestamp when sandbox will auto-terminate - */ - expiresAt: string; + /** @description Timestamp when sandbox will auto-terminate. Null when manual cleanup is enabled. */ + expiresAt?: string | null; /** * Format: date-time * @description Sandbox creation timestamp @@ -501,11 +498,8 @@ export interface components { * Always present in responses since entrypoint is required in creation requests. */ entrypoint: string[]; - /** - * Format: date-time - * @description Timestamp when sandbox will auto-terminate - */ - expiresAt: string; + /** @description Timestamp when sandbox will auto-terminate. Null when manual cleanup is enabled. */ + expiresAt?: string | null; /** * Format: date-time * @description Sandbox creation timestamp @@ -588,9 +582,9 @@ export interface components { image: components["schemas"]["ImageSpec"]; /** * @description Sandbox timeout in seconds. The sandbox will automatically terminate after this duration. - * SDK clients should provide a default value (e.g., 3600 seconds / 1 hour). + * Omit or set null to disable automatic expiration and require explicit cleanup. */ - timeout: number; + timeout?: number | null; /** * @description Runtime resource constraints for the sandbox instance. * SDK clients should provide sensible defaults (e.g., cpu: "500m", memory: "512Mi"). @@ -800,15 +794,20 @@ export interface components { path: string; }; /** - * @description Kubernetes PersistentVolumeClaim mount backend. References an existing - * PVC in the same namespace as the sandbox pod. + * @description Platform-managed named volume backend. A runtime-neutral abstraction + * for referencing a pre-existing, platform-managed named volume. + * + * - Kubernetes: maps to a PersistentVolumeClaim in the same namespace. + * - Docker: maps to a Docker named volume (created via `docker volume create`). * - * Only available in Kubernetes runtime. + * The volume must already exist on the target platform before sandbox + * creation. */ PVC: { /** - * @description Name of the PersistentVolumeClaim in the same namespace. - * Must be a valid Kubernetes resource name. + * @description Name of the volume on the target platform. + * In Kubernetes this is the PVC name; in Docker this is the named + * volume name. Must be a valid DNS label. */ claimName: string; }; diff --git a/sdks/sandbox/javascript/src/models/sandboxes.ts b/sdks/sandbox/javascript/src/models/sandboxes.ts index b5139f28..52c74cbb 100644 --- a/sdks/sandbox/javascript/src/models/sandboxes.ts +++ b/sdks/sandbox/javascript/src/models/sandboxes.ts @@ -157,7 +157,7 @@ export interface SandboxInfo extends Record { /** * Sandbox expiration time (server-side TTL). */ - expiresAt: Date; + expiresAt: Date | null; } export interface CreateSandboxRequest extends Record { @@ -166,7 +166,7 @@ export interface CreateSandboxRequest extends Record { /** * Timeout in seconds (server semantics). */ - timeout: number; + timeout?: number | null; resourceLimits: ResourceLimits; env?: Record; metadata?: Record; @@ -188,7 +188,7 @@ export interface CreateSandboxResponse extends Record { /** * Sandbox expiration time after creation. */ - expiresAt: Date; + expiresAt: Date | null; /** * Sandbox creation time. */ @@ -242,4 +242,4 @@ export interface ListSandboxesParams { metadata?: Record; page?: number; pageSize?: number; -}; \ No newline at end of file +}; diff --git a/sdks/sandbox/javascript/src/sandbox.ts b/sdks/sandbox/javascript/src/sandbox.ts index 4606c547..78148c6a 100644 --- a/sdks/sandbox/javascript/src/sandbox.ts +++ b/sdks/sandbox/javascript/src/sandbox.ts @@ -91,9 +91,9 @@ export interface SandboxCreateOptions { */ resource?: Record; /** - * Sandbox timeout in seconds. + * Sandbox timeout in seconds. Set to `null` to require explicit cleanup. */ - timeoutSeconds?: number; + timeoutSeconds?: number | null; /** * Skip readiness checks during create/connect. @@ -254,10 +254,14 @@ export class Sandbox { } } + const timeoutSeconds = + opts.timeoutSeconds === null + ? null + : Math.floor(opts.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS); + const req: CreateSandboxRequest = { image: toImageSpec(opts.image), entrypoint: opts.entrypoint ?? DEFAULT_ENTRYPOINT, - timeout: Math.floor(opts.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS), resourceLimits: opts.resource ?? DEFAULT_RESOURCE_LIMITS, env: opts.env ?? {}, metadata: opts.metadata ?? {}, @@ -270,6 +274,9 @@ export class Sandbox { volumes: opts.volumes, extensions: opts.extensions ?? {}, }; + if (timeoutSeconds !== null) { + req.timeout = timeoutSeconds; + } let sandboxId: SandboxId | undefined; try { diff --git a/sdks/sandbox/kotlin/README.md b/sdks/sandbox/kotlin/README.md index 2b492c8b..de881f30 100644 --- a/sdks/sandbox/kotlin/README.md +++ b/sdks/sandbox/kotlin/README.md @@ -91,6 +91,17 @@ sandbox.resume(); // Get current status SandboxInfo info = sandbox.getInfo(); System.out.println("State: " + info.getStatus().getState()); +System.out.println("Expires: " + info.getExpiresAt()); // null when manual cleanup mode is used +``` + +Create a non-expiring sandbox by passing `timeout(null)`: + +```java +Sandbox manual = Sandbox.builder() + .connectionConfig(config) + .image("ubuntu") + .timeout(null) + .build(); ``` ### 2. Custom Health Check diff --git a/sdks/sandbox/kotlin/README_zh.md b/sdks/sandbox/kotlin/README_zh.md index 0edfedf4..514ca354 100644 --- a/sdks/sandbox/kotlin/README_zh.md +++ b/sdks/sandbox/kotlin/README_zh.md @@ -92,6 +92,17 @@ sandbox.resume(); // 获取当前状态 SandboxInfo info = sandbox.getInfo(); System.out.println("当前状态: " + info.getStatus().getState()); +System.out.println("过期时间: " + info.getExpiresAt()); // 使用手动清理模式时为 null +``` + +通过传入 `timeout(null)` 创建一个不会自动过期的沙箱： + +```java +Sandbox manual = Sandbox.builder() + .connectionConfig(config) + .image("ubuntu") + .timeout(null) + .build(); ``` ### 2. 自定义健康检查 diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/Sandbox.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/Sandbox.kt index 06bf10bd..51a69cec 100644 --- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/Sandbox.kt +++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/Sandbox.kt @@ -276,7 +276,7 @@ class Sandbox internal constructor( entrypoint: List, env: Map, metadata: Map, - timeout: Duration, + timeout: Duration?, readyTimeout: Duration, resource: Map, networkPolicy: NetworkPolicy?, @@ -287,8 +287,9 @@ class Sandbox internal constructor( skipHealthCheck: Boolean, volumes: List?, ): Sandbox { + val timeoutLabel = if (timeout != null) "${timeout.seconds}s" else "manual-cleanup" return initializeSandbox( - operationName = "create sandbox with image ${imageSpec.image} (timeout: ${timeout.seconds}s)", + operationName = "create sandbox with image ${imageSpec.image} (timeout: $timeoutLabel)", connectionConfig = connectionConfig, healthCheck = healthCheck, timeout = readyTimeout, @@ -771,7 +772,7 @@ class Sandbox internal constructor( /** * Lifecycle config */ - private var timeout: Duration = Duration.ofSeconds(600) + private var timeout: Duration? = Duration.ofSeconds(600) private var readyTimeout: Duration = Duration.ofSeconds(30) private var healthCheckPollingInterval: Duration = Duration.ofMillis(200) private var healthCheck: ((Sandbox) -> Boolean)? = null @@ -1045,12 +1046,12 @@ class Sandbox internal constructor( /** * Sets the sandbox timeout (automatic termination time). * - * @param timeout Maximum sandbox lifetime + * @param timeout Maximum sandbox lifetime. Pass null to require explicit cleanup. * @return This builder for method chaining * @throws InvalidArgumentException if timeout is negative or zero */ - fun timeout(timeout: Duration): Builder { - if (timeout.isNegative || timeout.isZero) { + fun timeout(timeout: Duration?): Builder { + if (timeout != null && (timeout.isNegative || timeout.isZero)) { throw InvalidArgumentException( message = "Timeout must be positive, got: $timeout", ) diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/sandboxes/SandboxModels.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/sandboxes/SandboxModels.kt index cad59f93..9033c4a5 100644 --- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/sandboxes/SandboxModels.kt +++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/sandboxes/SandboxModels.kt @@ -503,7 +503,7 @@ class Volume private constructor( * @property id Unique identifier of the sandbox * @property status Current status of the sandbox * @property entrypoint Command line arguments used to start the sandbox - * @property expiresAt Timestamp when the sandbox is scheduled for automatic termination + * @property expiresAt Timestamp when the sandbox is scheduled for automatic termination. Null means manual cleanup mode. * @property createdAt Timestamp when the sandbox was created * @property image Image specification used to create this sandbox * @property metadata Custom metadata attached to the sandbox @@ -512,7 +512,7 @@ class SandboxInfo( val id: String, val status: SandboxStatus, val entrypoint: List, - val expiresAt: OffsetDateTime, + val expiresAt: OffsetDateTime?, val createdAt: OffsetDateTime, val image: SandboxImageSpec, val metadata: Map? = null, diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/services/Sandboxes.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/services/Sandboxes.kt index 0adecd07..2921fc72 100644 --- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/services/Sandboxes.kt +++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/services/Sandboxes.kt @@ -42,7 +42,7 @@ interface Sandboxes { * @param entrypoint The command to run as the sandbox's main process (e.g. `["python", "/app/main.py"]`) * @param env Environment variables injected into the sandbox runtime * @param metadata User-defined metadata used for management and filtering - * @param timeout Sandbox lifetime. The server may terminate the sandbox when it expires + * @param timeout Sandbox lifetime. Pass null to require explicit cleanup. * @param resource Runtime resource limits (e.g. cpu/memory). Exact semantics are server-defined * @param networkPolicy Optional outbound network policy (egress) * @param extensions Opaque extension parameters passed through to the server as-is. Prefer namespaced keys @@ -54,7 +54,7 @@ interface Sandboxes { entrypoint: List, env: Map, metadata: Map, - timeout: Duration, + timeout: Duration?, resource: Map, networkPolicy: NetworkPolicy?, extensions: Map, diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/converter/SandboxModelConverter.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/converter/SandboxModelConverter.kt index 41f2d9a3..7b94ca91 100644 --- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/converter/SandboxModelConverter.kt +++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/converter/SandboxModelConverter.kt @@ -139,7 +139,7 @@ internal object SandboxModelConverter { entrypoint: List, env: Map, metadata: Map, - timeout: Duration, + timeout: Duration?, resource: Map, networkPolicy: NetworkPolicy?, extensions: Map, @@ -148,9 +148,9 @@ internal object SandboxModelConverter { return CreateSandboxRequest( image = spec.toApiImageSpec(), entrypoint = entrypoint, + timeout = timeout?.seconds?.toInt(), env = env, metadata = metadata, - timeout = timeout.seconds.toInt(), resourceLimits = resource, networkPolicy = networkPolicy?.toApiNetworkPolicy(), extensions = extensions, diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/SandboxesAdapter.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/SandboxesAdapter.kt index 10adf21b..eb6d852a 100644 --- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/SandboxesAdapter.kt +++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/SandboxesAdapter.kt @@ -58,7 +58,7 @@ internal class SandboxesAdapter( entrypoint: List, env: Map, metadata: Map, - timeout: Duration, + timeout: Duration?, resource: Map, networkPolicy: NetworkPolicy?, extensions: Map, diff --git a/sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/SandboxesAdapterTest.kt b/sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/SandboxesAdapterTest.kt index 3d901a69..f9fb682d 100644 --- a/sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/SandboxesAdapterTest.kt +++ b/sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/SandboxesAdapterTest.kt @@ -133,6 +133,37 @@ class SandboxesAdapterTest { assertEquals("550e8400-e29b-41d4-a716-446655440000", result.id) } + @Test + fun `createSandbox should accept null expiresAt for manual cleanup response`() { + val responseBody = + """ + { + "id": "manual-sbx", + "status": { "state": "Running" }, + "expiresAt": null, + "createdAt": "2023-01-01T10:00:00Z", + "entrypoint": ["bash"] + } + """.trimIndent() + mockWebServer.enqueue(MockResponse().setBody(responseBody).setResponseCode(201)) + + val spec = SandboxImageSpec.builder().image("ubuntu:latest").build() + val result = + sandboxesAdapter.createSandbox( + spec = spec, + entrypoint = listOf("bash"), + env = emptyMap(), + metadata = emptyMap(), + timeout = null, + resource = mapOf("cpu" to "1"), + networkPolicy = null, + extensions = emptyMap(), + volumes = null, + ) + + assertEquals("manual-sbx", result.id) + } + @Test fun `getSandboxInfo should parse response correctly`() { val sandboxId = "sandbox-id" @@ -168,6 +199,37 @@ class SandboxesAdapterTest { assertEquals("/v1/sandboxes/$sandboxId", request.path) } + @Test + fun `getSandboxInfo should parse null expiresAt for manual cleanup`() { + val sandboxId = "manual-sandbox" + val responseBody = + """ + { + "id": "$sandboxId", + "status": { + "state": "Running", + "reason": null, + "message": null, + "lastTransitionAt": "2023-01-01T10:00:00Z" + }, + "entrypoint": ["/bin/bash"], + "expiresAt": null, + "createdAt": "2023-01-01T10:00:00Z", + "image": { + "uri": "ubuntu:latest" + }, + "metadata": {} + } + """.trimIndent() + + mockWebServer.enqueue(MockResponse().setBody(responseBody)) + + val result = sandboxesAdapter.getSandboxInfo(sandboxId) + + assertEquals(sandboxId, result.id) + assertEquals(null, result.expiresAt) + } + @Test fun `listSandboxes should construct query params correctly`() { val responseBody = diff --git a/sdks/sandbox/python/README.md b/sdks/sandbox/python/README.md index 7b39bdbe..d4095085 100644 --- a/sdks/sandbox/python/README.md +++ b/sdks/sandbox/python/README.md @@ -115,6 +115,17 @@ sandbox = await Sandbox.resume( # Get current status info = await sandbox.get_info() print(f"State: {info.status.state}") +print(f"Expires: {info.expires_at}") # None when manual cleanup mode is used +``` + +Create a non-expiring sandbox by passing `timeout=None`: + +```python +manual = await Sandbox.create( + "ubuntu", + connection_config=config, + timeout=None, +) ``` ### 2. Custom Health Check diff --git a/sdks/sandbox/python/README_zh.md b/sdks/sandbox/python/README_zh.md index 519574ea..5085bf74 100644 --- a/sdks/sandbox/python/README_zh.md +++ b/sdks/sandbox/python/README_zh.md @@ -115,6 +115,17 @@ sandbox = await Sandbox.resume( # 获取当前状态 info = await sandbox.get_info() print(f"当前状态: {info.status.state}") +print(f"过期时间: {info.expires_at}") # 使用手动清理模式时为 None +``` + +通过传入 `timeout=None` 创建一个不会自动过期的沙箱： + +```python +manual = await Sandbox.create( + "ubuntu", + connection_config=config, + timeout=None, +) ``` ### 2. 自定义健康检查 diff --git a/sdks/sandbox/python/src/opensandbox/adapters/converter/sandbox_model_converter.py b/sdks/sandbox/python/src/opensandbox/adapters/converter/sandbox_model_converter.py index 20ed66c4..57eac4f3 100644 --- a/sdks/sandbox/python/src/opensandbox/adapters/converter/sandbox_model_converter.py +++ b/sdks/sandbox/python/src/opensandbox/adapters/converter/sandbox_model_converter.py @@ -123,7 +123,7 @@ def to_api_create_sandbox_request( entrypoint: list[str], env: dict[str, str], metadata: dict[str, str], - timeout: timedelta, + timeout: timedelta | None, resource: dict[str, str], network_policy: NetworkPolicy | None, extensions: dict[str, str], @@ -209,17 +209,19 @@ def to_api_create_sandbox_request( SandboxModelConverter.to_api_volume(v) for v in volumes ] - return CreateSandboxRequest( + request = CreateSandboxRequest( image=SandboxModelConverter.to_api_image_spec(spec), entrypoint=entrypoint, env=api_env, metadata=api_metadata, - timeout=int(timeout.total_seconds()), resource_limits=api_resource_limits, network_policy=api_network_policy, extensions=api_extensions, volumes=api_volumes, ) + if timeout is not None: + request.timeout = int(timeout.total_seconds()) + return request @staticmethod def to_api_renew_request( diff --git a/sdks/sandbox/python/src/opensandbox/adapters/sandboxes_adapter.py b/sdks/sandbox/python/src/opensandbox/adapters/sandboxes_adapter.py index 0ce7a222..936af930 100644 --- a/sdks/sandbox/python/src/opensandbox/adapters/sandboxes_adapter.py +++ b/sdks/sandbox/python/src/opensandbox/adapters/sandboxes_adapter.py @@ -114,7 +114,7 @@ async def create_sandbox( entrypoint: list[str], env: dict[str, str], metadata: dict[str, str], - timeout: timedelta, + timeout: timedelta | None, resource: dict[str, str], network_policy: NetworkPolicy | None, extensions: dict[str, str], diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_request.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_request.py index 837c2de4..aa48d71d 100644 --- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_request.py +++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_request.py @@ -47,8 +47,7 @@ class CreateSandboxRequest: image (ImageSpec): Container image specification for sandbox provisioning. Supports public registry images and private registry images with authentication. - timeout (int): Sandbox timeout in seconds. The sandbox will automatically terminate after this duration. - SDK clients should provide a default value (e.g., 3600 seconds / 1 hour). + timeout (int | None | Unset): Sandbox timeout in seconds. Omit or set null to require explicit cleanup. resource_limits (ResourceLimits): Runtime resource constraints as key-value pairs. Similar to Kubernetes resource specifications, allows flexible definition of resource limits. Common resource types include: @@ -97,9 +96,9 @@ class CreateSandboxRequest: """ image: ImageSpec - timeout: int resource_limits: ResourceLimits entrypoint: list[str] + timeout: int | None | Unset = UNSET env: CreateSandboxRequestEnv | Unset = UNSET metadata: CreateSandboxRequestMetadata | Unset = UNSET network_policy: NetworkPolicy | Unset = UNSET @@ -144,11 +143,12 @@ def to_dict(self) -> dict[str, Any]: field_dict.update( { "image": image, - "timeout": timeout, "resourceLimits": resource_limits, "entrypoint": entrypoint, } ) + if timeout is not UNSET: + field_dict["timeout"] = timeout if env is not UNSET: field_dict["env"] = env if metadata is not UNSET: @@ -175,7 +175,7 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: d = dict(src_dict) image = ImageSpec.from_dict(d.pop("image")) - timeout = d.pop("timeout") + timeout = d.pop("timeout", UNSET) resource_limits = ResourceLimits.from_dict(d.pop("resourceLimits")) diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_response.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_response.py index 602b2fa2..78167409 100644 --- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_response.py +++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_response.py @@ -41,7 +41,7 @@ class CreateSandboxResponse: Attributes: id (str): Unique sandbox identifier status (SandboxStatus): Detailed status information with lifecycle state and transition details - expires_at (datetime.datetime): Timestamp when sandbox will auto-terminate + expires_at (datetime.datetime | None): Timestamp when sandbox will auto-terminate. Null when manual cleanup is enabled. created_at (datetime.datetime): Sandbox creation timestamp entrypoint (list[str]): Entry process specification from creation request metadata (CreateSandboxResponseMetadata | Unset): Custom metadata from creation request @@ -49,7 +49,7 @@ class CreateSandboxResponse: id: str status: SandboxStatus - expires_at: datetime.datetime + expires_at: datetime.datetime | None created_at: datetime.datetime entrypoint: list[str] metadata: CreateSandboxResponseMetadata | Unset = UNSET @@ -60,7 +60,7 @@ def to_dict(self) -> dict[str, Any]: status = self.status.to_dict() - expires_at = self.expires_at.isoformat() + expires_at = self.expires_at.isoformat() if self.expires_at is not None else None created_at = self.created_at.isoformat() @@ -96,7 +96,8 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: status = SandboxStatus.from_dict(d.pop("status")) - expires_at = isoparse(d.pop("expiresAt")) + _expires_at = d.pop("expiresAt") + expires_at = isoparse(_expires_at) if _expires_at is not None else None created_at = isoparse(d.pop("createdAt")) diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox.py index b6d786d2..8d22ef9f 100644 --- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox.py +++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox.py @@ -47,7 +47,7 @@ class Sandbox: status (SandboxStatus): Detailed status information with lifecycle state and transition details entrypoint (list[str]): The command to execute as the sandbox's entry process. Always present in responses since entrypoint is required in creation requests. - expires_at (datetime.datetime): Timestamp when sandbox will auto-terminate + expires_at (datetime.datetime | None): Timestamp when sandbox will auto-terminate. Null when manual cleanup is enabled. created_at (datetime.datetime): Sandbox creation timestamp metadata (SandboxMetadata | Unset): Custom metadata from creation request """ @@ -56,7 +56,7 @@ class Sandbox: image: ImageSpec status: SandboxStatus entrypoint: list[str] - expires_at: datetime.datetime + expires_at: datetime.datetime | None created_at: datetime.datetime metadata: SandboxMetadata | Unset = UNSET additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict) @@ -70,7 +70,7 @@ def to_dict(self) -> dict[str, Any]: entrypoint = self.entrypoint - expires_at = self.expires_at.isoformat() + expires_at = self.expires_at.isoformat() if self.expires_at is not None else None created_at = self.created_at.isoformat() @@ -110,7 +110,8 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: entrypoint = cast(list[str], d.pop("entrypoint")) - expires_at = isoparse(d.pop("expiresAt")) + _expires_at = d.pop("expiresAt") + expires_at = isoparse(_expires_at) if _expires_at is not None else None created_at = isoparse(d.pop("createdAt")) diff --git a/sdks/sandbox/python/src/opensandbox/models/sandboxes.py b/sdks/sandbox/python/src/opensandbox/models/sandboxes.py index 8a4130e2..9907eabe 100644 --- a/sdks/sandbox/python/src/opensandbox/models/sandboxes.py +++ b/sdks/sandbox/python/src/opensandbox/models/sandboxes.py @@ -297,8 +297,10 @@ class SandboxInfo(BaseModel): entrypoint: list[str] = Field( description="Command line arguments used to start the sandbox" ) - expires_at: datetime = Field( - description="Scheduled termination timestamp", alias="expires_at" + expires_at: datetime | None = Field( + default=None, + description="Scheduled termination timestamp. Null means manual cleanup mode.", + alias="expires_at", ) created_at: datetime = Field(description="Creation timestamp", alias="created_at") image: SandboxImageSpec | None = Field( diff --git a/sdks/sandbox/python/src/opensandbox/sandbox.py b/sdks/sandbox/python/src/opensandbox/sandbox.py index f09f0b6d..cdcfde28 100644 --- a/sdks/sandbox/python/src/opensandbox/sandbox.py +++ b/sdks/sandbox/python/src/opensandbox/sandbox.py @@ -371,7 +371,7 @@ async def create( cls, image: SandboxImageSpec | str, *, - timeout: timedelta = timedelta(minutes=10), + timeout: timedelta | None = timedelta(minutes=10), ready_timeout: timedelta = timedelta(seconds=30), env: dict[str, str] | None = None, metadata: dict[str, str] | None = None, @@ -390,7 +390,7 @@ async def create( Args: image: Container image specification including image reference and optional auth - timeout: Maximum sandbox lifetime + timeout: Maximum sandbox lifetime. Pass None to require explicit cleanup. ready_timeout: Maximum time to wait for sandbox to become ready env: Environment variables for the sandbox metadata: Custom metadata for the sandbox @@ -422,8 +422,11 @@ async def create( if isinstance(image, str): image = SandboxImageSpec(image=image) + timeout_log = "manual-cleanup" if timeout is None else f"{timeout.total_seconds()}s" logger.info( - f"Creating sandbox with image: {image.image} (timeout: {timeout.total_seconds()}s)" + "Creating sandbox with image: %s (timeout: %s)", + image.image, + timeout_log, ) factory = AdapterFactory(config) sandbox_id: str | None = None diff --git a/sdks/sandbox/python/src/opensandbox/services/sandbox.py b/sdks/sandbox/python/src/opensandbox/services/sandbox.py index e6e2c01c..0f49cbaa 100644 --- a/sdks/sandbox/python/src/opensandbox/services/sandbox.py +++ b/sdks/sandbox/python/src/opensandbox/services/sandbox.py @@ -49,7 +49,7 @@ async def create_sandbox( entrypoint: list[str], env: dict[str, str], metadata: dict[str, str], - timeout: timedelta, + timeout: timedelta | None, resource: dict[str, str], network_policy: NetworkPolicy | None, extensions: dict[str, str], @@ -63,7 +63,7 @@ async def create_sandbox( entrypoint: Command to run as the sandbox's main process. env: Environment variables injected into the sandbox runtime. metadata: User-defined metadata used for management and filtering. - timeout: Sandbox lifetime. The server may terminate the sandbox when it expires. + timeout: Sandbox lifetime. Pass None to create a sandbox that requires explicit cleanup. resource: Runtime resource limits (e.g. cpu/memory). Exact semantics are server-defined. network_policy: Optional outbound network policy (egress). extensions: Opaque extension parameters passed through to the server as-is. diff --git a/sdks/sandbox/python/src/opensandbox/sync/adapters/sandboxes_adapter.py b/sdks/sandbox/python/src/opensandbox/sync/adapters/sandboxes_adapter.py index 7c2b3ad9..5ca848a8 100644 --- a/sdks/sandbox/python/src/opensandbox/sync/adapters/sandboxes_adapter.py +++ b/sdks/sandbox/python/src/opensandbox/sync/adapters/sandboxes_adapter.py @@ -91,7 +91,7 @@ def create_sandbox( entrypoint: list[str], env: dict[str, str], metadata: dict[str, str], - timeout: timedelta, + timeout: timedelta | None, resource: dict[str, str], network_policy: NetworkPolicy | None, extensions: dict[str, str], diff --git a/sdks/sandbox/python/src/opensandbox/sync/sandbox.py b/sdks/sandbox/python/src/opensandbox/sync/sandbox.py index a7637316..c5a53dfa 100644 --- a/sdks/sandbox/python/src/opensandbox/sync/sandbox.py +++ b/sdks/sandbox/python/src/opensandbox/sync/sandbox.py @@ -361,7 +361,7 @@ def create( cls, image: SandboxImageSpec | str, *, - timeout: timedelta = timedelta(minutes=10), + timeout: timedelta | None = timedelta(minutes=10), ready_timeout: timedelta = timedelta(seconds=30), env: dict[str, str] | None = None, metadata: dict[str, str] | None = None, @@ -380,7 +380,7 @@ def create( Args: image: Container image specification including image reference and optional auth - timeout: Maximum sandbox lifetime + timeout: Maximum sandbox lifetime. Pass None to require explicit cleanup. ready_timeout: Maximum time to wait for sandbox to become ready env: Environment variables for the sandbox metadata: Custom metadata for the sandbox @@ -411,10 +411,11 @@ def create( if isinstance(image, str): image = SandboxImageSpec(image=image) + timeout_log = "manual-cleanup" if timeout is None else f"{timeout.total_seconds()}s" logger.info( - "Creating sandbox with image: %s (timeout: %ss)", + "Creating sandbox with image: %s (timeout: %s)", image.image, - timeout.total_seconds(), + timeout_log, ) factory = AdapterFactorySync(config) sandbox_id: str | None = None diff --git a/sdks/sandbox/python/src/opensandbox/sync/services/sandbox.py b/sdks/sandbox/python/src/opensandbox/sync/services/sandbox.py index 48164936..224ef30d 100644 --- a/sdks/sandbox/python/src/opensandbox/sync/services/sandbox.py +++ b/sdks/sandbox/python/src/opensandbox/sync/services/sandbox.py @@ -50,7 +50,7 @@ def create_sandbox( entrypoint: list[str], env: dict[str, str], metadata: dict[str, str], - timeout: timedelta, + timeout: timedelta | None, resource: dict[str, str], network_policy: NetworkPolicy | None, extensions: dict[str, str], @@ -64,7 +64,7 @@ def create_sandbox( entrypoint: Command to run as entrypoint. env: Environment variables. metadata: Custom metadata. - timeout: Sandbox lifetime / expiration duration. + timeout: Sandbox lifetime / expiration duration. Pass None to require explicit cleanup. resource: Resource limits. network_policy: Optional outbound network policy (egress). extensions: Opaque extension parameters passed through to the server as-is. diff --git a/sdks/sandbox/python/tests/test_converters_and_error_handling.py b/sdks/sandbox/python/tests/test_converters_and_error_handling.py index fd5be5f4..ac180d57 100644 --- a/sdks/sandbox/python/tests/test_converters_and_error_handling.py +++ b/sdks/sandbox/python/tests/test_converters_and_error_handling.py @@ -217,3 +217,20 @@ def test_sandbox_model_converter_to_api_create_request_and_renew_tz() -> None: renew = SandboxModelConverter.to_api_renew_request(datetime(2025, 1, 1)) assert renew.expires_at.tzinfo is timezone.utc + + +def test_sandbox_model_converter_omits_timeout_for_manual_cleanup() -> None: + req = SandboxModelConverter.to_api_create_sandbox_request( + spec=SandboxImageSpec("python:3.11"), + entrypoint=["/bin/sh"], + env={}, + metadata={}, + timeout=None, + resource={"cpu": "100m"}, + network_policy=None, + extensions={}, + volumes=None, + ) + + dumped = req.to_dict() + assert "timeout" not in dumped diff --git a/sdks/sandbox/python/tests/test_models_stability.py b/sdks/sandbox/python/tests/test_models_stability.py index e307cbbd..3c106e55 100644 --- a/sdks/sandbox/python/tests/test_models_stability.py +++ b/sdks/sandbox/python/tests/test_models_stability.py @@ -75,6 +75,20 @@ def test_sandbox_status_and_info_alias_dump_is_stable() -> None: assert dumped["status"]["last_transition_at"].endswith(("Z", "+00:00")) +def test_sandbox_info_supports_manual_cleanup_expiration() -> None: + info = SandboxInfo( + id=str(__import__("uuid").uuid4()), + status=SandboxStatus(state="RUNNING"), + entrypoint=["/bin/sh"], + expires_at=None, + created_at=datetime(2025, 1, 1, tzinfo=timezone.utc), + image=SandboxImageSpec("python:3.11"), + ) + + dumped = info.model_dump(by_alias=True, mode="json") + assert dumped["expires_at"] is None + + def test_filesystem_models_aliases_and_validation() -> None: m = MoveEntry(source="/a", destination="/b") assert m.src == "/a" diff --git a/sdks/sandbox/python/tests/test_sandbox_service_adapter_lifecycle.py b/sdks/sandbox/python/tests/test_sandbox_service_adapter_lifecycle.py index af85acb6..073af0ab 100644 --- a/sdks/sandbox/python/tests/test_sandbox_service_adapter_lifecycle.py +++ b/sdks/sandbox/python/tests/test_sandbox_service_adapter_lifecycle.py @@ -119,6 +119,35 @@ async def _fake_asyncio_detailed(*, client, body): assert network_policy["egress"] == [{"action": "allow", "target": "pypi.org"}] +@pytest.mark.asyncio +async def test_create_sandbox_manual_cleanup_omits_timeout(monkeypatch: pytest.MonkeyPatch) -> None: + called = {} + + async def _fake_asyncio_detailed(*, client, body): + called["body"] = body + return _Resp(status_code=200, parsed=_api_create_sandbox_response(str(uuid4()))) + + monkeypatch.setattr( + "opensandbox.api.lifecycle.api.sandboxes.post_sandboxes.asyncio_detailed", + _fake_asyncio_detailed, + ) + + adapter = SandboxesAdapter(ConnectionConfig(domain="example.com:8080", api_key="k")) + await adapter.create_sandbox( + spec=SandboxImageSpec("python:3.11"), + entrypoint=["/bin/sh"], + env={}, + metadata={}, + timeout=None, + resource={"cpu": "100m"}, + network_policy=None, + extensions={}, + volumes=None, + ) + + assert "timeout" not in called["body"].to_dict() + + @pytest.mark.asyncio async def test_create_sandbox_empty_response_raises(monkeypatch: pytest.MonkeyPatch) -> None: async def _fake_asyncio_detailed(*, client, body): diff --git a/server/README.md b/server/README.md index 63140c42..c0a09172 100644 --- a/server/README.md +++ b/server/README.md @@ -11,7 +11,7 @@ A production-grade, FastAPI-based service for managing the lifecycle of containe - **Pluggable runtimes**: - **Docker**: Production-ready - **Kubernetes**: Production-ready (see `kubernetes/` for deployment) -- **Automatic expiration**: Configurable TTL with renewal +- **Lifecycle cleanup modes**: Configurable TTL with renewal, or manual cleanup with explicit delete - **Access control**: API Key authentication (`OPEN-SANDBOX-API-KEY`); can be disabled for local/dev - **Networking modes**: - Host: shared host network, performance first @@ -88,6 +88,7 @@ Before you start the server, edit the configuration file to suit your environmen port = 8080 log_level = "INFO" api_key = "your-secret-api-key-change-this" + max_sandbox_timeout_seconds = 86400 # Maximum TTL for requests that specify timeout [runtime] type = "docker" @@ -104,6 +105,7 @@ Before you start the server, edit the configuration file to suit your environmen port = 8080 log_level = "INFO" api_key = "your-secret-api-key-change-this" + max_sandbox_timeout_seconds = 86400 # Maximum TTL for requests that specify timeout [runtime] type = "docker" @@ -144,6 +146,23 @@ The returned endpoint is rewritten to the server proxy route: Reference runtime compose file: - `server/docker-compose.example.yaml` +**Sandbox TTL configuration** + +- `timeout` requests must be at least 60 seconds. +- The maximum allowed TTL is controlled by `server.max_sandbox_timeout_seconds`. +- Omit `timeout` or set it to `null` in the create request to use manual cleanup mode instead of automatic expiration. + +**Upgrade order for manual cleanup** + +- Existing TTL-only clients can continue to work without changes as long as they do not encounter manual-cleanup sandboxes. +- Manual cleanup changes the lifecycle response contract: `expiresAt` may be `null`, and nullable lifecycle fields may be serialized explicitly. +- Before creating any manual-cleanup sandbox, upgrade every SDK/client that may call `create`, `get`, or `list` on the lifecycle API. +- Recommended rollout order: + 1. Upgrade SDKs/clients + 2. Upgrade the server + 3. Start creating sandboxes with `timeout` omitted or `null` +- Do not introduce manual-cleanup sandboxes into a shared environment while old SDKs are still actively reading lifecycle responses. + **Security hardening (applies to all Docker modes)** ```toml [docker] diff --git a/server/example.config.toml b/server/example.config.toml index 8babdd43..13dd367b 100644 --- a/server/example.config.toml +++ b/server/example.config.toml @@ -24,6 +24,8 @@ port = 8080 log_level = "INFO" # api_key = "your-secret-api-key" # Optional: Uncomment to enable API key authentication # eip = "1.2.3.4" # Optional: External IP/hostname for endpoint URLs when returning sandbox endpoints +# Maximum TTL for sandboxes that specify timeout. Set to null to disable the upper bound. +max_sandbox_timeout_seconds = 86400 [runtime] # Runtime selection (docker | kubernetes) diff --git a/server/src/api/lifecycle.py b/server/src/api/lifecycle.py index ec46a521..0062a629 100644 --- a/server/src/api/lifecycle.py +++ b/server/src/api/lifecycle.py @@ -73,7 +73,6 @@ @router.post( "/sandboxes", response_model=CreateSandboxResponse, - response_model_exclude_none=True, status_code=status.HTTP_202_ACCEPTED, responses={ 202: {"description": "Sandbox creation accepted for asynchronous provisioning"}, @@ -112,7 +111,6 @@ async def create_sandbox( @router.get( "/sandboxes", response_model=ListSandboxesResponse, - response_model_exclude_none=True, responses={ 200: {"description": "Paginated collection of sandboxes"}, 400: {"model": ErrorResponse, "description": "The request was invalid or malformed"}, @@ -176,7 +174,6 @@ async def list_sandboxes( @router.get( "/sandboxes/{sandbox_id}", response_model=Sandbox, - response_model_exclude_none=True, responses={ 200: {"description": "Sandbox current state and metadata"}, 401: {"model": ErrorResponse, "description": "Authentication credentials are missing or invalid"}, diff --git a/server/src/api/schema.py b/server/src/api/schema.py index c6373dd0..87c29f80 100644 --- a/server/src/api/schema.py +++ b/server/src/api/schema.py @@ -251,11 +251,14 @@ class CreateSandboxRequest(BaseModel): Request to create a new sandbox from a container image. """ image: ImageSpec = Field(..., description="Container image specification for the sandbox") - timeout: int = Field( - ..., + timeout: Optional[int] = Field( + None, ge=60, - le=86400, - description="Sandbox timeout in seconds (60-86400). The sandbox will automatically terminate after this duration.", + description=( + "Sandbox timeout in seconds (minimum 60). " + "The maximum is controlled by server.max_sandbox_timeout_seconds. " + "When omitted or null, the sandbox will not auto-terminate and must be deleted explicitly." + ), ) resource_limits: ResourceLimits = Field( ..., @@ -309,7 +312,11 @@ class CreateSandboxResponse(BaseModel): id: str = Field(..., description="Unique sandbox identifier") status: SandboxStatus = Field(..., description="Current lifecycle status and detailed state information") metadata: Optional[Dict[str, str]] = Field(None, description="Custom metadata from creation request") - expires_at: datetime = Field(..., alias="expiresAt", description="Timestamp when sandbox will auto-terminate") + expires_at: Optional[datetime] = Field( + None, + alias="expiresAt", + description="Timestamp when sandbox will auto-terminate. Null when manual cleanup is enabled.", + ) created_at: datetime = Field(..., alias="createdAt", description="Sandbox creation timestamp") entrypoint: List[str] = Field(..., description="Entry process specification from creation request") @@ -328,7 +335,11 @@ class Sandbox(BaseModel): status: SandboxStatus = Field(..., description="Current lifecycle status and detailed state information") metadata: Optional[Dict[str, str]] = Field(None, description="Custom metadata from creation request") entrypoint: List[str] = Field(..., description="The command to execute as the sandbox's entry process") - expires_at: datetime = Field(..., alias="expiresAt", description="Timestamp when sandbox will auto-terminate") + expires_at: Optional[datetime] = Field( + None, + alias="expiresAt", + description="Timestamp when sandbox will auto-terminate. Null when manual cleanup is enabled.", + ) created_at: datetime = Field(..., alias="createdAt", description="Sandbox creation timestamp") class Config: diff --git a/server/src/config.py b/server/src/config.py index 1ffd3892..06a63bae 100644 --- a/server/src/config.py +++ b/server/src/config.py @@ -185,6 +185,14 @@ class ServerConfig(BaseModel): default=None, description="Bound public IP. When set, used as the host part when returning sandbox endpoints.", ) + max_sandbox_timeout_seconds: Optional[int] = Field( + default=86400, + ge=60, + description=( + "Maximum allowed sandbox TTL in seconds for requests that specify timeout. " + "Set to null to disable the server-side upper bound." + ), + ) class KubernetesRuntimeConfig(BaseModel): diff --git a/server/src/services/constants.py b/server/src/services/constants.py index 8951b371..1aba9a78 100644 --- a/server/src/services/constants.py +++ b/server/src/services/constants.py @@ -16,6 +16,7 @@ SANDBOX_ID_LABEL = "opensandbox.io/id" SANDBOX_EXPIRES_AT_LABEL = "opensandbox.io/expires-at" +SANDBOX_MANUAL_CLEANUP_LABEL = "opensandbox.io/manual-cleanup" # Host-mapped ports recorded on containers (bridge mode). SANDBOX_EMBEDDING_PROXY_PORT_LABEL = "opensandbox.io/embedding-proxy-port" # maps container 44772 -> host port SANDBOX_HTTP_PORT_LABEL = "opensandbox.io/http-port" # maps container 8080 -> host port @@ -78,6 +79,7 @@ class SandboxErrorCodes: __all__ = [ "SANDBOX_ID_LABEL", "SANDBOX_EXPIRES_AT_LABEL", + "SANDBOX_MANUAL_CLEANUP_LABEL", "SANDBOX_EMBEDDING_PROXY_PORT_LABEL", "SANDBOX_HTTP_PORT_LABEL", "OPEN_SANDBOX_INGRESS_HEADER", diff --git a/server/src/services/docker.py b/server/src/services/docker.py index 019c8b0d..04409f47 100644 --- a/server/src/services/docker.py +++ b/server/src/services/docker.py @@ -63,6 +63,7 @@ SANDBOX_EXPIRES_AT_LABEL, SANDBOX_HTTP_PORT_LABEL, SANDBOX_ID_LABEL, + SANDBOX_MANUAL_CLEANUP_LABEL, SandboxErrorCodes, ) from src.services.helpers import ( @@ -78,6 +79,7 @@ ensure_entrypoint, ensure_future_expiration, ensure_metadata_labels, + ensure_timeout_within_limit, ensure_valid_host_path, ensure_volumes_valid, ) @@ -107,7 +109,7 @@ def _running_inside_docker_container() -> bool: class PendingSandbox: request: CreateSandboxRequest created_at: datetime - expires_at: datetime + expires_at: Optional[datetime] status: SandboxStatus @@ -274,12 +276,16 @@ def _remove_expiration_tracking(self, sandbox_id: str) -> None: timer.cancel() self._sandbox_expirations.pop(sandbox_id, None) + @staticmethod + def _has_manual_cleanup(labels: Dict[str, str]) -> bool: + """Return True when labels indicate manual cleanup mode.""" + return labels.get(SANDBOX_MANUAL_CLEANUP_LABEL, "").lower() == "true" + def _get_tracked_expiration( self, sandbox_id: str, labels: Dict[str, str], - fallback: datetime, - ) -> datetime: + ) -> Optional[datetime]: """Return the known expiration timestamp for the sandbox.""" with self._expiration_lock: tracked = self._sandbox_expirations.get(sandbox_id) @@ -288,7 +294,7 @@ def _get_tracked_expiration( label_value = labels.get(SANDBOX_EXPIRES_AT_LABEL) if label_value: return parse_timestamp(label_value) - return fallback + return None def _expire_sandbox(self, sandbox_id: str) -> None: """Timer callback to terminate expired sandboxes.""" @@ -343,6 +349,8 @@ def _restore_existing_sandboxes(self) -> None: expires_label = labels.get(SANDBOX_EXPIRES_AT_LABEL) if expires_label: expires_at = parse_timestamp(expires_label) + elif self._has_manual_cleanup(labels): + continue else: logger.warning( "Sandbox %s missing expires-at label; skipping expiration scheduling.", @@ -496,7 +504,7 @@ def _container_to_sandbox(self, container, sandbox_id: Optional[str] = None) -> metadata = { key: value for key, value in labels.items() - if key not in {SANDBOX_ID_LABEL, SANDBOX_EXPIRES_AT_LABEL} + if key not in {SANDBOX_ID_LABEL, SANDBOX_EXPIRES_AT_LABEL, SANDBOX_MANUAL_CLEANUP_LABEL} } or None entrypoint = container.attrs.get("Config", {}).get("Cmd") or [] if isinstance(entrypoint, str): @@ -511,7 +519,7 @@ def _container_to_sandbox(self, container, sandbox_id: Optional[str] = None) -> if finished_at and finished_at != "0001-01-01T00:00:00Z" else created_at ) - expires_at = self._get_tracked_expiration(resolved_id, labels, created_at) + expires_at = self._get_tracked_expiration(resolved_id, labels) status_info = SandboxStatus( state=state, @@ -618,10 +626,12 @@ def _prepare_sandbox_runtime(self, container, sandbox_id: str) -> None: def _prepare_creation_context( self, request: CreateSandboxRequest, - ) -> tuple[str, datetime, datetime]: + ) -> tuple[str, datetime, Optional[datetime]]: sandbox_id = self.generate_sandbox_id() created_at = datetime.now(timezone.utc) - expires_at = created_at + timedelta(seconds=request.timeout) + expires_at = None + if request.timeout is not None: + expires_at = created_at + timedelta(seconds=request.timeout) return sandbox_id, created_at, expires_at @staticmethod @@ -655,6 +665,10 @@ def create_sandbox(self, request: CreateSandboxRequest) -> CreateSandboxResponse """ ensure_entrypoint(request.entrypoint) ensure_metadata_labels(request.metadata) + ensure_timeout_within_limit( + request.timeout, + self.app_config.server.max_sandbox_timeout_seconds, + ) self._ensure_network_policy_support(request) self._validate_network_exists() pvc_inspect_cache = self._validate_volumes(request) @@ -666,7 +680,7 @@ def _async_provision_worker( sandbox_id: str, request: CreateSandboxRequest, created_at: datetime, - expires_at: datetime, + expires_at: Optional[datetime], pvc_inspect_cache: Optional[dict[str, dict]] = None, ) -> None: try: @@ -822,7 +836,7 @@ def _provision_sandbox( sandbox_id: str, request: CreateSandboxRequest, created_at: datetime, - expires_at: datetime, + expires_at: Optional[datetime], pvc_inspect_cache: Optional[dict[str, dict]] = None, ) -> CreateSandboxResponse: labels, environment = self._build_labels_and_env(sandbox_id, request, expires_at) @@ -904,7 +918,8 @@ def _provision_sandbox( last_transition_at=created_at, ) - self._schedule_expiration(sandbox_id, expires_at) + if expires_at is not None: + self._schedule_expiration(sandbox_id, expires_at) return CreateSandboxResponse( id=sandbox_id, @@ -1505,6 +1520,24 @@ def renew_expiration( new_expiration = ensure_future_expiration(request.expires_at) labels = container.attrs.get("Config", {}).get("Labels") or {} + if self._has_manual_cleanup(labels): + raise HTTPException( + status_code=status.HTTP_409_CONFLICT, + detail={ + "code": SandboxErrorCodes.INVALID_EXPIRATION, + "message": f"Sandbox {sandbox_id} does not have automatic expiration enabled.", + }, + ) + if self._get_tracked_expiration(sandbox_id, labels) is None: + raise HTTPException( + status_code=status.HTTP_409_CONFLICT, + detail={ + "code": SandboxErrorCodes.INVALID_EXPIRATION, + "message": ( + f"Sandbox {sandbox_id} is missing expiration metadata and cannot be renewed safely." + ), + }, + ) # Persist the new timeout in memory; it will also be respected on restart via _restore_existing_sandboxes self._schedule_expiration(sandbox_id, new_expiration) @@ -1620,12 +1653,15 @@ def _build_labels_and_env( self, sandbox_id: str, request: CreateSandboxRequest, - expires_at: datetime, + expires_at: Optional[datetime], ) -> tuple[dict[str, str], list[str]]: metadata = request.metadata or {} labels = {key: str(value) for key, value in metadata.items()} labels[SANDBOX_ID_LABEL] = sandbox_id - labels[SANDBOX_EXPIRES_AT_LABEL] = expires_at.isoformat() + if expires_at is None: + labels[SANDBOX_MANUAL_CLEANUP_LABEL] = "true" + else: + labels[SANDBOX_EXPIRES_AT_LABEL] = expires_at.isoformat() env_dict = request.env or {} environment = [] diff --git a/server/src/services/k8s/kubernetes_service.py b/server/src/services/k8s/kubernetes_service.py index 61399196..11d18f72 100644 --- a/server/src/services/k8s/kubernetes_service.py +++ b/server/src/services/k8s/kubernetes_service.py @@ -51,6 +51,7 @@ ensure_egress_configured, ensure_future_expiration, ensure_metadata_labels, + ensure_timeout_within_limit, ensure_volumes_valid, ) from src.services.k8s.client import K8sClient @@ -262,6 +263,10 @@ def create_sandbox(self, request: CreateSandboxRequest) -> CreateSandboxResponse # Validate request ensure_entrypoint(request.entrypoint) ensure_metadata_labels(request.metadata) + ensure_timeout_within_limit( + request.timeout, + self.app_config.server.max_sandbox_timeout_seconds, + ) self._ensure_network_policy_support(request) self._ensure_image_auth_support(request) @@ -270,7 +275,19 @@ def create_sandbox(self, request: CreateSandboxRequest) -> CreateSandboxResponse # Calculate expiration time created_at = datetime.now(timezone.utc) - expires_at = created_at + timedelta(seconds=request.timeout) + expires_at = None + if request.timeout is not None: + expires_at = created_at + timedelta(seconds=request.timeout) + elif not self.workload_provider.supports_manual_cleanup(): + raise HTTPException( + status_code=status.HTTP_400_BAD_REQUEST, + detail={ + "code": SandboxErrorCodes.INVALID_PARAMETER, + "message": ( + "Manual cleanup mode is not supported by the current Kubernetes workload provider." + ), + }, + ) # Build labels labels = { @@ -596,7 +613,17 @@ def renew_expiration( "message": f"Sandbox '{sandbox_id}' not found", }, ) - + + current_expiration = self.workload_provider.get_expiration(workload) + if current_expiration is None: + raise HTTPException( + status_code=status.HTTP_409_CONFLICT, + detail={ + "code": SandboxErrorCodes.INVALID_EXPIRATION, + "message": f"Sandbox {sandbox_id} does not have automatic expiration enabled.", + }, + ) + # Update BatchSandbox spec.expireTime field self.workload_provider.update_expiration( sandbox_id=sandbox_id, diff --git a/server/src/services/k8s/workload_provider.py b/server/src/services/k8s/workload_provider.py index c8e71cd6..279ce55b 100644 --- a/server/src/services/k8s/workload_provider.py +++ b/server/src/services/k8s/workload_provider.py @@ -183,6 +183,15 @@ def supports_image_auth(self) -> bool: """ return False + def supports_manual_cleanup(self) -> bool: + """ + Whether this provider can represent a non-expiring sandbox. + + Providers should override this only after their backing CRD semantics + are verified to support omitting expiration fields safely. + """ + return False + def legacy_resource_name(self, sandbox_id: str) -> str: """ Convert a sandbox_id to the legacy resource name with prefix. diff --git a/server/src/services/validators.py b/server/src/services/validators.py index f366f6b8..0c10ac74 100644 --- a/server/src/services/validators.py +++ b/server/src/services/validators.py @@ -167,6 +167,33 @@ def ensure_valid_port(port: int) -> None: ) +def ensure_timeout_within_limit(timeout_seconds: Optional[int], max_timeout_seconds: Optional[int]) -> None: + """ + Validate that a requested sandbox TTL does not exceed the configured limit. + + Args: + timeout_seconds: Requested sandbox TTL in seconds, or None for manual cleanup. + max_timeout_seconds: Configured maximum TTL in seconds, or None to disable the limit. + + Raises: + HTTPException: When the timeout exceeds the configured maximum. + """ + if timeout_seconds is None or max_timeout_seconds is None: + return + + if timeout_seconds > max_timeout_seconds: + raise HTTPException( + status_code=status.HTTP_400_BAD_REQUEST, + detail={ + "code": SandboxErrorCodes.INVALID_PARAMETER, + "message": ( + f"Sandbox timeout {timeout_seconds}s exceeds configured maximum " + f"of {max_timeout_seconds}s." + ), + }, + ) + + # Volume name must be a valid DNS label VOLUME_NAME_RE = re.compile(r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$") # Kubernetes resource name pattern diff --git a/server/tests/k8s/test_kubernetes_service.py b/server/tests/k8s/test_kubernetes_service.py index 5fc1be6b..df7043c2 100644 --- a/server/tests/k8s/test_kubernetes_service.py +++ b/server/tests/k8s/test_kubernetes_service.py @@ -194,6 +194,34 @@ def test_create_sandbox_allows_image_auth_when_provider_supported( k8s_service.create_sandbox(create_sandbox_request) k8s_service.workload_provider.create_workload.assert_called_once() + def test_create_sandbox_rejects_manual_cleanup_when_provider_not_supported( + self, k8s_service, create_sandbox_request + ): + create_sandbox_request.timeout = None + k8s_service.workload_provider.supports_manual_cleanup.return_value = False + + with pytest.raises(HTTPException) as exc_info: + k8s_service.create_sandbox(create_sandbox_request) + + assert exc_info.value.status_code == 400 + assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER + assert "Manual cleanup mode is not supported" in exc_info.value.detail["message"] + k8s_service.workload_provider.create_workload.assert_not_called() + + def test_create_sandbox_rejects_timeout_above_configured_maximum( + self, k8s_service, create_sandbox_request + ): + k8s_service.app_config.server.max_sandbox_timeout_seconds = 3600 + create_sandbox_request.timeout = 7200 + + with pytest.raises(HTTPException) as exc_info: + k8s_service.create_sandbox(create_sandbox_request) + + assert exc_info.value.status_code == 400 + assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER + assert "configured maximum of 3600s" in exc_info.value.detail["message"] + k8s_service.workload_provider.create_workload.assert_not_called() + class TestWaitForSandboxReady: """_wait_for_sandbox_ready method tests""" @@ -276,6 +304,23 @@ def test_wait_timeout_raises_exception(self, k8s_service, mock_workload): assert "timeout" in exc_info.value.detail["message"].lower() +class TestKubernetesSandboxServiceRenew: + def test_renew_expiration_rejects_manual_cleanup_sandbox(self, k8s_service): + k8s_service.workload_provider.get_workload.return_value = MagicMock() + k8s_service.workload_provider.get_expiration.return_value = None + request = MagicMock(expires_at=datetime.now(timezone.utc) + timedelta(hours=1)) + + with pytest.raises(HTTPException) as exc_info: + k8s_service.renew_expiration("test-sandbox-id", request) + + assert exc_info.value.status_code == 409 + assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_EXPIRATION + assert ( + exc_info.value.detail["message"] + == "Sandbox test-sandbox-id does not have automatic expiration enabled." + ) + + class TestGetSandbox: """get_sandbox method tests""" diff --git a/server/tests/test_config.py b/server/tests/test_config.py index 45e4f3df..e46f3c61 100644 --- a/server/tests/test_config.py +++ b/server/tests/test_config.py @@ -42,6 +42,7 @@ def test_load_config_from_file(tmp_path, monkeypatch): port = 9000 log_level = "DEBUG" api_key = "secret" + max_sandbox_timeout_seconds = 172800 [runtime] type = "kubernetes" @@ -61,6 +62,7 @@ def test_load_config_from_file(tmp_path, monkeypatch): assert loaded.server.port == 9000 assert loaded.server.log_level == "DEBUG" assert loaded.server.api_key == "secret" + assert loaded.server.max_sandbox_timeout_seconds == 172800 assert loaded.runtime.type == "kubernetes" assert loaded.runtime.execd_image == "opensandbox/execd:test" assert loaded.ingress is not None @@ -79,6 +81,11 @@ def test_docker_runtime_disallows_kubernetes_block(): AppConfig(server=server_cfg, runtime=runtime_cfg, kubernetes=kubernetes_cfg) +def test_server_config_defaults_include_max_sandbox_timeout(): + server_cfg = ServerConfig() + assert server_cfg.max_sandbox_timeout_seconds == 86400 + + def test_kubernetes_runtime_fills_missing_block(): server_cfg = ServerConfig() runtime_cfg = RuntimeConfig(type="kubernetes", execd_image="opensandbox/execd:latest") diff --git a/server/tests/test_docker_service.py b/server/tests/test_docker_service.py index b9e26878..a594060e 100644 --- a/server/tests/test_docker_service.py +++ b/server/tests/test_docker_service.py @@ -13,7 +13,7 @@ # limitations under the License. import os -from datetime import datetime, timezone +from datetime import datetime, timedelta, timezone from typing import Any, cast from unittest.mock import MagicMock, patch @@ -29,7 +29,11 @@ StorageConfig, IngressConfig, ) -from src.services.constants import SANDBOX_ID_LABEL, SandboxErrorCodes +from src.services.constants import ( + SANDBOX_ID_LABEL, + SANDBOX_MANUAL_CLEANUP_LABEL, + SandboxErrorCodes, +) from src.services.docker import DockerSandboxService, PendingSandbox from src.services.helpers import parse_memory_limit, parse_nano_cpus, parse_timestamp from src.api.schema import ( @@ -218,6 +222,33 @@ def test_create_sandbox_rejects_invalid_metadata(mock_docker): mock_client.containers.create.assert_not_called() +@patch("src.services.docker.docker") +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: + 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"] + + @patch("src.services.docker.docker") def test_create_sandbox_requires_entrypoint(mock_docker): mock_client = MagicMock() @@ -645,6 +676,110 @@ def test_restore_cleans_orphan_sidecar(): mock_cleanup.assert_called_once_with("orphan-id") +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 + + +@patch("src.services.docker.docker") +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 = 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() + + +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("src.services.docker.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() + + +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." + + @patch("src.services.docker.docker") def test_create_sandbox_async_returns_provisioning(mock_docker): mock_client = MagicMock() diff --git a/server/tests/test_routes.py b/server/tests/test_routes.py index 2b835993..73df4403 100644 --- a/server/tests/test_routes.py +++ b/server/tests/test_routes.py @@ -164,14 +164,14 @@ def test_get_sandbox_success( """ pass - def test_get_sandbox_excludes_null_fields( + def test_get_sandbox_preserves_nullable_expires_at( self, client: TestClient, auth_headers: dict, monkeypatch, ): """ - Ensure JSON response omits fields whose values are null. + Ensure expiresAt is returned as null for manual-cleanup sandboxes. """ now = datetime.now(timezone.utc) sandbox = Sandbox( @@ -180,7 +180,7 @@ def test_get_sandbox_excludes_null_fields( status=SandboxStatus(state="Running"), metadata=None, entrypoint=["python"], - expires_at=now, + expires_at=None, created_at=now, ) @@ -195,15 +195,16 @@ def get_sandbox(sandbox_id: str) -> Sandbox: assert response.status_code == 200 payload = response.json() - assert "metadata" not in payload + assert payload["metadata"] is None assert payload["id"] == "sandbox-123" assert payload["entrypoint"] == ["python"] assert "expiresAt" in payload + assert payload["expiresAt"] is None assert "createdAt" in payload assert payload["status"]["state"] == "Running" - assert "reason" not in payload["status"] - assert "message" not in payload["status"] - assert "lastTransitionAt" not in payload["status"] + assert payload["status"]["reason"] is None + assert payload["status"]["message"] is None + assert payload["status"]["lastTransitionAt"] is None def test_get_sandbox_not_found( self, diff --git a/server/tests/test_routes_create_delete.py b/server/tests/test_routes_create_delete.py index e5b8bcd3..a51a7a97 100644 --- a/server/tests/test_routes_create_delete.py +++ b/server/tests/test_routes_create_delete.py @@ -60,6 +60,44 @@ def create_sandbox(request) -> CreateSandboxResponse: assert calls[0].image.uri == "python:3.11" +def test_create_sandbox_manual_cleanup_returns_null_expiration( + client: TestClient, + auth_headers: dict, + sample_sandbox_request: dict, + monkeypatch, +) -> None: + now = datetime.now(timezone.utc) + + class StubService: + @staticmethod + def create_sandbox(request) -> CreateSandboxResponse: + return CreateSandboxResponse( + id="sbx-manual", + status=SandboxStatus(state="Pending"), + metadata=None, + expiresAt=None, + createdAt=now, + entrypoint=["python", "-c", "print('Hello from sandbox')"], + ) + + monkeypatch.setattr(lifecycle, "sandbox_service", StubService()) + sample_sandbox_request.pop("timeout", None) + + response = client.post( + "/v1/sandboxes", + headers=auth_headers, + json=sample_sandbox_request, + ) + + assert response.status_code == 202 + payload = response.json() + assert payload["expiresAt"] is None + assert payload["metadata"] is None + assert payload["status"]["reason"] is None + assert payload["status"]["message"] is None + assert payload["status"]["lastTransitionAt"] is None + + def test_create_sandbox_rejects_invalid_request( client: TestClient, auth_headers: dict, diff --git a/server/tests/test_routes_list_sandboxes.py b/server/tests/test_routes_list_sandboxes.py index 4d3b6a5e..046a4ea8 100644 --- a/server/tests/test_routes_list_sandboxes.py +++ b/server/tests/test_routes_list_sandboxes.py @@ -132,6 +132,50 @@ def list_sandboxes(request) -> ListSandboxesResponse: assert captured_requests[0].filter.metadata == {"team": "infra", "note": ""} +def test_list_sandboxes_preserves_only_nullable_expires_at( + client: TestClient, + auth_headers: dict, + monkeypatch, +) -> None: + now = datetime.now(timezone.utc) + + class StubService: + @staticmethod + def list_sandboxes(request) -> ListSandboxesResponse: + return ListSandboxesResponse( + items=[ + Sandbox( + id="sbx-manual", + image=ImageSpec(uri="python:3.11"), + status=SandboxStatus(state="Running"), + metadata=None, + entrypoint=["python"], + expiresAt=None, + createdAt=now, + ) + ], + pagination=PaginationInfo( + page=1, + pageSize=20, + totalItems=1, + totalPages=1, + hasNextPage=False, + ), + ) + + monkeypatch.setattr(lifecycle, "sandbox_service", StubService()) + + response = client.get("/v1/sandboxes", headers=auth_headers) + + assert response.status_code == 200 + item = response.json()["items"][0] + assert item["expiresAt"] is None + assert item["metadata"] is None + assert item["status"]["reason"] is None + assert item["status"]["message"] is None + assert item["status"]["lastTransitionAt"] is None + + def test_list_sandboxes_validates_page_bounds( client: TestClient, auth_headers: dict, diff --git a/server/tests/test_routes_renew_expiration.py b/server/tests/test_routes_renew_expiration.py index 4394c653..9105d4c6 100644 --- a/server/tests/test_routes_renew_expiration.py +++ b/server/tests/test_routes_renew_expiration.py @@ -93,6 +93,37 @@ def renew_expiration(sandbox_id: str, request) -> RenewSandboxExpirationResponse } +def test_renew_expiration_returns_409_for_manual_cleanup_sandbox( + client: TestClient, + auth_headers: dict, + monkeypatch, +) -> None: + class StubService: + @staticmethod + def renew_expiration(sandbox_id: str, request) -> RenewSandboxExpirationResponse: + raise HTTPException( + status_code=409, + detail={ + "code": "DOCKER::INVALID_EXPIRATION", + "message": f"Sandbox {sandbox_id} does not have automatic expiration enabled.", + }, + ) + + monkeypatch.setattr(lifecycle, "sandbox_service", StubService()) + + response = client.post( + "/v1/sandboxes/sbx-manual/renew-expiration", + headers=auth_headers, + json={"expiresAt": "2030-01-01T00:00:00Z"}, + ) + + assert response.status_code == 409 + assert response.json() == { + "code": "DOCKER::INVALID_EXPIRATION", + "message": "Sandbox sbx-manual does not have automatic expiration enabled.", + } + + def test_renew_expiration_requires_api_key(client: TestClient) -> None: response = client.post( "/v1/sandboxes/sbx-001/renew-expiration", diff --git a/server/tests/test_schema.py b/server/tests/test_schema.py index 1dc7d653..eaff5d58 100644 --- a/server/tests/test_schema.py +++ b/server/tests/test_schema.py @@ -244,6 +244,15 @@ def test_deserialization_pvc_volume(self): class TestCreateSandboxRequestWithVolumes: """Tests for CreateSandboxRequest with volumes field.""" + def test_request_without_timeout_uses_manual_cleanup(self): + """Request without timeout should be valid and represent manual cleanup mode.""" + request = CreateSandboxRequest( + image=ImageSpec(uri="python:3.11"), + resource_limits=ResourceLimits({"cpu": "500m", "memory": "512Mi"}), + entrypoint=["python", "-c", "print('hello')"], + ) + assert request.timeout is None + def test_request_without_volumes(self): """Request without volumes should be valid.""" request = CreateSandboxRequest( @@ -397,3 +406,24 @@ def test_deserialization_with_volumes(self): assert request.volumes[1].pvc.claim_name == "shared-models-pvc" assert request.volumes[1].mount_path == "/mnt/models" assert request.volumes[1].read_only is True + + def test_request_rejects_zero_timeout(self): + """Zero timeout should still be rejected.""" + with pytest.raises(ValidationError): + CreateSandboxRequest( + image=ImageSpec(uri="python:3.11"), + timeout=0, + resource_limits=ResourceLimits({"cpu": "500m"}), + entrypoint=["python", "-c", "print('hello')"], + ) + + def test_request_allows_timeout_above_previous_hardcoded_limit(self): + """Schema should not hardcode the server-side maximum timeout.""" + request = CreateSandboxRequest( + image=ImageSpec(uri="python:3.11"), + timeout=172800, + resource_limits=ResourceLimits({"cpu": "500m", "memory": "512Mi"}), + entrypoint=["python", "-c", "print('hello')"], + ) + + assert request.timeout == 172800 diff --git a/server/tests/test_validators.py b/server/tests/test_validators.py index 8a995d03..dd38b13c 100644 --- a/server/tests/test_validators.py +++ b/server/tests/test_validators.py @@ -19,6 +19,7 @@ from src.services.constants import SandboxErrorCodes from src.services.validators import ( ensure_metadata_labels, + ensure_timeout_within_limit, ensure_valid_host_path, ensure_valid_mount_path, ensure_valid_pvc_name, @@ -113,6 +114,22 @@ def test_ensure_metadata_labels_rejects_key_with_empty_prefix(): assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_METADATA_LABEL +def test_ensure_timeout_within_limit_allows_equal_boundary(): + ensure_timeout_within_limit(3600, 3600) + + +def test_ensure_timeout_within_limit_allows_disabled_upper_bound(): + ensure_timeout_within_limit(7200, None) + + +def test_ensure_timeout_within_limit_rejects_timeout_above_limit(): + with pytest.raises(HTTPException) as exc_info: + ensure_timeout_within_limit(3601, 3600) + + assert exc_info.value.status_code == 400 + assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER + + # ============================================================================ # Volume Name Validation Tests # ============================================================================ diff --git a/specs/sandbox-lifecycle.yml b/specs/sandbox-lifecycle.yml index cb9b4575..42b340e4 100644 --- a/specs/sandbox-lifecycle.yml +++ b/specs/sandbox-lifecycle.yml @@ -151,6 +151,15 @@ paths: egress: - action: deny target: "bad.example.com" + manual-cleanup: + summary: Manual cleanup without automatic expiration + value: + image: + uri: python:3.11 + resourceLimits: + cpu: "500m" + memory: "512Mi" + entrypoint: ["python", "/app/main.py"] responses: '202': description: | @@ -524,9 +533,11 @@ components: description: Custom metadata from creation request expiresAt: - type: string - format: date-time - description: Timestamp when sandbox will auto-terminate + oneOf: + - type: string + format: date-time + - type: 'null' + description: Timestamp when sandbox will auto-terminate. Null when manual cleanup is enabled. createdAt: type: string @@ -543,7 +554,6 @@ components: - id - status - createdAt - - expiresAt - entrypoint Sandbox: @@ -579,9 +589,11 @@ components: Always present in responses since entrypoint is required in creation requests. expiresAt: - type: string - format: date-time - description: Timestamp when sandbox will auto-terminate + oneOf: + - type: string + format: date-time + - type: 'null' + description: Timestamp when sandbox will auto-terminate. Null when manual cleanup is enabled. createdAt: type: string @@ -593,7 +605,6 @@ components: - status - createdAt - entrypoint - - expiresAt - image SandboxState: type: string @@ -678,7 +689,7 @@ components: additionalProperties: false CreateSandboxRequest: type: object - required: [image, timeout, resourceLimits, entrypoint] + required: [image, resourceLimits, entrypoint] description: | Request to create a new sandbox from a container image. @@ -689,12 +700,14 @@ components: description: Container image specification for the sandbox timeout: - type: integer - minimum: 60 - maximum: 86400 + oneOf: + - type: integer + minimum: 60 + - type: 'null' description: | Sandbox timeout in seconds. The sandbox will automatically terminate after this duration. - SDK clients should provide a default value (e.g., 3600 seconds / 1 hour). + The maximum is controlled by the server configuration (`server.max_sandbox_timeout_seconds`). + Omit or set null to disable automatic expiration and require explicit cleanup. resourceLimits: $ref: '#/components/schemas/ResourceLimits' @@ -965,4 +978,3 @@ components: pattern: "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" maxLength: 253 additionalProperties: false - diff --git a/tests/csharp/OpenSandbox.E2ETests/SandboxE2ETests.cs b/tests/csharp/OpenSandbox.E2ETests/SandboxE2ETests.cs index af4e4221..4b2f95a2 100644 --- a/tests/csharp/OpenSandbox.E2ETests/SandboxE2ETests.cs +++ b/tests/csharp/OpenSandbox.E2ETests/SandboxE2ETests.cs @@ -84,6 +84,32 @@ public async Task Sandbox_Lifecycle_Health_Endpoint_Metrics_Renew_Connect() } } + [Fact(Timeout = 2 * 60 * 1000)] + public async Task Sandbox_ManualCleanup_Returns_Null_ExpiresAt() + { + var sandbox = await Sandbox.CreateAsync(new SandboxCreateOptions + { + ConnectionConfig = _fixture.ConnectionConfig, + Image = _fixture.DefaultImage, + ManualCleanup = true, + ReadyTimeoutSeconds = _fixture.DefaultReadyTimeoutSeconds, + Metadata = new Dictionary { ["tag"] = "manual-csharp-e2e-test" } + }); + + try + { + var info = await sandbox.GetInfoAsync(); + Assert.Null(info.ExpiresAt); + Assert.NotNull(info.Metadata); + Assert.Equal("manual-csharp-e2e-test", info.Metadata!["tag"]); + } + finally + { + await sandbox.KillAsync(); + await sandbox.DisposeAsync(); + } + } + [Fact(Timeout = 2 * 60 * 1000)] public async Task Sandbox_Create_With_NetworkPolicy() { diff --git a/tests/java/src/test/java/com/alibaba/opensandbox/e2e/SandboxE2ETest.java b/tests/java/src/test/java/com/alibaba/opensandbox/e2e/SandboxE2ETest.java index b2af7c42..c02a02d5 100644 --- a/tests/java/src/test/java/com/alibaba/opensandbox/e2e/SandboxE2ETest.java +++ b/tests/java/src/test/java/com/alibaba/opensandbox/e2e/SandboxE2ETest.java @@ -218,6 +218,31 @@ void testSandboxLifecycleAndHealth() { } } + @Test + @Order(1) + @DisplayName("Sandbox manual cleanup returns null expiresAt") + @Timeout(value = 2, unit = TimeUnit.MINUTES) + void testSandboxManualCleanup() { + Sandbox manualSandbox = + Sandbox.builder() + .connectionConfig(sharedConnectionConfig) + .image(getSandboxImage()) + .timeout(null) + .readyTimeout(Duration.ofSeconds(60)) + .metadata(Map.of("tag", "manual-java-e2e-test")) + .build(); + + try { + SandboxInfo info = manualSandbox.getInfo(); + assertNull(info.getExpiresAt()); + assertNotNull(info.getMetadata()); + assertEquals("manual-java-e2e-test", info.getMetadata().get("tag")); + } finally { + manualSandbox.kill(); + manualSandbox.close(); + } + } + @Test @Order(2) @DisplayName("Sandbox create with networkPolicy") diff --git a/tests/javascript/tests/test_sandbox_e2e.test.ts b/tests/javascript/tests/test_sandbox_e2e.test.ts index d4cc1a2d..935e5586 100644 --- a/tests/javascript/tests/test_sandbox_e2e.test.ts +++ b/tests/javascript/tests/test_sandbox_e2e.test.ts @@ -113,6 +113,28 @@ test("01 sandbox lifecycle, health, endpoint, metrics, renew, connect", async () } }); +test("01b manual cleanup sandbox returns null expiresAt", async () => { + const connectionConfig = createConnectionConfig(); + const manualSandbox = await Sandbox.create({ + connectionConfig, + image: getSandboxImage(), + timeoutSeconds: null, + readyTimeoutSeconds: 60, + metadata: { tag: "manual-e2e-test" }, + entrypoint: ["tail", "-f", "/dev/null"], + healthCheckPollingInterval: 200, + }); + + try { + const info = await manualSandbox.getInfo(); + expect(info.expiresAt).toBeNull(); + expect(info.metadata?.tag).toBe("manual-e2e-test"); + } finally { + await manualSandbox.kill(); + await manualSandbox.close(); + } +}); + test.skip("01a sandbox create with networkPolicy", async () => { const connectionConfig = createConnectionConfig(); const networkPolicySandbox = await Sandbox.create({ diff --git a/tests/python/tests/test_sandbox_e2e.py b/tests/python/tests/test_sandbox_e2e.py index 3ecccca2..657da073 100644 --- a/tests/python/tests/test_sandbox_e2e.py +++ b/tests/python/tests/test_sandbox_e2e.py @@ -277,6 +277,25 @@ async def test_01_sandbox_lifecycle_and_health(self): finally: await sandbox2.close() + @pytest.mark.timeout(120) + @pytest.mark.order(1) + async def test_01b_manual_cleanup(self): + sandbox = await Sandbox.create( + image=SandboxImageSpec(get_sandbox_image()), + connection_config=TestSandboxE2E.connection_config, + timeout=None, + ready_timeout=timedelta(seconds=30), + metadata={"tag": "manual-e2e-test"}, + ) + try: + info = await sandbox.get_info() + assert info.expires_at is None + assert info.metadata is not None + assert info.metadata.get("tag") == "manual-e2e-test" + finally: + await sandbox.kill() + await sandbox.close() + logger.info("TEST 1 PASSED: Sandbox lifecycle and health test completed successfully") diff --git a/tests/python/tests/test_sandbox_e2e_sync.py b/tests/python/tests/test_sandbox_e2e_sync.py index 07eb3e22..96df6112 100644 --- a/tests/python/tests/test_sandbox_e2e_sync.py +++ b/tests/python/tests/test_sandbox_e2e_sync.py @@ -243,6 +243,25 @@ def test_01_sandbox_lifecycle_and_health(self) -> None: finally: sandbox2.close() + @pytest.mark.timeout(120) + @pytest.mark.order(1) + def test_01b_manual_cleanup(self) -> None: + sandbox = SandboxSync.create( + image=SandboxImageSpec(get_sandbox_image()), + connection_config=TestSandboxE2ESync.connection_config, + timeout=None, + ready_timeout=timedelta(seconds=30), + metadata={"tag": "manual-e2e-test"}, + ) + try: + info = sandbox.get_info() + assert info.expires_at is None + assert info.metadata is not None + assert info.metadata.get("tag") == "manual-e2e-test" + finally: + sandbox.kill() + sandbox.close() + @pytest.mark.timeout(120) @pytest.mark.order(1) def test_01a_network_policy_create(self) -> None: From 093b104d52cc5d5e216a882d6cc69f1cef0966b7 Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 11:13:27 +0800 Subject: [PATCH 02/15] fix(python-sdk): handle nullable lifecycle fields --- .../adapters/converter/sandbox_model_converter.py | 6 +++++- .../src/opensandbox/api/lifecycle/models/image_spec.py | 2 +- sdks/sandbox/python/tests/test_models_stability.py | 8 ++++++++ 3 files changed, 14 insertions(+), 2 deletions(-) diff --git a/sdks/sandbox/python/src/opensandbox/adapters/converter/sandbox_model_converter.py b/sdks/sandbox/python/src/opensandbox/adapters/converter/sandbox_model_converter.py index 57eac4f3..0f6a8c96 100644 --- a/sdks/sandbox/python/src/opensandbox/adapters/converter/sandbox_model_converter.py +++ b/sdks/sandbox/python/src/opensandbox/adapters/converter/sandbox_model_converter.py @@ -308,12 +308,16 @@ def to_sandbox_info(api_sandbox: Sandbox) -> SandboxInfo: elif isinstance(metadata_obj, dict): metadata = metadata_obj + expires_at = api_sandbox.expires_at + if isinstance(expires_at, Unset): + expires_at = None + return SandboxInfo( id=api_sandbox.id, status=SandboxModelConverter._convert_sandbox_status(api_sandbox.status), image=domain_image_spec, created_at=api_sandbox.created_at, - expires_at=api_sandbox.expires_at, + expires_at=expires_at, entrypoint=api_sandbox.entrypoint, metadata=metadata, ) diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/image_spec.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/image_spec.py index 3b7cbfe2..c574bfd5 100644 --- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/image_spec.py +++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/image_spec.py @@ -78,7 +78,7 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: _auth = d.pop("auth", UNSET) auth: ImageSpecAuth | Unset - if isinstance(_auth, Unset): + if isinstance(_auth, Unset) or _auth is None: auth = UNSET else: auth = ImageSpecAuth.from_dict(_auth) diff --git a/sdks/sandbox/python/tests/test_models_stability.py b/sdks/sandbox/python/tests/test_models_stability.py index 3c106e55..9cd410fa 100644 --- a/sdks/sandbox/python/tests/test_models_stability.py +++ b/sdks/sandbox/python/tests/test_models_stability.py @@ -19,6 +19,8 @@ import pytest +from opensandbox.api.lifecycle.models.image_spec import ImageSpec as ApiImageSpec +from opensandbox.api.lifecycle.types import UNSET from opensandbox.models.filesystem import MoveEntry, WriteEntry from opensandbox.models.sandboxes import ( PVC, @@ -42,6 +44,12 @@ def test_sandbox_image_spec_rejects_blank_image() -> None: SandboxImageSpec(" ") +def test_api_image_spec_tolerates_null_auth() -> None: + spec = ApiImageSpec.from_dict({"uri": "python:3.11", "auth": None}) + assert spec.uri == "python:3.11" + assert spec.auth is UNSET + + def test_sandbox_image_auth_rejects_blank_username_and_password() -> None: with pytest.raises(ValueError): SandboxImageAuth(username=" ", password="x") From 781ae516386ea54ea28a380af44af410ffe364bb Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 11:16:41 +0800 Subject: [PATCH 03/15] fix(python-sdk): regenerate nullable lifecycle models --- sdks/sandbox/python/scripts/generate_api.py | 17 ++++++++ .../models/create_sandbox_request.py | 26 +++++++++--- .../models/create_sandbox_response.py | 40 ++++++++++++++----- .../opensandbox/api/lifecycle/models/pvc.py | 15 ++++--- .../api/lifecycle/models/sandbox.py | 40 ++++++++++++++----- .../api/lifecycle/models/volume.py | 10 +++-- 6 files changed, 116 insertions(+), 32 deletions(-) diff --git a/sdks/sandbox/python/scripts/generate_api.py b/sdks/sandbox/python/scripts/generate_api.py index c11c2859..3a745610 100644 --- a/sdks/sandbox/python/scripts/generate_api.py +++ b/sdks/sandbox/python/scripts/generate_api.py @@ -195,6 +195,22 @@ def add_license_headers(root: Path) -> None: ) +def patch_lifecycle_nullable_nested_models(root: Path) -> None: + """Patch generated lifecycle models that openapi-python-client does not null-handle.""" + image_spec_file = root / "models" / "image_spec.py" + if not image_spec_file.exists(): + return + + content = image_spec_file.read_text(encoding="utf-8") + old = " if isinstance(_auth, Unset):\n auth = UNSET\n" + new = " if isinstance(_auth, Unset) or _auth is None:\n auth = UNSET\n" + if old not in content: + return + + image_spec_file.write_text(content.replace(old, new, 1), encoding="utf-8") + print(f"✅ Patched nullable nested auth handling in {image_spec_file}") + + def post_process_generated_code() -> None: """Post-process the generated code to ensure proper package structure.""" print("\n🔧 Post-processing generated code...") @@ -213,6 +229,7 @@ def post_process_generated_code() -> None: add_license_headers(Path("src/opensandbox/api/execd")) add_license_headers(Path("src/opensandbox/api/lifecycle")) add_license_headers(Path("src/opensandbox/api")) + patch_lifecycle_nullable_nested_models(Path("src/opensandbox/api/lifecycle")) def main() -> None: diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_request.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_request.py index aa48d71d..02b316bb 100644 --- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_request.py +++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_request.py @@ -47,7 +47,6 @@ class CreateSandboxRequest: image (ImageSpec): Container image specification for sandbox provisioning. Supports public registry images and private registry images with authentication. - timeout (int | None | Unset): Sandbox timeout in seconds. Omit or set null to require explicit cleanup. resource_limits (ResourceLimits): Runtime resource constraints as key-value pairs. Similar to Kubernetes resource specifications, allows flexible definition of resource limits. Common resource types include: @@ -70,6 +69,10 @@ class CreateSandboxRequest: - ["java", "-jar", "/app/app.jar"] - ["node", "server.js"] Example: ['python', '/app/main.py']. + timeout (int | None | Unset): Sandbox timeout in seconds. The sandbox will automatically terminate after this + duration. + The maximum is controlled by the server configuration (`server.max_sandbox_timeout_seconds`). + Omit or set null to disable automatic expiration and require explicit cleanup. env (CreateSandboxRequestEnv | Unset): Environment variables to inject into the sandbox runtime. Example: {'API_KEY': 'secret-key', 'DEBUG': 'true', 'LOG_LEVEL': 'info'}. metadata (CreateSandboxRequestMetadata | Unset): Custom key-value metadata for management, filtering, and @@ -109,12 +112,16 @@ class CreateSandboxRequest: def to_dict(self) -> dict[str, Any]: image = self.image.to_dict() - timeout = self.timeout - resource_limits = self.resource_limits.to_dict() entrypoint = self.entrypoint + timeout: int | None | Unset + if isinstance(self.timeout, Unset): + timeout = UNSET + else: + timeout = self.timeout + env: dict[str, Any] | Unset = UNSET if not isinstance(self.env, Unset): env = self.env.to_dict() @@ -175,12 +182,19 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: d = dict(src_dict) image = ImageSpec.from_dict(d.pop("image")) - timeout = d.pop("timeout", UNSET) - resource_limits = ResourceLimits.from_dict(d.pop("resourceLimits")) entrypoint = cast(list[str], d.pop("entrypoint")) + def _parse_timeout(data: object) -> int | None | Unset: + if data is None: + return data + if isinstance(data, Unset): + return data + return cast(int | None | Unset, data) + + timeout = _parse_timeout(d.pop("timeout", UNSET)) + _env = d.pop("env", UNSET) env: CreateSandboxRequestEnv | Unset if isinstance(_env, Unset): @@ -220,9 +234,9 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: create_sandbox_request = cls( image=image, - timeout=timeout, resource_limits=resource_limits, entrypoint=entrypoint, + timeout=timeout, env=env, metadata=metadata, network_policy=network_policy, diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_response.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_response.py index 78167409..4a5f4e76 100644 --- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_response.py +++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_response.py @@ -41,18 +41,19 @@ class CreateSandboxResponse: Attributes: id (str): Unique sandbox identifier status (SandboxStatus): Detailed status information with lifecycle state and transition details - expires_at (datetime.datetime | None): Timestamp when sandbox will auto-terminate. Null when manual cleanup is enabled. created_at (datetime.datetime): Sandbox creation timestamp entrypoint (list[str]): Entry process specification from creation request metadata (CreateSandboxResponseMetadata | Unset): Custom metadata from creation request + expires_at (datetime.datetime | None | Unset): Timestamp when sandbox will auto-terminate. Null when manual + cleanup is enabled. """ id: str status: SandboxStatus - expires_at: datetime.datetime | None created_at: datetime.datetime entrypoint: list[str] metadata: CreateSandboxResponseMetadata | Unset = UNSET + expires_at: datetime.datetime | None | Unset = UNSET additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict) def to_dict(self) -> dict[str, Any]: @@ -60,8 +61,6 @@ def to_dict(self) -> dict[str, Any]: status = self.status.to_dict() - expires_at = self.expires_at.isoformat() if self.expires_at is not None else None - created_at = self.created_at.isoformat() entrypoint = self.entrypoint @@ -70,19 +69,28 @@ def to_dict(self) -> dict[str, Any]: if not isinstance(self.metadata, Unset): metadata = self.metadata.to_dict() + expires_at: None | str | Unset + if isinstance(self.expires_at, Unset): + expires_at = UNSET + elif isinstance(self.expires_at, datetime.datetime): + expires_at = self.expires_at.isoformat() + else: + expires_at = self.expires_at + field_dict: dict[str, Any] = {} field_dict.update(self.additional_properties) field_dict.update( { "id": id, "status": status, - "expiresAt": expires_at, "createdAt": created_at, "entrypoint": entrypoint, } ) if metadata is not UNSET: field_dict["metadata"] = metadata + if expires_at is not UNSET: + field_dict["expiresAt"] = expires_at return field_dict @@ -96,9 +104,6 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: status = SandboxStatus.from_dict(d.pop("status")) - _expires_at = d.pop("expiresAt") - expires_at = isoparse(_expires_at) if _expires_at is not None else None - created_at = isoparse(d.pop("createdAt")) entrypoint = cast(list[str], d.pop("entrypoint")) @@ -110,13 +115,30 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: else: metadata = CreateSandboxResponseMetadata.from_dict(_metadata) + def _parse_expires_at(data: object) -> datetime.datetime | None | Unset: + if data is None: + return data + if isinstance(data, Unset): + return data + try: + if not isinstance(data, str): + raise TypeError() + expires_at_type_0 = isoparse(data) + + return expires_at_type_0 + except (TypeError, ValueError, AttributeError, KeyError): + pass + return cast(datetime.datetime | None | Unset, data) + + expires_at = _parse_expires_at(d.pop("expiresAt", UNSET)) + create_sandbox_response = cls( id=id, status=status, - expires_at=expires_at, created_at=created_at, entrypoint=entrypoint, metadata=metadata, + expires_at=expires_at, ) create_sandbox_response.additional_properties = d diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/pvc.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/pvc.py index 43e2f077..dd73cc93 100644 --- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/pvc.py +++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/pvc.py @@ -26,14 +26,19 @@ @_attrs_define class PVC: - """Kubernetes PersistentVolumeClaim mount backend. References an existing - PVC in the same namespace as the sandbox pod. + """Platform-managed named volume backend. A runtime-neutral abstraction + for referencing a pre-existing, platform-managed named volume. - Only available in Kubernetes runtime. + - Kubernetes: maps to a PersistentVolumeClaim in the same namespace. + - Docker: maps to a Docker named volume (created via `docker volume create`). + + The volume must already exist on the target platform before sandbox + creation. Attributes: - claim_name (str): Name of the PersistentVolumeClaim in the same namespace. - Must be a valid Kubernetes resource name. + claim_name (str): Name of the volume on the target platform. + In Kubernetes this is the PVC name; in Docker this is the named + volume name. Must be a valid DNS label. """ claim_name: str diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox.py index 8d22ef9f..0d6cfff3 100644 --- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox.py +++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox.py @@ -47,18 +47,19 @@ class Sandbox: status (SandboxStatus): Detailed status information with lifecycle state and transition details entrypoint (list[str]): The command to execute as the sandbox's entry process. Always present in responses since entrypoint is required in creation requests. - expires_at (datetime.datetime | None): Timestamp when sandbox will auto-terminate. Null when manual cleanup is enabled. created_at (datetime.datetime): Sandbox creation timestamp metadata (SandboxMetadata | Unset): Custom metadata from creation request + expires_at (datetime.datetime | None | Unset): Timestamp when sandbox will auto-terminate. Null when manual + cleanup is enabled. """ id: str image: ImageSpec status: SandboxStatus entrypoint: list[str] - expires_at: datetime.datetime | None created_at: datetime.datetime metadata: SandboxMetadata | Unset = UNSET + expires_at: datetime.datetime | None | Unset = UNSET additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict) def to_dict(self) -> dict[str, Any]: @@ -70,14 +71,20 @@ def to_dict(self) -> dict[str, Any]: entrypoint = self.entrypoint - expires_at = self.expires_at.isoformat() if self.expires_at is not None else None - created_at = self.created_at.isoformat() metadata: dict[str, Any] | Unset = UNSET if not isinstance(self.metadata, Unset): metadata = self.metadata.to_dict() + expires_at: None | str | Unset + if isinstance(self.expires_at, Unset): + expires_at = UNSET + elif isinstance(self.expires_at, datetime.datetime): + expires_at = self.expires_at.isoformat() + else: + expires_at = self.expires_at + field_dict: dict[str, Any] = {} field_dict.update(self.additional_properties) field_dict.update( @@ -86,12 +93,13 @@ def to_dict(self) -> dict[str, Any]: "image": image, "status": status, "entrypoint": entrypoint, - "expiresAt": expires_at, "createdAt": created_at, } ) if metadata is not UNSET: field_dict["metadata"] = metadata + if expires_at is not UNSET: + field_dict["expiresAt"] = expires_at return field_dict @@ -110,9 +118,6 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: entrypoint = cast(list[str], d.pop("entrypoint")) - _expires_at = d.pop("expiresAt") - expires_at = isoparse(_expires_at) if _expires_at is not None else None - created_at = isoparse(d.pop("createdAt")) _metadata = d.pop("metadata", UNSET) @@ -122,14 +127,31 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: else: metadata = SandboxMetadata.from_dict(_metadata) + def _parse_expires_at(data: object) -> datetime.datetime | None | Unset: + if data is None: + return data + if isinstance(data, Unset): + return data + try: + if not isinstance(data, str): + raise TypeError() + expires_at_type_0 = isoparse(data) + + return expires_at_type_0 + except (TypeError, ValueError, AttributeError, KeyError): + pass + return cast(datetime.datetime | None | Unset, data) + + expires_at = _parse_expires_at(d.pop("expiresAt", UNSET)) + sandbox = cls( id=id, image=image, status=status, entrypoint=entrypoint, - expires_at=expires_at, created_at=created_at, metadata=metadata, + expires_at=expires_at, ) sandbox.additional_properties = d diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/volume.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/volume.py index 5dfc4f83..88d91817 100644 --- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/volume.py +++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/volume.py @@ -48,10 +48,14 @@ class Volume: Security note: Host paths are restricted by server-side allowlist. Users must specify paths under permitted prefixes. - pvc (PVC | Unset): Kubernetes PersistentVolumeClaim mount backend. References an existing - PVC in the same namespace as the sandbox pod. + pvc (PVC | Unset): Platform-managed named volume backend. A runtime-neutral abstraction + for referencing a pre-existing, platform-managed named volume. - Only available in Kubernetes runtime. + - Kubernetes: maps to a PersistentVolumeClaim in the same namespace. + - Docker: maps to a Docker named volume (created via `docker volume create`). + + The volume must already exist on the target platform before sandbox + creation. read_only (bool | Unset): If true, the volume is mounted as read-only. Defaults to false (read-write). Default: False. sub_path (str | Unset): Optional subdirectory under the backend path to mount. From de5859f27f4452698fcb103e54f934f6b4ee8614 Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 11:46:40 +0800 Subject: [PATCH 04/15] fix(python-sdk): accept null lifecycle metadata --- sdks/sandbox/python/scripts/generate_api.py | 52 +++++++++++++++---- .../models/create_sandbox_response.py | 2 +- .../api/lifecycle/models/sandbox.py | 2 +- .../api/lifecycle/models/sandbox_status.py | 2 +- .../python/tests/test_models_stability.py | 37 +++++++++++++ 5 files changed, 82 insertions(+), 13 deletions(-) diff --git a/sdks/sandbox/python/scripts/generate_api.py b/sdks/sandbox/python/scripts/generate_api.py index 3a745610..64e9a4ff 100644 --- a/sdks/sandbox/python/scripts/generate_api.py +++ b/sdks/sandbox/python/scripts/generate_api.py @@ -197,18 +197,50 @@ def add_license_headers(root: Path) -> None: def patch_lifecycle_nullable_nested_models(root: Path) -> None: """Patch generated lifecycle models that openapi-python-client does not null-handle.""" - image_spec_file = root / "models" / "image_spec.py" - if not image_spec_file.exists(): - return + replacements = { + root / "models" / "image_spec.py": [ + ( + " if isinstance(_auth, Unset):\n auth = UNSET\n", + " if isinstance(_auth, Unset) or _auth is None:\n auth = UNSET\n", + ) + ], + root / "models" / "create_sandbox_response.py": [ + ( + " if isinstance(_metadata, Unset):\n metadata = UNSET\n", + " if isinstance(_metadata, Unset) or _metadata is None:\n metadata = UNSET\n", + ) + ], + root / "models" / "sandbox.py": [ + ( + " if isinstance(_metadata, Unset):\n metadata = UNSET\n", + " if isinstance(_metadata, Unset) or _metadata is None:\n metadata = UNSET\n", + ) + ], + root / "models" / "sandbox_status.py": [ + ( + " if isinstance(_last_transition_at, Unset):\n last_transition_at = UNSET\n", + " if isinstance(_last_transition_at, Unset) or _last_transition_at is None:\n last_transition_at = UNSET\n", + ) + ], + } - content = image_spec_file.read_text(encoding="utf-8") - old = " if isinstance(_auth, Unset):\n auth = UNSET\n" - new = " if isinstance(_auth, Unset) or _auth is None:\n auth = UNSET\n" - if old not in content: - return + patched_files = 0 + for file_path, file_replacements in replacements.items(): + if not file_path.exists(): + continue + + content = file_path.read_text(encoding="utf-8") + updated = content + for old, new in file_replacements: + if old in updated: + updated = updated.replace(old, new, 1) + + if updated != content: + file_path.write_text(updated, encoding="utf-8") + patched_files += 1 - image_spec_file.write_text(content.replace(old, new, 1), encoding="utf-8") - print(f"✅ Patched nullable nested auth handling in {image_spec_file}") + if patched_files: + print(f"✅ Patched nullable lifecycle model handling in {patched_files} files") def post_process_generated_code() -> None: diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_response.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_response.py index 4a5f4e76..a254b4cd 100644 --- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_response.py +++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_sandbox_response.py @@ -110,7 +110,7 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: _metadata = d.pop("metadata", UNSET) metadata: CreateSandboxResponseMetadata | Unset - if isinstance(_metadata, Unset): + if isinstance(_metadata, Unset) or _metadata is None: metadata = UNSET else: metadata = CreateSandboxResponseMetadata.from_dict(_metadata) diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox.py index 0d6cfff3..f355a672 100644 --- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox.py +++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox.py @@ -122,7 +122,7 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: _metadata = d.pop("metadata", UNSET) metadata: SandboxMetadata | Unset - if isinstance(_metadata, Unset): + if isinstance(_metadata, Unset) or _metadata is None: metadata = UNSET else: metadata = SandboxMetadata.from_dict(_metadata) diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox_status.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox_status.py index f3fc6c65..5338e3cd 100644 --- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox_status.py +++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/sandbox_status.py @@ -106,7 +106,7 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: _last_transition_at = d.pop("lastTransitionAt", UNSET) last_transition_at: datetime.datetime | Unset - if isinstance(_last_transition_at, Unset): + if isinstance(_last_transition_at, Unset) or _last_transition_at is None: last_transition_at = UNSET else: last_transition_at = isoparse(_last_transition_at) diff --git a/sdks/sandbox/python/tests/test_models_stability.py b/sdks/sandbox/python/tests/test_models_stability.py index 9cd410fa..6fbe4eab 100644 --- a/sdks/sandbox/python/tests/test_models_stability.py +++ b/sdks/sandbox/python/tests/test_models_stability.py @@ -20,6 +20,10 @@ import pytest from opensandbox.api.lifecycle.models.image_spec import ImageSpec as ApiImageSpec +from opensandbox.api.lifecycle.models.create_sandbox_response import ( + CreateSandboxResponse as ApiCreateSandboxResponse, +) +from opensandbox.api.lifecycle.models.sandbox import Sandbox as ApiSandbox from opensandbox.api.lifecycle.types import UNSET from opensandbox.models.filesystem import MoveEntry, WriteEntry from opensandbox.models.sandboxes import ( @@ -50,6 +54,39 @@ def test_api_image_spec_tolerates_null_auth() -> None: assert spec.auth is UNSET +def test_api_create_sandbox_response_tolerates_null_metadata() -> None: + response = ApiCreateSandboxResponse.from_dict( + { + "id": "sandbox-1", + "status": {"state": "Running", "lastTransitionAt": None}, + "createdAt": "2025-01-01T00:00:00Z", + "entrypoint": ["/bin/sh"], + "metadata": None, + "expiresAt": None, + } + ) + assert response.metadata is UNSET + assert response.expires_at is None + assert response.status.last_transition_at is UNSET + + +def test_api_sandbox_tolerates_null_metadata() -> None: + sandbox = ApiSandbox.from_dict( + { + "id": "sandbox-1", + "image": {"uri": "python:3.11", "auth": None}, + "status": {"state": "Running", "lastTransitionAt": None}, + "entrypoint": ["/bin/sh"], + "createdAt": "2025-01-01T00:00:00Z", + "metadata": None, + "expiresAt": None, + } + ) + assert sandbox.metadata is UNSET + assert sandbox.expires_at is None + assert sandbox.status.last_transition_at is UNSET + + def test_sandbox_image_auth_rejects_blank_username_and_password() -> None: with pytest.raises(ValueError): SandboxImageAuth(username=" ", password="x") From 94fa113055aa651695d06d9668e26a8f1d75bb6b Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 11:48:15 +0800 Subject: [PATCH 05/15] style(python-sdk): sort nullable model test imports --- sdks/sandbox/python/tests/test_models_stability.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdks/sandbox/python/tests/test_models_stability.py b/sdks/sandbox/python/tests/test_models_stability.py index 6fbe4eab..82f64986 100644 --- a/sdks/sandbox/python/tests/test_models_stability.py +++ b/sdks/sandbox/python/tests/test_models_stability.py @@ -19,10 +19,10 @@ import pytest -from opensandbox.api.lifecycle.models.image_spec import ImageSpec as ApiImageSpec from opensandbox.api.lifecycle.models.create_sandbox_response import ( CreateSandboxResponse as ApiCreateSandboxResponse, ) +from opensandbox.api.lifecycle.models.image_spec import ImageSpec as ApiImageSpec from opensandbox.api.lifecycle.models.sandbox import Sandbox as ApiSandbox from opensandbox.api.lifecycle.types import UNSET from opensandbox.models.filesystem import MoveEntry, WriteEntry From 18ffcd46b9fba06551e2d929746eceed42a5902e Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 13:57:32 +0800 Subject: [PATCH 06/15] test(e2e): harden code interpreter retries --- .../CodeInterpreterE2ETests.cs | 58 +++++++++++++++- .../python/tests/test_code_interpreter_e2e.py | 68 ++++++++++++++++++- 2 files changed, 123 insertions(+), 3 deletions(-) diff --git a/tests/csharp/OpenSandbox.E2ETests/CodeInterpreterE2ETests.cs b/tests/csharp/OpenSandbox.E2ETests/CodeInterpreterE2ETests.cs index e34f4e26..62cb66c7 100644 --- a/tests/csharp/OpenSandbox.E2ETests/CodeInterpreterE2ETests.cs +++ b/tests/csharp/OpenSandbox.E2ETests/CodeInterpreterE2ETests.cs @@ -45,7 +45,7 @@ public async Task CreateInterpreter_ExposesSandboxServices() var metrics = await interpreter.Metrics.GetMetricsAsync(); Assert.True(metrics.CpuCount > 0); - var cmd = await interpreter.Commands.RunAsync("echo code-interpreter-ready"); + var cmd = await RunCommandWithRetryAsync(interpreter, "echo code-interpreter-ready"); Assert.Null(cmd.Error); Assert.Contains(cmd.Logs.Stdout, m => m.Text.Contains("code-interpreter-ready", StringComparison.Ordinal)); } @@ -506,6 +506,62 @@ private static async Task> RunStreamCollectWithRetryAsyn throw lastError ?? new TimeoutException("RunStreamCollectWithRetryAsync failed unexpectedly."); } + private static async Task RunCommandWithRetryAsync( + CodeInterpreterClient interpreter, + string command, + int maxRetries = 3, + int perCallTimeoutSeconds = 30) + { + Exception? lastError = null; + Execution? lastResult = null; + var delayMs = 1000; + + for (var attempt = 1; attempt <= maxRetries; attempt++) + { + try + { + var result = await interpreter.Commands + .RunAsync(command) + .WaitAsync(TimeSpan.FromSeconds(perCallTimeoutSeconds)); + + lastResult = result; + var hasExpectedStdout = result.Logs.Stdout.Any(log => + log.Text.Contains("code-interpreter-ready", StringComparison.Ordinal)); + if (result.Error == null && hasExpectedStdout) + { + return result; + } + + if (attempt < maxRetries) + { + await Task.Delay(delayMs); + delayMs = (int)(delayMs * 1.5); + continue; + } + + return result; + } + catch (Exception ex) when (IsRetryable(ex) && attempt < maxRetries) + { + lastError = ex; + await Task.Delay(delayMs); + delayMs = (int)(delayMs * 1.5); + } + catch (Exception ex) + { + lastError = ex; + break; + } + } + + if (lastResult != null) + { + return lastResult; + } + + throw lastError ?? new TimeoutException("RunCommandWithRetryAsync failed unexpectedly."); + } + private static bool IsRetryable(Exception ex) { if (ex is TimeoutException || ex is TaskCanceledException) diff --git a/tests/python/tests/test_code_interpreter_e2e.py b/tests/python/tests/test_code_interpreter_e2e.py index 852d47f3..67e73598 100644 --- a/tests/python/tests/test_code_interpreter_e2e.py +++ b/tests/python/tests/test_code_interpreter_e2e.py @@ -107,6 +107,62 @@ def _assert_terminal_event_contract( _assert_recent_timestamp_ms(errors[0].timestamp) +def _buffer_attempt_handlers( + handlers: ExecutionHandlers, +) -> tuple[ExecutionHandlers, Callable[[], Awaitable[None]]]: + buffered_events: list[tuple[str, object]] = [] + + async def on_stdout(msg: OutputMessage) -> None: + buffered_events.append(("stdout", msg)) + + async def on_stderr(msg: OutputMessage) -> None: + buffered_events.append(("stderr", msg)) + + async def on_result(result: ExecutionResult) -> None: + buffered_events.append(("result", result)) + + async def on_complete(complete: ExecutionComplete) -> None: + buffered_events.append(("complete", complete)) + + async def on_error(error: ExecutionError) -> None: + buffered_events.append(("error", error)) + + async def on_init(init: ExecutionInit) -> None: + buffered_events.append(("init", init)) + + async def flush() -> None: + for event_type, payload in buffered_events: + if event_type == "stdout" and handlers.on_stdout is not None: + await handlers.on_stdout(payload) + elif event_type == "stderr" and handlers.on_stderr is not None: + await handlers.on_stderr(payload) + elif event_type == "result" and handlers.on_result is not None: + await handlers.on_result(payload) + elif ( + event_type == "complete" + and handlers.on_execution_complete is not None + ): + await handlers.on_execution_complete(payload) + elif event_type == "error" and handlers.on_error is not None: + await handlers.on_error(payload) + elif event_type == "init" and handlers.on_init is not None: + await handlers.on_init(payload) + + return ( + ExecutionHandlers( + on_stdout=on_stdout if handlers.on_stdout is not None else None, + on_stderr=on_stderr if handlers.on_stderr is not None else None, + on_result=on_result if handlers.on_result is not None else None, + on_execution_complete=( + on_complete if handlers.on_execution_complete is not None else None + ), + on_error=on_error if handlers.on_error is not None else None, + on_init=on_init if handlers.on_init is not None else None, + ), + flush, + ) + + async def run_with_retry( code_interpreter: CodeInterpreter, code: str, @@ -131,17 +187,26 @@ async def run_with_retry( for attempt in range(max_retries): try: + attempt_handlers = handlers + flush_attempt_events: Callable[[], Awaitable[None]] | None = None + if handlers is not None: + attempt_handlers, flush_attempt_events = _buffer_attempt_handlers( + handlers + ) + result = await asyncio.wait_for( code_interpreter.codes.run( code, context=context, language=language, - handlers=handlers, + handlers=attempt_handlers, ), timeout=per_call_timeout, ) last_result = result if result is not None and result.id is not None: + if flush_attempt_events is not None: + await flush_attempt_events() return result # Empty result - retry if attempt < max_retries - 1: @@ -1224,4 +1289,3 @@ async def test_09_context_management_endpoints(self): ] assert len(final_contexts) == 0 logger.info("✓ delete_contexts removed all bash contexts") - From da444e9fb27e3e44b12ae5c63baa82326c9d1171 Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 14:00:53 +0800 Subject: [PATCH 07/15] fix(python-e2e): import retry handler typing --- tests/python/tests/test_code_interpreter_e2e.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tests/python/tests/test_code_interpreter_e2e.py b/tests/python/tests/test_code_interpreter_e2e.py index 67e73598..7657bdea 100644 --- a/tests/python/tests/test_code_interpreter_e2e.py +++ b/tests/python/tests/test_code_interpreter_e2e.py @@ -32,6 +32,7 @@ import time from contextlib import AsyncExitStack, asynccontextmanager from datetime import timedelta +from typing import Callable import pytest from code_interpreter import CodeInterpreter From 9f29d6522f828a2067dceffe23111575f092d8d4 Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 14:02:59 +0800 Subject: [PATCH 08/15] fix(python-e2e): import buffered retry typing --- tests/python/tests/test_code_interpreter_e2e.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/python/tests/test_code_interpreter_e2e.py b/tests/python/tests/test_code_interpreter_e2e.py index 7657bdea..edc6c22d 100644 --- a/tests/python/tests/test_code_interpreter_e2e.py +++ b/tests/python/tests/test_code_interpreter_e2e.py @@ -32,7 +32,7 @@ import time from contextlib import AsyncExitStack, asynccontextmanager from datetime import timedelta -from typing import Callable +from typing import Awaitable, Callable import pytest from code_interpreter import CodeInterpreter From c6d39dc5d2230e5500d871130ce53c6dceaae119 Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 14:18:21 +0800 Subject: [PATCH 09/15] test(python-e2e): relax interrupt terminal event expectation --- .../python/tests/test_code_interpreter_e2e.py | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/tests/python/tests/test_code_interpreter_e2e.py b/tests/python/tests/test_code_interpreter_e2e.py index edc6c22d..fc2585ce 100644 --- a/tests/python/tests/test_code_interpreter_e2e.py +++ b/tests/python/tests/test_code_interpreter_e2e.py @@ -1197,9 +1197,6 @@ async def on_error(error: ExecutionError): result_int = await asyncio.wait_for(execution_task, timeout=60.0) except (asyncio.TimeoutError, Exception) as exc: execution_task.cancel() - # If the execution timed out or raised a network error after - # interrupt, the interrupt itself was effective — verify via - # the events collected by the handlers. logger.warning( "Execution task did not return cleanly after interrupt: %s", exc ) @@ -1208,11 +1205,6 @@ async def on_error(error: ExecutionError): if result_int is not None: assert result_int.id is not None assert result_int.id == execution_id - # At least one terminal event (complete or error) should have arrived. - assert (len(completed_events) > 0) or (len(errors) > 0), ( - "expected at least one of complete/error after interrupt" - ) - logger.info("✓ Python execution was interrupted successfully") quick_result = None try: @@ -1231,6 +1223,16 @@ async def on_error(error: ExecutionError): except (asyncio.TimeoutError, Exception) as exc: logger.warning("Quick execution after interrupt failed: %s", exc) + # Different backends may close the interrupted SSE stream without + # emitting an explicit terminal event. Accept either a terminal + # event or proof that the context became usable again. + assert ( + len(completed_events) > 0 + or len(errors) > 0 + or quick_result is not None + ), "expected terminal event or successful follow-up execution after interrupt" + logger.info("✓ Python execution was interrupted successfully") + # Interrupting a completed execution may or may not throw depending on backend behavior. try: if quick_result is not None: From efcb23bbce4b085c9597ca7e7ac3c9a78065098f Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 14:39:08 +0800 Subject: [PATCH 10/15] test(js-e2e): harden read-only volume assertions --- tests/javascript/tests/test_sandbox_e2e.test.ts | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/tests/javascript/tests/test_sandbox_e2e.test.ts b/tests/javascript/tests/test_sandbox_e2e.test.ts index 935e5586..eb91d088 100644 --- a/tests/javascript/tests/test_sandbox_e2e.test.ts +++ b/tests/javascript/tests/test_sandbox_e2e.test.ts @@ -262,7 +262,13 @@ test("01c sandbox create with host volume mount (read-only)", async () => { const writeResult = await roSandbox.commands.run( `touch ${containerMountPath}/should-fail.txt` ); - expect(writeResult.error).toBeTruthy(); + const statResult = await roSandbox.commands.run( + `test ! -e ${containerMountPath}/should-fail.txt && echo OK` + ); + const writeWasRejected = + writeResult.error != null || writeResult.logs.stderr.length > 0; + const fileWasNotCreated = statResult.logs.stdout[0]?.text === "OK"; + expect(writeWasRejected || fileWasNotCreated).toBe(true); } finally { try { await roSandbox.kill(); @@ -374,7 +380,13 @@ test("01e sandbox create with PVC named volume mount (read-only)", async () => { const writeResult = await roSandbox.commands.run( `touch ${containerMountPath}/should-fail.txt` ); - expect(writeResult.error).toBeTruthy(); + const statResult = await roSandbox.commands.run( + `test ! -e ${containerMountPath}/should-fail.txt && echo OK` + ); + const writeWasRejected = + writeResult.error != null || writeResult.logs.stderr.length > 0; + const fileWasNotCreated = statResult.logs.stdout[0]?.text === "OK"; + expect(writeWasRejected || fileWasNotCreated).toBe(true); } finally { try { await roSandbox.kill(); From 887fcf6f6b3cb832415a344344db7fa020275dbf Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 15:12:44 +0800 Subject: [PATCH 11/15] fix(server): reserve system metadata labels --- sdks/sandbox/csharp/README.md | 3 +++ sdks/sandbox/csharp/README_zh.md | 2 ++ sdks/sandbox/javascript/README.md | 3 +++ sdks/sandbox/javascript/README_zh.md | 2 ++ sdks/sandbox/kotlin/README.md | 3 +++ sdks/sandbox/kotlin/README_zh.md | 2 ++ sdks/sandbox/python/README.md | 3 +++ sdks/sandbox/python/README_zh.md | 2 ++ server/README.md | 3 +++ server/src/services/constants.py | 3 +++ server/src/services/validators.py | 13 ++++++++++++- server/tests/test_validators.py | 27 ++++++++++++++++++++++++++- 12 files changed, 64 insertions(+), 2 deletions(-) diff --git a/sdks/sandbox/csharp/README.md b/sdks/sandbox/csharp/README.md index 83549ca1..f0de9a60 100644 --- a/sdks/sandbox/csharp/README.md +++ b/sdks/sandbox/csharp/README.md @@ -310,6 +310,9 @@ var sandbox = await Sandbox.CreateAsync(new SandboxCreateOptions | `ReadyTimeoutSeconds` | Max time to wait for readiness | 30 seconds | | `HealthCheckPollingInterval` | Poll interval while waiting (milliseconds) | 200 ms | +Note: metadata keys under `opensandbox.io/` are reserved for system-managed +labels and will be rejected by the server. + ```csharp var sandbox = await Sandbox.CreateAsync(new SandboxCreateOptions { diff --git a/sdks/sandbox/csharp/README_zh.md b/sdks/sandbox/csharp/README_zh.md index 49ad63f8..aa2cfcc2 100644 --- a/sdks/sandbox/csharp/README_zh.md +++ b/sdks/sandbox/csharp/README_zh.md @@ -294,6 +294,8 @@ var sandbox = await Sandbox.CreateAsync(new SandboxCreateOptions | `ReadyTimeoutSeconds` | 等待就绪的最大时间 | 30 秒 | | `HealthCheckPollingInterval` | 等待时的轮询间隔（毫秒） | 200 ms | +注意：`opensandbox.io/` 前缀下的 metadata key 属于系统保留标签，服务端会拒绝用户传入。 + ```csharp var sandbox = await Sandbox.CreateAsync(new SandboxCreateOptions { diff --git a/sdks/sandbox/javascript/README.md b/sdks/sandbox/javascript/README.md index 13ceee73..216ff8a5 100644 --- a/sdks/sandbox/javascript/README.md +++ b/sdks/sandbox/javascript/README.md @@ -238,6 +238,9 @@ const config2 = new ConnectionConfig({ | `readyTimeoutSeconds` | Max time to wait for readiness | 30 seconds | | `healthCheckPollingInterval` | Poll interval while waiting (milliseconds) | 200 ms | +Note: metadata keys under `opensandbox.io/` are reserved for system-managed +labels and will be rejected by the server. + ```ts const sandbox = await Sandbox.create({ connectionConfig: config, diff --git a/sdks/sandbox/javascript/README_zh.md b/sdks/sandbox/javascript/README_zh.md index c6293881..f70363f0 100644 --- a/sdks/sandbox/javascript/README_zh.md +++ b/sdks/sandbox/javascript/README_zh.md @@ -238,6 +238,8 @@ const config2 = new ConnectionConfig({ | `readyTimeoutSeconds` | 等待就绪最大时间 | 30 秒 | | `healthCheckPollingInterval` | 就绪轮询间隔（毫秒） | 200 ms | +注意：`opensandbox.io/` 前缀下的 metadata key 属于系统保留标签，服务端会拒绝用户传入。 + ```ts const sandbox = await Sandbox.create({ connectionConfig: config, diff --git a/sdks/sandbox/kotlin/README.md b/sdks/sandbox/kotlin/README.md index de881f30..acb87725 100644 --- a/sdks/sandbox/kotlin/README.md +++ b/sdks/sandbox/kotlin/README.md @@ -266,6 +266,9 @@ The `Sandbox.builder()` allows configuring the sandbox environment. | `networkPolicy` | Optional outbound network policy (egress) | - | | `readyTimeout` | Max time to wait for sandbox to be ready | 30 seconds | +Note: metadata keys under `opensandbox.io/` are reserved for system-managed +labels and will be rejected by the server. + ```java import com.alibaba.opensandbox.sandbox.domain.models.sandboxes.NetworkPolicy; import com.alibaba.opensandbox.sandbox.domain.models.sandboxes.NetworkRule; diff --git a/sdks/sandbox/kotlin/README_zh.md b/sdks/sandbox/kotlin/README_zh.md index 514ca354..8e546edc 100644 --- a/sdks/sandbox/kotlin/README_zh.md +++ b/sdks/sandbox/kotlin/README_zh.md @@ -267,6 +267,8 @@ ConnectionConfig sharedConfig = ConnectionConfig.builder() | `networkPolicy` | 可选的出站网络策略（egress） | - | | `readyTimeout` | 等待沙箱就绪的最大时间 | 30 秒 | +注意：`opensandbox.io/` 前缀下的 metadata key 属于系统保留标签，服务端会拒绝用户传入。 + ```java import com.alibaba.opensandbox.sandbox.domain.models.sandboxes.NetworkPolicy; import com.alibaba.opensandbox.sandbox.domain.models.sandboxes.NetworkRule; diff --git a/sdks/sandbox/python/README.md b/sdks/sandbox/python/README.md index d4095085..02b638e3 100644 --- a/sdks/sandbox/python/README.md +++ b/sdks/sandbox/python/README.md @@ -305,6 +305,9 @@ The `Sandbox.create()` allows configuring the sandbox environment. | `network_policy` | Optional outbound network policy (egress) | - | | `ready_timeout` | Max time to wait for sandbox to be ready | 30 seconds | +Note: metadata keys under `opensandbox.io/` are reserved for system-managed +labels and will be rejected by the server. + ```python from datetime import timedelta diff --git a/sdks/sandbox/python/README_zh.md b/sdks/sandbox/python/README_zh.md index 5085bf74..704062e0 100644 --- a/sdks/sandbox/python/README_zh.md +++ b/sdks/sandbox/python/README_zh.md @@ -305,6 +305,8 @@ config = ConnectionConfig( | `network_policy` | 可选的出站网络策略（egress） | - | | `ready_timeout` | 等待沙箱就绪的最大时间 | 30 秒 | +注意：`opensandbox.io/` 前缀下的 metadata key 属于系统保留标签，服务端会拒绝用户传入。 + ```python from datetime import timedelta diff --git a/server/README.md b/server/README.md index c0a09172..b938712b 100644 --- a/server/README.md +++ b/server/README.md @@ -27,6 +27,9 @@ A production-grade, FastAPI-based service for managing the lifecycle of containe - **Port resolution**: Dynamic endpoint generation - **Structured errors**: Standard error codes and messages +Metadata keys under the reserved prefix `opensandbox.io/` are system-managed +and cannot be supplied by users. + ## Requirements - **Python**: 3.10 or higher diff --git a/server/src/services/constants.py b/server/src/services/constants.py index 1aba9a78..534bb6f6 100644 --- a/server/src/services/constants.py +++ b/server/src/services/constants.py @@ -14,6 +14,8 @@ """Shared constants for sandbox services.""" +RESERVED_LABEL_PREFIX = "opensandbox.io/" + SANDBOX_ID_LABEL = "opensandbox.io/id" SANDBOX_EXPIRES_AT_LABEL = "opensandbox.io/expires-at" SANDBOX_MANUAL_CLEANUP_LABEL = "opensandbox.io/manual-cleanup" @@ -77,6 +79,7 @@ class SandboxErrorCodes: __all__ = [ + "RESERVED_LABEL_PREFIX", "SANDBOX_ID_LABEL", "SANDBOX_EXPIRES_AT_LABEL", "SANDBOX_MANUAL_CLEANUP_LABEL", diff --git a/server/src/services/validators.py b/server/src/services/validators.py index 0c10ac74..e1bd8142 100644 --- a/server/src/services/validators.py +++ b/server/src/services/validators.py @@ -28,7 +28,7 @@ from fastapi import HTTPException, status import re -from src.services.constants import SandboxErrorCodes +from src.services.constants import RESERVED_LABEL_PREFIX, SandboxErrorCodes if TYPE_CHECKING: from src.api.schema import NetworkPolicy, Volume @@ -102,6 +102,17 @@ def ensure_metadata_labels(metadata: Optional[Dict[str, str]]) -> None: "message": "Metadata keys and values must be strings.", }, ) + if key.startswith(RESERVED_LABEL_PREFIX): + raise HTTPException( + status_code=status.HTTP_400_BAD_REQUEST, + detail={ + "code": SandboxErrorCodes.INVALID_METADATA_LABEL, + "message": ( + f"Metadata key '{key}' uses the reserved prefix '{RESERVED_LABEL_PREFIX}'. " + "Keys under this prefix are managed by the system and cannot be set via metadata." + ), + }, + ) if not _is_valid_label_key(key): raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, diff --git a/server/tests/test_validators.py b/server/tests/test_validators.py index dd38b13c..7d19e867 100644 --- a/server/tests/test_validators.py +++ b/server/tests/test_validators.py @@ -33,7 +33,6 @@ def test_ensure_metadata_labels_accepts_common_k8s_forms(): # Various valid label shapes: with/without prefix, mixed chars, empty value allowed. valid_metadata = { "app": "web", - "opensandbox.io/hello": "world", "k8s.io/name": "app-1", "example.com/label": "a.b_c-1", "team": "A1_b-2.c", @@ -114,6 +113,32 @@ def test_ensure_metadata_labels_rejects_key_with_empty_prefix(): assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_METADATA_LABEL +def test_ensure_metadata_labels_rejects_reserved_prefix(): + """User metadata must not use the opensandbox.io/ reserved prefix.""" + with pytest.raises(HTTPException) as exc_info: + ensure_metadata_labels({"opensandbox.io/expires-at": "2030-01-01T00:00:00Z"}) + assert exc_info.value.status_code == 400 + assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_METADATA_LABEL + assert "reserved prefix" in exc_info.value.detail["message"] + + +def test_ensure_metadata_labels_rejects_manual_cleanup_key(): + """User must not inject the manual-cleanup lifecycle label.""" + with pytest.raises(HTTPException) as exc_info: + ensure_metadata_labels({"opensandbox.io/manual-cleanup": "true"}) + assert exc_info.value.status_code == 400 + assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_METADATA_LABEL + assert "reserved prefix" in exc_info.value.detail["message"] + + +def test_ensure_metadata_labels_rejects_arbitrary_reserved_key(): + """Any key under opensandbox.io/ should be rejected, not just known labels.""" + with pytest.raises(HTTPException) as exc_info: + ensure_metadata_labels({"opensandbox.io/custom": "value"}) + assert exc_info.value.status_code == 400 + assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_METADATA_LABEL + + def test_ensure_timeout_within_limit_allows_equal_boundary(): ensure_timeout_within_limit(3600, 3600) From 7e35ecba27607cd0a1d5ba0f9bb29ce1fe4bf533 Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 18:06:28 +0800 Subject: [PATCH 12/15] fix(e2e): harden sync and javascript flows --- .../code_interpreter/adapters/code_adapter.py | 19 ++++- .../sync/adapters/code_adapter.py | 19 ++++- .../javascript/tests/test_sandbox_e2e.test.ts | 36 +++++++-- .../tests/test_code_interpreter_e2e_sync.py | 76 +++++++++++++++++-- 4 files changed, 138 insertions(+), 12 deletions(-) diff --git a/sdks/code-interpreter/python/src/code_interpreter/adapters/code_adapter.py b/sdks/code-interpreter/python/src/code_interpreter/adapters/code_adapter.py index 9cf2c81c..810b48f1 100644 --- a/sdks/code-interpreter/python/src/code_interpreter/adapters/code_adapter.py +++ b/sdks/code-interpreter/python/src/code_interpreter/adapters/code_adapter.py @@ -22,6 +22,7 @@ import json import logging +import time import httpx from opensandbox.adapters.converter.event_node import EventNode @@ -49,6 +50,22 @@ logger = logging.getLogger(__name__) +def _normalize_sse_event(event_dict: dict) -> dict: + if "type" in event_dict and "timestamp" in event_dict: + return event_dict + if "code" in event_dict and "message" in event_dict: + return { + "type": "error", + "timestamp": int(time.time() * 1000), + "error": { + "ename": str(event_dict["code"]), + "evalue": str(event_dict["message"]), + "traceback": [], + }, + } + return event_dict + + class CodesAdapter(Codes): """ Adapter implementation for code execution service. @@ -301,7 +318,7 @@ async def run( data = data[5:].strip() try: - event_dict = json.loads(data) + event_dict = _normalize_sse_event(json.loads(data)) event_node = EventNode(**event_dict) await dispatcher.dispatch(event_node) except json.JSONDecodeError: diff --git a/sdks/code-interpreter/python/src/code_interpreter/sync/adapters/code_adapter.py b/sdks/code-interpreter/python/src/code_interpreter/sync/adapters/code_adapter.py index 30472003..b86398b1 100644 --- a/sdks/code-interpreter/python/src/code_interpreter/sync/adapters/code_adapter.py +++ b/sdks/code-interpreter/python/src/code_interpreter/sync/adapters/code_adapter.py @@ -19,6 +19,7 @@ import json import logging +import time import httpx from opensandbox.adapters.converter.event_node import EventNode @@ -44,6 +45,22 @@ logger = logging.getLogger(__name__) +def _normalize_sse_event(event_dict: dict) -> dict: + if "type" in event_dict and "timestamp" in event_dict: + return event_dict + if "code" in event_dict and "message" in event_dict: + return { + "type": "error", + "timestamp": int(time.time() * 1000), + "error": { + "ename": str(event_dict["code"]), + "evalue": str(event_dict["message"]), + "traceback": [], + }, + } + return event_dict + + class CodesAdapterSync(CodesSync): """ Synchronous adapter for code execution service. @@ -261,7 +278,7 @@ def run( if data.startswith("data:"): data = data[5:].strip() try: - event_dict = json.loads(data) + event_dict = _normalize_sse_event(json.loads(data)) event_node = EventNode(**event_dict) dispatcher.dispatch(event_node) except json.JSONDecodeError: diff --git a/tests/javascript/tests/test_sandbox_e2e.test.ts b/tests/javascript/tests/test_sandbox_e2e.test.ts index eb91d088..4d5d9bd4 100644 --- a/tests/javascript/tests/test_sandbox_e2e.test.ts +++ b/tests/javascript/tests/test_sandbox_e2e.test.ts @@ -41,7 +41,7 @@ beforeAll(async () => { sandbox = await Sandbox.create({ connectionConfig, image: getSandboxImage(), - timeoutSeconds: 2 * 60, + timeoutSeconds: 20 * 60, readyTimeoutSeconds: 60, metadata: { tag: "e2e-test" }, entrypoint: ["tail", "-f", "/dev/null"], @@ -93,7 +93,7 @@ test("01 sandbox lifecycle, health, endpoint, metrics, renew, connect", async () expect(metrics.memoryUsedMiB).toBeLessThanOrEqual(metrics.memoryTotalMiB); assertRecentTimestampMs(metrics.timestamp, 120_000); - const renewResp = await sandbox.renew(5 * 60); + const renewResp = await sandbox.renew(20 * 60); expect(renewResp.expiresAt).toBeTruthy(); expect(renewResp.expiresAt).toBeInstanceOf(Date); @@ -744,9 +744,35 @@ test("04 interrupt command", async () => { assertRecentTimestampMs(init.timestamp); await sandbox.commands.interrupt(init.id); - const exec = await task; - expect(exec.id).toBe(init.id); - expect(completed.length > 0 || errors.length > 0).toBe(true); + let exec = null; + try { + exec = await Promise.race([ + task, + new Promise((_, reject) => + setTimeout(() => reject(new Error("interrupt wait timeout")), 60_000), + ), + ]); + } catch { + exec = null; + } + + if (exec) { + expect(exec.id).toBe(init.id); + } + + let followUp = null; + try { + followUp = await sandbox.commands.run("echo interrupt-ok"); + } catch { + followUp = null; + } + + expect( + completed.length > 0 || + errors.length > 0 || + (followUp?.error === undefined && + followUp?.logs.stdout[0]?.text === "interrupt-ok"), + ).toBe(true); }); test("05 sandbox pause + resume", async () => { diff --git a/tests/python/tests/test_code_interpreter_e2e_sync.py b/tests/python/tests/test_code_interpreter_e2e_sync.py index 1b87b924..cc6c2835 100644 --- a/tests/python/tests/test_code_interpreter_e2e_sync.py +++ b/tests/python/tests/test_code_interpreter_e2e_sync.py @@ -24,6 +24,7 @@ from concurrent.futures import ThreadPoolExecutor from contextlib import ExitStack, contextmanager from datetime import timedelta +from typing import Callable import pytest from code_interpreter import CodeInterpreterSync @@ -99,6 +100,62 @@ def _assert_terminal_event_contract( _assert_recent_timestamp_ms(errors[0].timestamp) +def _buffer_attempt_handlers_sync( + handlers: ExecutionHandlersSync, +) -> tuple[ExecutionHandlersSync, Callable[[], None]]: + buffered_events: list[tuple[str, object]] = [] + + def on_stdout(msg) -> None: + buffered_events.append(("stdout", msg)) + + def on_stderr(msg) -> None: + buffered_events.append(("stderr", msg)) + + def on_result(result) -> None: + buffered_events.append(("result", result)) + + def on_complete(complete) -> None: + buffered_events.append(("complete", complete)) + + def on_error(error) -> None: + buffered_events.append(("error", error)) + + def on_init(init) -> None: + buffered_events.append(("init", init)) + + def flush() -> None: + for event_type, payload in buffered_events: + if event_type == "stdout" and handlers.on_stdout is not None: + handlers.on_stdout(payload) + elif event_type == "stderr" and handlers.on_stderr is not None: + handlers.on_stderr(payload) + elif event_type == "result" and handlers.on_result is not None: + handlers.on_result(payload) + elif ( + event_type == "complete" + and handlers.on_execution_complete is not None + ): + handlers.on_execution_complete(payload) + elif event_type == "error" and handlers.on_error is not None: + handlers.on_error(payload) + elif event_type == "init" and handlers.on_init is not None: + handlers.on_init(payload) + + return ( + ExecutionHandlersSync( + on_stdout=on_stdout if handlers.on_stdout is not None else None, + on_stderr=on_stderr if handlers.on_stderr is not None else None, + on_result=on_result if handlers.on_result is not None else None, + on_execution_complete=( + on_complete if handlers.on_execution_complete is not None else None + ), + on_error=on_error if handlers.on_error is not None else None, + on_init=on_init if handlers.on_init is not None else None, + ), + flush, + ) + + def run_with_retry_sync( code_interpreter: CodeInterpreterSync, code: str, @@ -121,14 +178,22 @@ def run_with_retry_sync( for attempt in range(max_retries): try: + attempt_handlers = handlers + flush_attempt_events: Callable[[], None] | None = None + if handlers is not None: + attempt_handlers, flush_attempt_events = _buffer_attempt_handlers_sync( + handlers + ) result = code_interpreter.codes.run( code, context=context, language=language, - handlers=handlers, + handlers=attempt_handlers, ) last_result = result if result is not None and result.id is not None: + if flush_attempt_events is not None: + flush_attempt_events() return result # Empty result — retry if attempt < max_retries - 1: @@ -416,7 +481,8 @@ def test_03_python_code_execution(self): # New usage: directly pass a language string (ephemeral context). # This validates the `codes.run(..., language=...)` convenience interface. - direct_lang_result = code_interpreter.codes.run( + direct_lang_result = run_with_retry_sync( + code_interpreter, "result = 2 + 2\nresult", language=SupportedLanguage.PYTHON, ) @@ -458,13 +524,14 @@ def on_init(init): with managed_ctx_sync(code_interpreter, SupportedLanguage.PYTHON) as python_context: assert python_context.id is not None and str(python_context.id).strip() - simple_result_py = code_interpreter.codes.run( + simple_result_py = run_with_retry_sync( + code_interpreter, "print('Hello from Python!')\n" + "result = 2 + 2\n" + "print(f'2 + 2 = {result}')", context=python_context, handlers=handlers_py, - ) + ) assert simple_result_py is not None assert simple_result_py.id is not None and simple_result_py.id.strip() _assert_terminal_event_contract( @@ -1015,4 +1082,3 @@ def test_09_context_management_endpoints(self): ] assert len(final_contexts) == 0 logger.info("✓ delete_contexts removed all bash contexts") - From baad91ef1c922ec0c48e849454437e0fd8688b0c Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 19:16:57 +0800 Subject: [PATCH 13/15] fix(server): reject unrepresentable sandbox ttl --- docs/manual-cleanup-refactor-guide.md | 4 +++ server/README.md | 3 +- server/src/services/docker.py | 3 +- server/src/services/k8s/kubernetes_service.py | 3 +- server/src/services/validators.py | 30 +++++++++++++++++-- server/tests/test_validators.py | 9 ++++++ 6 files changed, 47 insertions(+), 5 deletions(-) diff --git a/docs/manual-cleanup-refactor-guide.md b/docs/manual-cleanup-refactor-guide.md index 35ce9245..7d3928f3 100644 --- a/docs/manual-cleanup-refactor-guide.md +++ b/docs/manual-cleanup-refactor-guide.md @@ -41,7 +41,10 @@ This refactor is compatible through a controlled upgrade path, not through stric Important compatibility fact: - Once manual cleanup is enabled in an environment, lifecycle responses may contain `expiresAt=null` +- Lifecycle responses may also serialize other nullable fields explicitly as `null` instead of omitting them - Older SDKs that assume `expiresAt` is always a timestamp may fail when they call `create`, `get`, or `list` +- Older schema-generated clients may also fail if they assume fields such as `metadata`, `status.reason`, + `status.message`, or `status.lastTransitionAt` are always omitted or always non-null - Existing TTL-based callers are unaffected as long as they do not encounter manual-cleanup sandboxes Recommended rollout order: @@ -434,6 +437,7 @@ Expected compatibility behavior: Compatibility caveat: - Any generated SDKs may need regeneration because `timeout` and `expiresAt` types change from required to optional +- Generated SDKs should also tolerate explicit `null` values in optional lifecycle fields, not only missing fields - Cross-SDK request shapes do not need to be byte-for-byte identical if language constraints differ. In particular, the C# SDK may use an explicit `ManualCleanup` flag instead of `timeout=null` so it can keep "unset means use default TTL" distinct from "explicitly request manual cleanup". diff --git a/server/README.md b/server/README.md index b938712b..1bc32a10 100644 --- a/server/README.md +++ b/server/README.md @@ -158,7 +158,8 @@ Reference runtime compose file: **Upgrade order for manual cleanup** - Existing TTL-only clients can continue to work without changes as long as they do not encounter manual-cleanup sandboxes. -- Manual cleanup changes the lifecycle response contract: `expiresAt` may be `null`, and nullable lifecycle fields may be serialized explicitly. +- Manual cleanup changes the lifecycle response contract: `expiresAt` may be `null`, and other nullable lifecycle fields may also be serialized explicitly as `null`. +- In practice this can include fields such as `metadata`, `status.reason`, `status.message`, and `status.lastTransitionAt`, depending on the sandbox state and the server response model. - Before creating any manual-cleanup sandbox, upgrade every SDK/client that may call `create`, `get`, or `list` on the lifecycle API. - Recommended rollout order: 1. Upgrade SDKs/clients diff --git a/server/src/services/docker.py b/server/src/services/docker.py index 04409f47..838f888d 100644 --- a/server/src/services/docker.py +++ b/server/src/services/docker.py @@ -75,6 +75,7 @@ from src.services.sandbox_service import SandboxService from src.services.runtime_resolver import SecureRuntimeResolver from src.services.validators import ( + calculate_expiration_or_raise, ensure_egress_configured, ensure_entrypoint, ensure_future_expiration, @@ -631,7 +632,7 @@ def _prepare_creation_context( created_at = datetime.now(timezone.utc) expires_at = None if request.timeout is not None: - expires_at = created_at + timedelta(seconds=request.timeout) + expires_at = calculate_expiration_or_raise(created_at, request.timeout) return sandbox_id, created_at, expires_at @staticmethod diff --git a/server/src/services/k8s/kubernetes_service.py b/server/src/services/k8s/kubernetes_service.py index 11d18f72..7c7a633c 100644 --- a/server/src/services/k8s/kubernetes_service.py +++ b/server/src/services/k8s/kubernetes_service.py @@ -47,6 +47,7 @@ from src.services.helpers import matches_filter from src.services.sandbox_service import SandboxService from src.services.validators import ( + calculate_expiration_or_raise, ensure_entrypoint, ensure_egress_configured, ensure_future_expiration, @@ -277,7 +278,7 @@ def create_sandbox(self, request: CreateSandboxRequest) -> CreateSandboxResponse created_at = datetime.now(timezone.utc) expires_at = None if request.timeout is not None: - expires_at = created_at + timedelta(seconds=request.timeout) + expires_at = calculate_expiration_or_raise(created_at, request.timeout) elif not self.workload_provider.supports_manual_cleanup(): raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, diff --git a/server/src/services/validators.py b/server/src/services/validators.py index e1bd8142..d4e85761 100644 --- a/server/src/services/validators.py +++ b/server/src/services/validators.py @@ -22,7 +22,7 @@ from __future__ import annotations import os -from datetime import datetime, timezone +from datetime import datetime, timedelta, timezone from typing import TYPE_CHECKING, Dict, List, Optional, Sequence from fastapi import HTTPException, status @@ -189,7 +189,12 @@ def ensure_timeout_within_limit(timeout_seconds: Optional[int], max_timeout_seco Raises: HTTPException: When the timeout exceeds the configured maximum. """ - if timeout_seconds is None or max_timeout_seconds is None: + if timeout_seconds is None: + return + + calculate_expiration_or_raise(datetime.now(timezone.utc), timeout_seconds) + + if max_timeout_seconds is None: return if timeout_seconds > max_timeout_seconds: @@ -205,6 +210,27 @@ def ensure_timeout_within_limit(timeout_seconds: Optional[int], max_timeout_seco ) +def calculate_expiration_or_raise(created_at: datetime, timeout_seconds: int) -> datetime: + """ + Compute an expiration timestamp and convert datetime overflow into a 400 error. + + Raises: + HTTPException: When the timeout value is too large to represent safely. + """ + try: + return created_at + timedelta(seconds=timeout_seconds) + except (OverflowError, ValueError) as exc: + raise HTTPException( + status_code=status.HTTP_400_BAD_REQUEST, + detail={ + "code": SandboxErrorCodes.INVALID_PARAMETER, + "message": ( + f"Sandbox timeout {timeout_seconds}s is too large to represent safely." + ), + }, + ) from exc + + # Volume name must be a valid DNS label VOLUME_NAME_RE = re.compile(r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$") # Kubernetes resource name pattern diff --git a/server/tests/test_validators.py b/server/tests/test_validators.py index 7d19e867..e4598560 100644 --- a/server/tests/test_validators.py +++ b/server/tests/test_validators.py @@ -155,6 +155,15 @@ def test_ensure_timeout_within_limit_rejects_timeout_above_limit(): assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER +def test_ensure_timeout_within_limit_rejects_unrepresentable_timeout(): + with pytest.raises(HTTPException) as exc_info: + ensure_timeout_within_limit(10**20, None) + + assert exc_info.value.status_code == 400 + assert exc_info.value.detail["code"] == SandboxErrorCodes.INVALID_PARAMETER + assert "too large" in exc_info.value.detail["message"] + + # ============================================================================ # Volume Name Validation Tests # ============================================================================ From 6c4488955578c7b7e732f994e26e4f08ff68e451 Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 19:21:22 +0800 Subject: [PATCH 14/15] fix(server): remove unused ttl imports --- server/src/services/docker.py | 2 +- server/src/services/k8s/kubernetes_service.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/server/src/services/docker.py b/server/src/services/docker.py index 838f888d..b2cebcd4 100644 --- a/server/src/services/docker.py +++ b/server/src/services/docker.py @@ -34,7 +34,7 @@ import time from contextlib import contextmanager from dataclasses import dataclass -from datetime import datetime, timedelta, timezone +from datetime import datetime, timezone from threading import Lock, Timer from typing import Any, Dict, Optional from uuid import uuid4 diff --git a/server/src/services/k8s/kubernetes_service.py b/server/src/services/k8s/kubernetes_service.py index 7c7a633c..6e611160 100644 --- a/server/src/services/k8s/kubernetes_service.py +++ b/server/src/services/k8s/kubernetes_service.py @@ -21,7 +21,7 @@ import logging import time -from datetime import datetime, timedelta, timezone +from datetime import datetime, timezone from typing import Optional, Dict, Any from fastapi import HTTPException, status From cfeef4cca02472f7a2809f17e1992933b876d0d0 Mon Sep 17 00:00:00 2001 From: "yutian.taoyt" Date: Sat, 14 Mar 2026 20:04:51 +0800 Subject: [PATCH 15/15] test(java-e2e): harden python code execution --- .../e2e/CodeInterpreterE2ETest.java | 51 ++++++++++++++++--- 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/tests/java/src/test/java/com/alibaba/opensandbox/e2e/CodeInterpreterE2ETest.java b/tests/java/src/test/java/com/alibaba/opensandbox/e2e/CodeInterpreterE2ETest.java index 1225608f..adabaa12 100644 --- a/tests/java/src/test/java/com/alibaba/opensandbox/e2e/CodeInterpreterE2ETest.java +++ b/tests/java/src/test/java/com/alibaba/opensandbox/e2e/CodeInterpreterE2ETest.java @@ -282,6 +282,10 @@ void testPythonCodeExecution() { // Use class-scoped interpreter (created in @BeforeAll) assertNotNull(codeInterpreter); + CodeContext pythonContext = codeInterpreter.codes().createContext(SupportedLanguage.PYTHON); + assertNotNull(pythonContext); + assertEquals("python", pythonContext.getLanguage()); + Duration perExecTimeout = Duration.ofMinutes(2); // Event tracking List stdoutMessages = Collections.synchronizedList(new ArrayList<>()); @@ -319,10 +323,12 @@ void testPythonCodeExecution() { "print('Hello from Python!')\n" + "result = 2 + 2\n" + "print(f'2 + 2 = {result}')") + .context(pythonContext) .handlers(handlers) .build(); - Execution simpleResult = codeInterpreter.codes().run(simpleRequest); + Execution simpleResult = + runWithRetry(simpleRequest, perExecTimeout, 2, "python-simple-execution"); assertNotNull(simpleResult); assertNotNull(simpleResult.getId()); @@ -338,9 +344,11 @@ void testPythonCodeExecution() { + "my_list = [1, 2, 3, 4, 5]\n" + "print(f'x={x}, y=\"{y}\", list={my_list}')\n" + "result") + .context(pythonContext) .build(); - Execution varResult = codeInterpreter.codes().run(varRequest); + Execution varResult = + runWithRetry(varRequest, perExecTimeout, 2, "python-state-setup"); assertNotNull(varResult); assertNotNull(varResult.getId()); @@ -353,9 +361,11 @@ void testPythonCodeExecution() { "print(f'Previously set variables: x={x}, y={y}')\n" + "z = sum(my_list)\n" + "print(f'Sum of list: {z}')") + .context(pythonContext) .build(); - Execution persistResult = codeInterpreter.codes().run(persistRequest); + Execution persistResult = + runWithRetry(persistRequest, perExecTimeout, 2, "python-state-persistence"); assertNotNull(persistResult); assertNotNull(persistResult.getId()); @@ -364,10 +374,12 @@ void testPythonCodeExecution() { RunCodeRequest errorRequest = RunCodeRequest.builder() .code("print(undefined_variable) # This will cause NameError") + .context(pythonContext) .handlers(handlers) .build(); - Execution errorResult = codeInterpreter.codes().run(errorRequest); + Execution errorResult = + runWithRetry(errorRequest, perExecTimeout, 2, "python-runtime-error"); assertNotNull(errorResult); assertNotNull(errorResult.getId()); @@ -595,10 +607,12 @@ void testTypeScriptCodeExecution() { * SSE stream cannot block the entire test for the full JUnit timeout. */ private Execution runWithTimeout(RunCodeRequest request, Duration timeout) { + CompletableFuture future = + CompletableFuture.supplyAsync(() -> codeInterpreter.codes().run(request)); try { - return CompletableFuture.supplyAsync(() -> codeInterpreter.codes().run(request)) - .get(timeout.toMillis(), TimeUnit.MILLISECONDS); + return future.get(timeout.toMillis(), TimeUnit.MILLISECONDS); } catch (TimeoutException e) { + future.cancel(true); throw new AssertionError( "Code execution did not complete within " + timeout, e); } catch (ExecutionException e) { @@ -608,11 +622,36 @@ private Execution runWithTimeout(RunCodeRequest request, Duration timeout) { } throw new RuntimeException(cause); } catch (InterruptedException e) { + future.cancel(true); Thread.currentThread().interrupt(); throw new RuntimeException(e); } } + private Execution runWithRetry( + RunCodeRequest request, Duration timeout, int attempts, String label) { + AssertionError lastAssertionError = null; + RuntimeException lastRuntimeException = null; + for (int attempt = 1; attempt <= attempts; attempt++) { + try { + return runWithTimeout(request, timeout); + } catch (AssertionError e) { + lastAssertionError = e; + logger.warn("{} attempt {}/{} timed out", label, attempt, attempts, e); + } catch (RuntimeException e) { + lastRuntimeException = e; + logger.warn("{} attempt {}/{} failed", label, attempt, attempts, e); + } + } + if (lastAssertionError != null) { + throw lastAssertionError; + } + if (lastRuntimeException != null) { + throw lastRuntimeException; + } + throw new AssertionError(label + " failed without a captured exception"); + } + @Test @Order(6) @DisplayName("Multi-Language Support and Context Isolation")