Secure, Fast, and Extensible Sandbox runtime for AI agents.
fix(diagnostics): harden backend errors and SDK regression coverage
ninan.nnbccaecea8beb
diff --git a/sdks/sandbox/javascript/src/internal.ts b/sdks/sandbox/javascript/src/internal.tsindex aad7b2935..3e6cd1ce7 100644--- a/sdks/sandbox/javascript/src/internal.ts+++ b/sdks/sandbox/javascript/src/internal.ts@@ -24,6 +24,7 @@*/export { createLifecycleClient } from "./openapi/lifecycleClient.js";+export { createDiagnosticClient } from "./openapi/diagnosticClient.js";export type { LifecycleClient } from "./openapi/lifecycleClient.js";export { createExecdClient } from "./openapi/execdClient.js";export type { ExecdClient } from "./openapi/execdClient.js";diff --git a/sdks/sandbox/javascript/src/openapi/diagnosticClient.ts b/sdks/sandbox/javascript/src/openapi/diagnosticClient.tsindex f721fe565..d5c65b2b0 100644--- a/sdks/sandbox/javascript/src/openapi/diagnosticClient.ts+++ b/sdks/sandbox/javascript/src/openapi/diagnosticClient.ts@@ -12,19 +12,16 @@// See the License for the specific language governing permissions and// limitations under the License.-import createClient from "openapi-fetch";import type { Client } from "openapi-fetch";import type { paths } from "../api/diagnostic.js";import type { CreateLifecycleClientOptions } from "./lifecycleClient.js";+import { createLifecycleApiClient } from "./lifecycleClient.js";export type DiagnosticClient = Client<paths>;-export function createDiagnosticClient(opts: CreateLifecycleClientOptions): DiagnosticClient {- const headers: Record<string, string> = { Accept: "application/json", ...opts.headers };- if (opts.apiKey && !headers["OPEN-SANDBOX-API-KEY"]) {- headers["OPEN-SANDBOX-API-KEY"] = opts.apiKey;- }- const createClientFn =- (createClient as unknown as { default?: typeof createClient }).default ?? createClient;- return createClientFn<paths>({ baseUrl: opts.baseUrl, headers, fetch: opts.fetch });+export function createDiagnosticClient(opts: CreateLifecycleClientOptions = {}): DiagnosticClient {+ return createLifecycleApiClient<paths>({+ ...opts,+ headers: { Accept: "application/json", ...opts.headers },+ });}diff --git a/sdks/sandbox/javascript/src/openapi/lifecycleClient.ts b/sdks/sandbox/javascript/src/openapi/lifecycleClient.tsindex 8327a4b10..af2752e7b 100644--- a/sdks/sandbox/javascript/src/openapi/lifecycleClient.ts+++ b/sdks/sandbox/javascript/src/openapi/lifecycleClient.ts@@ -52,6 +52,13 @@ function readEnvApiKey(): string | undefined {}export function createLifecycleClient(opts: CreateLifecycleClientOptions = {}): LifecycleClient {+ return createLifecycleApiClient<LifecyclePaths>(opts);+}++// Shared bootstrap keeps diagnostics and lifecycle auth and URL defaults aligned.+export function createLifecycleApiClient<Paths extends object>(+ opts: CreateLifecycleClientOptions = {},+): Client<Paths> {const apiKey = opts.apiKey ?? readEnvApiKey();const headers: Record<string, string> = {@@ -64,9 +71,9 @@ export function createLifecycleClient(opts: CreateLifecycleClientOptions = {}):const createClientFn =(createClient as unknown as { default?: typeof createClient }).default ?? createClient;- return createClientFn<LifecyclePaths>({+ return createClientFn<Paths>({baseUrl: opts.baseUrl ?? "http://localhost:8080/v1",headers,fetch: opts.fetch,});-}\ No newline at end of file+}diff --git a/sdks/sandbox/javascript/tests/diagnostics.test.mjs b/sdks/sandbox/javascript/tests/diagnostics.test.mjsindex 3f7756782..9ca748710 100644--- a/sdks/sandbox/javascript/tests/diagnostics.test.mjs+++ b/sdks/sandbox/javascript/tests/diagnostics.test.mjs@@ -15,6 +15,7 @@import assert from "node:assert/strict";import test from "node:test";import { Sandbox, SandboxManager, ConnectionConfig, SandboxApiException } from "../dist/index.js";+import { createDiagnosticClient, createLifecycleClient } from "../dist/internal.js";const context = { sandboxId: "sbx-1", backendType: "kubernetes", backendIdentifiers: { namespace: "tenant-ns" } };@@ -113,7 +114,84 @@ test("sandbox diagnostics delegates through the injected lifecycle stack", async} finally { await sandbox.close(); }});-test("context preserves API errors", async () => {+test("diagnostic and lifecycle clients share environment and URL defaults", async () => {+ const previousKey = process.env.OPEN_SANDBOX_API_KEY;+ process.env.OPEN_SANDBOX_API_KEY = "environment-key";+ const calls = [];+ const fetch = async (req) => {+ calls.push(req);+ assert.equal(req.headers.get("OPEN-SANDBOX-API-KEY"), "environment-key");+ return Response.json(context);+ };+ try {+ await createLifecycleClient({ fetch }).GET("/sandboxes/{sandboxId}", {+ params: { path: { sandboxId: "sbx-1" } },+ });+ await createDiagnosticClient({ fetch }).GET("/sandboxes/{sandboxId}/diagnostics/context", {+ params: { path: { sandboxId: "sbx-1" } },+ });+ assert.deepEqual(calls.map((req) => req.url), [+ "http://localhost:8080/v1/sandboxes/sbx-1",+ "http://localhost:8080/v1/sandboxes/sbx-1/diagnostics/context",+ ]);+ } finally {+ if (previousKey === undefined) delete process.env.OPEN_SANDBOX_API_KEY;+ else process.env.OPEN_SANDBOX_API_KEY = previousKey;+ }+});++test("inline diagnostics preserves content without requiring an expiry", async () => {+ for (const expiry of [{}, { expiresAt: null }]) {+ const manager = SandboxManager.create({ connectionConfig: mockConfig(async (req) => {+ const kind = new URL(req.url).pathname.endsWith("/logs") ? "logs" : "events";+ return Response.json({+ sandboxId: "sbx-1", kind, scope: "all", delivery: "inline", contentType: "text/plain",+ content: "hello\n", contentLength: 6, truncated: false, ...expiry,+ });+ }) });+ try {+ for (const kind of ["Logs", "Events"]) {+ const result = await manager[`getDiagnostic${kind}`]("sbx-1", "all");+ assert.equal(result.delivery, "inline");+ assert.equal(result.content, "hello\n");+ assert.equal(result.contentLength, 6);+ assert.equal(result.expiresAt, undefined);+ }+ } finally { await manager.close(); }+ }+});++test("custom factories without diagnostics produce an actionable error", async () => {+ const config = new ConnectionConfig({ domain: "localhost:8080" });+ const adapterFactory = {+ createLifecycleStack: () => ({+ sandboxes: { getSandboxEndpoint: async () => ({ endpoint: "localhost:44772" }) },+ }),+ createExecdStack: () => ({ commands: {}, files: {}, health: {}, metrics: {} }),+ createEgressStack: () => ({ egress: {} }),+ };+ const manager = SandboxManager.create({ connectionConfig: config, adapterFactory });+ const sandbox = await Sandbox.connect({+ sandboxId: "sbx-1", connectionConfig: config, skipHealthCheck: true, adapterFactory,+ });+ try {+ for (const call of [+ () => manager.getDiagnosticContext("sbx-1"),+ () => manager.getDiagnosticLogs("sbx-1", "all"),+ () => manager.getDiagnosticEvents("sbx-1", "all"),+ () => sandbox.getDiagnosticContext(),+ () => sandbox.getDiagnosticLogs("all"),+ () => sandbox.getDiagnosticEvents("all"),+ ]) {+ assert.throws(call, /The adapter factory does not provide diagnostics/);+ }+ } finally {+ await sandbox.close();+ await manager.close();+ }+});++test("diagnostics preserves API errors", async () => {for (const status of [403, 404, 501]) {const manager = SandboxManager.create({ connectionConfig: mockConfig(async () => Response.json(@@ -121,8 +199,14 @@ test("context preserves API errors", async () => {),) });try {- await assert.rejects(manager.getDiagnosticContext("sbx-1"), (error) =>- error instanceof SandboxApiException && error.statusCode === status && error.requestId === "request-1");+ for (const call of [+ () => manager.getDiagnosticContext("sbx-1"),+ () => manager.getDiagnosticLogs("sbx-1", "all"),+ () => manager.getDiagnosticEvents("sbx-1", "all"),+ ]) {+ await assert.rejects(call, (error) =>+ error instanceof SandboxApiException && error.statusCode === status && error.requestId === "request-1");+ }} finally { await manager.close(); }}});diff --git a/server/opensandbox_server/services/docker/docker_diagnostics.py b/server/opensandbox_server/services/docker/docker_diagnostics.pyindex 825b303c4..3236db4d6 100644--- a/server/opensandbox_server/services/docker/docker_diagnostics.py+++ b/server/opensandbox_server/services/docker/docker_diagnostics.py@@ -23,6 +23,7 @@ from __future__ import annotationsimport reimport time+from typing import Anyfrom docker.errors import DockerExceptionfrom fastapi import HTTPException, status@@ -57,6 +58,26 @@ def _parse_since_to_timestamp(since: str) -> int:return int(time.time()) - seconds+def _container_lifecycle_state(container: Any) -> tuple[str, str, str]:+ """Classify container inspect data without looking up its image."""+ state = container.attrs.get("State", {})+ status_value = (state.get("Status") or container.status or "").lower()+ if state.get("Running", False) and not state.get("Paused", False):+ return "Running", "CONTAINER_RUNNING", "Sandbox container is running."+ if state.get("Paused", False):+ return "Paused", "CONTAINER_PAUSED", "Sandbox container is paused."+ if state.get("Restarting", False):+ return "Running", "CONTAINER_RESTARTING", "Sandbox container is restarting."+ if status_value in {"created", "starting"}:+ return "Pending", "CONTAINER_STARTING", "Sandbox container is starting."+ if status_value in {"exited", "dead"}:+ exit_code = state.get("ExitCode")+ if exit_code == 0:+ return "Terminated", "CONTAINER_EXITED", "Sandbox container exited successfully."+ return "Failed", "CONTAINER_EXITED_ERROR", f"Sandbox container exited with code {exit_code}."+ return "Unknown", "CONTAINER_STATE_UNKNOWN", f"Sandbox container is in state '{status_value or 'unknown'}'."++class DockerDiagnosticsMixin:"""Mixin that implements diagnostics methods for the Docker backend."""@@ -64,20 +85,7 @@ class DockerDiagnosticsMixin:container = self._get_container_by_sandbox_id(sandbox_id)# Container lookup already provides inspect data. Do not construct a full# Sandbox here: that also inspects the image, which may no longer exist.- container_state = container.attrs.get("State", {})- status_value = (container_state.get("Status") or container.status or "").lower()- if container_state.get("Running") and not container_state.get("Paused"):- state = "Running"- elif container_state.get("Paused"):- state = "Paused"- elif container_state.get("Restarting"):- state = "Running"- elif status_value in {"created", "starting"}:- state = "Pending"- elif status_value in {"exited", "dead"}:- state = "Terminated" if container_state.get("ExitCode") == 0 else "Failed"- else:- state = "Unknown"+ state, _, _ = _container_lifecycle_state(container)return DiagnosticContext(sandbox_id=sandbox_id,state=state,diff --git a/server/opensandbox_server/services/docker/docker_service.py b/server/opensandbox_server/services/docker/docker_service.pyindex a52b81c8a..359b96c6a 100644--- a/server/opensandbox_server/services/docker/docker_service.py+++ b/server/opensandbox_server/services/docker/docker_service.py@@ -58,7 +58,10 @@ from opensandbox_server.api.schema import (PlatformSpec,)from opensandbox_server.config import AppConfig, get_config-from opensandbox_server.services.docker.docker_diagnostics import DockerDiagnosticsMixin+from opensandbox_server.services.docker.docker_diagnostics import (+ DockerDiagnosticsMixin,+ _container_lifecycle_state,+)from opensandbox_server.services.docker.runtime import (DockerRuntimeMixin,)@@ -525,42 +528,8 @@ class DockerSandboxService(DockerDiagnosticsMixin, DockerRuntimeMixin, DockerVol)status_section = container.attrs.get("State", {})- status_value = (status_section.get("Status") or container.status or "").lower()- running = status_section.get("Running", False)- paused = status_section.get("Paused", False)- restarting = status_section.get("Restarting", False)- exit_code = status_section.get("ExitCode")finished_at = status_section.get("FinishedAt")-- if running and not paused:- state = "Running"- reason = "CONTAINER_RUNNING"- message = "Sandbox container is running."- elif paused:- state = "Paused"- reason = "CONTAINER_PAUSED"- message = "Sandbox container is paused."- elif restarting:- state = "Running"- reason = "CONTAINER_RESTARTING"- message = "Sandbox container is restarting."- elif status_value in {"created", "starting"}:- state = "Pending"- reason = "CONTAINER_STARTING"- message = "Sandbox container is starting."- elif status_value in {"exited", "dead"}:- if exit_code == 0:- state = "Terminated"- reason = "CONTAINER_EXITED"- message = "Sandbox container exited successfully."- else:- state = "Failed"- reason = "CONTAINER_EXITED_ERROR"- message = f"Sandbox container exited with code {exit_code}."- else:- state = "Unknown"- reason = "CONTAINER_STATE_UNKNOWN"- message = f"Sandbox container is in state '{status_value or 'unknown'}'."+ state, reason, message = _container_lifecycle_state(container)metadata = self._metadata_store.get(resolved_id, labels)entrypoint = container.attrs.get("Config", {}).get("Cmd") or []diff --git a/server/opensandbox_server/services/k8s/k8s_diagnostics.py b/server/opensandbox_server/services/k8s/k8s_diagnostics.pyindex 11ff8de0b..ce93d2eff 100644--- a/server/opensandbox_server/services/k8s/k8s_diagnostics.py+++ b/server/opensandbox_server/services/k8s/k8s_diagnostics.py@@ -22,6 +22,7 @@ by querying K8s Pod state and events. Mixed into KubernetesSandboxService.from __future__ import annotationsimport re+import loggingfrom typing import Anyfrom fastapi import HTTPException, status@@ -38,12 +39,14 @@ from opensandbox_server.services.diagnostics import (unsupported_scope_error,)from opensandbox_server.services.k8s.workload_access import _get_owned_workload_or_404+from opensandbox_server.services.k8s.error_helpers import _build_k8s_api_errorfrom opensandbox_server.services.k8s.workload_mapper import (_build_sandbox_from_workload,allocated_pod_names,)_SUPPORTED_LOG_SCOPES = ("container", "all")+logger = logging.getLogger(__name__)_SUPPORTED_EVENT_SCOPES = ("runtime", "all")_STABLE_LOG_LINE_LIMIT = 100_STABLE_EVENT_LINE_LIMIT = 50@@ -70,9 +73,15 @@ class K8sDiagnosticsMixin:"""Mixin that implements diagnostics methods for the Kubernetes backend."""def get_sandbox_diagnostic_context(self, sandbox_id: str) -> DiagnosticContext:- namespace = self._resolve_namespace_for_lookup(sandbox_id)- workload = _get_owned_workload_or_404(self.workload_provider, namespace, sandbox_id)- sandbox = _build_sandbox_from_workload(workload, self.workload_provider)+ try:+ namespace = self._resolve_namespace_for_lookup(sandbox_id)+ workload = _get_owned_workload_or_404(self.workload_provider, namespace, sandbox_id)+ sandbox = _build_sandbox_from_workload(workload, self.workload_provider)+ except HTTPException:+ raise+ except Exception as exc:+ logger.exception("Error getting sandbox diagnostic context %s", sandbox_id)+ raise _build_k8s_api_error("get sandbox diagnostic context", exc) from excmetadata = workload.get("metadata", {}) if isinstance(workload, dict) else workload.metadataname = metadata.get("name") if isinstance(metadata, dict) else metadata.nameuid = metadata.get("uid") if isinstance(metadata, dict) else metadata.uiddiff --git a/server/tests/test_diagnostic_context.py b/server/tests/test_diagnostic_context.pyindex 134f9b75d..1e0be638d 100644--- a/server/tests/test_diagnostic_context.py+++ b/server/tests/test_diagnostic_context.py@@ -149,6 +149,47 @@ def test_fast_context_uses_lifecycle_identity():service.get_sandbox.assert_called_once_with("fsb-1")[email protected]("failure_stage", ["namespace", "workload", "mapping"])+def test_kubernetes_context_normalizes_errors(client, auth_headers, monkeypatch, failure_stage):+ service = K8sDiagnosticsMixin()+ service._resolve_namespace_for_lookup = Mock(return_value="tenant-ns")+ service.workload_provider = Mock()+ owned = Mock(return_value={"metadata": {}})+ mapper = Mock()+ monkeypatch.setattr(+ "opensandbox_server.services.k8s.k8s_diagnostics._get_owned_workload_or_404", owned+ )+ monkeypatch.setattr(+ "opensandbox_server.services.k8s.k8s_diagnostics._build_sandbox_from_workload", mapper+ )+ stages = {"namespace": service._resolve_namespace_for_lookup, "workload": owned, "mapping": mapper}+ stages[failure_stage].side_effect = RuntimeError("API server unavailable")+ monkeypatch.setattr(devops, "sandbox_service", service)++ response = client.get("/v1/sandboxes/sbx-1/diagnostics/context", headers=auth_headers)++ assert response.status_code == 500+ assert response.json() == {+ "code": "KUBERNETES::API_ERROR",+ "message": "Failed to get sandbox diagnostic context: API server unavailable",+ }++[email protected]("status_code", [403, 404])+def test_kubernetes_context_preserves_http_errors(monkeypatch, status_code):+ service = K8sDiagnosticsMixin()+ service._resolve_namespace_for_lookup = Mock(return_value="tenant-ns")+ service.workload_provider = Mock()+ error = HTTPException(status_code, detail={"code": "TEST_ERROR", "message": "Unavailable"})+ monkeypatch.setattr(+ "opensandbox_server.services.k8s.k8s_diagnostics._get_owned_workload_or_404",+ Mock(side_effect=error),+ )+ with pytest.raises(HTTPException) as raised:+ service.get_sandbox_diagnostic_context("sbx-1")+ assert raised.value is error++@pytest.mark.parametrize("sandbox_id,backend", [("fsb-1", "fsb"), ("sbx-1", "kubernetes")])def test_composite_routes_context(sandbox_id, backend):k8s, fsb = Mock(), Mock()diff --git a/tests/csharp/OpenSandbox.E2ETests/DiagnosticsE2ETests.cs b/tests/csharp/OpenSandbox.E2ETests/DiagnosticsE2ETests.csindex d60f2371b..8bca7b673 100644--- a/tests/csharp/OpenSandbox.E2ETests/DiagnosticsE2ETests.cs+++ b/tests/csharp/OpenSandbox.E2ETests/DiagnosticsE2ETests.cs@@ -18,6 +18,7 @@ using Xunit;namespace OpenSandbox.E2ETests;+[Collection("CSharp E2E Tests")]public class DiagnosticsE2ETests : IClassFixture<DiagnosticsE2ETestFixture>{private readonly DiagnosticsE2ETestFixture _fixture;@@ -147,6 +148,7 @@ public sealed class DiagnosticsE2ETestFixture : IAsyncLifetimeif (_sandbox != null){try { await _sandbox.KillAsync(); }+ catch (SandboxApiException error) when (error.StatusCode == 404) { }finally { await _sandbox.DisposeAsync(); }}}