stackbox 0.1.0__py3-none-any.whl

stackbox/backends/modal.py

@@ -0,0 +1,190 @@
+"""Modal backend: gVisor sandboxes from any registry image.
+
+Modal can boot an unprepared image (it builds the image layer with execd at create
+time, which is slow the first time), so unprepared images are served "cold".
+Preparing builds that layer ahead of time; creates then reference it by id.
+
+Requests are in vCPU (as in OpenSandbox/Kubernetes); Modal's ``cpu`` is physical
+cores, so the adapter passes vCPU / 2. Configure ``cost_per_vcpu_hour`` as half of
+Modal's per-core price.
+
+Sandboxes are named ``stackbox-<gw_id>`` inside the configured Modal app, so a create the
+gateway lost track of can be found by name or tag. Modal fixes a sandbox's lifetime
+at create; renewing beyond it is refused.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shlex
+from typing import TYPE_CHECKING, Any
+
+from stackbox import ledger as L
+from stackbox.backends.base import BackendError, CreateFailure, UpstreamResponse
+from stackbox.backends.hosted import (
+    EXECD_PATH,
+    EXECD_PORT,
+    HostedBackend,
+    Provisioned,
+    entrypoint_command,
+    execd_command,
+    from_provider_tags,
+    parse_iso,
+)
+
+if TYPE_CHECKING:
+    from stackbox.ledger import SandboxRecord
+
+
+class ModalBackend(HostedBackend):
+    kind = "modal"
+    unprepared_support = "cold"
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        super().__init__(*args, **kwargs)
+        self._app: Any = None
+        self._app_lock = asyncio.Lock()
+
+    async def app(self) -> Any:
+        import modal
+
+        async with self._app_lock:
+            if self._app is None:
+                self._app = await modal.App.lookup.aio(
+                    self.cfg.modal_app, create_if_missing=True
+                )
+        return self._app
+
+    def fresh_image(self, image: str) -> Any:
+        import modal
+
+        return modal.Image.from_registry(image).add_local_file(
+            str(self.execd_file), EXECD_PATH, copy=True
+        )
+
+    async def build_image(self, image: str) -> tuple[str, dict[str, Any]]:
+        img = self.fresh_image(image)
+        await img.build.aio(await self.app())
+        return img.object_id, {}
+
+    async def provision(
+        self,
+        *,
+        gw_id: str,
+        image: str,
+        image_rec: L.ImageRecord | None,
+        cpu: float,
+        memory_gib: float,
+        timeout_s: int,
+        env: dict[str, str],
+        entrypoint: list[str] | None,
+        token: str,
+    ) -> Provisioned:
+        import modal
+        from modal import exception as mex
+
+        img = (
+            modal.Image.from_id(image_rec.ref)
+            if image_rec is not None and image_rec.ref
+            else self.fresh_image(image)
+        )
+        execd_args = execd_command(token, self.cfg.execd_graceful_shutdown)
+        execd = shlex.join(execd_args)
+        user_cmd = entrypoint_command(entrypoint)
+        args = ["sh", "-c", f"{execd} & exec {user_cmd}"] if user_cmd else execd_args
+        try:
+            sb = await modal.Sandbox.create.aio(
+                *args,
+                app=await self.app(),
+                image=img,
+                name=f"stackbox-{gw_id}",
+                tags={"stackbox_gw_id": gw_id, "stackbox_managed": self.instance_id},
+                env=env or None,
+                timeout=timeout_s,
+                cpu=max(0.125, cpu / 2),  # Modal counts physical cores (2 vCPU)
+                memory=max(128, int(memory_gib * 1024)),
+                encrypted_ports=[EXECD_PORT],
+                region=self.cfg.modal_region,
+            )
+        except mex.ResourceExhaustedError as exc:
+            raise CreateFailure("clear", f"Modal at capacity: {exc}", 429) from exc
+        except (
+            mex.AuthError,
+            mex.NotFoundError,
+            mex.ImageBuildError,
+            mex.InvalidError,
+        ) as exc:
+            raise CreateFailure("clear", f"{type(exc).__name__}: {exc}") from exc
+        except Exception as exc:  # connection drops, timeouts, AlreadyExists: may exist
+            raise CreateFailure("ambiguous", f"{type(exc).__name__}: {exc}") from exc
+        try:
+            tunnels = await sb.tunnels.aio(timeout=60)
+            host = tunnels[EXECD_PORT].url.split("://", 1)[-1].rstrip("/")
+        except Exception as exc:
+            await self.discard(sb.object_id)
+            raise CreateFailure(
+                "clear", f"sandbox created but no tunnel: {type(exc).__name__}: {exc}"
+            ) from exc
+        return Provisioned(upstream_id=sb.object_id, host=host, handle=sb)
+
+    async def provider_state(self, upstream_id: str) -> tuple[str, float | None] | None:
+        import modal
+        from modal import exception as mex
+
+        try:
+            sb = await modal.Sandbox.from_id.aio(upstream_id)
+            rc = await sb.poll.aio()
+        except mex.NotFoundError:
+            return None
+        except Exception as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+        return ("Running", None) if rc is None else None
+
+    async def kill(self, upstream_id: str) -> bool:
+        import modal
+        from modal import exception as mex
+
+        try:
+            sb = await modal.Sandbox.from_id.aio(upstream_id)
+            if await sb.poll.aio() is not None:
+                return False
+            await sb.terminate.aio()
+            return True
+        except mex.NotFoundError:
+            return False
+        except Exception as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+
+    def endpoint_for(
+        self, rec: SandboxRecord, port: int
+    ) -> tuple[str, dict[str, str]] | None:
+        host = (rec.backend_data or {}).get("host")
+        return (host, {}) if port == EXECD_PORT and host else None
+
+    async def extend(self, rec: SandboxRecord, expires_at: float) -> UpstreamResponse:
+        current = (rec.backend_data or {}).get("expiresAt")
+        if current and expires_at <= parse_iso(current) + 1:
+            return UpstreamResponse(200, {"expiresAt": current})
+        return await super().extend(rec, expires_at)
+
+    async def list_provider(self, tags: dict[str, str]) -> list[dict[str, Any]]:
+        import modal
+
+        out: list[dict[str, Any]] = []
+        try:
+            app = await self.app()
+            async for sb in modal.Sandbox.list.aio(
+                app_id=app.app_id, tags=tags or None
+            ):
+                meta = from_provider_tags(await sb.get_tags.aio())
+                out.append(
+                    {
+                        "id": sb.object_id,
+                        "status": {"state": "Running"},
+                        "createdAt": None,
+                        "metadata": meta,
+                    }
+                )
+        except Exception as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+        return out

stackbox/backends/opensandbox.py

@@ -0,0 +1,148 @@
+"""Backend that is itself an OpenSandbox-compatible lifecycle API (a server we proxy to)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from stackbox.backends.base import (
+    Backend,
+    BackendError,
+    Created,
+    CreateFailure,
+    UpstreamResponse,
+)
+from stackbox.config import BackendConfig
+
+if TYPE_CHECKING:
+    from stackbox.ledger import SandboxRecord
+
+# Requests that never reached the server: nothing can have been created.
+_NOT_SENT = (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout)
+_CLIENT_STATUSES = {400, 401, 403, 404, 405, 409, 413, 415, 422}
+
+
+def _json(resp: httpx.Response) -> Any:
+    try:
+        return resp.json()
+    except ValueError:
+        return resp.text or None
+
+
+class OpenSandboxBackend(Backend):
+    kind = "opensandbox"
+
+    def __init__(
+        self,
+        cfg: BackendConfig,
+        *,
+        create_timeout_s: float,
+        request_timeout_s: float,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ):
+        super().__init__(cfg)
+        assert cfg.url is not None
+        headers = {"OPEN-SANDBOX-API-KEY": cfg.api_key} if cfg.api_key else {}
+        self._create_timeout = create_timeout_s
+        self._client = httpx.AsyncClient(
+            base_url=cfg.url.rstrip("/").removesuffix("/v1") + "/v1",
+            headers=headers,
+            timeout=request_timeout_s,
+            transport=transport,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def create(self, body: dict[str, Any], *, gw_id: str) -> Created:
+        try:
+            resp = await self._client.post(
+                "/sandboxes", json=body, timeout=self._create_timeout
+            )
+        except _NOT_SENT as exc:
+            raise CreateFailure("clear", f"{type(exc).__name__}: {exc}") from exc
+        except httpx.HTTPError as exc:
+            # Sent (at least partly) but no usable response: it may exist upstream.
+            raise CreateFailure("ambiguous", f"{type(exc).__name__}: {exc}") from exc
+        if 200 <= resp.status_code < 300:
+            data = _json(resp)
+            if not isinstance(data, dict) or "id" not in data:
+                raise CreateFailure(
+                    "ambiguous",
+                    "create returned 2xx without a sandbox id",
+                    resp.status_code,
+                    data,
+                )
+            return Created(sandbox=data)
+        if resp.status_code == 429:
+            raise CreateFailure(
+                "clear", "backend rate limited or at capacity", 429, _json(resp)
+            )
+        if resp.status_code in _CLIENT_STATUSES:
+            raise CreateFailure(
+                "client",
+                f"rejected with {resp.status_code}",
+                resp.status_code,
+                _json(resp),
+            )
+        # 5xx and anything unexpected: the server may have created a container before failing.
+        raise CreateFailure(
+            "ambiguous",
+            f"upstream error {resp.status_code}",
+            resp.status_code,
+            _json(resp),
+        )
+
+    async def list_sandboxes(
+        self, metadata: dict[str, str] | None = None
+    ) -> list[dict[str, Any]]:
+        """All sandboxes matching the metadata filter (follows pagination)."""
+        items: list[dict[str, Any]] = []
+        page = 1
+        try:
+            while True:
+                params: dict[str, Any] = {"page": page, "pageSize": 100}
+                if metadata:
+                    params["metadata"] = "&".join(
+                        f"{k}={v}" for k, v in metadata.items()
+                    )
+                resp = await self._client.get("/sandboxes", params=params)
+                resp.raise_for_status()
+                data = resp.json()
+                items.extend(data.get("items") or [])
+                if not (data.get("pagination") or {}).get("hasNextPage"):
+                    return items
+                page += 1
+        except httpx.HTTPError as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Any = None,
+        json: Any = None,
+    ) -> UpstreamResponse:
+        resp = await self._client.request(method, path, params=params, json=json)
+        return UpstreamResponse(resp.status_code, _json(resp), dict(resp.headers))
+
+    async def get(self, rec: SandboxRecord) -> UpstreamResponse:
+        return await self.request("GET", f"/sandboxes/{rec.upstream_id}")
+
+    async def delete(self, upstream_id: str) -> UpstreamResponse:
+        return await self.request("DELETE", f"/sandboxes/{upstream_id}")
+
+    async def subresource(
+        self,
+        rec: SandboxRecord,
+        method: str,
+        rest: str,
+        *,
+        params: Any = None,
+        json: Any = None,
+    ) -> UpstreamResponse:
+        return await self.request(
+            method, f"/sandboxes/{rec.upstream_id}/{rest}", params=params, json=json
+        )

stackbox/backends/vercel.py

@@ -0,0 +1,309 @@
+"""Vercel Sandbox backend: Firecracker microVMs on Vercel.
+
+Vercel boots images from Vercel Container Registry (VCR) only: ``ubuntu:24.04`` by
+name returns "Image not found". Preparing an image builds it plus execd and pushes it
+to VCR (needs a local Docker daemon), unless ``vercel_images`` already maps it to a VCR
+reference; then it checks the image boots with execd in it. Creates boot it directly (measured 0.4-1.2 s, about the
+same as booting a snapshot, so no snapshot step).
+
+Sandboxes are named ``stackbox-<gw_id>``; that name is the upstream id, so a create the
+gateway lost track of is found by name. Port 44772 is exposed as a public route
+(execd's token protects it). Credentials come from the Vercel SDK's usual sources:
+``VERCEL_TOKEN`` + ``VERCEL_TEAM_ID`` + ``VERCEL_PROJECT_ID``, or an OIDC token.
+
+Vercel bills CPU only while it is active; set ``cpu_billed_fraction`` to model that.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+import shlex
+import time
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from stackbox import ledger as L
+from stackbox.backends.base import (
+    BackendError,
+    CreateFailure,
+    ReconcileError,
+    UpstreamResponse,
+)
+from stackbox.backends.hosted import (
+    EXECD_PATH,
+    EXECD_PORT,
+    HostedBackend,
+    Provisioned,
+    entrypoint_command,
+    execd_command,
+    from_provider_tags,
+    iso,
+)
+
+if TYPE_CHECKING:
+    from stackbox.ledger import SandboxRecord
+
+logger = logging.getLogger(__name__)
+
+_LIVE = {"pending", "running", "snapshotting"}
+
+
+def _status(sb: Any) -> str:
+    return str(getattr(sb.status, "value", sb.status)).lower()
+
+
+def _route_host(sb: Any, port: int) -> str | None:
+    for r in sb.routes or ():
+        if r.port == port:
+            return r.url.split("://", 1)[-1].rstrip("/")
+    return None
+
+
+class VercelBackend(HostedBackend):
+    kind = "vercel"
+    unprepared_support = (
+        None  # Vercel boots VCR images only; prepare maps and checks one
+    )
+
+    def vcpus(self, cpu: float) -> int:
+        """Vercel allows 1 or an even number of vCPUs."""
+        v = max(1, math.ceil(cpu))
+        return v if v == 1 else v + (v % 2)
+
+    def allocated_resources(
+        self, image: str | None, cpu: float | None, memory_gib: float | None
+    ) -> tuple[float, float]:
+        req_cpu, _ = self.requested_resources(cpu, memory_gib)
+        v = self.vcpus(req_cpu)
+        return float(v), 2.0 * v  # 2 GB of memory per vCPU
+
+    async def build_image(self, image: str) -> tuple[str, dict[str, Any]]:
+        """Check that Vercel boots the image (via its VCR reference) with execd in it."""
+        import vercel.sandbox as vs
+
+        ref = self.cfg.vercel_images.get(image)
+        pushed = False
+        if ref is None:
+            ref, pushed = await self._push_to_vcr(image), True
+        try:
+            sb = await vs.create_sandbox(
+                image=ref,
+                execution_time_limit=300,
+                resources=vs.SandboxResources(vcpus=1),
+                tags={"stackbox_prepare": "1"},
+            )
+        except vs.SandboxApiError as exc:
+            if "not found" in str(exc).lower():
+                raise RuntimeError(
+                    f"Vercel cannot boot {ref}: it boots images from Vercel Container "
+                    "Registry only. Run `stackbox prepare {image}` on a machine with "
+                    "Docker, or map a VCR reference in vercel_images."
+                ) from exc
+            raise
+        try:
+            result = await sb.run_command(
+                "sh", ["-c", f"test -x {EXECD_PATH} && id -u"], capture_output=True
+            )
+            code = getattr(result, "returncode", getattr(result, "exit_code", 0))
+            if code not in (0, None):
+                raise RuntimeError(
+                    f"{ref} has no {EXECD_PATH}; build it with scripts/vercel_push_image.py"
+                )
+        finally:
+            try:
+                await sb.stop()
+                await sb.destroy()
+            except Exception as exc:  # noqa: BLE001 - only a probe
+                logger.warning("could not destroy Vercel prepare sandbox: %s", exc)
+        return ref, {"vcr_ref": ref, "pushed": pushed}
+
+    async def _push_to_vcr(self, image: str) -> str:
+        """Vercel boots VCR images only: build image + execd and push it (needs Docker)."""
+        import asyncio
+
+        from stackbox import vcr
+
+        found = await asyncio.to_thread(vcr.existing, image, self.execd_file)
+        if found:
+            return found  # pushed before (same image + execd): no Docker needed
+        if not await asyncio.to_thread(vcr.docker_available):
+            raise RuntimeError(
+                f"Vercel boots images from Vercel Container Registry only, and {image} is "
+                "not there yet. Pushing it needs a running Docker daemon: start Docker and "
+                "rerun `stackbox prepare`, or push from another machine with "
+                "scripts/vercel_push_image.py and set vercel_images in the config."
+            )
+        logger.info("pushing %s + execd to Vercel Container Registry", image)
+        return await asyncio.to_thread(vcr.push, image, self.execd_file)
+
+    async def provision(
+        self,
+        *,
+        gw_id: str,
+        image: str,
+        image_rec: L.ImageRecord | None,
+        cpu: float,
+        memory_gib: float,
+        timeout_s: int,
+        env: dict[str, str],
+        entrypoint: list[str] | None,
+        token: str,
+    ) -> Provisioned:
+        import vercel.sandbox as vs
+
+        if image_rec is None or not image_rec.ref:
+            raise CreateFailure("clear", f"no Vercel image prepared for {image}")
+        name = f"stackbox-{gw_id}"
+        try:
+            sb = await vs.create_sandbox(
+                name=name,
+                image=image_rec.ref,
+                ports=[EXECD_PORT],
+                execution_time_limit=timeout_s,
+                resources=vs.SandboxResources(vcpus=self.vcpus(cpu)),
+                env=env or None,
+                tags={"stackbox_gw_id": gw_id, "stackbox_managed": self.instance_id},
+            )
+        except (httpx.ConnectError, httpx.ConnectTimeout) as exc:
+            raise CreateFailure("clear", f"{type(exc).__name__}: {exc}") from exc
+        except vs.SandboxApiError as exc:
+            status = getattr(exc, "status_code", None) or getattr(exc, "status", None)
+            if status in (400, 401, 403, 404, 422, 429):
+                if status == 404:
+                    self._ledger.set_image(
+                        self.name,
+                        image,
+                        L.IMAGE_FAILED,
+                        error=f"image missing: {exc}"[:500],
+                    )
+                raise CreateFailure(
+                    "clear", f"Vercel rejected create: {exc}", status
+                ) from exc
+            raise CreateFailure(
+                "ambiguous", f"{type(exc).__name__}: {exc}", status
+            ) from exc
+        except vs.SandboxTerminalStateError as exc:
+            # Reached a terminal failure state: it exists but is unusable.
+            await self.discard(name)
+            raise CreateFailure("clear", f"sandbox failed to start: {exc}") from exc
+        except Exception as exc:
+            raise CreateFailure("ambiguous", f"{type(exc).__name__}: {exc}") from exc
+        host = _route_host(sb, EXECD_PORT)
+        if host is None:
+            await self.discard(name)
+            raise CreateFailure("clear", "sandbox has no route for the execd port")
+        return Provisioned(upstream_id=name, host=host, handle=sb)
+
+    async def start(
+        self,
+        prov: Provisioned,
+        *,
+        token: str,
+        env: dict[str, str],
+        entrypoint: list[str] | None,
+    ) -> None:
+        sb = prov.handle
+        execd = shlex.join(execd_command(token, self.cfg.execd_graceful_shutdown))
+        cmd = f"nohup {execd} > /tmp/execd.log 2>&1 &"
+        user_cmd = entrypoint_command(entrypoint)
+        if user_cmd:
+            cmd += f" nohup sh -c {shlex.quote(user_cmd)} > /tmp/entrypoint.log 2>&1 &"
+        # VCR images built by scripts/vercel_push_image.py run as root, and a plain base
+        # image may have no sudo, so execd starts as the image's user.
+        await sb.run_command("sh", ["-c", cmd], env=env or None)
+
+    async def _get(self, name: str) -> Any | None:
+        import vercel.sandbox as vs
+
+        try:
+            return await vs.get_sandbox(name=name)
+        except vs.SandboxApiError as exc:
+            if (
+                getattr(exc, "status_code", None) or getattr(exc, "status", None)
+            ) == 404:
+                return None
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+        except Exception as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+
+    async def provider_state(self, upstream_id: str) -> tuple[str, float | None] | None:
+        sb = await self._get(upstream_id)
+        if sb is None or _status(sb) not in _LIVE:
+            return None
+        return "Running", None
+
+    async def kill(self, upstream_id: str) -> bool:
+        sb = await self._get(upstream_id)
+        if sb is None:
+            return False
+        live = _status(sb) in _LIVE
+        try:
+            if live:
+                await sb.stop()
+            await sb.destroy()
+        except Exception as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+        return live
+
+    def endpoint_for(
+        self, rec: SandboxRecord, port: int
+    ) -> tuple[str, dict[str, str]] | None:
+        host = (rec.backend_data or {}).get("host")
+        return (host, {}) if port == EXECD_PORT and host else None
+
+    async def extend(self, rec: SandboxRecord, expires_at: float) -> UpstreamResponse:
+        sb = await self._get(rec.upstream_id or "")
+        if sb is None:
+            return UpstreamResponse(
+                404, {"code": "SANDBOX::NOT_FOUND", "message": "gone"}
+            )
+        extra = max(0, int(expires_at - time.time()))
+        try:
+            await sb.extend_execution_time_limit(extra)
+        except Exception as exc:  # noqa: BLE001 - reported to the client
+            return UpstreamResponse(
+                502, {"code": "STACKBOX::BACKEND_ERROR", "message": str(exc)}
+            )
+        return UpstreamResponse(200, {"expiresAt": iso(expires_at)})
+
+    async def find_by_gw_id(self, gw_id: str) -> dict[str, Any] | None:
+        try:
+            sb = await self._get(f"stackbox-{gw_id}")
+        except BackendError as exc:
+            raise ReconcileError(f"{self.name}: {exc}") from exc
+        if sb is None or _status(sb) not in _LIVE:
+            return None
+        return self._as_dict(sb)
+
+    def _as_dict(self, sb: Any) -> dict[str, Any]:
+        created = getattr(sb, "created_at", None)
+        return {
+            "id": sb.name,
+            "status": {"state": "Running"},
+            "createdAt": iso(created.timestamp())
+            if hasattr(created, "timestamp")
+            else None,
+            "metadata": from_provider_tags(dict(sb.tags or {})),
+        }
+
+    async def list_provider(self, tags: dict[str, str]) -> list[dict[str, Any]]:
+        import vercel.sandbox as vs
+
+        # The API filters on one tag; filter the rest here.
+        first = next(iter(tags.items()), None)
+        query = vs.SandboxQueryByCreatedAt(
+            tag=vs.TagFilter(key=first[0], value=first[1]) if first else None
+        )
+        out: list[dict[str, Any]] = []
+        try:
+            async for sb in vs.query_sandboxes(query=query):
+                if _status(sb) not in _LIVE:
+                    continue
+                st = dict(sb.tags or {})
+                if all(st.get(k) == v for k, v in tags.items()):
+                    out.append(self._as_dict(sb))
+        except Exception as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+        return out