Skip to content

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.ts
index 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.ts
index 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.ts
index 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.mjs
index 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.py
index 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 annotations
import re
import time
+from typing import Any
from docker.errors import DockerException
from 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.py
index 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.py
index 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 annotations
import re
+import logging
from typing import Any
from 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_error
from 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 exc
metadata = workload.get("metadata", {}) if isinstance(workload, dict) else workload.metadata
name = metadata.get("name") if isinstance(metadata, dict) else metadata.name
uid = metadata.get("uid") if isinstance(metadata, dict) else metadata.uid
diff --git a/server/tests/test_diagnostic_context.py b/server/tests/test_diagnostic_context.py
index 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.cs
index 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 : IAsyncLifetime
if (_sandbox != null)
{
try { await _sandbox.KillAsync(); }
+ catch (SandboxApiException error) when (error.StatusCode == 404) { }
finally { await _sandbox.DisposeAsync(); }
}
}