opensandbox-server 0.2.2__tar.gz → 1.1.0__tar.gz

{opensandbox_server-0.2.2 → opensandbox_server-1.1.0}/.gitignore

@@ -269,6 +269,19 @@ nbdist/
 generated/
 **/generated/**
 
+# Fast Sandbox 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/fast_sandbox/generated/
+!server/opensandbox_server/services/fast_sandbox/generated/**
+server/opensandbox_server/services/fast_sandbox/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
@@ -277,3 +290,7 @@ obj/
 
 .qoder/
 /.vs
+
+# fast-sandbox pinned source checkout (materialized by
+# manifests/release/build-fast-sandbox.sh from manifests/third-party/fast-sandbox.commit)
+.fast-sandbox/

{opensandbox_server-0.2.2 → opensandbox_server-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: opensandbox-server
-Version: 0.2.2
+Version: 1.1.0
 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,14 @@ 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: psycopg[binary,pool]<4,>=3.2
 Requires-Dist: pydantic
 Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: python-multipart>=0.0.31

{opensandbox_server-0.2.2 → opensandbox_server-1.1.0}/opensandbox_server/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_server-0.2.2 → opensandbox_server-1.1.0}/opensandbox_server/api/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_server-0.2.2 → opensandbox_server-1.1.0}/opensandbox_server/api/devops.py

@@ -1,4 +1,4 @@
-# Copyright 2026 Alibaba Group Holding Ltd.
+# Copyright 2026 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -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"},
     },
 )
@@ -96,10 +102,9 @@ def get_sandbox_logs(
 ) -> 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, container=container
-    )
+        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)
 
 
@@ -125,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"},
     },
 )
@@ -151,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)
 
@@ -189,10 +192,9 @@ def get_sandbox_diagnostics_summary(
     except HTTPException:
         raise
     except Exception:
-        logger.exception("Failed to collect sandbox inspect diagnostics for %s", sandbox_id)
+        logger.exception(f"Failed to collect sandbox inspect diagnostics for {sandbox_id}")
         sections.append("[error] Failed to collect inspect diagnostics.")
 
-    # Events
     sections.append("")
     sections.append("-" * 40)
     sections.append("EVENTS")
@@ -202,20 +204,19 @@ def get_sandbox_diagnostics_summary(
     except HTTPException:
         raise
     except Exception:
-        logger.exception("Failed to collect sandbox event diagnostics for %s", sandbox_id)
+        logger.exception(f"Failed to collect sandbox event diagnostics for {sandbox_id}")
         sections.append("[error] Failed to collect event diagnostics.")
 
-    # Logs
     sections.append("")
     sections.append("-" * 40)
-    sections.append("LOGS (last {} lines)".format(tail))
+    sections.append(f"LOGS (last {tail} lines)")
     sections.append("-" * 40)
     try:
         sections.append(sandbox_service.get_sandbox_logs(sandbox_id, tail=tail))
     except HTTPException:
         raise
     except Exception:
-        logger.exception("Failed to collect sandbox log diagnostics for %s", sandbox_id)
+        logger.exception(f"Failed to collect sandbox log diagnostics for {sandbox_id}")
         sections.append("[error] Failed to collect log diagnostics.")
 
     return PlainTextResponse(content="\n".join(sections) + "\n")

{opensandbox_server-0.2.2 → opensandbox_server-1.1.0}/opensandbox_server/api/lifecycle.py

@@ -1,4 +1,4 @@
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -45,16 +45,22 @@ 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,
+    OPEN_SANDBOX_ORIGIN_HEADER,
+    SANDBOX_ORIGIN_TEMPLATE,
+    SandboxErrorCodes,
+)
 from opensandbox_server.services.factory import create_sandbox_service
+from opensandbox_server.services.snapshot_restore import resolve_sandbox_image_from_request
 from opensandbox_server.services.snapshot_service import create_snapshot_service
 
-# Initialize router
 router = APIRouter(tags=["Sandboxes"])
 
-# Initialize service based on configuration from config.toml (defaults to docker)
 sandbox_service = create_sandbox_service()
 snapshot_service = create_snapshot_service(sandbox_service)
+# React to snapshot status changes so rows converge without waiting on reads
+snapshot_service.start_background_sync()
 
 
 # ============================================================================
@@ -67,10 +73,21 @@ snapshot_service = create_snapshot_service(sandbox_service)
     response_model_exclude_none=True,
     status_code=status.HTTP_202_ACCEPTED,
     responses={
-        202: {"description": "Sandbox creation accepted for asynchronous provisioning"},
+        202: {"description": "Sandbox created and provisioned successfully"},
         400: {"model": ErrorResponse, "description": "The request was invalid or malformed"},
         401: {"model": ErrorResponse, "description": "Authentication credentials are missing or invalid"},
+        403: {"model": ErrorResponse, "description": "Namespace ResourceQuota exhausted — the sandbox was not admitted (KUBERNETES::QUOTA_EXCEEDED)"},
         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"},
     },
 )
@@ -96,10 +113,13 @@ async def create_sandbox(
         HTTPException: If sandbox creation scheduling fails
     """
     validate_extensions(request.extensions)
+    # Resolve snapshotId before backend routing: the owning backend recorded
+    # on the snapshot row selects the fsb vs pod backend for restores.
+    if not (request.template_id or "").strip():
+        request = await resolve_sandbox_image_from_request(request)
     return await sandbox_service.create_sandbox(request)
 
 
-# Search endpoint
 @router.get(
     "/sandboxes",
     response_model=ListSandboxesResponse,
@@ -134,12 +154,10 @@ def list_sandboxes(
     Returns:
         ListSandboxesResponse: Paginated list of sandboxes
     """
-    # Parse metadata query string into dictionary
     metadata_dict = {}
     if metadata:
         from urllib.parse import parse_qsl
         try:
-            # Parse query string format: key=value&key2=value2
             # strict_parsing=True rejects malformed segments like "a=1&broken"
             parsed = parse_qsl(metadata, keep_blank_values=True, strict_parsing=True)
             metadata_dict = dict(parsed)
@@ -150,7 +168,6 @@ def list_sandboxes(
                 detail={"code": "INVALID_METADATA_FORMAT", "message": f"Invalid metadata format: {str(e)}"}
             )
 
-    # Construct request object
     request = ListSandboxesRequest(
         filter=SandboxFilter(state=state, metadata=metadata_dict if metadata_dict else None),
         pagination=PaginationRequest(page=page, pageSize=page_size)
@@ -158,9 +175,8 @@ def list_sandboxes(
 
     import logging
     logger = logging.getLogger(__name__)
-    logger.info("ListSandboxes: %s", request.filter)
+    logger.info(f"ListSandboxes: {request.filter}")
 
-    # Delegate to the service layer for filtering and pagination
     return sandbox_service.list_sandboxes(request)
 
 
@@ -196,7 +212,6 @@ def get_sandbox(
     Raises:
         HTTPException: If sandbox not found or access denied
     """
-    # Delegate to the service layer for sandbox lookup
     return sandbox_service.get_sandbox(sandbox_id)
 
 
@@ -258,7 +273,6 @@ def delete_sandbox(
     Raises:
         HTTPException: If sandbox not found or deletion fails
     """
-    # Delegate to the service layer for deletion
     sandbox_service.delete_sandbox(sandbox_id)
     return Response(status_code=status.HTTP_204_NO_CONTENT)
 
@@ -299,7 +313,6 @@ def pause_sandbox(
     Raises:
         HTTPException: If sandbox not found or cannot be paused
     """
-    # Delegate to the service layer for pause orchestration
     sandbox_service.pause_sandbox(sandbox_id)
     return Response(status_code=status.HTTP_202_ACCEPTED)
 
@@ -336,7 +349,6 @@ def resume_sandbox(
     Raises:
         HTTPException: If sandbox not found or cannot be resumed
     """
-    # Delegate to the service layer for resume orchestration
     sandbox_service.resume_sandbox(sandbox_id)
     return Response(status_code=status.HTTP_202_ACCEPTED)
 
@@ -377,7 +389,6 @@ def renew_sandbox_expiration(
     Raises:
         HTTPException: If sandbox not found or renewal fails
     """
-    # Delegate to the service layer for expiration updates
     return sandbox_service.renew_expiration(sandbox_id, request)
 
 
@@ -520,6 +531,7 @@ def get_sandbox_endpoint(
     use_server_proxy: bool = Query(False, description="Whether to return a server-proxied URL"),
     expires: Optional[int] = Query(None, description="Request a signed route token with this Unix epoch second expiration. Requires ingress gateway with secure_access configured."),
     x_request_id: Optional[str] = Header(None, alias="X-Request-ID", description="Unique request identifier for tracing"),
+    response: Response = None,  # type: ignore[assignment]
 ) -> Endpoint:
     """
     Get sandbox access endpoint.
@@ -561,7 +573,6 @@ def get_sandbox_endpoint(
             },
         )
 
-    # Delegate to the service layer for endpoint resolution
     endpoint = sandbox_service.get_endpoint(sandbox_id, port, expires=expires)
 
     if use_server_proxy:
@@ -580,5 +591,19 @@ def get_sandbox_endpoint(
             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
+
+    # Tell clients the origin of this sandbox. fsb sandboxes (id prefix,
+    # mirroring CompositeSandboxService._backend routing) run on golden-image
+    # templates and have no sandbox-side egress sidecar; the value space may
+    # grow (image/snapshot) as server-side origin tracking matures. Clients
+    # treat a missing/unknown value as "not template".
+    if response is not None and sandbox_id.startswith("fsb-"):
+        response.headers[OPEN_SANDBOX_ORIGIN_HEADER] = SANDBOX_ORIGIN_TEMPLATE
 
     return endpoint

{opensandbox_server-0.2.2 → opensandbox_server-1.1.0}/opensandbox_server/api/metrics.py

@@ -1,4 +1,4 @@
-# Copyright 2026 Alibaba Group Holding Ltd.
+# Copyright 2026 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -71,13 +71,8 @@ def report_metrics_event(
             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,
+            f"Accepted sandbox.create metrics event sandbox_id={event.sandbox_id} "
+            f"image={event.image} duration_ms={event.create_duration_ms} "
+            f"sdk={sdk_language}/{sdk_version} success={event.success}"
         )
     return Response(status_code=status.HTTP_204_NO_CONTENT)

opensandbox_server-1.1.0/opensandbox_server/api/network_policy.py

@@ -0,0 +1,60 @@
+# Copyright 2026 The OpenSandbox Authors
+# 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
+
+"""Read/replace/patch policy intent without exposing the Fastlet's loopback handler."""
+
+import asyncio
+
+from fastapi import APIRouter, HTTPException, Request
+
+from opensandbox_server.api import lifecycle
+from opensandbox_server.api.proxy import _proxy_http_request
+from opensandbox_server.api.schema import NetworkPolicy, NetworkRule
+from opensandbox_server.services.composite_service import CompositeSandboxService
+from opensandbox_server.services.fast_sandbox import FastSandboxService
+
+router = APIRouter(tags=["Sandboxes"])
+
+
+def _fsb_service():
+    service = lifecycle.sandbox_service
+    if not isinstance(service, (FastSandboxService, CompositeSandboxService)):
+        raise HTTPException(404, detail="Fsb sandbox not found.")
+    return service
+
+
+@router.get("/sandboxes/{sandbox_id}/networkpolicy")
+async def get_network_policy(request: Request, sandbox_id: str):
+    if sandbox_id.startswith("fsb-"):
+        return await asyncio.to_thread(_fsb_service().get_network_policy, sandbox_id)
+    return await _proxy_http_request(request, sandbox_id, 18080, "policy", internal=True)
+
+
+@router.put("/sandboxes/{sandbox_id}/networkpolicy")
+async def replace_network_policy(request: Request, sandbox_id: str, policy: NetworkPolicy):
+    if sandbox_id.startswith("fsb-"):
+        return await asyncio.to_thread(_fsb_service().replace_network_policy, sandbox_id, policy)
+    return await _proxy_http_request(request, sandbox_id, 18080, "policy", internal=True)
+
+
+@router.patch("/sandboxes/{sandbox_id}/networkpolicy")
+async def patch_network_policy(request: Request, sandbox_id: str, rules: list[NetworkRule]):
+    """Merge rules into the persisted policy (sidecar PATCH semantics).
+
+    Incoming rules replace existing rules with the same target in place;
+    the first rule per target in the payload wins; the current
+    defaultAction is preserved.
+    """
+    if sandbox_id.startswith("fsb-"):
+        return await asyncio.to_thread(_fsb_service().patch_network_policy, sandbox_id, rules)
+    return await _proxy_http_request(request, sandbox_id, 18080, "policy", internal=True)
+
+
+@router.delete("/sandboxes/{sandbox_id}/networkpolicy")
+async def delete_network_policy(request: Request, sandbox_id: str, targets: list[str]):
+    """Remove rules by target (idempotent); the current defaultAction is preserved."""
+    if sandbox_id.startswith("fsb-"):
+        return await asyncio.to_thread(_fsb_service().delete_network_policy_rules, sandbox_id, targets)
+    return await _proxy_http_request(request, sandbox_id, 18080, "policy", internal=True)

{opensandbox_server-0.2.2 → opensandbox_server-1.1.0}/opensandbox_server/api/pool.py

@@ -1,4 +1,4 @@
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -70,10 +70,6 @@ def _get_pool_service():
     return PoolService(k8s_client, namespace=config.kubernetes.namespace)
 
 
-# ============================================================================
-# Pool CRUD Endpoints
-# ============================================================================
-
 @router.post(
     "/pools",
     response_model=PoolResponse,