stackbox 0.1.0__py3-none-any.whl

stackbox/backends/base.py

@@ -0,0 +1,181 @@
+"""What the router needs from a backend, and the errors backends raise.
+
+Create failures are classified so the router can decide whether retrying elsewhere
+is safe:
+
+* ``clear``     no sandbox exists on the backend (or one was created and we already
+                cleaned it up)                                  -> safe to try elsewhere
+* ``ambiguous`` the request may have been processed            -> reconcile before retrying
+* ``client``    the request itself is invalid                   -> return to caller, no retry
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal
+
+from stackbox.config import BackendConfig
+
+if TYPE_CHECKING:
+    from stackbox.ledger import SandboxRecord
+
+GW_ID_KEY = "stackbox.dev/gw-id"
+# Value: the owning gateway's instance id (one per ledger). The reconciler only ever
+# deletes sandboxes carrying its own id, so gateways sharing a provider account (or a
+# test gateway next to a production one) never delete each other's sandboxes.
+MANAGED_KEY = "stackbox.dev/managed"
+PIN_KEY = "stackbox.dev/backend"
+# Per-request routing preferences as metadata (Harbor can set metadata, not headers).
+STRATEGY_KEY = "stackbox.dev/strategy"
+PROVIDERS_KEY = (
+    "stackbox.dev/providers"  # allow-list in order: "e2b.modal" or "e2b,modal"
+)
+MAX_PRICE_KEY = "stackbox.dev/max-price"  # USD per sandbox-hour
+ROUTER_KEYS = (
+    GW_ID_KEY,
+    MANAGED_KEY,
+    PIN_KEY,
+    STRATEGY_KEY,
+    PROVIDERS_KEY,
+    MAX_PRICE_KEY,
+)
+
+GONE_STATES = {"Terminated", "Failed", "Stopping"}
+
+FailureKind = Literal["clear", "ambiguous", "client"]
+
+# What a backend can do with an image right now.
+#   ready: prepared (or the backend pulls images itself and has no preparation step)
+#   cold:  can serve it, but the first start includes an image build
+#   None:  cannot serve it until it is prepared
+ImageSupport = Literal["ready", "cold"] | None
+
+
+@dataclass
+class UpstreamResponse:
+    status: int
+    body: Any
+    headers: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class Created:
+    """A sandbox a backend created and reports as running."""
+
+    sandbox: dict[str, Any]  # OpenSandbox Sandbox shape, upstream id, router metadata
+    cpu: float | None = None  # what was actually allocated, if the backend knows
+    memory_gib: float | None = None
+    backend_data: dict[str, Any] | None = None  # persisted; e.g. endpoint details
+    cold: bool = False  # the start included an image build
+
+
+class CreateFailure(Exception):
+    def __init__(
+        self,
+        kind: FailureKind,
+        message: str,
+        status: int | None = None,
+        body: Any = None,
+    ):
+        super().__init__(message)
+        self.kind = kind
+        self.status = status
+        self.body = body
+
+
+class BackendError(Exception):
+    """A non-create call to a backend failed (network, auth, 5xx)."""
+
+
+class ReconcileError(BackendError):
+    """The backend could not be queried, so an ambiguous create stays unresolved."""
+
+
+def error_body(code: str, message: str) -> dict[str, str]:
+    return {"code": code, "message": message}
+
+
+class Backend:
+    """Interface every backend kind implements. Upstream ids never leave the router."""
+
+    kind: str = "abstract"
+    #: After an ambiguous create, a sandbox found upstream may be handed to the client.
+    #: Hosted backends set this False: a found sandbox may not have finished execd
+    #: setup, so it is deleted and the create retried instead.
+    adopt_ambiguous: bool = True
+
+    def __init__(self, cfg: BackendConfig, instance_id: str = "true"):
+        self.cfg = cfg
+        self.instance_id = instance_id
+
+    @property
+    def name(self) -> str:
+        return self.cfg.name
+
+    async def aclose(self) -> None:
+        return None
+
+    # --- placement ---------------------------------------------------------
+    def image_support(
+        self, image: str | None, cpu: float | None, memory_gib: float | None
+    ) -> ImageSupport:
+        return "ready"
+
+    def allocated_resources(
+        self, image: str | None, cpu: float | None, memory_gib: float | None
+    ) -> tuple[float, float]:
+        """(vCPU, GiB) a create with these requests would be billed for."""
+        return (
+            cpu if cpu is not None else self.cfg.default_cpu,
+            memory_gib if memory_gib is not None else self.cfg.default_memory_gib,
+        )
+
+    def price_per_hour(
+        self, image: str | None, cpu: float | None, memory_gib: float | None
+    ) -> float:
+        vcpu, gib = self.allocated_resources(image, cpu, memory_gib)
+        return (
+            vcpu * self.cfg.cost_per_vcpu_hour * self.cfg.cpu_billed_fraction
+            + gib * self.cfg.cost_per_gib_hour
+        )
+
+    async def prepare(self, image: str) -> dict[str, Any]:
+        """Make the image fast to start on this backend. Returns a summary."""
+        return {"backend": self.name, "image": image, "status": "ready", "ref": None}
+
+    # --- lifecycle ---------------------------------------------------------
+    async def create(self, body: dict[str, Any], *, gw_id: str) -> Created:
+        raise NotImplementedError
+
+    async def get(self, rec: SandboxRecord) -> UpstreamResponse:
+        raise NotImplementedError
+
+    async def delete(self, upstream_id: str) -> UpstreamResponse:
+        raise NotImplementedError
+
+    async def subresource(
+        self,
+        rec: SandboxRecord,
+        method: str,
+        rest: str,
+        *,
+        params: Any = None,
+        json: Any = None,
+    ) -> UpstreamResponse:
+        raise NotImplementedError
+
+    async def list_sandboxes(
+        self, metadata: dict[str, str] | None = None
+    ) -> list[dict[str, Any]]:
+        """Sandboxes matching the metadata filter, in OpenSandbox shape. Raises BackendError."""
+        raise NotImplementedError
+
+    async def find_by_gw_id(self, gw_id: str) -> dict[str, Any] | None:
+        try:
+            found = await self.list_sandboxes({GW_ID_KEY: gw_id})
+        except BackendError as exc:
+            raise ReconcileError(f"{self.name}: {exc}") from exc
+        live = [
+            s for s in found if (s.get("status") or {}).get("state") not in GONE_STATES
+        ]
+        return live[0] if live else None

stackbox/backends/cloudflare.py

@@ -0,0 +1,241 @@
+"""Cloudflare backend: Cloudflare Containers, through a bridge Worker you deploy.
+
+Cloudflare has no hosted "create a sandbox" API: sandboxes run inside your own Worker.
+`bridges/cloudflare/` is that Worker. It runs the task image plus execd on Cloudflare
+Containers (the layer Cloudflare's Sandbox SDK is built on), exposes a small control
+API to the gateway, and proxies execd traffic at ``<bridge>/x/<id>/...``, so no
+wildcard custom domain is needed.
+
+Config: ``url`` is the bridge (e.g. https://stackbox-bridge.<account>.workers.dev),
+``api_key`` its BRIDGE_TOKEN. Images are fixed when the bridge is deployed (one container
+class per image), so "preparing" an image only checks the bridge serves it; vCPU and
+memory come from the class's instance type. Cloudflare bills CPU by active use only:
+model that with ``cpu_billed_fraction``.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from stackbox import ledger as L
+from stackbox.backends.base import (
+    BackendError,
+    CreateFailure,
+    ReconcileError,
+    UpstreamResponse,
+)
+from stackbox.backends.hosted import (
+    EXECD_PORT,
+    HostedBackend,
+    Provisioned,
+    from_provider_tags,
+    iso,
+    parse_iso,
+)
+from stackbox.config import BackendConfig, GatewaySettings
+
+if TYPE_CHECKING:
+    from stackbox.ledger import SandboxRecord
+
+_NOT_SENT = (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout)
+
+
+class CloudflareBackend(HostedBackend):
+    kind = "cloudflare"
+    unprepared_support = None  # images are baked into the bridge deployment
+
+    def __init__(
+        self,
+        cfg: BackendConfig,
+        *,
+        settings: GatewaySettings,
+        ledger: L.Ledger,
+        token_key: str,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ):
+        super().__init__(cfg, settings=settings, ledger=ledger, token_key=token_key)
+        if not cfg.url:
+            raise ValueError(
+                f"backend {cfg.name}: kind=cloudflare requires url (the bridge)"
+            )
+        parts = urlsplit(cfg.url.rstrip("/"))
+        self.scheme = parts.scheme or "https"
+        self.bridge_host = parts.netloc + parts.path  # host[/prefix], no scheme
+        headers = {"authorization": f"Bearer {cfg.api_key}"} if cfg.api_key else {}
+        self._bridge = httpx.AsyncClient(
+            base_url=cfg.url.rstrip("/"),
+            headers=headers,
+            timeout=settings.request_timeout_s,
+            transport=transport,
+        )
+        self._images: tuple[float, dict[str, Any]] | None = None
+
+    async def aclose(self) -> None:
+        await self._bridge.aclose()
+        await super().aclose()
+
+    def sandbox_id(self, gw_id: str) -> str:
+        return f"stackbox-{gw_id}"
+
+    async def bridge_images(self) -> dict[str, Any]:
+        if self._images is None or time.monotonic() - self._images[0] > 60:
+            r = await self._bridge.get("/v1/images")
+            r.raise_for_status()
+            self._images = (time.monotonic(), r.json())
+        return self._images[1]
+
+    def allocated_resources(
+        self, image: str | None, cpu: float | None, memory_gib: float | None
+    ) -> tuple[float, float]:
+        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"])
+        return self.requested_resources(cpu, memory_gib)
+
+    async def build_image(self, image: str) -> tuple[str, dict[str, Any]]:
+        images = await self.bridge_images()
+        info = images.get(image)
+        if info is None:
+            raise RuntimeError(
+                f"the bridge does not serve {image}; add a container class for it "
+                "(bridges/cloudflare/README.md) and redeploy"
+            )
+        return str(info["binding"]), {
+            "cpu": float(info["vcpu"]),
+            "memory_gib": float(info["memory_gib"]),
+        }
+
+    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:
+        sid = self.sandbox_id(gw_id)
+        body = {
+            "id": sid,
+            "image": image,
+            "env": env,
+            "token": token,
+            "ttl_s": timeout_s,
+            "labels": {"stackbox_gw_id": gw_id, "stackbox_managed": self.instance_id},
+        }
+        try:
+            r = await self._bridge.post(
+                "/v1/sandboxes", json=body, timeout=self._settings.create_timeout_s
+            )
+        except _NOT_SENT as exc:
+            raise CreateFailure("clear", f"{type(exc).__name__}: {exc}") from exc
+        except httpx.HTTPError as exc:
+            raise CreateFailure("ambiguous", f"{type(exc).__name__}: {exc}") from exc
+        if r.status_code == 201:
+            return Provisioned(
+                upstream_id=sid,
+                host=f"{self.bridge_host}/x/{sid}",
+                backend_data={"bridge_path": f"/x/{sid}"},
+                scheme=self.scheme,
+            )
+        detail = r.text[:300]
+        if r.status_code == 429:
+            raise CreateFailure("clear", f"Cloudflare at capacity: {detail}", 429)
+        if r.status_code == 404:
+            self._ledger.set_image(
+                self.name, image, L.IMAGE_FAILED, error=f"bridge: {detail}"[:500]
+            )
+            raise CreateFailure("clear", f"bridge does not serve {image}", 404)
+        if r.status_code in (400, 401, 403):
+            raise CreateFailure(
+                "clear", f"bridge rejected create: {detail}", r.status_code
+            )
+        if r.status_code == 502:
+            # The bridge reports a failed start after destroying the container.
+            raise CreateFailure("clear", f"container failed to start: {detail}", 502)
+        # 409 (id exists), other 5xx: it may exist; the router reconciles by id.
+        raise CreateFailure(
+            "ambiguous", f"bridge {r.status_code}: {detail}", r.status_code
+        )
+
+    async def provider_state(self, upstream_id: str) -> tuple[str, float | None] | None:
+        try:
+            r = await self._bridge.get(f"/v1/sandboxes/{upstream_id}")
+        except httpx.HTTPError as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+        if r.status_code == 404:
+            return None
+        if r.status_code != 200:
+            raise BackendError(f"bridge {r.status_code}: {r.text[:200]}")
+        exp = r.json().get("expires_at")
+        return "Running", parse_iso(exp) if exp else None
+
+    async def kill(self, upstream_id: str) -> bool:
+        try:
+            r = await self._bridge.delete(f"/v1/sandboxes/{upstream_id}")
+        except httpx.HTTPError as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+        if r.status_code == 404:
+            return False
+        if r.status_code not in (200, 204):
+            raise BackendError(f"bridge {r.status_code}: {r.text[:200]}")
+        return True
+
+    def endpoint_for(
+        self, rec: SandboxRecord, port: int
+    ) -> tuple[str, dict[str, str]] | None:
+        if port != EXECD_PORT or not rec.upstream_id:
+            return None
+        return f"{self.bridge_host}/x/{rec.upstream_id}", {}
+
+    async def extend(self, rec: SandboxRecord, expires_at: float) -> UpstreamResponse:
+        try:
+            r = await self._bridge.post(
+                f"/v1/sandboxes/{rec.upstream_id}/renew-expiration",
+                json={"expires_at": iso(expires_at)},
+            )
+        except httpx.HTTPError as exc:
+            return UpstreamResponse(
+                502, {"code": "STACKBOX::BACKEND_ERROR", "message": str(exc)}
+            )
+        if r.status_code != 200:
+            return UpstreamResponse(r.status_code, r.json() if r.content else None)
+        return UpstreamResponse(200, {"expiresAt": r.json()["expires_at"]})
+
+    def _as_dict(self, item: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "id": item["id"],
+            "status": {"state": "Running"},
+            "createdAt": item.get("created_at"),
+            "metadata": from_provider_tags(item.get("labels") or {}),
+        }
+
+    async def find_by_gw_id(self, gw_id: str) -> dict[str, Any] | None:
+        sid = self.sandbox_id(gw_id)
+        try:
+            r = await self._bridge.get(f"/v1/sandboxes/{sid}")
+        except httpx.HTTPError as exc:
+            raise ReconcileError(f"{self.name}: {type(exc).__name__}: {exc}") from exc
+        if r.status_code == 404:
+            return None
+        if r.status_code != 200:
+            raise ReconcileError(f"{self.name}: bridge {r.status_code}")
+        return self._as_dict(r.json())
+
+    async def list_provider(self, tags: dict[str, str]) -> list[dict[str, Any]]:
+        try:
+            r = await self._bridge.get(
+                "/v1/sandboxes", params={f"label.{k}": v for k, v in tags.items()}
+            )
+            r.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise BackendError(f"{type(exc).__name__}: {exc}") from exc
+        return [self._as_dict(i) for i in r.json().get("items", [])]