bladekit 4.5.0__py3-none-any.whl

bladekit/_client.py

@@ -0,0 +1,1152 @@
+"""Thin HTTP client over the control plane ``/v1/*`` surface.
+
+Responsibilities:
+- attach the bearer token,
+- decode the standard error envelope (conventions.md §2) into typed exceptions,
+- expose the handful of endpoints the SDK/CLI use.
+
+``httpx`` is imported lazily so ``import bladekit`` stays cheap.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Mapping, Optional
+from urllib.parse import quote
+
+from . import exceptions as exc
+from ._constants import DEFAULT_PAGE_LIMIT
+
+# HTTP status -> envelope-aware exception class. The ``code`` in the envelope is
+# authoritative; status only picks the broad family for unknown codes.
+_STATUS_EXC = {
+    400: exc.InvalidArgumentError,
+    401: exc.AuthenticationError,
+    403: exc.PermissionDeniedError,
+    404: exc.NotFoundError,
+    409: exc.ConflictError,
+    413: exc.PayloadTooLargeError,
+    503: exc.UnavailableError,
+}
+
+_CODE_EXC = {
+    "UNAUTHENTICATED": exc.AuthenticationError,
+    "RUN_TOKEN_EXPIRED": exc.AuthenticationError,
+    "PERMISSION_DENIED": exc.PermissionDeniedError,
+    "NOT_FOUND": exc.NotFoundError,
+    "RUN_NOT_FOUND": exc.NotFoundError,
+    "CALL_NOT_FOUND": exc.NotFoundError,
+    "BUNDLE_NOT_FOUND": exc.NotFoundError,
+    "NODE_NOT_FOUND": exc.NotFoundError,
+    "INVALID_ARGUMENT": exc.InvalidArgumentError,
+    "INVALID_CURSOR": exc.InvalidArgumentError,
+    "IMAGE_ALIAS_UNKNOWN": exc.InvalidArgumentError,
+    "BUNDLE_NOT_READY": exc.ConflictError,
+    "BUNDLE_CHECKSUM_MISMATCH": exc.ConflictError,
+    "RUN_NOT_CANCELLABLE": exc.ConflictError,
+    "RUN_NOT_ACCEPTING_CALLS": exc.ConflictError,
+    "CALL_ALREADY_FINISHED": exc.ConflictError,
+    "BUNDLE_TOO_LARGE": exc.PayloadTooLargeError,
+    "PAYLOAD_TOO_LARGE": exc.PayloadTooLargeError,
+    "UNAVAILABLE": exc.UnavailableError,
+    "IMAGE_BUILD_NOT_FOUND": exc.NotFoundError,
+    "VOLUME_NOT_FOUND": exc.NotFoundError,
+    "SECRET_NOT_FOUND": exc.NotFoundError,
+    "VOLUME_COMMIT_NOT_FOUND": exc.NotFoundError,
+    "VOLUME_FILE_NOT_FOUND": exc.NotFoundError,
+    "IMAGE_DEFINITION_INVALID": exc.InvalidArgumentError,
+    # Submit-time refusal of a run whose pickle would cross Python minors. The
+    # same verdict the runner would reach at boot (VersionMismatchError, run
+    # level), raised here as an API error because nothing was ever created.
+    "PYTHON_VERSION_INCOMPATIBLE": exc.InvalidArgumentError,
+    "MOUNT_PATH_INVALID": exc.InvalidArgumentError,
+    "SECRET_KEY_RESERVED": exc.InvalidArgumentError,
+    "IMAGE_BUILD_NOT_READY": exc.ConflictError,
+    "IMAGE_BUILD_FAILED": exc.ConflictError,
+    "VOLUME_IN_USE": exc.ConflictError,
+    "VOLUME_COMMIT_OBJECTS_MISSING": exc.ConflictError,
+    "VOLUME_COMMIT_NOT_PENDING": exc.ConflictError,
+    "RUN_NOT_UPDATABLE": exc.ConflictError,
+    "RUN_NOT_SERVING": exc.ConflictError,
+    "APP_NAME_INVALID": exc.InvalidArgumentError,
+    "APP_NOT_FOUND": exc.NotFoundError,
+    "DEPLOYMENT_NOT_FOUND": exc.NotFoundError,
+    "AUTOSCALE_LIMIT_INVALID": exc.InvalidArgumentError,
+    "ENDPOINT_ROUTE_CONFLICT": exc.ConflictError,
+    "DEPLOYMENT_NOT_READY": exc.ConflictError,
+    "DEPLOYMENT_NOT_ROLLBACKABLE": exc.ConflictError,
+    "APP_STOPPED": exc.UnavailableError,
+    "MAP_NOT_FOUND": exc.NotFoundError,
+    "MAP_INPUT_NOT_FOUND": exc.NotFoundError,
+    "CRON_NOT_FOUND": exc.NotFoundError,
+    "CRON_EXECUTION_NOT_FOUND": exc.NotFoundError,
+    "QUEUE_NOT_FOUND": exc.NotFoundError,
+    "DICT_NOT_FOUND": exc.NotFoundError,
+    "NAMESPACE_NOT_FOUND": exc.NotFoundError,
+    "MAP_NOT_ACCEPTING_INPUTS": exc.ConflictError,
+    "MAP_NOT_CANCELLABLE": exc.ConflictError,
+    "MAP_INPUTS_NOT_FINALIZED": exc.ConflictError,
+    "CRON_EXPRESSION_INVALID": exc.InvalidArgumentError,
+    "CRON_NOT_TRIGGERABLE": exc.ConflictError,
+    "QUEUE_NAME_INVALID": exc.InvalidArgumentError,
+    "DICT_NAME_INVALID": exc.InvalidArgumentError,
+    "QUEUE_ITEM_TOO_LARGE": exc.PayloadTooLargeError,
+    "DICT_VALUE_TOO_LARGE": exc.PayloadTooLargeError,
+    "DICT_KEY_TOO_LARGE": exc.InvalidArgumentError,
+    "PRIORITY_INVALID": exc.InvalidArgumentError,
+    "RETRY_POLICY_INVALID": exc.InvalidArgumentError,
+    "GPU_QUOTA_EXCEEDED": exc.GPUQuotaExceededError,
+    "ORG_GPU_QUOTA_EXCEEDED": exc.OrgGPUQuotaExceededError,
+    # --- sandbox errors ---
+    "SANDBOX_NOT_FOUND": exc.NotFoundError,
+    "SANDBOX_EXEC_NOT_FOUND": exc.NotFoundError,
+    "SANDBOX_TUNNEL_NOT_FOUND": exc.NotFoundError,
+    "SANDBOX_NOT_RUNNING": exc.SandboxNotRunningError,
+    "SANDBOX_EXEC_LIMIT": exc.SandboxExecLimitError,
+    "SANDBOX_FILE_NOT_FOUND": exc.SandboxFileNotFoundError,
+    "SANDBOX_FILE_TOO_LARGE": exc.SandboxFileTooLargeError,
+    "SANDBOX_PATH_INVALID": exc.SandboxPathInvalidError,
+    "SANDBOX_DISK_QUOTA_EXCEEDED": exc.SandboxDiskQuotaExceededError,
+    "SANDBOX_PORT_IN_USE": exc.SandboxPortInUseError,
+    "RUNTIME_INVALID": exc.InvalidArgumentError,
+}
+
+
+def _version_tuple(v: str) -> tuple:
+    """Best-effort numeric semver key: leading ``major.minor.patch`` ints.
+
+    Stops at the first non-numeric component (pre-release / build metadata), so
+    ``0.1.0+g1a2b3c4`` -> ``(0, 1, 0)``. Unparseable -> ``(0,)``.
+    """
+    head = v.strip().lstrip("vV").split("+", 1)[0].split("-", 1)[0]
+    parts: list[int] = []
+    for chunk in head.split("."):
+        if chunk.isdigit():
+            parts.append(int(chunk))
+        else:
+            break
+    return tuple(parts) if parts else (0,)
+
+
+def _version_lt(current: str, minimum: str) -> bool:
+    """True iff ``current`` is strictly below ``minimum`` (numeric semver)."""
+    return _version_tuple(current) < _version_tuple(minimum)
+
+
+def _raise_for_envelope(status: int, body: Any) -> None:
+    code = "INTERNAL"
+    message = f"HTTP {status}"
+    details: Mapping[str, Any] = {}
+    if isinstance(body, Mapping):
+        err = body.get("error")
+        if isinstance(err, Mapping):
+            code = str(err.get("code", code))
+            message = str(err.get("message", message))
+            details = err.get("details") or {}
+
+    # Prefer the machine code for the class; fall back to status family; then
+    # a generic APIError so unknown codes are still surfaced (conventions §2).
+    cls = _CODE_EXC.get(code) or _STATUS_EXC.get(status) or exc.APIError
+    raise cls(code, message, status_code=status, details=details)
+
+
+def _could_not_connect(err: BaseException) -> bool:
+    """True when the request never reached a server.
+
+    `_request` collapses every httpx error into ConnectionFailed, read timeouts
+    included. Only a failed CONNECT may be retried against a different address: a read
+    timeout means the host accepted the request, and re-sending it elsewhere would run
+    the caller's work twice.
+    """
+    import httpx
+
+    return isinstance(err.__cause__, (httpx.ConnectError, httpx.ConnectTimeout))
+
+
+class Client:
+    """Synchronous control-plane client."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token: Optional[str],
+        *,
+        timeout: float = 30.0,
+        transport: Any = None,
+    ) -> None:
+        import httpx
+
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        headers = {"User-Agent": "forge-sdk/0.3.0"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        # ``transport`` lets tests inject an in-process ASGI/WSGI transport.
+        kwargs: dict[str, Any] = {
+            "base_url": self.base_url,
+            "headers": headers,
+            "timeout": timeout,
+        }
+        if transport is not None:
+            kwargs["transport"] = transport
+        self._http = httpx.Client(**kwargs)
+        # Per-instance guard so the version handshake fires at most once per client
+        # *after a successful contact*. Per-instance (not process-global) so a 2nd
+        # Client — e.g. the App lifecycle creating its own — still checks; the lock
+        # makes the at-most-once promise safe if a worker thread also touches it.
+        self._version_checked = False
+        self._version_lock = threading.Lock()
+
+    # -- low level ----------------------------------------------------------
+
+    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:  # connect/read/timeout
+            raise exc.ConnectionFailed(
+                f"could not reach control plane at {self.base_url}: {e}"
+            ) from e
+
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+            except ValueError:
+                body = None
+            _raise_for_envelope(resp.status_code, body)
+
+        if resp.content:
+            return resp.json()
+        return None
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    # -- meta ---------------------------------------------------------------
+
+    def get_version(self) -> dict:
+        return self._request("GET", "/v1/version")
+
+    def warn_if_outdated(self) -> None:
+        """Call ``/v1/version`` once and warn if the SDK is below ``min_sdk_version``.
+
+        Per openapi ``/v1/version``: the SDK calls this on first contact and shows
+        a warning if the server announces a ``min_sdk_version`` greater than the
+        SDK's own version. Best-effort: any network/parse failure is swallowed so a
+        version smoke-test never breaks a real command.
+
+        The HTTP call is made **outside** the lock so that a slow or stalled
+        control plane does not block a second thread that also calls this method
+        (e.g. the log-pump thread in blade serve). The lock only protects the
+        read/write of ``_version_checked``.
+        """
+        with self._version_lock:
+            if self._version_checked:
+                return
+        # Network call outside the lock.
+        try:
+            info = self.get_version()
+        except exc.FabricError:
+            # Transient failure (server not yet reachable): leave the guard
+            # unset so a later command re-attempts the smoke-test instead of
+            # silently disarming the compat warning for the process lifetime.
+            return
+        # Write back under the lock — another thread may have raced us.
+        with self._version_lock:
+            if self._version_checked:
+                # Other thread beat us; they already printed any warning.
+                return
+            self._version_checked = True
+        if not isinstance(info, Mapping):
+            return
+        min_sdk = info.get("min_sdk_version")
+        if not min_sdk:
+            return
+        from . import __version__
+
+        if _version_lt(__version__, str(min_sdk)):
+            from ._render import err_console
+
+            err_console.print(
+                f"[yellow]warning[/yellow]: bladekit {__version__} is older than the "
+                f"server's minimum ({min_sdk}). Upgrade with "
+                f"`pip install --upgrade bladekit`."
+            )
+
+    def healthz(self) -> dict:
+        return self._request("GET", "/healthz")
+
+    # -- bundles ------------------------------------------------------------
+
+    def create_bundle(self, size_bytes: int, sha256: str) -> dict:
+        return self._request(
+            "POST",
+            "/v1/bundles",
+            json={"size_bytes": size_bytes, "sha256": sha256},
+        )
+
+    def complete_bundle(self, bundle_id: str) -> dict:
+        return self._request("POST", f"/v1/bundles/{bundle_id}/complete")
+
+    def upload_to_presigned(self, url: str, data: bytes, content_type: str) -> None:
+        """PUT raw bytes to a presigned URL (bundle or payload)."""
+        import httpx
+
+        try:
+            resp = httpx.put(
+                url, content=data, headers={"Content-Type": content_type}, timeout=300.0
+            )
+        except httpx.HTTPError as e:
+            raise exc.ConnectionFailed(f"upload to object store failed: {e}") from e
+        if resp.status_code >= 400:
+            raise exc.FabricError(
+                f"object store rejected upload (HTTP {resp.status_code})"
+            )
+
+    def download_presigned(self, url: str) -> bytes:
+        import httpx
+
+        try:
+            resp = httpx.get(url, timeout=300.0)
+        except httpx.HTTPError as e:
+            raise exc.ConnectionFailed(f"download from object store failed: {e}") from e
+        if resp.status_code >= 400:
+            raise exc.FabricError(
+                f"object store rejected download (HTTP {resp.status_code})"
+            )
+        return resp.content
+
+    # -- payloads -----------------------------------------------------------
+
+    def create_payload(self, size_bytes: int, sha256: str) -> dict:
+        return self._request(
+            "POST",
+            "/v1/payloads",
+            json={"size_bytes": size_bytes, "sha256": sha256},
+        )
+
+    # -- runs ---------------------------------------------------------------
+
+    def create_run(self, body: dict) -> dict:
+        return self._request("POST", "/v1/runs", json=body)
+
+    def get_run(self, run_id: str) -> dict:
+        return self._request("GET", f"/v1/runs/{run_id}")
+
+    def list_runs(
+        self,
+        *,
+        state: Optional[list] = None,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if state:
+            params["state"] = state
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/v1/runs", params=params)
+
+    def cancel_run(self, run_id: str) -> dict:
+        return self._request("POST", f"/v1/runs/{run_id}/cancel")
+
+    # ---- admin (role=admin tokens only; PAAS-24 containment) ----
+
+    def admin_contain_user(self, user_id: str, reason: str = "") -> dict:
+        """Stop every workload of an account (graceful then hard). Idempotent.
+        The suspension itself is iam's (the backoffice)."""
+        return self._request(
+            "POST", f"/v1/admin/users/{user_id}/contain", json={"reason": reason}
+        )
+
+    def admin_force_stop(self, kind: str, ref: str) -> dict:
+        """Force-stop ANY tenant's workload (audited). kind is one of
+        app, deployment, run, sandbox, map."""
+        path = {
+            "app": f"/v1/admin/apps/{ref}/stop",
+            "deployment": f"/v1/admin/deployments/{ref}/stop",
+            "run": f"/v1/admin/runs/{ref}/cancel",
+            "sandbox": f"/v1/admin/sandboxes/{ref}/terminate",
+            "map": f"/v1/admin/maps/{ref}/cancel",
+        }[kind]
+        return self._request("POST", path)
+
+    def complete_run(self, run_id: str) -> dict:
+        return self._request("POST", f"/v1/runs/{run_id}/complete")
+
+    # -- calls --------------------------------------------------------------
+
+    def create_call(self, run_id: str, args_payload: dict) -> dict:
+        return self._request(
+            "POST", f"/v1/runs/{run_id}/calls", json={"args": args_payload}
+        )
+
+    def get_call(self, call_id: str) -> dict:
+        return self._request("GET", f"/v1/calls/{call_id}")
+
+    def spawn_async_endpoint(
+        self, app_name: str, path: str, *, input: Any, webhook: Optional[dict] = None
+    ) -> dict:
+        """POST /v1/serve-async/<app>/<path> — enqueue an async job on a deployed
+        endpoint; the control plane answers 202 with a call_id without holding the
+        connection (async-jobs-study.md)."""
+        body: dict[str, Any] = {"input": input}
+        if webhook:
+            body["webhook"] = webhook
+        app_seg = quote(app_name, safe="")
+        path_seg = quote(path.lstrip("/"), safe="/")
+        return self._request("POST", f"/v1/serve-async/{app_seg}/{path_seg}", json=body)
+
+    def cancel_call(self, call_id: str) -> dict:
+        return self._request("POST", f"/v1/calls/{call_id}/cancel")
+
+    # -- logs ---------------------------------------------------------------
+
+    def get_logs(
+        self,
+        run_id: str,
+        *,
+        cursor: Optional[int] = None,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        stream: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if cursor is not None:
+            params["cursor"] = cursor
+        if stream:
+            params["stream"] = stream
+        return self._request("GET", f"/v1/runs/{run_id}/logs", params=params)
+
+    def stream_logs(self, run_id: str, *, cursor: Optional[int] = None):
+        """Yield SSE events as ``(event, data_str, event_id)`` tuples.
+
+        Used by ``blade run`` / ``blade logs --follow``. Reconnection with a
+        resume cursor is handled by the caller (it re-invokes with the last seq).
+        """
+        import httpx
+
+        params: dict[str, Any] = {}
+        headers: dict[str, str] = {}
+        if cursor is not None:
+            # Resume via the standard SSE header only; the contract says the header
+            # wins over ?cursor= when both are present, so sending both is just
+            # redundancy that could mask a divergence bug later (Last-Event-ID is
+            # also what an EventSource-style reconnect would send natively).
+            headers["Last-Event-ID"] = str(cursor)
+
+        try:
+            with self._http.stream(
+                "GET",
+                f"/v1/runs/{run_id}/logs/stream",
+                params=params,
+                headers=headers,
+                # Finite read timeout: the server sends `event: ping` every 15 s
+                # (openapi /logs/stream). 60 s (4× ping) tolerates jitter but still
+                # bounds a silently-wedged socket so iter_lines() can't block
+                # forever — a ReadTimeout surfaces as ConnectionFailed and the
+                # caller reconnects from the last seq.
+                timeout=httpx.Timeout(connect=5.0, read=60.0, write=5.0, pool=5.0),
+            ) as resp:
+                if resp.status_code >= 400:
+                    body = resp.read()
+                    try:
+                        import json
+
+                        parsed = json.loads(body)
+                    except ValueError:
+                        parsed = None
+                    _raise_for_envelope(resp.status_code, parsed)
+                yield from _warn_on_gap(_parse_sse(resp.iter_lines()))
+        except httpx.HTTPError as e:
+            raise exc.ConnectionFailed(f"log stream failed: {e}") from e
+
+    # -- image builds -------------------------------------------------------
+
+    def create_image_build(
+        self,
+        definition: dict,
+        definition_hash: Optional[str] = None,
+        *,
+        force: bool = False,
+        force_compression: bool = False,
+        context_bundle_id: Optional[str] = None,
+    ) -> dict:
+        body: dict[str, Any] = {"definition": definition}
+        if definition_hash:
+            body["definition_hash"] = definition_hash
+        if force:
+            body["force"] = True
+        if context_bundle_id:
+            # from_dockerfile build context (docs/specs/image-from-dockerfile.md):
+            # required iff definition.base.context_sha256 is set.
+            body["context_bundle_id"] = context_bundle_id
+        if force_compression:
+            # Admin-only operator knob (phase2-dogfood-catalog-build.md §4b/§4f.5):
+            # omit the field entirely by default so ordinary callers see no
+            # behavior change — only `--force-compression` sends it.
+            body["force_compression"] = True
+        return self._request("POST", "/v1/images/builds", json=body)
+
+    def get_image_build(self, build_id: str) -> dict:
+        return self._request("GET", f"/v1/images/builds/{build_id}")
+
+    def list_image_builds(
+        self,
+        *,
+        definition_hash: Optional[str] = None,
+        state: Optional[list] = None,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if definition_hash:
+            params["definition_hash"] = definition_hash
+        if state:
+            params["state"] = state
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/v1/images/builds", params=params)
+
+    def list_images(self, *, limit: int = DEFAULT_PAGE_LIMIT, cursor: Optional[str] = None) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/v1/images", params=params)
+
+    def stream_build_logs(self, build_id: str, *, cursor: Optional[int] = None):
+        """Yield SSE ``(event, data, id)`` tuples for a build's logs (same as runs)."""
+        import httpx
+
+        headers: dict[str, str] = {}
+        if cursor is not None:
+            headers["Last-Event-ID"] = str(cursor)
+        try:
+            with self._http.stream(
+                "GET",
+                f"/v1/images/builds/{build_id}/logs/stream",
+                headers=headers,
+                timeout=httpx.Timeout(connect=5.0, read=60.0, write=5.0, pool=5.0),
+            ) as resp:
+                if resp.status_code >= 400:
+                    body = resp.read()
+                    try:
+                        import json
+
+                        parsed = json.loads(body)
+                    except ValueError:
+                        parsed = None
+                    _raise_for_envelope(resp.status_code, parsed)
+                yield from _parse_sse(resp.iter_lines())
+        except httpx.HTTPError as e:
+            raise exc.ConnectionFailed(f"build log stream failed: {e}") from e
+
+    def get_build_logs(
+        self, build_id: str, *, cursor: Optional[int] = None, limit: int = DEFAULT_PAGE_LIMIT
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if cursor is not None:
+            params["cursor"] = cursor
+        return self._request("GET", f"/v1/images/builds/{build_id}/logs", params=params)
+
+    # -- volumes ------------------------------------------------------------
+
+    def create_volume(self, name: str) -> dict:
+        return self._request("POST", "/v1/volumes", json={"name": name})
+
+    def list_volumes(
+        self,
+        *,
+        name: Optional[str] = None,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if name:
+            params["name"] = name
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/v1/volumes", params=params)
+
+    def get_volume(self, volume_id: str) -> dict:
+        return self._request("GET", f"/v1/volumes/{volume_id}")
+
+    def delete_volume(self, volume_id: str) -> None:
+        self._request("DELETE", f"/v1/volumes/{volume_id}")
+
+    def list_volume_files(
+        self,
+        volume_id: str,
+        *,
+        path: str = "/",
+        generation: Optional[int] = None,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"path": path, "limit": limit}
+        if generation is not None:
+            params["generation"] = generation
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", f"/v1/volumes/{volume_id}/files", params=params)
+
+    def get_volume_file_content(
+        self, volume_id: str, path: str, *, generation: Optional[int] = None
+    ) -> dict:
+        params: dict[str, Any] = {"path": path}
+        if generation is not None:
+            params["generation"] = generation
+        return self._request(
+            "GET", f"/v1/volumes/{volume_id}/files/content", params=params
+        )
+
+    def create_volume_commit(self, volume_id: str, body: dict) -> dict:
+        return self._request("POST", f"/v1/volumes/{volume_id}/commits", json=body)
+
+    def finalize_volume_commit(self, volume_id: str, commit_id: str) -> dict:
+        return self._request(
+            "POST", f"/v1/volumes/{volume_id}/commits/{commit_id}/finalize"
+        )
+
+    def list_volume_commits(
+        self, volume_id: str, *, limit: int = DEFAULT_PAGE_LIMIT, cursor: Optional[str] = None
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", f"/v1/volumes/{volume_id}/commits", params=params)
+
+    # -- secrets ------------------------------------------------------------
+
+    def set_secret(self, name: str, values: dict) -> dict:
+        return self._request(
+            "POST", "/v1/secrets", json={"name": name, "values": values}
+        )
+
+    def list_secrets(
+        self,
+        *,
+        name: Optional[str] = None,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if name:
+            params["name"] = name
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/v1/secrets", params=params)
+
+    def delete_secret(self, secret_id: str) -> None:
+        self._request("DELETE", f"/v1/secrets/{secret_id}")
+
+    # -- gpu types ----------------------------------------------------------
+
+    def list_gpu_types(self) -> dict:
+        return self._request("GET", "/v1/gpu-types")
+
+    # -- hot bundle reload (blade serve) ------------------------------------
+
+    def update_run_bundle(self, run_id: str, bundle_id: str) -> dict:
+        return self._request(
+            "POST", f"/v1/runs/{run_id}/bundle", json={"bundle_id": bundle_id}
+        )
+
+    # -- apps / deployments -------------------------------------------------
+
+    def create_app(self, name: str) -> dict:
+        return self._request("POST", "/v1/apps", json={"name": name})
+
+    def list_apps(
+        self,
+        *,
+        name: Optional[str] = None,
+        state: Optional[str] = None,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if name:
+            params["name"] = name
+        if state:
+            params["state"] = state
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/v1/apps", params=params)
+
+    def get_app(self, app_id: str) -> dict:
+        return self._request("GET", f"/v1/apps/{app_id}")
+
+    def get_app_coldstarts(self, app_id: str, *, limit: Optional[int] = None) -> dict:
+        """Recent cold-start breakdowns for an app (newest first).
+
+        Recomputed on the fly from ready replicas' phase columns; returns
+        ``{"items": []}`` when no replica has gone ready yet (the common case
+        right after a ``min_replicas=0`` deploy), so callers must treat the
+        result as best-effort.
+        """
+        params: dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        return self._request(
+            "GET", f"/v1/apps/{app_id}/coldstarts", params=params or None
+        )
+
+    def get_app_by_name(self, name: str) -> dict:
+        page = self.list_apps(name=name, limit=1)
+        for app in page.get("items", []):
+            if app.get("name") == name:
+                return app
+        raise exc.NotFoundError("APP_NOT_FOUND", f"app {name!r} not found")
+
+    def stop_app(self, app_id: str) -> dict:
+        return self._request("POST", f"/v1/apps/{app_id}/stop")
+
+    def scale_endpoint(
+        self,
+        app_id: str,
+        endpoint_name: str,
+        *,
+        min_replicas: Optional[int] = None,
+        max_replicas: Optional[int] = None,
+        max_concurrent_inputs: Optional[int] = None,
+        scale_down_idle_seconds: Optional[int] = None,
+        reserved_replicas: Optional[int] = None,
+        scaling_policy: Optional[dict] = None,
+        clear_scaling_policy: bool = False,
+    ) -> dict:
+        """Update a deployed endpoint's autoscaling bounds live (no redeploy).
+
+        Only the provided fields change; the autoscaler picks the new bounds up
+        on its next tick. Returns the updated app.
+
+        ``scaling_policy`` is a FULL REPLACEMENT of the endpoint's v2 policy
+        (the wire ``{"v": 1, ...}`` document) — the server never merges it
+        field by field. Pass ``clear_scaling_policy=True`` to send an explicit
+        ``null`` (back to default concurrency autoscaling).
+        """
+        body: dict[str, Any] = {}
+        if min_replicas is not None:
+            body["min_replicas"] = min_replicas
+        if max_replicas is not None:
+            body["max_replicas"] = max_replicas
+        if max_concurrent_inputs is not None:
+            body["max_concurrent_inputs"] = max_concurrent_inputs
+        if scale_down_idle_seconds is not None:
+            body["scale_down_idle_seconds"] = scale_down_idle_seconds
+        if reserved_replicas is not None:
+            body["reserved_replicas"] = reserved_replicas
+        if clear_scaling_policy:
+            body["scaling_policy"] = None
+        elif scaling_policy is not None:
+            body["scaling_policy"] = scaling_policy
+        return self._request(
+            "POST", f"/v1/apps/{app_id}/endpoints/{endpoint_name}/scale", json=body
+        )
+
+    def create_deployment(self, app_id: str, body: dict) -> dict:
+        return self._request("POST", f"/v1/apps/{app_id}/deployments", json=body)
+
+    def list_deployments(
+        self,
+        app_id: str,
+        *,
+        state: Optional[str] = None,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if state:
+            params["state"] = state
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", f"/v1/apps/{app_id}/deployments", params=params)
+
+    def get_deployment(self, deployment_id: str) -> dict:
+        return self._request("GET", f"/v1/deployments/{deployment_id}")
+
+    def get_active_deployment_for_app(self, app: dict) -> dict:
+        app_id = app.get("app_id")
+        active_id = app.get("active_deployment_id")
+        if active_id:
+            return self.get_deployment(str(active_id))
+        if not app_id:
+            raise exc.NotFoundError("DEPLOYMENT_NOT_FOUND", "app has no app_id")
+        page = self.list_deployments(str(app_id), state="active", limit=1)
+        items = page.get("items", [])
+        if items:
+            return items[0]
+        raise exc.NotFoundError(
+            "DEPLOYMENT_NOT_FOUND",
+            f"app {app.get('name')!r} has no active deployment",
+        )
+
+    def rollback_app(
+        self,
+        app_id: str,
+        *,
+        deployment_id: Optional[str] = None,
+        version: Optional[int] = None,
+    ) -> dict:
+        body: dict[str, Any] = {}
+        if deployment_id is not None:
+            body["deployment_id"] = deployment_id
+        if version is not None:
+            body["version"] = version
+        return self._request("POST", f"/v1/apps/{app_id}/rollback", json=body)
+
+    def invoke_web_endpoint(
+        self,
+        app_name: str,
+        endpoint_path: str,
+        *,
+        method: str = "POST",
+        json: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        params: Optional[Mapping[str, Any]] = None,
+        url: Optional[str] = None,
+    ) -> Any:
+        import httpx
+
+        if not endpoint_path.startswith("/"):
+            endpoint_path = f"/{endpoint_path}"
+        app_segment = quote(app_name, safe="")
+        path_segment = quote(endpoint_path.lstrip("/"), safe="/")
+        path_url = f"/serve/{app_segment}/{path_segment}"
+        # The address the SERVER reported first, the path ingress behind it. A host
+        # route that cannot be resolved — a cell with no wildcard DNS, a stale record —
+        # must not be a dead end for a client that can still reach the control plane.
+        # Only a failure to CONNECT falls through: once the host has answered anything,
+        # including a 401 or a 503, that answer is the answer.
+        targets = [url, path_url] if url and url != path_url else [path_url]
+        # The ingress layer may block up to IngressWakeTimeout (server default: 60 s)
+        # while waiting for a scale-to-zero replica to start. The default client
+        # timeout of 30 s would fire before that window closes, surfacing a
+        # misleading ConnectionFailed instead of a successful cold-start response.
+        # Use a dedicated read timeout of 90 s (1.5× the server maximum) so a
+        # legitimate wake-from-zero always completes. The connect timeout remains
+        # short (5 s) to catch genuine network unreachability quickly.
+        # On UNAVAILABLE (503) the ingress polled past its wake window without
+        # getting a replica; retry up to 2 times with a short backoff
+        # (conventions.md §2: "le client peut retenter").
+        _INGRESS_TIMEOUT = httpx.Timeout(connect=5.0, read=90.0, write=10.0, pool=5.0)
+        _MAX_RETRIES = 2
+        _RETRY_INITIAL = 1.0
+        _RETRY_BACKOFF = 2.0
+
+        for index, target in enumerate(targets):
+            delay = _RETRY_INITIAL
+            for attempt in range(_MAX_RETRIES + 1):
+                try:
+                    return self._request(
+                        method.upper(),
+                        target,
+                        json=json,
+                        headers=dict(headers or {}),
+                        params=dict(params or {}),
+                        timeout=_INGRESS_TIMEOUT,
+                    )
+                except exc.UnavailableError:
+                    if attempt >= _MAX_RETRIES:
+                        raise
+                    time.sleep(delay)
+                    delay *= _RETRY_BACKOFF
+                except exc.ConnectionFailed as e:
+                    # Never reached it at all, and something else to try: fall through
+                    # WITHOUT consuming this target's remaining 503 retries.
+                    if index + 1 < len(targets) and _could_not_connect(e):
+                        break
+                    raise
+        # Unreachable; satisfy type checkers.
+        raise exc.UnavailableError("UNAVAILABLE", "service unavailable after retries")
+
+
+    # -- maps (batch fan-out) -----------------------------------------------
+
+    def create_map(self, body: dict) -> dict:
+        return self._request("POST", "/v1/maps", json=body)
+
+    def get_map(self, map_id: str) -> dict:
+        return self._request("GET", f"/v1/maps/{map_id}")
+
+    def push_map_inputs(self, map_id: str, inputs: list) -> dict:
+        return self._request(
+            "POST", f"/v1/maps/{map_id}/inputs", json={"inputs": inputs}
+        )
+
+    def finalize_map(self, map_id: str) -> dict:
+        return self._request("POST", f"/v1/maps/{map_id}/finalize")
+
+    def cancel_map(self, map_id: str) -> dict:
+        return self._request("POST", f"/v1/maps/{map_id}/cancel")
+
+    def get_map_results(
+        self,
+        map_id: str,
+        *,
+        order: str = "index",
+        return_exceptions: bool = False,
+        cursor: Optional[str] = None,
+        limit: int = 200,
+    ) -> dict:
+        params: dict[str, Any] = {
+            "order": order,
+            "return_exceptions": "true" if return_exceptions else "false",
+            "limit": limit,
+        }
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", f"/v1/maps/{map_id}/results", params=params)
+
+    def list_maps(
+        self,
+        *,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/v1/maps", params=params)
+
+    # -- crons --------------------------------------------------------------
+
+    def list_crons(self, app_id: str) -> dict:
+        return self._request("GET", f"/v1/apps/{app_id}/crons")
+
+    def get_cron(self, cron_id: str) -> dict:
+        return self._request("GET", f"/v1/crons/{cron_id}")
+
+    def list_cron_executions(
+        self,
+        cron_id: str,
+        *,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        return self._request(
+            "GET", f"/v1/crons/{cron_id}/executions", params=params
+        )
+
+    def trigger_cron(self, cron_id: str) -> dict:
+        return self._request("POST", f"/v1/crons/{cron_id}/trigger")
+
+    def pause_cron(self, cron_id: str) -> dict:
+        return self._request("POST", f"/v1/crons/{cron_id}/pause")
+
+    def resume_cron(self, cron_id: str) -> dict:
+        return self._request("POST", f"/v1/crons/{cron_id}/resume")
+
+    # -- queues (name-keyed, get-or-create on use — openapi /v1/queues) -----
+
+    def get_queue(self, name: str) -> dict:
+        """GET /v1/queues/{name} — returns {queue_id, name, len, created_at}."""
+        return self._request("GET", f"/v1/queues/{_quote_key(name)}")
+
+    def delete_queue(self, name: str) -> None:
+        self._request("DELETE", f"/v1/queues/{_quote_key(name)}")
+
+    def queue_put(self, name: str, payload: dict, *, block: bool = False,
+                  wait_seconds: int = 0) -> dict:
+        body: dict[str, Any] = {"value": payload}
+        if block:
+            body["block"] = True
+            body["wait_seconds"] = wait_seconds
+        return self._request("POST", f"/v1/queues/{_quote_key(name)}/put", json=body)
+
+    def queue_get(self, name: str, *, timeout: int = 0) -> dict:
+        """POST /v1/queues/{name}/get — claim-and-delete the head item.
+        Returns {item, item_id}; item is null when empty (never 404)."""
+        body: dict[str, Any] = {}
+        if timeout > 0:
+            body = {"block": True, "wait_seconds": timeout}
+        return self._request("POST", f"/v1/queues/{_quote_key(name)}/get", json=body)
+
+    # -- dicts (name-keyed, get-or-create on use — openapi /v1/dicts) -------
+
+    def get_dict(self, name: str) -> dict:
+        """GET /v1/dicts/{name} — returns {dict_id, name, created_at}."""
+        return self._request("GET", f"/v1/dicts/{_quote_key(name)}")
+
+    def delete_dict(self, name: str) -> None:
+        self._request("DELETE", f"/v1/dicts/{_quote_key(name)}")
+
+    def dict_get(self, name: str, key: str) -> dict:
+        """GET /v1/dicts/{name}/items/{key} — returns {found, value}."""
+        return self._request(
+            "GET", f"/v1/dicts/{_quote_key(name)}/items/{_quote_key(key)}"
+        )
+
+    def dict_put(self, name: str, key: str, payload: dict) -> None:
+        self._request(
+            "PUT", f"/v1/dicts/{_quote_key(name)}/items/{_quote_key(key)}",
+            json={"value": payload},
+        )
+
+    def dict_delete(self, name: str, key: str) -> None:
+        self._request(
+            "DELETE", f"/v1/dicts/{_quote_key(name)}/items/{_quote_key(key)}"
+        )
+
+    # -- namespaces ---------------------------------------------------------
+
+    def list_namespaces(
+        self,
+        *,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/v1/namespaces", params=params)
+
+
+    # -- sandboxes ----------------------------------------------------------
+
+    def create_sandbox(self, body: dict) -> dict:
+        return self._request("POST", "/v1/sandboxes", json=body)
+
+    def get_sandbox(self, sandbox_id: str) -> dict:
+        return self._request("GET", f"/v1/sandboxes/{sandbox_id}")
+
+    def list_sandboxes(
+        self,
+        *,
+        state: Optional[list] = None,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if state:
+            params["state"] = state
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/v1/sandboxes", params=params)
+
+    def sandbox_terminate(self, sandbox_id: str) -> dict:
+        return self._request("POST", f"/v1/sandboxes/{sandbox_id}/terminate")
+
+    def sandbox_exec(self, sandbox_id: str, body: dict) -> dict:
+        return self._request("POST", f"/v1/sandboxes/{sandbox_id}/exec", json=body)
+
+    def get_sandbox_exec(self, sandbox_id: str, exec_id: str) -> dict:
+        return self._request("GET", f"/v1/sandboxes/{sandbox_id}/execs/{exec_id}")
+
+    def sandbox_put_file(self, sandbox_id: str, body: dict) -> None:
+        self._request("PUT", f"/v1/sandboxes/{sandbox_id}/files", json=body)
+
+    def sandbox_get_file(self, sandbox_id: str, path: str) -> dict:
+        return self._request(
+            "GET",
+            f"/v1/sandboxes/{sandbox_id}/files/content",
+            params={"path": path},
+        )
+
+    def sandbox_ls(
+        self,
+        sandbox_id: str,
+        path: str,
+        *,
+        limit: int = 200,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"path": path, "limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", f"/v1/sandboxes/{sandbox_id}/ls", params=params)
+
+    def sandbox_open_tunnel(self, sandbox_id: str, container_port: int) -> dict:
+        return self._request(
+            "POST",
+            f"/v1/sandboxes/{sandbox_id}/tunnels",
+            json={"container_port": container_port},
+        )
+
+    def sandbox_close_tunnel(self, sandbox_id: str, tunnel_id: str) -> None:
+        self._request("DELETE", f"/v1/sandboxes/{sandbox_id}/tunnels/{tunnel_id}")
+
+    def sandbox_list_tunnels(self, sandbox_id: str) -> dict:
+        return self._request("GET", f"/v1/sandboxes/{sandbox_id}/tunnels")
+
+    def stream_sandbox_logs(self, sandbox_id: str, *, cursor: Optional[int] = None):
+        """Yield SSE log events for a sandbox (same protocol as run logs)."""
+        import httpx
+
+        headers: dict[str, str] = {}
+        if cursor is not None:
+            headers["Last-Event-ID"] = str(cursor)
+        try:
+            with self._http.stream(
+                "GET",
+                f"/v1/sandboxes/{sandbox_id}/logs/stream",
+                headers=headers,
+                timeout=httpx.Timeout(connect=5.0, read=60.0, write=5.0, pool=5.0),
+            ) as resp:
+                if resp.status_code >= 400:
+                    body = resp.read()
+                    try:
+                        import json as _json
+                        parsed = _json.loads(body)
+                    except ValueError:
+                        parsed = None
+                    _raise_for_envelope(resp.status_code, parsed)
+                yield from _warn_on_gap(_parse_sse(resp.iter_lines()))
+        except httpx.HTTPError as e:
+            raise exc.ConnectionFailed(f"sandbox log stream failed: {e}") from e
+
+
+def _quote_key(key: str) -> str:
+    """URL-encode a Dict key for use in a path segment."""
+    return quote(key, safe="")
+
+
+def _warn_on_gap(events):
+    """Pass SSE events through, warning on stderr at each ``gap`` (the stream stays open)."""
+    for event in events:
+        if event[0] == "gap":
+            from ._render import warn_logs_incomplete
+
+            warn_logs_incomplete()
+        yield event
+
+
+def _parse_sse(lines):
+    """Parse an SSE byte/line iterator into ``(event, data, id)`` tuples."""
+    event = "message"
+    data_lines: list[str] = []
+    last_id: Optional[str] = None
+    for raw in lines:
+        line = raw if isinstance(raw, str) else raw.decode("utf-8", "replace")
+        if line == "":
+            if data_lines:
+                yield event, "\n".join(data_lines), last_id
+            event = "message"
+            data_lines = []
+            continue
+        if line.startswith(":"):
+            continue  # comment
+        if line.startswith("event:"):
+            event = line[len("event:"):].strip()
+        elif line.startswith("data:"):
+            # SSE spec: strip exactly one leading space after the colon, not all
+            # whitespace — so a payload that begins with significant spaces/tabs
+            # survives intact.
+            value = line[len("data:"):]
+            if value.startswith(" "):
+                value = value[1:]
+            data_lines.append(value)
+        elif line.startswith("id:"):
+            last_id = line[len("id:"):].strip()
+    if data_lines:
+        yield event, "\n".join(data_lines), last_id