bladekit 4.5.0__py3-none-any.whl

bladekit/_runner_api.py

@@ -0,0 +1,148 @@
+"""Minimal client for the *runner-internal* API, used from inside a container.
+
+Only the SDK-in-runner needs this — currently just ``volume.commit()``
+(runner-protocol.md §11). It authenticates with the run's ephemeral token and
+talks to ``{FABRIC_API_URL}/internal/runner/v1/…`` (``FORGE_API_URL`` as injected
+by the control plane today — see :mod:`bladekit._env`).
+
+Where the token comes from (PAAS-250): the runner (PID 1) reads
+``FORGE_RUNNER_TOKEN`` at boot and REMOVES it from ``os.environ`` before any user
+code is imported, so the function's subprocesses and ``env`` dumps no longer
+carry it. The SDK therefore asks the runner in-process —
+``forge_runner.runtime.credentials()`` — and only falls back to the environment
+for a runner too old to scrub it. See :func:`runner_credentials`.
+
+The runner never talks to the agent (invariant): commits are orchestrated by
+the control plane. ``httpx`` is imported lazily to keep ``import bladekit`` cheap.
+"""
+
+from __future__ import annotations
+
+from types import ModuleType
+from typing import Any, NamedTuple, Optional
+
+from . import _env
+from . import exceptions as exc
+
+
+class RunnerCredentials(NamedTuple):
+    """The run's API base URL and ephemeral token, with where they came from."""
+
+    api_url: str
+    token: str
+    source: str  # "runner" (in-process context) | "env (FABRIC_RUNNER_TOKEN)" | "env (FORGE_RUNNER_TOKEN)"
+
+
+def runner_credentials() -> Optional[RunnerCredentials]:
+    """Return the credentials of the run this process belongs to, or ``None``.
+
+    1. ``forge_runner.runtime.credentials()`` — the runner's in-process context,
+       set before user code is imported. The runner package is only importable
+       inside an AI Fabric container, so this is ``None`` on a laptop.
+    2. ``FABRIC_API_URL`` + ``FABRIC_RUNNER_TOKEN`` (or their ``FORGE_*`` spelling,
+       which is what the control plane injects today) in the environment — the legacy
+       channel, still honoured for a runner older than 1.4 that does not scrub
+       the variable. A current runner leaves nothing here to read.
+    """
+    _runner_runtime: Optional[ModuleType]
+    try:
+        from forge_runner import runtime as _runner_runtime  # type: ignore[import-not-found,no-redef]
+    except Exception:  # noqa: BLE001 — not in a container, or a foreign package
+        _runner_runtime = None
+    if _runner_runtime is not None:
+        get = getattr(_runner_runtime, "credentials", None)
+        if callable(get):
+            got = get()
+            if got:
+                api_url, token = got
+                if api_url and token:
+                    return RunnerCredentials(str(api_url), str(token), "runner")
+    base = _env.get("API_URL")
+    token, token_var = _env.lookup("RUNNER_TOKEN")
+    if base and token:
+        return RunnerCredentials(base, token, f"env ({token_var})")
+    return None
+
+# 404 VOLUME_COMMIT_NOT_FOUND / VOLUME_NOT_MOUNTED etc. map onto these.
+_CODE_EXC = {
+    "VOLUME_NOT_MOUNTED": exc.VolumeError,
+    "VOLUME_READ_ONLY": exc.VolumeCommitError,
+    "VOLUME_COMMIT_IN_PROGRESS": exc.VolumeCommitError,
+    "VOLUME_COMMIT_NOT_FOUND": exc.VolumeCommitError,
+}
+
+
+class RunnerApiClient:
+    """Synchronous client for ``/internal/runner/v1/*`` (run-token auth)."""
+
+    def __init__(self, base_url: str, runner_token: str) -> None:
+        import httpx
+
+        self.base_url = base_url.rstrip("/")
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {runner_token}",
+                "User-Agent": "forge-runner-sdk/0.1.0",
+            },
+            timeout=30.0,
+        )
+
+    @classmethod
+    def from_env(cls) -> "RunnerApiClient":
+        """Build the client from the run's credentials (see :func:`runner_credentials`).
+
+        The name predates PAAS-250: the primary source is now the runner's
+        in-process context, not the environment.
+        """
+        creds = runner_credentials()
+        if creds is None:
+            raise exc.VolumeError(
+                "volume.commit() must run inside an AI Fabric container "
+                "(no runner credentials: not started by forge-runner)."
+            )
+        return cls(creds.api_url, creds.token)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        import httpx
+
+        try:
+            resp = self._http.request(method, path, **kwargs)
+        except httpx.HTTPError as e:
+            raise exc.ConnectionFailed(
+                f"runner API call to {path} failed: {e}"
+            ) from e
+        if resp.status_code >= 400:
+            code = "INTERNAL"
+            message = f"HTTP {resp.status_code}"
+            try:
+                body = resp.json()
+                err = body.get("error") if isinstance(body, dict) else None
+                if isinstance(err, dict):
+                    code = str(err.get("code", code))
+                    message = str(err.get("message", message))
+            except ValueError:
+                pass
+            exc_cls = _CODE_EXC.get(code)
+            if exc_cls is exc.VolumeError:
+                raise exc_cls(message)
+            if exc_cls is exc.VolumeCommitError:
+                raise exc_cls(code, message)
+            raise exc.APIError(code, message, status_code=resp.status_code)
+        if resp.content:
+            return resp.json()
+        return None
+
+    def commit_volume(self, volume_id: str) -> dict:
+        """POST the commit (202 + VolumeCommit). Idempotent on network retry."""
+        return self._request(
+            "POST", f"/internal/runner/v1/volumes/{volume_id}/commit"
+        )
+
+    def get_volume_commit(self, commit_id: str) -> dict:
+        return self._request(
+            "GET", f"/internal/runner/v1/volume-commits/{commit_id}"
+        )
+
+    def close(self) -> None:
+        self._http.close()