opensandbox-server 0.2.1__tar.gz → 0.2.3__tar.gz

{opensandbox_server-0.2.1 → opensandbox_server-0.2.3}/.gitignore

@@ -269,6 +269,19 @@ nbdist/
 generated/
 **/generated/**
 
+# fleets FastPath gRPC stubs are committed intentionally (deterministic protoc
+# output; the server package needs them at install time, so they are checked
+# in rather than regenerated).
+!server/opensandbox_server/services/fleets/generated/
+!server/opensandbox_server/services/fleets/generated/**
+server/opensandbox_server/services/fleets/generated/__pycache__/
+
+# execd eBPF kernel BTF dumps (bpf2go build-time only, never committed —
+# see components/execd/pkg/ebpf/prog/audit.bpf.c; regenerate with:
+#   bpftool btf dump file /sys/kernel/btf/vmlinux format c > .../vmlinux.h)
+components/execd/pkg/ebpf/prog/vmlinux.h
+components/execd/pkg/ebpf/prog/vmlinux_*.h
+
 # gVisor runtime binaries (downloaded dynamically)
 kubernetes/test/kind/gvisor/runsc
 kubernetes/test/kind/gvisor/containerd-shim-runsc-v1
@@ -276,3 +289,4 @@ bin/
 obj/
 
 .qoder/
+/.vs

{opensandbox_server-0.2.1 → opensandbox_server-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: opensandbox-server
-Version: 0.2.1
+Version: 0.2.3
 Summary: FastAPI control plane for OpenSandbox that manages sandbox lifecycle on Docker (ready) and Kubernetes (planned) runtimes.
 Project-URL: Homepage, https://github.com/opensandbox-group/OpenSandbox
 Project-URL: Repository, https://github.com/opensandbox-group/OpenSandbox
@@ -24,11 +24,16 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: docker
 Requires-Dist: fastapi>=0.137.0
+Requires-Dist: grpcio>=1.83.0
 Requires-Dist: httpx[socks]
 Requires-Dist: kubernetes
+Requires-Dist: opentelemetry-api
+Requires-Dist: opentelemetry-exporter-otlp-proto-http
+Requires-Dist: opentelemetry-sdk
+Requires-Dist: protobuf>=7.35.1
 Requires-Dist: pydantic
-Requires-Dist: pydantic-settings
-Requires-Dist: python-multipart>=0.0.30
+Requires-Dist: pydantic-settings>=2.14.2
+Requires-Dist: python-multipart>=0.0.31
 Requires-Dist: pyyaml
 Requires-Dist: redis>=5
 Requires-Dist: starlette>=1.3.1

{opensandbox_server-0.2.1 → opensandbox_server-0.2.3}/opensandbox_server/api/devops.py

@@ -15,10 +15,9 @@
 """
 API routes for OpenSandbox DevOps diagnostics.
 
-Requests that include `scope` target the stable Diagnostics API. The open-source
-server has not implemented that API yet, so these requests return a uniform
-not-implemented error. Requests without `scope` preserve the deprecated DevOps
-plain-text behavior for legacy humans, agents, and CLI clients.
+Requests that include ``scope`` target the stable Diagnostics API and return an
+inline JSON descriptor. Requests without ``scope`` preserve the deprecated
+DevOps plain-text behavior for legacy humans, agents, and CLI clients.
 """
 
 import logging
@@ -28,19 +27,29 @@ from fastapi import APIRouter, HTTPException, Query, status
 from fastapi.responses import JSONResponse, PlainTextResponse
 
 from opensandbox_server.api.lifecycle import sandbox_service
+from opensandbox_server.services.diagnostics import DiagnosticResult
 
 logger = logging.getLogger(__name__)
 router = APIRouter(tags=["DevOps"])
 
 
-def _diagnostics_not_implemented_response() -> JSONResponse:
-    return JSONResponse(
-        status_code=status.HTTP_501_NOT_IMPLEMENTED,
-        content={
-            "code": "DIAGNOSTICS_NOT_IMPLEMENTED",
-            "message": "The stable Diagnostics API is not implemented by this OpenSandbox server.",
-        },
-    )
+def _diagnostic_inline_response(
+    result: DiagnosticResult,
+) -> JSONResponse:
+    """Build a Diagnostics API descriptor for inline plain-text content."""
+    payload: dict[str, object] = {
+        "sandboxId": result.sandbox_id,
+        "kind": result.kind,
+        "scope": result.scope,
+        "delivery": "inline",
+        "contentType": "text/plain; charset=utf-8",
+        "content": result.content,
+        "contentLength": len(result.content.encode("utf-8")),
+        "truncated": result.truncated,
+    }
+    if result.warnings:
+        payload["warnings"] = list(result.warnings)
+    return JSONResponse(status_code=status.HTTP_200_OK, content=payload)
 
 
 def _deprecated_plain_text_response(content: str) -> PlainTextResponse:
@@ -56,13 +65,10 @@ def _deprecated_plain_text_response(content: str) -> PlainTextResponse:
     status_code=status.HTTP_200_OK,
     responses={
         200: {
-            "description": "Deprecated plain-text logs when scope is omitted",
-            "content": {"text/plain": {}},
-        },
-        501: {
-            "description": "Stable Diagnostics API is not implemented by this server",
-            "content": {"application/json": {}},
+            "description": "Stable JSON descriptor, or deprecated text when scope is omitted",
+            "content": {"application/json": {}, "text/plain": {}},
         },
+        400: {"description": "Unsupported diagnostics scope"},
         404: {"description": "Sandbox not found"},
     },
 )
@@ -84,11 +90,21 @@ def get_sandbox_logs(
         deprecated=True,
         description="Deprecated plain-text logs only. Only return logs newer than this duration (e.g. 10m, 1h).",
     ),
+    container: Optional[str] = Query(
+        None,
+        deprecated=True,
+        description=(
+            "Deprecated plain-text logs only. Container name to read logs from. "
+            "Defaults to the canonical user container (typically 'sandbox') when "
+            "the runtime supports multi-container pods."
+        ),
+    ),
 ) -> JSONResponse | PlainTextResponse:
     """Retrieve diagnostic logs for a sandbox."""
     if scope is not None:
-        return _diagnostics_not_implemented_response()
-    text = sandbox_service.get_sandbox_logs(sandbox_id, tail=tail, since=since)
+        result = sandbox_service.get_sandbox_log_diagnostics(sandbox_id, scope)
+        return _diagnostic_inline_response(result)
+    text = sandbox_service.get_sandbox_logs(sandbox_id, tail=tail, since=since, container=container)
     return _deprecated_plain_text_response(text)
 
 
@@ -114,13 +130,10 @@ def get_sandbox_inspect(sandbox_id: str) -> PlainTextResponse:
     status_code=status.HTTP_200_OK,
     responses={
         200: {
-            "description": "Deprecated plain-text events when scope is omitted",
-            "content": {"text/plain": {}},
-        },
-        501: {
-            "description": "Stable Diagnostics API is not implemented by this server",
-            "content": {"application/json": {}},
+            "description": "Stable JSON descriptor, or deprecated text when scope is omitted",
+            "content": {"application/json": {}, "text/plain": {}},
         },
+        400: {"description": "Unsupported diagnostics scope"},
         404: {"description": "Sandbox not found"},
     },
 )
@@ -140,7 +153,8 @@ def get_sandbox_events(
 ) -> JSONResponse | PlainTextResponse:
     """Retrieve diagnostic events for a sandbox."""
     if scope is not None:
-        return _diagnostics_not_implemented_response()
+        result = sandbox_service.get_sandbox_event_diagnostics(sandbox_id, scope)
+        return _diagnostic_inline_response(result)
     text = sandbox_service.get_sandbox_events(sandbox_id, limit=limit)
     return _deprecated_plain_text_response(text)
 

{opensandbox_server-0.2.1 → opensandbox_server-0.2.3}/opensandbox_server/api/lifecycle.py

@@ -45,7 +45,10 @@ from opensandbox_server.api.schema import (
     Snapshot,
     SnapshotFilter,
 )
-from opensandbox_server.services.constants import SandboxErrorCodes
+from opensandbox_server.services.constants import (
+    OPEN_SANDBOX_INGRESS_HEADER,
+    SandboxErrorCodes,
+)
 from opensandbox_server.services.factory import create_sandbox_service
 from opensandbox_server.services.snapshot_service import create_snapshot_service
 
@@ -71,6 +74,16 @@ snapshot_service = create_snapshot_service(sandbox_service)
         400: {"model": ErrorResponse, "description": "The request was invalid or malformed"},
         401: {"model": ErrorResponse, "description": "Authentication credentials are missing or invalid"},
         409: {"model": ErrorResponse, "description": "The operation conflicts with the current state"},
+        429: {
+            "model": ErrorResponse,
+            "description": "Pool capacity remained unavailable before the acquisition timeout",
+            "headers": {
+                "Retry-After": {
+                    "description": "Suggested delay in seconds before retrying",
+                    "schema": {"type": "integer", "minimum": 1},
+                }
+            },
+        },
         500: {"model": ErrorResponse, "description": "An unexpected server error occurred"},
     },
 )
@@ -431,6 +444,7 @@ def create_snapshot(
 )
 def list_snapshots(
     sandbox_id: Optional[str] = Query(None, alias="sandboxId", description="Filter snapshots by source sandbox identifier"),
+    name: Optional[str] = Query(None, description="Filter snapshots by exact snapshot name"),
     state: Optional[List[str]] = Query(None, description="Filter by snapshot lifecycle state. Pass multiple times for OR logic."),
     page: int = Query(1, ge=1, description="Page number for pagination"),
     page_size: int = Query(20, ge=1, le=200, alias="pageSize", description="Number of items per page"),
@@ -440,7 +454,7 @@ def list_snapshots(
     List snapshots with optional filtering and pagination.
     """
     request = ListSnapshotsRequest(
-        filter=SnapshotFilter(sandboxId=sandbox_id, state=state),
+        filter=SnapshotFilter(sandboxId=sandbox_id, name=name, state=state),
         pagination=PaginationRequest(page=page, pageSize=page_size),
     )
     return snapshot_service.list_snapshots(request)
@@ -564,12 +578,26 @@ def get_sandbox_endpoint(
     endpoint = sandbox_service.get_endpoint(sandbox_id, port, expires=expires)
 
     if use_server_proxy:
-        # Prefer configured external address when available.
-        base_url = str(request.base_url).rstrip("/")
+        # Prefer configured external address when available (it is the full
+        # external base and may already carry a path prefix).
         eip = (get_config().server.eip or "").strip().rstrip("/")
         if eip:
             base_url = eip
+        else:
+            # Reflect how the client reached this API: same host AND same mount
+            # prefix (the API is served both bare and under /v1). Dropping the
+            # prefix pointed proxied traffic at whatever backend owns the root
+            # path on shared hosts (breaking HTTP with redirects and WebSocket
+            # handshakes outright).
+            mount_prefix = request.url.path.split("/sandboxes/", 1)[0]
+            base_url = str(request.base_url).rstrip("/") + mount_prefix
         base_url = base_url.replace("https://", "").replace("http://", "")
         endpoint.endpoint = f"{base_url}/sandboxes/{sandbox_id}/proxy/{port}"
+        if endpoint.headers:
+            endpoint.headers = {
+                key: value
+                for key, value in endpoint.headers.items()
+                if key.lower() != OPEN_SANDBOX_INGRESS_HEADER.lower()
+            } or None
 
     return endpoint

opensandbox_server-0.2.3/opensandbox_server/api/metrics.py

@@ -0,0 +1,83 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""SDK metrics ingestion endpoints."""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Optional
+
+from fastapi import APIRouter, Header, Response, status
+
+from opensandbox_server.api.schema import MetricsEvent
+from opensandbox_server.integrations.otel import record_sandbox_create_duration
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["Metrics"])
+
+# OpenSandbox-Python-SDK/0.1.14, OpenSandbox-Go-SDK/0.1.0, OpenSandbox-JS-SDK/0.1.10
+_SDK_USER_AGENT_RE = re.compile(
+    r"OpenSandbox-([A-Za-z0-9]+)-SDK/([^\s]+)",
+    re.IGNORECASE,
+)
+
+
+def parse_sdk_user_agent(user_agent: Optional[str]) -> tuple[str, str]:
+    """Extract (language, version) from SDK User-Agent; fallback to unknown."""
+    if not user_agent:
+        return "unknown", "unknown"
+    match = _SDK_USER_AGENT_RE.search(user_agent)
+    if not match:
+        return "unknown", "unknown"
+    return match.group(1).lower(), match.group(2)
+
+
+@router.post(
+    "/metrics/events",
+    status_code=status.HTTP_204_NO_CONTENT,
+    responses={
+        400: {"description": "Bad request"},
+        401: {"description": "Unauthorized"},
+        500: {"description": "Internal server error"},
+    },
+)
+def report_metrics_event(
+    event: MetricsEvent,
+    x_request_id: Optional[str] = Header(None, alias="X-Request-ID"),
+    user_agent: Optional[str] = Header(None, alias="User-Agent"),
+) -> Response:
+    """Accept best-effort SDK metrics and record to OTEL (noop when disabled)."""
+    _ = x_request_id
+    if event.event_type == "sandbox.create":
+        sdk_language, sdk_version = parse_sdk_user_agent(user_agent)
+        record_sandbox_create_duration(
+            create_duration_ms=event.create_duration_ms,
+            sdk_language=sdk_language,
+            sdk_version=sdk_version,
+            success=event.success,
+        )
+        logger.debug(
+            "Accepted sandbox.create metrics event sandbox_id=%s image=%s "
+            "duration_ms=%s sdk=%s/%s success=%s",
+            event.sandbox_id,
+            event.image,
+            event.create_duration_ms,
+            sdk_language,
+            sdk_version,
+            event.success,
+        )
+    return Response(status_code=status.HTTP_204_NO_CONTENT)