stackbox 0.1.0__py3-none-any.whl

stackbox/backends/daytona.py

@@ -0,0 +1,306 @@
+"""Daytona backend.
+
+Creates boot a declarative image (the requested image plus an execd layer), which
+Daytona builds once and caches; this needs no snapshot permission on the API key.
+Each create starts execd and fetches the port preview link; clients reach execd at
+the preview URL with Daytona's ``x-daytona-preview-token`` header plus execd's token.
+
+Sandboxes are named ``stackbox-<gw_id>`` and labelled with the gateway id and owner, so a
+create the gateway lost track of is found by name. Credentials: ``DAYTONA_API_KEY``
+(and optionally ``DAYTONA_API_URL`` / ``DAYTONA_TARGET``), or ``api_key`` in config.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import math
+import shlex
+import time
+from typing import TYPE_CHECKING, Any
+
+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__)
+
+PREVIEW_TOKEN_HEADER = "x-daytona-preview-token"
+_LIVE = {"started", "starting", "creating", "pulling_snapshot", "restoring", "resuming"}
+
+
+def _state(sb: Any) -> str:
+    return str(getattr(sb.state, "value", sb.state)).lower()
+
+
+def _live(sb: Any) -> bool:
+    """Running and not already being destroyed (Daytona deletes asynchronously)."""
+    desired = str(getattr(sb.desired_state, "value", sb.desired_state) or "").lower()
+    return _state(sb) in _LIVE and desired not in ("destroyed", "stopped", "archived")
+
+
+class DaytonaBackend(HostedBackend):
+    kind = "daytona"
+    # Daytona builds a declarative image (base image + execd layer) on first use and
+    # caches it, so an unprepared image is served cold (measured: 16.8 s first create,
+    # then 1.3 s). Preparing does one throwaway create to warm that cache.
+    unprepared_support = "cold"
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        super().__init__(*args, **kwargs)
+        self._client: Any = None
+        self._client_lock = asyncio.Lock()
+        self._images: dict[str, Any] = {}
+
+    async def client(self) -> Any:
+        import daytona as d
+
+        async with self._client_lock:
+            if self._client is None:
+                cfg = (
+                    d.DaytonaConfig(api_key=self.cfg.api_key)
+                    if self.cfg.api_key
+                    else None
+                )
+                self._client = d.AsyncDaytona(cfg)
+        return self._client
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            try:
+                await self._client.close()
+            except Exception:
+                logger.debug("closing the Daytona client failed", exc_info=True)
+        await super().aclose()
+
+    def declarative_image(self, image: str) -> Any:
+        import daytona as d
+
+        if image not in self._images:
+            self._images[image] = (
+                d.Image.base(image)
+                .add_local_file(str(self.execd_file), EXECD_PATH)
+                .run_commands(f"chmod 755 {EXECD_PATH}")
+            )
+        return self._images[image]
+
+    @staticmethod
+    def whole(cpu: float, memory_gib: float) -> tuple[int, int]:
+        """Daytona takes whole vCPUs and GiB."""
+        return max(1, math.ceil(cpu)), max(1, math.ceil(memory_gib))
+
+    def allocated_resources(
+        self, image: str | None, cpu: float | None, memory_gib: float | None
+    ) -> tuple[float, float]:
+        c, m = self.whole(*self.requested_resources(cpu, memory_gib))
+        return float(c), float(m)
+
+    async def build_image(self, image: str) -> tuple[str, dict[str, Any]]:
+        import daytona as d
+
+        dt = await self.client()
+        cpu, mem = self.whole(self.cfg.default_cpu, self.cfg.default_memory_gib)
+        t0 = time.monotonic()
+        sb = await dt.create(
+            d.CreateSandboxFromImageParams(
+                image=self.declarative_image(image),
+                resources=d.Resources(cpu=cpu, memory=mem),
+                labels={"stackbox_prepare": "1"},
+                ephemeral=True,
+            ),
+            timeout=1800,
+        )
+        first_create_s = round(time.monotonic() - t0, 1)
+        await sb.delete()
+        return image, {"first_create_s": first_create_s}
+
+    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 daytona as d
+
+        dt = await self.client()
+        c, m = self.whole(cpu, memory_gib)
+        try:
+            sb = await dt.create(
+                d.CreateSandboxFromImageParams(
+                    name=f"stackbox-{gw_id}",
+                    image=self.declarative_image(image),
+                    resources=d.Resources(cpu=c, memory=m),
+                    labels={
+                        "stackbox_gw_id": gw_id,
+                        "stackbox_managed": self.instance_id,
+                    },
+                    env_vars=env or None,
+                    ttl_minutes=max(1, math.ceil(timeout_s / 60)),
+                    auto_stop_interval=0,
+                    ephemeral=True,
+                ),
+                timeout=self._settings.create_timeout_s,
+            )
+        except (d.DaytonaRateLimitError, d.DaytonaServiceUnavailableError) as exc:
+            raise CreateFailure("clear", f"Daytona at capacity: {exc}", 429) from exc
+        except (
+            d.DaytonaAuthenticationError,
+            d.DaytonaAuthorizationError,
+            d.DaytonaForbiddenError,
+        ) as exc:
+            raise CreateFailure("clear", f"Daytona auth failed: {exc}", 401) from exc
+        except (
+            d.DaytonaBadRequestError,
+            d.DaytonaValidationError,
+            d.DaytonaUnprocessableEntityError,
+        ) as exc:
+            msg = str(exc).lower()
+            if "limit exceeded" in msg or "quota" in msg or "concurrency limit" in msg:
+                # e.g. "Total memory limit exceeded. Maximum allowed: 10GiB."
+                raise CreateFailure(
+                    "clear", f"Daytona account limit: {exc}", 429
+                ) from exc
+            raise CreateFailure(
+                "clear", f"Daytona rejected the request: {exc}", 400
+            ) from exc
+        except d.DaytonaConnectionError as exc:
+            raise CreateFailure("clear", f"{type(exc).__name__}: {exc}") from exc
+        except Exception as exc:
+            raise CreateFailure("ambiguous", f"{type(exc).__name__}: {exc}") from exc
+        try:
+            link = await sb.get_preview_link(EXECD_PORT)
+        except Exception as exc:
+            await self.discard(sb.id)
+            raise CreateFailure("clear", f"no preview link: {exc}") from exc
+        host = link.url.split("://", 1)[-1].rstrip("/")
+        headers = {PREVIEW_TOKEN_HEADER: link.token} if link.token else {}
+        return Provisioned(
+            upstream_id=sb.id,
+            host=host,
+            headers=headers,
+            backend_data={"preview_token": link.token},
+            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 &"
+        await sb.process.exec(f"sh -c {shlex.quote(cmd)}", env=env or None, timeout=30)
+
+    async def _get(self, id_or_name: str) -> Any | None:
+        import daytona as d
+
+        dt = await self.client()
+        try:
+            return await dt.get(id_or_name)
+        except d.DaytonaNotFoundError:
+            return None
+        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 not _live(sb):
+            return None
+        return "Running", None
+
+    async def kill(self, upstream_id: str) -> bool:
+        sb = await self._get(upstream_id)
+        if sb is None or _state(sb) in ("destroyed", "destroying"):
+            return False
+        try:
+            await sb.delete()
+        except Exception as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+        return True
+
+    def endpoint_for(
+        self, rec: SandboxRecord, port: int
+    ) -> tuple[str, dict[str, str]] | None:
+        bd = rec.backend_data or {}
+        host = bd.get("host")
+        if port != EXECD_PORT or not host:
+            return None
+        tok = bd.get("preview_token")
+        return host, ({PREVIEW_TOKEN_HEADER: tok} if tok else {})
+
+    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"}
+            )
+        minutes = max(1, math.ceil((expires_at - time.time()) / 60))
+        try:
+            await sb.set_ttl(minutes)
+        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(time.time() + minutes * 60)})
+
+    def _as_dict(self, sb: Any) -> dict[str, Any]:
+        created = getattr(sb, "created_at", None)
+        return {
+            "id": sb.id,
+            "status": {"state": "Running"},
+            "createdAt": str(created) if created else None,
+            "metadata": from_provider_tags(dict(sb.labels or {})),
+        }
+
+    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 not _live(sb):
+            return None
+        return self._as_dict(sb)
+
+    async def list_provider(self, tags: dict[str, str]) -> list[dict[str, Any]]:
+        import daytona as d
+
+        dt = await self.client()
+        out: list[dict[str, Any]] = []
+        try:
+            async for sb in dt.list(d.ListSandboxesQuery(labels=tags or None)):
+                if _live(sb):
+                    out.append(self._as_dict(sb))
+        except Exception as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+        return out

stackbox/backends/e2b.py

@@ -0,0 +1,241 @@
+"""E2B backend: Firecracker microVMs, booted from templates.
+
+E2B only boots templates, so an image must be prepared (built into a template with
+execd baked in) before E2B can serve it. Until then the router does not consider
+E2B for that image, and with ``auto_prepare`` it builds the template in the
+background. A template fixes vCPU and memory, so requests asking for more than the
+template has are not placed here.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+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,
+    iso,
+)
+
+if TYPE_CHECKING:
+    from stackbox.ledger import SandboxRecord
+
+TRAFFIC_HEADER = "e2b-traffic-access-token"
+
+
+class E2BBackend(HostedBackend):
+    kind = "e2b"
+    unprepared_support = None
+
+    def _api(self) -> dict[str, Any]:
+        opts: dict[str, Any] = {"request_timeout": self._settings.request_timeout_s}
+        if self.cfg.api_key:
+            opts["api_key"] = self.cfg.api_key
+        return opts
+
+    def template_resources(self) -> tuple[int, int]:
+        """(cpu_count, memory_mb) for templates this backend builds."""
+        cpu = max(1, math.ceil(self.cfg.default_cpu))
+        mem = max(512, round(self.cfg.default_memory_gib * 1024))
+        return cpu, mem + (mem % 2)
+
+    def template_name(self, image: str) -> str:
+        cpu, mem = self.template_resources()
+        key = f"{image}|{self.execd_digest()}|{cpu}|{mem}".encode()
+        return f"stackbox-{hashlib.sha256(key).hexdigest()[:16]}"
+
+    def allocated_resources(
+        self, image: str | None, cpu: float | None, memory_gib: float | None
+    ) -> tuple[float, float]:
+        # Billed for what the template allocates, not what was requested.
+        rec = self.image_record(image) if image else None
+        if rec is not None and rec.detail and "cpu" in rec.detail:
+            return float(rec.detail["cpu"]), float(rec.detail["memory_gib"])
+        c, m = self.template_resources()
+        return float(c), m / 1024
+
+    async def build_image(self, image: str) -> tuple[str, dict[str, Any]]:
+        from e2b import AsyncTemplate
+
+        name = self.template_name(image)
+        cpu, mem = self.template_resources()
+        detail: dict[str, Any] = {"cpu": cpu, "memory_gib": mem / 1024}
+        if await AsyncTemplate.exists(name, **self._api()):
+            return name, {**detail, "reused": True}
+        template = (
+            AsyncTemplate(file_context_path=str(self.execd_file.parent))
+            .from_image(image)
+            .copy(self.execd_file.name, EXECD_PATH, mode=0o755, user="root")
+        )
+        opts = {**self._api(), "request_timeout": 1800}
+        info = await AsyncTemplate.build(
+            template, name, cpu_count=cpu, memory_mb=mem, **opts
+        )
+        return name, {**detail, "template_id": getattr(info, "template_id", None)}
+
+    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:
+        from e2b import AsyncSandbox
+        from e2b import exceptions as ex
+
+        if image_rec is None or not image_rec.ref:
+            raise CreateFailure("clear", f"no E2B template for {image}")
+        try:
+            sb = await AsyncSandbox.create(
+                template=image_rec.ref,
+                timeout=timeout_s,
+                metadata={
+                    "stackbox_gw_id": gw_id,
+                    "stackbox_managed": self.instance_id,
+                },
+                envs=env or None,
+                idempotency_key=gw_id,
+                **{**self._api(), "request_timeout": self._settings.create_timeout_s},
+            )
+        except (ex.RateLimitException, ex.NotEnoughSpaceException) as exc:
+            raise CreateFailure("clear", f"E2B at capacity: {exc}", 429) from exc
+        except ex.AuthenticationException as exc:
+            raise CreateFailure("clear", f"E2B auth failed: {exc}", 401) from exc
+        except (ex.NotFoundException, ex.TemplateException) as exc:
+            # Template gone: forget the preparation so it is rebuilt.
+            self._ledger.set_image(
+                self.name, image, L.IMAGE_FAILED, error=f"template missing: {exc}"[:500]
+            )
+            raise CreateFailure("clear", f"E2B template missing: {exc}", 404) from exc
+        except ex.InvalidArgumentException as exc:
+            # The request was translated by us; another backend may accept it.
+            raise CreateFailure(
+                "clear", f"E2B rejected the request: {exc}", 400
+            ) from exc
+        except (httpx.ConnectError, httpx.ConnectTimeout) as exc:
+            raise CreateFailure("clear", f"{type(exc).__name__}: {exc}") from exc
+        except Exception as exc:  # timeouts, 5xx: it may exist
+            raise CreateFailure("ambiguous", f"{type(exc).__name__}: {exc}") from exc
+        tok = getattr(sb, "traffic_access_token", None)
+        return Provisioned(
+            upstream_id=sb.sandbox_id,
+            host=sb.get_host(EXECD_PORT),
+            headers={TRAFFIC_HEADER: tok} if tok else {},
+            backend_data={"domain": sb.sandbox_domain, "traffic_token": tok},
+            handle=sb,
+        )
+
+    async def start(
+        self,
+        prov: Provisioned,
+        *,
+        token: str,
+        env: dict[str, str],
+        entrypoint: list[str] | None,
+    ) -> None:
+        import shlex
+
+        sb = prov.handle
+        cmd = f"nohup {shlex.join(execd_command(token, self.cfg.execd_graceful_shutdown))} > /tmp/execd.log 2>&1 &"
+        await sb.commands.run(cmd, user="root", envs=env or None, background=True)
+        user_cmd = entrypoint_command(entrypoint)
+        if user_cmd:
+            await sb.commands.run(
+                f"nohup sh -c {shlex.quote(user_cmd)} > /tmp/entrypoint.log 2>&1 &",
+                user="root",
+                envs=env or None,
+                background=True,
+            )
+
+    async def provider_state(self, upstream_id: str) -> tuple[str, float | None] | None:
+        from e2b import AsyncSandbox
+        from e2b import exceptions as ex
+
+        try:
+            info = await AsyncSandbox.get_info(upstream_id, **self._api())
+        except ex.NotFoundException:
+            return None
+        except Exception as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+        state = str(getattr(info.state, "value", info.state)).lower()
+        end = info.end_at.timestamp() if info.end_at else None
+        return ("Paused" if state == "paused" else "Running"), end
+
+    async def kill(self, upstream_id: str) -> bool:
+        from e2b import AsyncSandbox
+
+        try:
+            return bool(await AsyncSandbox.kill(upstream_id, **self._api()))
+        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:
+        from e2b.connection_config import ConnectionConfig
+
+        bd = rec.backend_data or {}
+        cc = ConnectionConfig(
+            **({"api_key": self.cfg.api_key} if self.cfg.api_key else {})
+        )
+        host = cc.get_host(rec.upstream_id, bd.get("domain"), port)
+        tok = bd.get("traffic_token")
+        return host, ({TRAFFIC_HEADER: tok} if tok else {})
+
+    async def extend(self, rec: SandboxRecord, expires_at: float) -> UpstreamResponse:
+        import time
+
+        from e2b import AsyncSandbox
+
+        seconds = max(1, min(int(expires_at - time.time()), self.cfg.max_timeout_s))
+        try:
+            await AsyncSandbox.set_timeout(rec.upstream_id, seconds, **self._api())
+        except Exception as exc:  # noqa: BLE001 - reported to the client as 502
+            return UpstreamResponse(
+                502, {"code": "STACKBOX::BACKEND_ERROR", "message": str(exc)}
+            )
+        return UpstreamResponse(200, {"expiresAt": iso(time.time() + seconds)})
+
+    async def list_provider(self, tags: dict[str, str]) -> list[dict[str, Any]]:
+        from e2b import AsyncSandbox, SandboxQuery, SandboxState
+
+        out: list[dict[str, Any]] = []
+        try:
+            pager = AsyncSandbox.list(
+                query=SandboxQuery(
+                    metadata=tags, state=[SandboxState.RUNNING, SandboxState.PAUSED]
+                ),
+                limit=100,
+                **self._api(),
+            )
+            while pager.has_next:
+                for info in await pager.next_items():
+                    meta = from_provider_tags(info.metadata)
+                    out.append(
+                        {
+                            "id": info.sandbox_id,
+                            "status": {"state": "Running"},
+                            "createdAt": iso(info.started_at.timestamp()),
+                            "metadata": meta,
+                        }
+                    )
+        except Exception as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+        return out