stackbox 0.1.0__py3-none-any.whl

stackbox/__init__.py

@@ -0,0 +1,9 @@
+"""OpenSandbox-compatible gateway that routes sandboxes across providers."""
+
+__version__ = "0.1.0"
+
+
+def main() -> None:
+    from stackbox.cli import main as cli_main
+
+    cli_main()

stackbox/__main__.py

@@ -0,0 +1,3 @@
+from stackbox import main
+
+main()

stackbox/app.py

@@ -0,0 +1,405 @@
+"""OpenSandbox-compatible lifecycle API that places sandboxes across backends.
+
+Only lifecycle calls pass through the gateway. Command/file traffic goes from the
+client straight to execd, at whatever endpoint the owning backend reports.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from typing import Any
+
+import httpx
+from fastapi import APIRouter, FastAPI, Request
+from fastapi.responses import JSONResponse, Response
+
+from stackbox import ledger as L
+from stackbox.backends import MANAGED_KEY, BackendError, make_backend
+from stackbox.config import RouterConfig
+
+
+def _when(value: str | None) -> float | None:
+    """ISO time, or a relative time ago: 30m, 24h, 7d."""
+    import datetime as dt
+    import re
+    import time as _time
+
+    if not value:
+        return None
+    m = re.fullmatch(r"(\d+(?:\.\d+)?)([smhd])", value.strip())
+    if m:
+        n, unit = float(m.group(1)), m.group(2)
+        return _time.time() - n * {"s": 1, "m": 60, "h": 3600, "d": 86400}[unit]
+    try:
+        return dt.datetime.fromisoformat(value).timestamp()
+    except ValueError as exc:
+        raise ValueError(f"can't read time '{value}'") from exc
+
+
+from stackbox.router import PlacementError, Router, parse_preferences
+from stackbox.router import Request as PlacementRequest
+
+logger = logging.getLogger(__name__)
+
+API_KEY_HEADER = "OPEN-SANDBOX-API-KEY"
+PIN_HEADER = "X-Stackbox-Backend"
+
+
+def _error(
+    status: int, code: str, message: str, details: Any = None, hint: str | None = None
+) -> JSONResponse:
+    # SDKs show code and message only, so the hint also goes into the message.
+    body: dict[str, Any] = {
+        "code": code,
+        "message": f"{message}. Hint: {hint}" if hint else message,
+    }
+    if details is not None:
+        body["details"] = details
+    if hint:
+        body["hint"] = hint
+    return JSONResponse(body, status_code=status)
+
+
+def _passthrough(status: int, body: Any) -> Response:
+    if status == 204 or body is None:
+        return Response(status_code=status)
+    return JSONResponse(body, status_code=status)
+
+
+def create_app(
+    cfg: RouterConfig,
+    *,
+    transports: dict[str, httpx.AsyncBaseTransport] | None = None,
+    run_reconciler: bool = True,
+) -> FastAPI:
+    transports = transports or {}
+    ledger = L.Ledger(cfg.gateway.db_path)
+    backends = {
+        b.name: make_backend(b, cfg.gateway, ledger, transport=transports.get(b.name))
+        for b in cfg.backends
+    }
+    router = Router(cfg, ledger, backends)
+
+    @contextlib.asynccontextmanager
+    async def lifespan(app: FastAPI):
+        task = (
+            asyncio.create_task(router.reconcile_forever()) if run_reconciler else None
+        )
+        yield
+        if task:
+            task.cancel()
+        for b in backends.values():
+            await b.aclose()
+
+    app = FastAPI(title="stackbox", lifespan=lifespan)
+    app.state.router = router
+
+    @app.middleware("http")
+    async def auth(request: Request, call_next):
+        key = cfg.gateway.api_key
+        if (
+            key
+            and request.url.path not in ("/health", "/v1/health")
+            and request.headers.get(API_KEY_HEADER) != key
+        ):
+            return _error(
+                401,
+                "STACKBOX::UNAUTHORIZED",
+                "missing or invalid API key",
+                hint="send the gateway's api_key in the OPEN-SANDBOX-API-KEY header "
+                "(OpenSandbox SDK: ConnectionConfig(api_key=...))",
+            )
+        return await call_next(request)
+
+    api = APIRouter()
+
+    @api.get("/health")
+    async def health():
+        return {"status": "healthy"}
+
+    @api.post("/sandboxes")
+    async def create_sandbox(request: Request):
+        body = await request.json()
+        try:
+            created = await router.create(
+                body,
+                request.headers.get(PIN_HEADER),
+                dict(request.headers),
+            )
+        except PlacementError as exc:
+            if exc.code == "STACKBOX::UPSTREAM_REJECTED" and isinstance(
+                exc.details, dict
+            ):
+                return JSONResponse(exc.details, status_code=exc.status)
+            return _error(exc.status, exc.code, str(exc), exc.details, exc.hint)
+        return JSONResponse(created, status_code=202)
+
+    @api.get("/sandboxes")
+    async def list_sandboxes(request: Request):
+        page = int(request.query_params.get("page", 1))
+        page_size = int(request.query_params.get("pageSize", 20))
+        states = set(request.query_params.getlist("state"))
+        items: list[dict[str, Any]] = []
+        for name, backend in backends.items():
+            try:
+                upstream = await backend.list_sandboxes(
+                    {MANAGED_KEY: router.instance_id}
+                )
+            except BackendError:
+                logger.warning("list failed for backend %s", name)
+                continue
+            for s in upstream:
+                rec = router.ledger.by_upstream(name, s["id"])
+                if rec is None or rec.state != L.ACTIVE:
+                    continue
+                if states and (s.get("status") or {}).get("state") not in states:
+                    continue
+                items.append(router.to_client(s, rec.gw_id))
+        meta_filter = request.query_params.get("metadata")
+        if meta_filter:
+            wanted = dict(p.split("=", 1) for p in meta_filter.split("&") if "=" in p)
+            items = [
+                i
+                for i in items
+                if all((i.get("metadata") or {}).get(k) == v for k, v in wanted.items())
+            ]
+        total = len(items)
+        start = (page - 1) * page_size
+        return {
+            "items": items[start : start + page_size],
+            "pagination": {
+                "page": page,
+                "pageSize": page_size,
+                "totalItems": total,
+                "totalPages": (total + page_size - 1) // page_size,
+                "hasNextPage": start + page_size < total,
+            },
+        }
+
+    @api.get("/sandboxes/{gw_id}")
+    async def get_sandbox(gw_id: str):
+        try:
+            rec, backend = router.resolve(gw_id)
+        except PlacementError as exc:
+            return _error(exc.status, exc.code, str(exc))
+        try:
+            resp = await backend.get(rec)
+        except httpx.HTTPError as exc:
+            return _error(502, "STACKBOX::BACKEND_ERROR", str(exc))
+        if resp.status == 404:
+            router.ledger.set_state(gw_id, L.EXPIRED, "upstream returned 404")
+        if resp.status == 200 and isinstance(resp.body, dict):
+            return router.to_client(resp.body, gw_id)
+        return _passthrough(resp.status, resp.body)
+
+    @api.delete("/sandboxes/{gw_id}")
+    async def delete_sandbox(gw_id: str):
+        try:
+            status = await router.delete(gw_id)
+        except PlacementError as exc:
+            return _error(exc.status, exc.code, str(exc))
+        return Response(status_code=204 if status in (200, 202, 204, 404) else status)
+
+    @api.api_route(
+        "/sandboxes/{gw_id}/{rest:path}",
+        methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
+    )
+    async def sandbox_subresource(gw_id: str, rest: str, request: Request):
+        """Endpoints, renew-expiration, pause/resume, metadata, network policy, ..."""
+        try:
+            rec, backend = router.resolve(gw_id)
+        except PlacementError as exc:
+            return _error(exc.status, exc.code, str(exc))
+        raw = await request.body()
+        try:
+            resp = await backend.subresource(
+                rec,
+                request.method,
+                rest,
+                params=list(request.query_params.multi_items()),
+                json=(await request.json()) if raw else None,
+            )
+        except httpx.HTTPError as exc:
+            return _error(502, "STACKBOX::BACKEND_ERROR", str(exc))
+        body = resp.body
+        if isinstance(body, dict) and body.get("id") == rec.upstream_id:
+            body = router.to_client(body, gw_id)
+        return _passthrough(resp.status, body)
+
+    # ---------------------------------------------------------------------------
+    # stackbox API: plain nouns under /v1, beside the OpenSandbox routes. They avoid
+    # OpenSandbox's names (sandboxes, snapshots, templates, metrics) and never add
+    # to /sandboxes/{id}/..., which OpenSandbox keeps extending.
+    ext = APIRouter(prefix="/v1")
+
+    def _provider_or_404(name: str) -> dict[str, Any] | JSONResponse:
+        if name not in backends:
+            return _error(
+                404,
+                "STACKBOX::UNKNOWN_BACKEND",
+                f"no provider named '{name}'",
+                hint=f"configured providers: {', '.join(backends)}",
+            )
+        return router.provider_view(name)
+
+    @ext.get("/providers")
+    async def list_providers():
+        """Every configured provider: pricing, capacity, health, learned startup,
+        prepared images and usage."""
+        return {"items": [router.provider_view(n) for n in backends]}
+
+    @ext.get("/providers/{name}")
+    async def get_provider(name: str):
+        return _provider_or_404(name)
+
+    @ext.get("/route")
+    async def route(
+        image: str,
+        cpu: float | None = None,
+        memory_gib: float | None = None,
+        strategy: str | None = None,
+        providers: str | None = None,
+        max_price: float | None = None,
+    ):
+        """Where a sandbox for this image would go right now, and why, for every
+        provider (dry run). Takes the same preferences as a create."""
+        try:
+            strat, provs, price = parse_preferences(
+                {
+                    k: v
+                    for k, v in {
+                        "x-stackbox-strategy": strategy,
+                        "x-stackbox-providers": providers,
+                        "x-stackbox-max-price": None
+                        if max_price is None
+                        else str(max_price),
+                    }.items()
+                    if v
+                },
+                {},
+            )
+            req = PlacementRequest(image, cpu, memory_gib, strat, provs, price)
+            return {
+                "image": image,
+                "strategy": strat or cfg.routing.strategy,
+                "items": router.explain(req),
+            }
+        except PlacementError as exc:
+            return _error(exc.status, exc.code, str(exc), exc.details, exc.hint)
+
+    @ext.get("/placements/{sandbox_id}")
+    async def get_placement(sandbox_id: str):
+        """Where a sandbox went, every provisioning attempt, and its cost so far."""
+        found = router.placement(sandbox_id)
+        if found is None:
+            return _error(
+                404,
+                "STACKBOX::NOT_FOUND",
+                f"no sandbox {sandbox_id} in this gateway's ledger",
+                hint="ids are the ones POST /v1/sandboxes returned",
+            )
+        return found
+
+    @ext.get("/images")
+    async def list_images(image: str | None = None):
+        """Prepared images per provider (optionally one image)."""
+        return {
+            "items": [
+                {
+                    "provider": i["backend"],
+                    **{k: i[k] for k in ("image", "status", "ref", "error")},
+                }
+                for i in router.ledger.images()
+                if image is None or i["image"] == image
+            ]
+        }
+
+    @ext.post("/images")
+    async def prepare_images(request: Request):
+        """Prepare an image: {"image": "ubuntu:24.04", "providers": ["e2b"]} (providers
+        optional, default all). Builds templates/layers, pushes to registries."""
+        body = await request.json() if await request.body() else {}
+        image = body.get("image")
+        if not image:
+            return _error(
+                400,
+                "STACKBOX::BAD_REQUEST",
+                "image is required",
+                hint='send {"image": "ubuntu:24.04"}',
+            )
+        names = body.get("providers") or [
+            n for n, b in backends.items() if b.kind != "opensandbox"
+        ]
+        unknown = [n for n in names if n not in backends]
+        if unknown:
+            return _error(
+                400,
+                "STACKBOX::UNKNOWN_BACKEND",
+                f"unknown provider(s): {', '.join(unknown)}",
+                hint=f"configured providers: {', '.join(backends)}",
+            )
+        results = await asyncio.gather(
+            *(backends[n].prepare(image) for n in names), return_exceptions=True
+        )
+        return {
+            "items": [
+                {"provider": n, "image": image, "ok": False, "error": str(r)}
+                if isinstance(r, BaseException)
+                else {
+                    "provider": n,
+                    "ok": True,
+                    **{k: v for k, v in r.items() if k != "backend"},
+                }
+                for n, r in zip(names, results, strict=True)
+            ]
+        }
+
+    @ext.get("/usage")
+    async def usage(
+        since: str | None = None, until: str | None = None, group_by: str = "provider"
+    ):
+        """Sandbox time and estimated cost. since/until: ISO time or relative (30m, 24h, 7d)."""
+        if group_by not in ("provider", "sandbox"):
+            return _error(
+                400,
+                "STACKBOX::BAD_REQUEST",
+                f"group_by '{group_by}'",
+                hint="use provider or sandbox",
+            )
+        try:
+            lo, hi = _when(since), _when(until)
+        except ValueError as exc:
+            return _error(
+                400,
+                "STACKBOX::BAD_REQUEST",
+                str(exc),
+                hint="use an ISO time or 30m, 24h, 7d",
+            )
+        return router.usage(lo, hi, group_by)
+
+    @ext.post("/admin/reconcile")
+    async def reconcile():
+        """Run cleanup now: resolve unknown creates, expire vanished sandboxes, delete leaks."""
+        return await router.reconcile_once()
+
+    @ext.api_route(
+        "/snapshots{rest:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE"]
+    )
+    @ext.api_route(
+        "/templates{rest:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE"]
+    )
+    async def unsupported(request: Request, rest: str = ""):
+        return _error(
+            501,
+            "STACKBOX::UNSUPPORTED",
+            f"{request.method} {request.url.path} is not supported by stackbox yet",
+            hint="stackbox routes sandboxes across providers; snapshots and templates are "
+            "provider-specific. Prepare images with POST /v1/images instead of templates",
+        )
+
+    app.include_router(ext)
+    app.include_router(api)
+    app.include_router(api, prefix="/v1")
+    return app

stackbox/backends/__init__.py

@@ -0,0 +1,107 @@
+"""Backend kinds the router can place sandboxes on."""
+
+from __future__ import annotations
+
+import secrets
+
+import httpx
+
+from stackbox import ledger as L
+from stackbox.backends.base import (
+    GONE_STATES,
+    GW_ID_KEY,
+    MANAGED_KEY,
+    PIN_KEY,
+    ROUTER_KEYS,
+    Backend,
+    BackendError,
+    Created,
+    CreateFailure,
+    ReconcileError,
+    UpstreamResponse,
+)
+from stackbox.backends.opensandbox import OpenSandboxBackend
+from stackbox.config import BackendConfig, GatewaySettings
+
+__all__ = [
+    "GONE_STATES",
+    "GW_ID_KEY",
+    "MANAGED_KEY",
+    "PIN_KEY",
+    "ROUTER_KEYS",
+    "Backend",
+    "BackendError",
+    "CreateFailure",
+    "Created",
+    "OpenSandboxBackend",
+    "ReconcileError",
+    "UpstreamResponse",
+    "gateway_instance_id",
+    "make_backend",
+]
+
+
+def gateway_instance_id(ledger: L.Ledger) -> str:
+    """Stable id of the gateway that owns this ledger; the value of the managed tag."""
+    return ledger.get_or_create_secret(
+        "instance_id", lambda: "gw" + secrets.token_hex(6)
+    )
+
+
+def make_backend(
+    cfg: BackendConfig,
+    settings: GatewaySettings,
+    ledger: L.Ledger,
+    *,
+    transport: httpx.AsyncBaseTransport | None = None,
+) -> Backend:
+    instance_id = gateway_instance_id(ledger)
+    if cfg.kind == "opensandbox":
+        b: Backend = OpenSandboxBackend(
+            cfg,
+            create_timeout_s=settings.create_timeout_s,
+            request_timeout_s=settings.request_timeout_s,
+            transport=transport,
+        )
+        b.instance_id = instance_id
+        return b
+    token_key = ledger.get_or_create_secret(
+        "execd_token_key", lambda: secrets.token_hex(32)
+    )
+    if cfg.kind == "e2b":
+        from stackbox.backends.e2b import E2BBackend
+
+        b = E2BBackend(cfg, settings=settings, ledger=ledger, token_key=token_key)
+        b.instance_id = instance_id
+        return b
+    if cfg.kind == "modal":
+        from stackbox.backends.modal import ModalBackend
+
+        b = ModalBackend(cfg, settings=settings, ledger=ledger, token_key=token_key)
+        b.instance_id = instance_id
+        return b
+    if cfg.kind == "cloudflare":
+        from stackbox.backends.cloudflare import CloudflareBackend
+
+        b = CloudflareBackend(
+            cfg,
+            settings=settings,
+            ledger=ledger,
+            token_key=token_key,
+            transport=transport,
+        )
+        b.instance_id = instance_id
+        return b
+    if cfg.kind == "daytona":
+        from stackbox.backends.daytona import DaytonaBackend
+
+        b = DaytonaBackend(cfg, settings=settings, ledger=ledger, token_key=token_key)
+        b.instance_id = instance_id
+        return b
+    if cfg.kind == "vercel":
+        from stackbox.backends.vercel import VercelBackend
+
+        b = VercelBackend(cfg, settings=settings, ledger=ledger, token_key=token_key)
+        b.instance_id = instance_id
+        return b
+    raise ValueError(f"unknown backend kind {cfg.kind}")