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

{opensandbox_server-0.2.2 → 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

{opensandbox_server-0.2.2 → 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.2
+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,13 @@ 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>=2.14.2
 Requires-Dist: python-multipart>=0.0.31

{opensandbox_server-0.2.2 → 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"},
     },
 )
@@ -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)
 

{opensandbox_server-0.2.2 → 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"},
     },
 )
@@ -580,5 +593,11 @@ 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
 
     return endpoint

{opensandbox_server-0.2.2 → opensandbox_server-0.2.3}/opensandbox_server/api/proxy.py

@@ -20,6 +20,7 @@ import hmac
 import logging
 from collections.abc import AsyncIterator, Mapping
 from typing import Optional
+from urllib.parse import urlsplit
 
 import anyio
 import httpx
@@ -27,6 +28,7 @@ import websockets
 from fastapi import APIRouter, Request, WebSocket, status
 from fastapi.exceptions import HTTPException
 from fastapi.responses import StreamingResponse
+from starlette.types import Receive, Scope, Send
 from starlette.websockets import WebSocketDisconnect
 from websockets.asyncio.client import ClientConnection
 from websockets.typing import Origin
@@ -52,6 +54,12 @@ HOP_BY_HOP_HEADERS = {
     "upgrade",
 }
 
+# Uvicorn adds this to client-facing responses. Forwarding the backend value as
+# well would produce a duplicate field on the wire.
+SERVER_GENERATED_RESPONSE_HEADERS = {
+    "server",
+}
+
 # Headers that shouldn't be forwarded to untrusted/internal backends
 SENSITIVE_HEADERS = {
     "authorization",
@@ -163,6 +171,30 @@ def _set_forwarded_headers(
         headers["X-Forwarded-For"] = request.client.host
 
 
+def _rewrite_proxy_location(
+    location: str,
+    request: Request,
+    sandbox_id: str,
+    port: int,
+) -> str:
+    """Keep root-relative redirects inside the current sandbox proxy route."""
+    if not location.startswith("/") or location.startswith("//"):
+        return location
+
+    proxy_suffix = f"/sandboxes/{sandbox_id}/proxy/{port}"
+    eip = (lifecycle.get_config().server.eip or "").strip().rstrip("/")
+    if eip:
+        external_url = eip if "://" in eip else f"//{eip}"
+        external_prefix = urlsplit(external_url).path.rstrip("/")
+        return f"{external_prefix}{proxy_suffix}{location}"
+
+    proxy_start = request.url.path.find(proxy_suffix)
+    if proxy_start < 0:
+        return location
+    proxy_path = request.url.path[: proxy_start + len(proxy_suffix)]
+    return f"{proxy_path}{location}"
+
+
 def _schedule_proxy_renew(request: Request | WebSocket, sandbox_id: str) -> None:
     proxy_renew = getattr(request.app.state, "proxy_renew_coordinator", None)
     if proxy_renew is not None:
@@ -207,19 +239,43 @@ async def _authenticate_websocket_tenant(websocket: WebSocket) -> bool:
     return True
 
 
+async def _close_backend_response(resp: httpx.Response) -> None:
+    """Return a streamed backend response to httpx's pool, even during cancellation."""
+    with anyio.CancelScope(shield=True):
+        await resp.aclose()
+
+
 async def _stream_backend_response(resp: httpx.Response) -> AsyncIterator[bytes]:
-    """
-    Yield backend body chunks without httpx content decoding and always close the response.
+    """Yield raw backend chunks so content-encoding still matches the body bytes."""
+    async for chunk in resp.aiter_raw():
+        yield chunk
+
+
+class _ProxyStreamingResponse(StreamingResponse):
+    """Streaming response that owns and always releases its httpx response."""
+
+    def __init__(
+        self,
+        resp: httpx.Response,
+        *,
+        status_code: int,
+        headers: Mapping[str, str],
+    ) -> None:
+        self._backend_response = resp
+        super().__init__(
+            content=_stream_backend_response(resp),
+            status_code=status_code,
+            headers=headers,
+        )
 
-    httpx requires ``await resp.aclose()`` for ``stream=True`` responses so connections
-    return to the pool; Starlette's StreamingResponse does not do this automatically.
-    Use ``aiter_raw`` so forwarded ``content-encoding`` headers still match the body bytes.
-    """
-    try:
-        async for chunk in resp.aiter_raw():
-            yield chunk
-    finally:
-        await resp.aclose()
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        try:
+            await super().__call__(scope, receive, send)
+        finally:
+            # The body iterator may never start if the downstream disconnects
+            # while Starlette sends response headers. Keep ownership here so
+            # that connection is still returned to the shared httpx pool.
+            await _close_backend_response(self._backend_response)
 
 
 def _verify_secure_access(endpoint: Endpoint, caller_headers: Mapping[str, str]) -> None:
@@ -295,25 +351,36 @@ async def _proxy_http_request(
 
         resp = await client.send(req, stream=True)
 
-        hop_by_hop = set(HOP_BY_HOP_HEADERS)
-        connection_header = resp.headers.get("connection")
-        if connection_header:
-            hop_by_hop.update(
-                header.strip().lower()
-                for header in connection_header.split(",")
-                if header.strip()
-            )
-        response_headers = {
-            key: value
-            for key, value in resp.headers.items()
-            if key.lower() not in hop_by_hop
-        }
+        try:
+            hop_by_hop = set(HOP_BY_HOP_HEADERS)
+            connection_header = resp.headers.get("connection")
+            if connection_header:
+                hop_by_hop.update(
+                    header.strip().lower()
+                    for header in connection_header.split(",")
+                    if header.strip()
+                )
+            response_header_exclusions = hop_by_hop | SERVER_GENERATED_RESPONSE_HEADERS
+            response_headers = {
+                key: (
+                    _rewrite_proxy_location(value, request, sandbox_id, port)
+                    if key.lower() == "location"
+                    else value
+                )
+                for key, value in resp.headers.items()
+                if key.lower() not in response_header_exclusions
+            }
 
-        return StreamingResponse(
-            content=_stream_backend_response(resp),
-            status_code=resp.status_code,
-            headers=response_headers,
-        )
+            return _ProxyStreamingResponse(
+                resp,
+                status_code=resp.status_code,
+                headers=response_headers,
+            )
+        except BaseException:
+            # Until ownership passes to _ProxyStreamingResponse, any failure
+            # after client.send() must release the acquired pool connection.
+            await _close_backend_response(resp)
+            raise
     except httpx.ConnectError as e:
         raise HTTPException(
             status_code=502,
@@ -495,10 +562,6 @@ async def _proxy_websocket_request(
         await _fail_client_websocket(websocket, status.WS_1011_INTERNAL_ERROR, "")
 
 
-@router.api_route(
-    "/sandboxes/{sandbox_id}/proxy/{port}",
-    methods=["GET", "POST", "PUT", "DELETE", "PATCH"],
-)
 async def proxy_sandbox_endpoint_root(
     request: Request,
     sandbox_id: str,
@@ -508,10 +571,6 @@ async def proxy_sandbox_endpoint_root(
     return await _proxy_http_request(request, sandbox_id, port, "")
 
 
-@router.api_route(
-    "/sandboxes/{sandbox_id}/proxy/{port}/{full_path:path}",
-    methods=["GET", "POST", "PUT", "DELETE", "PATCH"],
-)
 async def proxy_sandbox_endpoint_request(
     request: Request,
     sandbox_id: str,
@@ -522,6 +581,39 @@ async def proxy_sandbox_endpoint_request(
     return await _proxy_http_request(request, sandbox_id, port, full_path)
 
 
+_PROXY_HTTP_METHODS = ("GET", "POST", "PUT", "DELETE", "PATCH")
+
+# Keep the multi-method route first for runtime dispatch so 405 responses retain
+# the complete Allow header. The method-specific routes provide unique OpenAPI IDs.
+router.add_api_route(
+    "/sandboxes/{sandbox_id}/proxy/{port}",
+    proxy_sandbox_endpoint_root,
+    methods=list(_PROXY_HTTP_METHODS),
+    include_in_schema=False,
+)
+
+for _method in _PROXY_HTTP_METHODS:
+    router.add_api_route(
+        "/sandboxes/{sandbox_id}/proxy/{port}",
+        proxy_sandbox_endpoint_root,
+        methods=[_method],
+    )
+
+router.add_api_route(
+    "/sandboxes/{sandbox_id}/proxy/{port}/{full_path:path}",
+    proxy_sandbox_endpoint_request,
+    methods=list(_PROXY_HTTP_METHODS),
+    include_in_schema=False,
+)
+
+for _method in _PROXY_HTTP_METHODS:
+    router.add_api_route(
+        "/sandboxes/{sandbox_id}/proxy/{port}/{full_path:path}",
+        proxy_sandbox_endpoint_request,
+        methods=[_method],
+    )
+
+
 @router.websocket("/sandboxes/{sandbox_id}/proxy/{port}")
 async def proxy_sandbox_endpoint_root_websocket(
     websocket: WebSocket,

{opensandbox_server-0.2.2 → opensandbox_server-0.2.3}/opensandbox_server/api/schema.py

@@ -24,6 +24,7 @@ from typing import Dict, List, Literal, Optional
 
 from pydantic import BaseModel, Field, RootModel, model_validator
 
+from opensandbox_server.constants import OPENSANDBOX_LIFECYCLE
 
 # ============================================================================
 # Image Specification
@@ -138,6 +139,66 @@ class CredentialProxyConfig(BaseModel):
         populate_by_name = True
 
 
+class LifecycleHook(BaseModel):
+    """Command executed by execd before the user entrypoint starts."""
+
+    command: List[str] = Field(..., min_length=1)
+    timeout_seconds: Optional[int] = Field(None, alias="timeoutSeconds", ge=1, le=10800)
+
+    @model_validator(mode="after")
+    def validate_command(self) -> "LifecycleHook":
+        if not self.command[0].strip():
+            raise ValueError("Lifecycle hook command must not be empty.")
+        return self
+
+    class Config:
+        populate_by_name = True
+        extra = "forbid"
+
+
+class PeriodicLifecycleHook(BaseModel):
+    """Named command scheduled by execd while the sandbox is running."""
+
+    name: str = Field(..., min_length=1)
+    schedule: str = Field(..., min_length=1)
+    command: List[str] = Field(..., min_length=1)
+    timeout_seconds: Optional[int] = Field(None, alias="timeoutSeconds", ge=1, le=300)
+
+    @model_validator(mode="after")
+    def normalize_and_validate(self) -> "PeriodicLifecycleHook":
+        self.name = self.name.strip()
+        self.schedule = self.schedule.strip()
+        if not self.name:
+            raise ValueError("Periodic lifecycle hook name must not be blank.")
+        if not self.schedule:
+            raise ValueError("Periodic lifecycle hook schedule must not be blank.")
+        if not self.command[0].strip():
+            raise ValueError("Periodic lifecycle hook command must not be empty.")
+        return self
+
+    class Config:
+        populate_by_name = True
+        extra = "forbid"
+
+
+class SandboxLifecycle(BaseModel):
+    """Extensible lifecycle configuration transported internally to execd."""
+
+    pre_start: Optional[LifecycleHook] = Field(None, alias="preStart")
+    periodic: Optional[List[PeriodicLifecycleHook]] = None
+
+    @model_validator(mode="after")
+    def validate_periodic_names(self) -> "SandboxLifecycle":
+        names = [hook.name for hook in self.periodic or []]
+        if len(names) != len(set(names)):
+            raise ValueError("Periodic lifecycle hook names must be unique.")
+        return self
+
+    class Config:
+        populate_by_name = True
+        extra = "forbid"
+
+
 # ============================================================================
 # Volume Definitions
 # ============================================================================
@@ -443,6 +504,10 @@ class CreateSandboxRequest(BaseModel):
         None,
         description="Custom key-value metadata for management, filtering, and tagging",
     )
+    lifecycle: Optional[SandboxLifecycle] = Field(
+        None,
+        description="Optional declarative lifecycle hooks executed by execd.",
+    )
     entrypoint: Optional[List[str]] = Field(
         None,
         min_length=1,
@@ -493,10 +558,18 @@ class CreateSandboxRequest(BaseModel):
 
     @model_validator(mode="after")
     def validate_source_and_entrypoint(self) -> "CreateSandboxRequest":
+        if self.env and OPENSANDBOX_LIFECYCLE in self.env:
+            raise ValueError(
+                f"Environment variable '{OPENSANDBOX_LIFECYCLE}' is reserved. "
+                "Use the lifecycle request field instead."
+            )
+
         # When poolRef is set, image/snapshotId/entrypoint/resourceLimits are
         # all defined in the Pool CRD and not required from the caller.
         has_pool_ref = bool((self.extensions or {}).get("poolRef", "").strip())
         if has_pool_ref:
+            if self.lifecycle is not None:
+                raise ValueError("lifecycle cannot be used together with poolRef.")
             # Reject conflicting fields that would be ignored in pool mode
             if bool((self.snapshot_id or "").strip()):
                 raise ValueError("snapshotId cannot be used together with poolRef.")
@@ -566,6 +639,17 @@ class CreateSandboxResponse(BaseModel):
         populate_by_name = True
 
 
+class AllocationSummary(BaseModel):
+    """Current runtime-confirmed pool allocation summary."""
+    mode: Literal["pool"] = Field("pool", description="Allocation mode.")
+    pool_ref: str = Field(..., alias="poolRef", description="Concrete pool reference currently allocated.")
+    state: Literal["allocated"] = Field("allocated", description="Current confirmed allocation state.")
+
+    class Config:
+        populate_by_name = True
+        extra = "forbid"
+
+
 class Sandbox(BaseModel):
     """
     Runtime execution environment provisioned from a container image.
@@ -592,6 +676,14 @@ class Sandbox(BaseModel):
         None,
         description="Opaque extension data restored from provider-specific storage",
     )
+    allocation: Optional[AllocationSummary] = Field(
+        None,
+        description=(
+            "Current runtime-confirmed pool allocation summary. Omitted unless the runtime confirms "
+            "an active pool allocation; it is not a request echo, allocation history, readiness signal, "
+            "or Kubernetes introspection result."
+        ),
+    )
     entrypoint: Optional[List[str]] = Field(None, description="The command to execute as the sandbox's entry process")
     expires_at: Optional[datetime] = Field(
         None,

{opensandbox_server-0.2.2 → opensandbox_server-0.2.3}/opensandbox_server/cli.py

@@ -305,6 +305,7 @@ def main() -> None:
         backlog=server_cfg.backlog,
         loop=server_cfg.loop,
         http=server_cfg.http,
+        date_header=False,
         timeout_graceful_shutdown=server_cfg.timeout_graceful_shutdown,
     )