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

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

@@ -276,3 +276,4 @@ bin/
 obj/
 
 .qoder/
+/.vs

opensandbox_server-0.2.2/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: opensandbox-server
+Version: 0.2.2
+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
+Project-URL: Issues, https://github.com/opensandbox-group/OpenSandbox/issues
+Author-email: OpenSandbox Team <pangjiping.pjp@alibaba-inc.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: control-plane,fastapi,opensandbox,sandbox,server
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: docker
+Requires-Dist: fastapi>=0.137.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: pydantic
+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
+Requires-Dist: tomli; python_version < '3.11'
+Requires-Dist: uvicorn[standard]
+Requires-Dist: websockets>=14.0
+Description-Content-Type: text/markdown
+
+# OpenSandbox Server
+
+Documentation: [docs/components/server.md](../docs/components/server.md)
+

opensandbox_server-0.2.2/README.md

@@ -0,0 +1,4 @@
+# OpenSandbox Server
+
+Documentation: [docs/components/server.md](../docs/components/server.md)
+

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

@@ -84,11 +84,22 @@ 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)
+    text = sandbox_service.get_sandbox_logs(
+        sandbox_id, tail=tail, since=since, container=container
+    )
     return _deprecated_plain_text_response(text)
 
 

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

@@ -431,6 +431,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 +441,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,11 +565,19 @@ 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}"
 

opensandbox_server-0.2.2/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)

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

@@ -16,6 +16,7 @@
 HTTP and WebSocket proxy routes for reaching services inside sandboxes via the lifecycle API.
 """
 
+import hmac
 import logging
 from collections.abc import AsyncIterator, Mapping
 from typing import Optional
@@ -34,6 +35,8 @@ from opensandbox_server.api import lifecycle
 from opensandbox_server.api.schema import Endpoint
 from opensandbox_server.middleware.auth import SANDBOX_API_KEY_HEADER
 from opensandbox_server.services.constants import OPEN_SANDBOX_EGRESS_AUTH_HEADER, OPEN_SANDBOX_SECURE_ACCESS_HEADER
+from opensandbox_server.tenants.context import set_current_tenant
+from opensandbox_server.tenants.provider import TenantProviderUnavailable
 
 logger = logging.getLogger(__name__)
 
@@ -54,6 +57,16 @@ SENSITIVE_HEADERS = {
     "authorization",
     "cookie",
     SANDBOX_API_KEY_HEADER.lower(),
+    OPEN_SANDBOX_SECURE_ACCESS_HEADER.lower(),
+}
+
+FORWARDED_HEADERS = {
+    "forwarded",
+    "x-forwarded-for",
+    "x-forwarded-host",
+    "x-forwarded-port",
+    "x-forwarded-proto",
+    "x-real-ip",
 }
 
 # Handled by websockets on the outbound handshake; do not duplicate on additional_headers
@@ -103,7 +116,7 @@ def _filter_proxy_headers(
     Endpoint-resolved headers are merged for routing, except secure-access
     credentials which callers must explicitly provide on server-proxy requests.
     """
-    excluded = set(HOP_BY_HOP_HEADERS) | set(SENSITIVE_HEADERS)
+    excluded = set(HOP_BY_HOP_HEADERS) | set(SENSITIVE_HEADERS) | set(FORWARDED_HEADERS)
     if extra_excluded:
         excluded.update(extra_excluded)
     if connection_header:
@@ -121,7 +134,7 @@ def _filter_proxy_headers(
         endpoint_header_excluded = {
             OPEN_SANDBOX_SECURE_ACCESS_HEADER.lower(),
             OPEN_SANDBOX_EGRESS_AUTH_HEADER.lower(),
-        }
+        } | FORWARDED_HEADERS
         forwarded.update(
             {
                 key: value
@@ -132,12 +145,68 @@ def _filter_proxy_headers(
     return forwarded
 
 
+def _set_forwarded_headers(
+    headers: dict[str, str], request: Request | WebSocket
+) -> None:
+    """Rebuild proxy headers from the connection observed by this server."""
+    scheme = request.url.scheme.lower()
+    if scheme == "ws":
+        scheme = "http"
+    elif scheme == "wss":
+        scheme = "https"
+    headers["X-Forwarded-Proto"] = scheme
+
+    inbound_host = request.headers.get("host", "")
+    if inbound_host:
+        headers["X-Forwarded-Host"] = inbound_host
+    if request.client:
+        headers["X-Forwarded-For"] = request.client.host
+
+
 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:
         proxy_renew.schedule(sandbox_id)
 
 
+async def _authenticate_websocket_tenant(websocket: WebSocket) -> bool:
+    """Authenticate WebSocket connections in multi-tenant mode.
+
+    BaseHTTPMiddleware only intercepts HTTP requests, so WebSocket
+    connections must be authenticated here to establish tenant context.
+    Returns True if the request is authorized (or single-tenant mode).
+    """
+    import asyncio
+
+    provider = getattr(websocket.app.state, "tenant_provider", None)
+    if provider is None:
+        return True
+
+    api_key = websocket.headers.get(SANDBOX_API_KEY_HEADER)
+    if not api_key:
+        await _fail_client_websocket(
+            websocket, status.WS_1008_POLICY_VIOLATION, "missing API key"
+        )
+        return False
+
+    try:
+        tenant = await asyncio.to_thread(provider.lookup, api_key)
+    except TenantProviderUnavailable:
+        await _fail_client_websocket(
+            websocket, status.WS_1011_INTERNAL_ERROR, "tenant provider unavailable"
+        )
+        return False
+
+    if tenant is None:
+        await _fail_client_websocket(
+            websocket, status.WS_1008_POLICY_VIOLATION, "invalid API key"
+        )
+        return False
+
+    set_current_tenant(tenant)
+    return True
+
+
 async def _stream_backend_response(resp: httpx.Response) -> AsyncIterator[bytes]:
     """
     Yield backend body chunks without httpx content decoding and always close the response.
@@ -153,14 +222,47 @@ async def _stream_backend_response(resp: httpx.Response) -> AsyncIterator[bytes]
         await resp.aclose()
 
 
+def _verify_secure_access(endpoint: Endpoint, caller_headers: Mapping[str, str]) -> None:
+    """Enforce OpenSandbox-Secure-Access validation on server-proxy requests.
+
+    When endpoint resolution returns a secure-access token, the caller must
+    supply the same header value.  Raises 401 for missing or mismatched tokens.
+    Uses constant-time comparison to avoid timing side-channels.
+    """
+    if not endpoint.headers:
+        return
+    expected_token = endpoint.headers.get(OPEN_SANDBOX_SECURE_ACCESS_HEADER)
+    if not expected_token:
+        return
+    caller_token = None
+    for key, value in caller_headers.items():
+        if key.lower() == OPEN_SANDBOX_SECURE_ACCESS_HEADER.lower():
+            caller_token = value
+            break
+    if not caller_token or not hmac.compare_digest(
+        caller_token.encode(), expected_token.encode()
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail={
+                "code": "MISSING_OR_INVALID_SECURE_ACCESS",
+                "message": (
+                    "This sandbox requires the "
+                    f"{OPEN_SANDBOX_SECURE_ACCESS_HEADER} header for access."
+                ),
+            },
+        )
+
+
 async def _proxy_http_request(
     request: Request,
     sandbox_id: str,
     port: int,
     full_path: str,
 ) -> StreamingResponse:
-    _schedule_proxy_renew(request, sandbox_id)
     endpoint = lifecycle.sandbox_service.get_endpoint(sandbox_id, port, resolve_internal=True)
+    _verify_secure_access(endpoint, request.headers)
+    _schedule_proxy_renew(request, sandbox_id)
     query_string = request.url.query
     target_url = _build_proxy_target_url(endpoint, full_path, query_string, websocket=False)
     client: httpx.AsyncClient = request.app.state.http_client
@@ -178,19 +280,9 @@ async def _proxy_http_request(
             endpoint.headers,
             connection_header=request.headers.get("connection"),
         )
-        # Inject standard reverse-proxy headers. Check for existing values
-        # case-insensitively so an already-present header with any casing
-        # (e.g. lowercase "x-forwarded-proto" from an upstream edge) is
-        # preserved and we don't emit a duplicate with different casing,
-        # which would break chain-safe semantics for downstream backends.
-        existing_lower = {key.lower() for key in headers}
-        if "x-forwarded-proto" not in existing_lower:
-            headers["X-Forwarded-Proto"] = request.url.scheme
-        inbound_host = request.headers.get("host", "")
-        if inbound_host and "x-forwarded-host" not in existing_lower:
-            headers["X-Forwarded-Host"] = inbound_host
-        if request.client and "x-forwarded-for" not in existing_lower:
-            headers["X-Forwarded-For"] = request.client.host
+        # Forwarded headers are stripped above and rebuilt from the connection
+        # observed by this trusted proxy, so clients cannot spoof transport state.
+        _set_forwarded_headers(headers, request)
 
         stream_body = request.method in ("POST", "PUT", "PATCH", "DELETE")
         req = client.build_request(
@@ -307,7 +399,8 @@ async def _proxy_websocket_request(
     port: int,
     full_path: str,
 ) -> None:
-    _schedule_proxy_renew(websocket, sandbox_id)
+    if not await _authenticate_websocket_tenant(websocket):
+        return
 
     try:
         endpoint = lifecycle.sandbox_service.get_endpoint(sandbox_id, port, resolve_internal=True)
@@ -325,6 +418,17 @@ async def _proxy_websocket_request(
         )
         return
 
+    try:
+        _verify_secure_access(endpoint, dict(websocket.headers))
+    except HTTPException:
+        await _fail_client_websocket(
+            websocket,
+            status.WS_1008_POLICY_VIOLATION,
+            "Missing or invalid secure-access token",
+        )
+        return
+
+    _schedule_proxy_renew(websocket, sandbox_id)
     query_string = websocket.url.query or ""
     target_url = _build_proxy_target_url(
         endpoint,
@@ -338,6 +442,7 @@ async def _proxy_websocket_request(
         extra_excluded=WEBSOCKET_HANDSHAKE_HEADERS,
         connection_header=websocket.headers.get("connection"),
     )
+    _set_forwarded_headers(headers, websocket)
     subprotocols = list(websocket.scope.get("subprotocols", []))
     raw_origin = websocket.headers.get("origin")
     origin: Origin | None = Origin(raw_origin) if raw_origin else None

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

@@ -198,9 +198,9 @@ class PVC(BaseModel):
         description=(
             "When true, the volume is automatically removed when the sandbox is "
             "deleted. Only applies to volumes that were auto-created by the server "
-            "(Docker only). Pre-existing volumes are never removed. Has no effect "
-            "on Kubernetes PVCs, whose lifecycle is managed by the StorageClass "
-            "reclaim policy."
+            "on this request; pre-existing volumes are never removed. For "
+            "Kubernetes, the resulting PVC delete then triggers the bound PV's "
+            "StorageClass reclaim policy (Retain/Delete)."
         ),
     )
 
@@ -424,7 +424,16 @@ class CreateSandboxRequest(BaseModel):
     resource_limits: Optional[ResourceLimits] = Field(
         None,
         alias="resourceLimits",
-        description="Runtime resource constraints for the sandbox instance. Optional when poolRef is provided.",
+        description="Runtime resource constraints (hard caps) for the sandbox instance. Optional when poolRef is provided.",
+    )
+    resource_requests: Optional[ResourceLimits] = Field(
+        None,
+        alias="resourceRequests",
+        description=(
+            "Resource reservations (guaranteed minimums) for the sandbox instance. "
+            "When provided, used as Kubernetes resource requests, enabling Burstable QoS. "
+            "When omitted, resourceLimits values are used for both limits and requests."
+        ),
     )
     env: Optional[Dict[str, Optional[str]]] = Field(
         None,
@@ -449,7 +458,8 @@ class CreateSandboxRequest(BaseModel):
         alias="networkPolicy",
         description=(
             "Optional outbound network policy. Shape matches the egress sidecar /policy endpoint. "
-            "Empty/omitted means allow-all until updated."
+            "Empty/omitted means allow-all until updated. Not supported together with "
+            "extensions.poolRef because pooled pods are pre-created."
         ),
     )
     credential_proxy: Optional[CredentialProxyConfig] = Field(
@@ -490,16 +500,15 @@ class CreateSandboxRequest(BaseModel):
             # 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.")
-            if self.credential_proxy and self.credential_proxy.enabled:
-                raise ValueError("credentialProxy.enabled cannot be used together with poolRef.")
             # Normalize blank snapshotId so downstream code won't see
             # a truthy whitespace string (e.g. "   ") as a real value.
             if self.snapshot_id is not None and not self.snapshot_id.strip():
                 self.snapshot_id = None
             return self
 
-        if self.credential_proxy and self.credential_proxy.enabled and self.network_policy is None:
-            raise ValueError("credentialProxy.enabled requires networkPolicy.")
+        if self.credential_proxy and self.credential_proxy.enabled:
+            if self.network_policy is None:
+                raise ValueError("credentialProxy.enabled requires networkPolicy.")
 
         has_image = self.image is not None and bool(self.image.uri.strip())
         has_snapshot = bool((self.snapshot_id or "").strip())
@@ -534,6 +543,10 @@ class CreateSandboxResponse(BaseModel):
     id: str = Field(..., description="Unique sandbox identifier")
     status: SandboxStatus = Field(..., description="Current lifecycle status and detailed state information")
     metadata: Optional[Dict[str, str]] = Field(None, description="Custom metadata from creation request")
+    extensions: Optional[Dict[str, str]] = Field(
+        None,
+        description="Opaque extension data restored from provider-specific storage",
+    )
     platform: Optional[PlatformSpec] = Field(
         None,
         description=(
@@ -575,6 +588,10 @@ class Sandbox(BaseModel):
     )
     status: SandboxStatus = Field(..., description="Current lifecycle status and detailed state information")
     metadata: Optional[Dict[str, str]] = Field(None, description="Custom metadata from creation request")
+    extensions: Optional[Dict[str, str]] = Field(
+        None,
+        description="Opaque extension data restored from provider-specific storage",
+    )
     entrypoint: Optional[List[str]] = Field(None, description="The command to execute as the sandbox's entry process")
     expires_at: Optional[datetime] = Field(
         None,
@@ -668,6 +685,10 @@ class SnapshotFilter(BaseModel):
         alias="sandboxId",
         description="Filter snapshots by source sandbox identifier",
     )
+    name: Optional[str] = Field(
+        None,
+        description="Filter snapshots by exact snapshot name",
+    )
     state: Optional[List[str]] = Field(
         None,
         min_length=1,
@@ -961,3 +982,41 @@ class ListPoolsResponse(BaseModel):
     Collection of pools.
     """
     items: List[PoolResponse] = Field(..., description="List of pools.")
+
+
+# ============================================================================
+# Metrics
+# ============================================================================
+
+class MetricsEvent(BaseModel):
+    """
+    SDK-reported metrics event (Phase 1: sandbox creation latency).
+    """
+
+    event_type: Literal["sandbox.create"] = Field(
+        ...,
+        alias="eventType",
+        description="Metric event type",
+    )
+    sandbox_id: Optional[str] = Field(
+        default=None,
+        alias="sandboxId",
+        description="Sandbox identifier when available",
+    )
+    image: Optional[str] = Field(
+        default=None,
+        description="Container image URI or snapshot startup source label",
+    )
+    create_duration_ms: int = Field(
+        ...,
+        alias="createDurationMs",
+        ge=0,
+        description="Wall-clock duration in milliseconds from create start to ready or failure",
+    )
+    success: bool = Field(
+        ...,
+        description="Whether create + readiness completed successfully",
+    )
+
+    class Config:
+        populate_by_name = True

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

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