stackbox 0.1.0__py3-none-any.whl

stackbox/config.py

@@ -0,0 +1,294 @@
+"""Gateway configuration, loaded from TOML."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class GatewaySettings(BaseModel):
+    api_key: str | None = Field(
+        default=None,
+        description="Key clients must send in OPEN-SANDBOX-API-KEY. None disables auth (local dev only).",
+    )
+    db_path: str = "stackbox.db"
+    queue_timeout_s: float = Field(
+        default=60.0,
+        description="How long a create waits for capacity on some backend before returning 503.",
+    )
+    create_timeout_s: float = Field(
+        default=120.0,
+        description="Upstream create timeout. For hosted backends this covers boot and execd readiness.",
+    )
+    request_timeout_s: float = Field(
+        default=30.0, description="Timeout for other upstream calls."
+    )
+    max_create_attempts: int = Field(
+        default=3,
+        ge=1,
+        description="Provisioning attempts per create across all backends before returning 503.",
+    )
+    breaker_failures: int = Field(
+        default=3,
+        description="Consecutive provisioning failures that open a backend's circuit breaker.",
+    )
+    breaker_cooldown_s: float = 30.0
+    reconcile_interval_s: float = 30.0
+
+
+Strategy = Literal["priority", "cost", "latency", "balanced"]
+
+
+class RoutingSettings(BaseModel):
+    strategy: Strategy = Field(
+        default="priority",
+        description=(
+            "How to order backends that can serve a create. priority: fixed priority. "
+            "cost: cheapest hourly price for the requested resources. latency: lowest "
+            "expected startup for this image. balanced: weighted mix of cost and latency."
+        ),
+    )
+    cost_weight: float = Field(default=1.0, ge=0)
+    latency_weight: float = Field(default=1.0, ge=0)
+    ewma_alpha: float = Field(
+        default=0.3,
+        gt=0,
+        le=1,
+        description="Weight of the newest startup observation in the per (backend, image) estimate.",
+    )
+    explore_samples: int = Field(
+        default=3,
+        ge=0,
+        description=(
+            "latency/balanced: a ready backend with fewer warm startup samples than this for an "
+            "image is ranked just ahead of the fastest measured one, so every backend gets "
+            "measured instead of losing forever to a prior. 0 disables exploration."
+        ),
+    )
+
+
+class BackendConfig(BaseModel):
+    name: str = Field(pattern=r"^[a-z0-9][a-z0-9-]{0,40}$")
+    kind: Literal["opensandbox", "e2b", "modal", "vercel", "daytona", "cloudflare"] = (
+        "opensandbox"
+    )
+    url: str | None = Field(
+        default=None,
+        description=(
+            "opensandbox: base URL of an OpenSandbox-compatible lifecycle API. "
+            "cloudflare: base URL of the deployed bridge Worker (bridges/cloudflare)."
+        ),
+    )
+    api_key: str | None = Field(
+        default=None,
+        description=(
+            "opensandbox: upstream OPEN-SANDBOX-API-KEY. e2b: API key (defaults to $E2B_API_KEY). "
+            "modal: unused (the Modal SDK reads ~/.modal.toml or MODAL_TOKEN_ID/SECRET)."
+        ),
+    )
+    max_active: int = Field(
+        default=10,
+        ge=1,
+        description="Sandboxes this backend may hold at once (account quota or owned capacity).",
+    )
+    priority: int = Field(
+        default=100,
+        description="Lower is preferred. The order under strategy=priority; a tie-break otherwise.",
+    )
+    cost_per_vcpu_hour: float = 0.0
+    cost_per_gib_hour: float = 0.0
+    cpu_billed_fraction: float = Field(
+        default=1.0,
+        ge=0,
+        le=1,
+        description=(
+            "Share of provisioned vCPU time the provider bills. 1.0 for providers that bill "
+            "allocated CPU; lower for ones that bill active CPU only (Vercel), set to the "
+            "workload's expected CPU utilization."
+        ),
+    )
+    startup_prior_s: float = Field(
+        default=5.0,
+        description="Expected startup for a prepared image before any observation.",
+    )
+    cold_start_prior_s: float = Field(
+        default=30.0,
+        description="Expected startup for an image this backend has not prepared yet.",
+    )
+
+    # Hosted backends (e2b, modal)
+    execd_path: str | None = Field(
+        default=None,
+        description="Local path to the static OpenSandbox execd binary baked into provider images.",
+    )
+    max_timeout_s: int = Field(
+        default=3600,
+        description="Longest sandbox lifetime the provider account allows; requests are clamped.",
+    )
+    default_cpu: float = Field(
+        default=1.0, description="vCPUs when the request sets none."
+    )
+    default_memory_gib: float = Field(
+        default=2.0, description="Memory when the request sets none."
+    )
+    execd_graceful_shutdown: str = Field(
+        default="50ms",
+        description=(
+            "execd --graceful-shutdown-timeout: how long execd holds each command's response "
+            "stream open after the command ends. execd v1.1.0 defaults to 1s, which exists so "
+            "OpenSandbox's egress sidecar can sync; hosted backends run no sidecar, and the "
+            "default adds a full second to every command."
+        ),
+    )
+    auto_prepare: bool = Field(
+        default=True,
+        description="Prepare (build) an image in the background the first time a create asks for it.",
+    )
+    modal_app: str = "stackbox"
+    vercel_images: dict[str, str] = Field(
+        default_factory=dict,
+        description=(
+            "Image -> Vercel Container Registry reference to boot when preparing, for images "
+            "Vercel cannot resolve by name (e.g. ones mirrored into VCR)."
+        ),
+    )
+    vercel_snapshot_expiration_s: int | None = Field(
+        default=None,
+        description="Lifetime of prepared Vercel snapshots; None = Vercel's default.",
+    )
+    modal_region: str | None = None
+
+    @model_validator(mode="after")
+    def _check_kind(self) -> BackendConfig:
+        if self.kind == "opensandbox" and not self.url:
+            raise ValueError(f"backend {self.name}: kind=opensandbox requires url")
+        if self.kind == "cloudflare" and not self.url:
+            raise ValueError(
+                f"backend {self.name}: kind=cloudflare requires url (the bridge)"
+            )
+        return self
+
+
+class RouterConfig(BaseModel):
+    gateway: GatewaySettings = Field(default_factory=GatewaySettings)
+    routing: RoutingSettings = Field(default_factory=RoutingSettings)
+    backends: list[BackendConfig]
+
+    def backend(self, name: str) -> BackendConfig:
+        for b in self.backends:
+            if b.name == name:
+                return b
+        raise KeyError(name)
+
+
+class ConfigError(ValueError):
+    """A config problem, worded for the person fixing it."""
+
+
+def _expand_env(value: object) -> object:
+    """ "env:NAME" strings are read from the environment, so secrets stay out of config files.
+    "env:A|B" uses the first of A, B that is set."""
+    if isinstance(value, str) and value.startswith("env:"):
+        names = value[4:].split("|")
+        for name in names:
+            if os.environ.get(name):
+                return os.environ[name]
+        raise ConfigError(
+            f"config refers to environment variable {' or '.join(names)}, which is not set"
+        )
+    if isinstance(value, dict):
+        return {k: _expand_env(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_expand_env(v) for v in value]
+    return value
+
+
+CONFIG_ENV = "STACKBOX_CONFIG"
+CONFIG_FILE = "stackbox.toml"
+
+
+def default_db_path() -> str:
+    base = os.environ.get("XDG_STATE_HOME") or str(Path.home() / ".local" / "state")
+    return str(Path(base) / "stackbox" / "stackbox.db")
+
+
+def _with_catalog_defaults(backend: dict) -> dict:
+    """Fill in what the provider catalog knows (prices, limits, sizes) for unset fields."""
+    from stackbox.catalog import defaults_for
+
+    kind = backend.get("kind", "opensandbox")
+    merged = {**defaults_for(kind), **backend}
+    merged.setdefault("name", kind)
+    return merged
+
+
+def build_config(data: dict, base_dir: Path | None = None) -> RouterConfig:
+    data = dict(data)
+    data["backends"] = [_with_catalog_defaults(b) for b in data.get("backends") or []]
+    data = _expand_env(data)  # type: ignore[assignment]
+    cfg = RouterConfig.model_validate(data)
+    names = [b.name for b in cfg.backends]
+    dupes = sorted({n for n in names if names.count(n) > 1})
+    if dupes:
+        raise ConfigError(f"backend names must be unique; repeated: {', '.join(dupes)}")
+    if not cfg.backends:
+        raise ConfigError(
+            "no backends configured. Add a [[backends]] block, or set a provider's "
+            "credentials (see `stackbox providers`)."
+        )
+    for b in cfg.backends:
+        if b.execd_path and base_dir and not Path(b.execd_path).is_absolute():
+            b.execd_path = str((base_dir / b.execd_path).resolve())
+    return cfg
+
+
+def load_config(path: str | Path) -> RouterConfig:
+    path = Path(path)
+    if not path.is_file():
+        raise ConfigError(f"config file {path} not found")
+    try:
+        data = tomllib.loads(path.read_text())
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{path}: invalid TOML: {exc}") from exc
+    data.setdefault("gateway", {})
+    return build_config(data, base_dir=path.parent)
+
+
+def auto_config() -> RouterConfig:
+    """A config built from whichever providers have credentials in the environment."""
+    from stackbox.catalog import detected
+
+    found = detected()
+    if not found:
+        raise ConfigError(
+            "no provider credentials found in the environment and no config file. "
+            "Set one provider's credentials (e.g. export E2B_API_KEY=...), or run "
+            "`stackbox init`. See `stackbox providers`."
+        )
+    return build_config(
+        {
+            "gateway": {
+                "db_path": default_db_path(),
+                "api_key": os.environ.get("STACKBOX_API_KEY") or None,
+            },
+            "routing": {"strategy": "balanced"},
+            "backends": [{"kind": p.kind} for p in found],
+        }
+    )
+
+
+def resolve_config(path: str | Path | None = None) -> tuple[RouterConfig, str]:
+    """Explicit path, then $STACKBOX_CONFIG, then ./stackbox.toml, then
+    auto-detection. Returns the config and where it came from."""
+    if path:
+        return load_config(path), str(path)
+    if os.environ.get(CONFIG_ENV):
+        env = os.environ[CONFIG_ENV]
+        return load_config(env), f"{env} (from ${CONFIG_ENV})"
+    if Path(CONFIG_FILE).is_file():
+        return load_config(CONFIG_FILE), f"./{CONFIG_FILE}"
+    return auto_config(), "auto-detected from environment credentials"

stackbox/execd.py

@@ -0,0 +1,118 @@
+"""Get OpenSandbox's static execd binary without Docker.
+
+Hosted backends run execd inside every sandbox. Instead of asking users to copy it out
+of an image by hand, it is downloaded once from the public ``opensandbox/execd`` image
+(Docker Hub registry API, anonymous) and cached under ``$XDG_CACHE_HOME/stackbox``.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import stat
+import tarfile
+import tempfile
+from pathlib import Path
+
+import httpx
+
+EXECD_IMAGE = "opensandbox/execd"
+EXECD_TAG = "v1.1.0"
+_REGISTRY = "https://registry-1.docker.io"
+_AUTH = "https://auth.docker.io/token"
+_ACCEPT = (
+    "application/vnd.oci.image.index.v1+json, "
+    "application/vnd.docker.distribution.manifest.list.v2+json, "
+    "application/vnd.oci.image.manifest.v1+json, "
+    "application/vnd.docker.distribution.manifest.v2+json"
+)
+
+
+class ExecdError(RuntimeError):
+    pass
+
+
+def cache_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / "stackbox"
+
+
+def cached_path(tag: str = EXECD_TAG) -> Path:
+    return cache_dir() / f"execd-{tag}-linux-amd64"
+
+
+def _is_execd(member: tarfile.TarInfo) -> bool:
+    name = member.name.lstrip("./")
+    return member.isfile() and (name == "execd" or name.endswith("/execd"))
+
+
+def download(dest: Path, tag: str = EXECD_TAG, *, timeout: float = 300) -> Path:
+    """Fetch execd (linux/amd64) from the registry into ``dest``."""
+    with httpx.Client(timeout=timeout, follow_redirects=True) as c:
+        try:
+            token = c.get(
+                _AUTH,
+                params={
+                    "service": "registry.docker.io",
+                    "scope": f"repository:{EXECD_IMAGE}:pull",
+                },
+            ).json()["token"]
+            h = {"Authorization": f"Bearer {token}", "Accept": _ACCEPT}
+            m = c.get(f"{_REGISTRY}/v2/{EXECD_IMAGE}/manifests/{tag}", headers=h)
+            m.raise_for_status()
+            manifest = m.json()
+            if "manifests" in manifest:  # multi-arch index
+                amd64 = next(
+                    x
+                    for x in manifest["manifests"]
+                    if x.get("platform", {}).get("architecture") == "amd64"
+                    and x.get("platform", {}).get("os") == "linux"
+                )
+                m = c.get(
+                    f"{_REGISTRY}/v2/{EXECD_IMAGE}/manifests/{amd64['digest']}",
+                    headers=h,
+                )
+                m.raise_for_status()
+                manifest = m.json()
+            # The top-most layer that contains execd wins.
+            for layer in reversed(manifest["layers"]):
+                blob = c.get(
+                    f"{_REGISTRY}/v2/{EXECD_IMAGE}/blobs/{layer['digest']}", headers=h
+                )
+                blob.raise_for_status()
+                with tarfile.open(fileobj=io.BytesIO(blob.content), mode="r:*") as tar:
+                    member = next((m for m in tar.getmembers() if _is_execd(m)), None)
+                    if member is None:
+                        continue
+                    data = tar.extractfile(member).read()  # type: ignore[union-attr]
+                break
+            else:
+                raise ExecdError(f"no execd binary found in {EXECD_IMAGE}:{tag}")
+        except (httpx.HTTPError, KeyError, StopIteration) as exc:
+            raise ExecdError(
+                f"could not download execd from {EXECD_IMAGE}:{tag}: {exc}. "
+                "Set execd_path in the config to a local copy instead."
+            ) from exc
+    if not data.startswith(b"\x7fELF"):
+        raise ExecdError("downloaded execd is not an ELF binary")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(dir=dest.parent, delete=False) as tmp:
+        tmp.write(data)
+    os.chmod(tmp.name, 0o755)
+    os.replace(tmp.name, dest)
+    return dest
+
+
+def ensure(path: str | None = None) -> Path:
+    """The execd to use: an explicit path, else the cached download (fetched on first use)."""
+    if path:
+        p = Path(path).expanduser()
+        if not p.is_file():
+            raise ExecdError(f"execd_path {p} does not exist")
+        return p
+    p = cached_path()
+    if not p.is_file():
+        download(p)
+    if not p.stat().st_mode & stat.S_IXUSR:
+        os.chmod(p, 0o755)
+    return p