coding-client 1.21.2__py3-none-any.whl

coding_client/auth/websocket.py

@@ -0,0 +1,148 @@
+"""Identity resolution for WebSocket handshakes.
+
+``AuthMiddleware`` is a ``BaseHTTPMiddleware``, and Starlette never invokes
+``dispatch`` on a ``websocket`` scope. So **no flip and no middleware can close a
+WebSocket route** — every WS handler has to resolve identity itself, explicitly.
+That is why this module exists and why it is a plain function rather than
+middleware: middleware is precisely the thing that does not run here.
+
+The consequence is sharp. Once the HTTP paths stopped trusting a bare
+``X-Tenant-Id`` (``TRUST_TENANT_HEADER=false``), the WS handlers became the only
+remaining place in the fleet where a pod could assert any tenant and be believed.
+
+The rule mirrors the HTTP one exactly
+-------------------------------------
+Same three-way decision as :func:`.._onbehalf.resolve_tenant_assertion`, for the
+same reasons:
+
+* no asserted header — the tenant is the one the caller's own licence names;
+* asserted and **equal** — a no-op (this is what a proxy re-injecting the tenant
+  it resolved from that same token looks like);
+* asserted and **differing** — honoured only when the licence's ``subject_id`` is
+  allowlisted, otherwise refused.
+
+An uncredentialed handshake is now closed (1.15.0)
+--------------------------------------------------
+A browser cannot set an ``Authorization`` header on a WebSocket handshake — the
+WebSocket API has no way to pass one. Browser-originated sockets therefore reach
+a backend through a server-side proxy, and it is the PROXY that must present a
+credential. Until every proxy had been converted, requiring one unconditionally
+would not have hardened the browser path, it would simply have broken it. So
+until 1.15.0 ``Outcome.NO_CREDENTIAL`` did **not** set
+:attr:`WebSocketIdentity.should_close`: the handler fell back to a raw
+``X-Tenant-Id`` read and logged a WARNING naming the peer.
+
+That fallback was never a safety property, it was an *instrument* — the WARNING
+existed to find the callers still to convert, and it has now reported. Over the
+full log retention on both consumers (~10.5h on coding-realtime, ~18h on
+coding-analysis) the WARNING fired 5 times on coding-realtime, every one of them
+from ``peer=127.0.0.1`` — a verification probe — and 0 times on coding-analysis.
+No real caller has ever used it. Meanwhile both legitimate callers now present a
+credential: coding-gateway attaches its own licence on WS upgrades, and ``fr``
+presents ``svc-fr-backend``'s licence on both of its WS proxies (driven live:
+101 with auth, 403 without).
+
+With the instrument's reading in, the residual is closed. A handshake carrying no
+verifiable credential cannot name a tenant, so serving it is an authorisation
+failure exactly as a refusal is, and ``should_close`` is True for both. The
+``Outcome`` enum stays three-valued on purpose: REFUSED ("a credential, but not
+for that tenant") and NO_CREDENTIAL ("no credential at all") are different
+operational facts and want different log lines. Only the *decision* is now shared.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from enum import Enum, auto
+
+from ._onbehalf import forwarded_license_id, resolve_tenant_assertion
+from .middleware import _user_from_license
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["Outcome", "WebSocketIdentity", "resolve_websocket_identity"]
+
+#: WS close code for a policy violation. 1008 is the protocol's own
+#: "policy violation", which is what an authorisation refusal is.
+POLICY_VIOLATION = 1008
+
+
+class Outcome(Enum):
+    """What the handshake proved, and therefore what the handler may do."""
+
+    #: A licence was verified. ``tenant_id`` is authoritative.
+    RESOLVED = auto()
+    #: A licence was verified but it may not act for the tenant it asserted.
+    #: The handler MUST close; serving this connection is a cross-tenant read.
+    REFUSED = auto()
+    #: No ``Authorization`` at all, or one that did not introspect to a live
+    #: licence. Nothing was proved, so nothing may be served: the handler MUST
+    #: close, same as REFUSED. Kept distinct from REFUSED because the two are
+    #: different operational facts worth different log lines — see the module
+    #: docstring for the measurement that made closing this safe.
+    NO_CREDENTIAL = auto()
+
+
+@dataclass(frozen=True)
+class WebSocketIdentity:
+    """The result of resolving a handshake. Immutable so a handler cannot
+    accidentally widen it after the decision has been made."""
+
+    outcome: Outcome
+    tenant_id: str | None = None
+    subject_id: str | None = None
+    license_id: str | None = None
+    #: Human-readable, safe to put in a WS close reason. Never contains the
+    #: asserted tenant — echoing it back confirms the guess to an attacker.
+    reason: str | None = None
+
+    @property
+    def should_close(self) -> bool:
+        """True when serving this connection would be an authorisation failure.
+
+        Both non-RESOLVED outcomes qualify, and the test is written as "not
+        RESOLVED" rather than a list of the two so that a fourth outcome added
+        later fails CLOSED by default: a new member is a new way of *not*
+        proving an identity, and enumerating the refusing side would silently
+        admit it.
+        """
+        return self.outcome is not Outcome.RESOLVED
+
+
+async def resolve_websocket_identity(websocket) -> WebSocketIdentity:
+    """Resolve who is on the other end of *websocket*.
+
+    Takes the Starlette ``WebSocket`` rather than a ``Request``: both expose
+    ``.headers`` and ``.url``, which is all the shared decision function reads, so
+    the HTTP and WS paths run the *same* code and cannot drift.
+
+    Never raises. A handshake is either resolved, refused, or credential-less.
+    """
+    user = await _user_from_license(websocket)
+
+    if user is None:
+        return WebSocketIdentity(
+            outcome=Outcome.NO_CREDENTIAL,
+            reason="no verifiable credential on the handshake",
+        )
+
+    effective_tenant, refused = resolve_tenant_assertion(
+        websocket,
+        subject_id=user.sub,
+        token_tenant=user.tenant_id or "",
+    )
+
+    if refused:
+        return WebSocketIdentity(
+            outcome=Outcome.REFUSED,
+            subject_id=user.sub,
+            reason="this credential may not act for the tenant it asserted",
+        )
+
+    return WebSocketIdentity(
+        outcome=Outcome.RESOLVED,
+        tenant_id=effective_tenant,
+        subject_id=user.sub,
+        license_id=forwarded_license_id(websocket),
+    )

coding_client/clients/__init__.py

@@ -0,0 +1,24 @@
+"""HTTP service clients for inter-service communication."""
+
+from .base import ServiceClient, ServiceError
+from .coding_ai import CodingAIClient
+from .coding_analysis import CodingAnalysisClient
+from .coding_containers import CodingContainersClient
+from .coding_github import CodingGitHubClient
+from .coding_realtime import CodingRealtimeClient
+from .coding_security import CodingSecurityClient
+from .coding_testing import CodingTestingClient
+from .coding_workspaces import CodingWorkspacesClient
+
+__all__ = [
+    "ServiceClient",
+    "ServiceError",
+    "CodingAIClient",
+    "CodingAnalysisClient",
+    "CodingContainersClient",
+    "CodingGitHubClient",
+    "CodingRealtimeClient",
+    "CodingSecurityClient",
+    "CodingTestingClient",
+    "CodingWorkspacesClient",
+]

coding_client/clients/base.py

@@ -0,0 +1,131 @@
+"""Base async HTTP client with retry, error handling, and structured logging."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+import structlog
+from tenacity import (
+    AsyncRetrying,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+logger = structlog.get_logger(__name__)
+
+
+class ServiceError(Exception):
+    """Raised when a downstream service returns a non-2xx response."""
+
+    def __init__(self, status_code: int, message: str, body: Any = None):
+        self.status_code = status_code
+        self.body = body
+        super().__init__(message)
+
+
+class ServiceClient:
+    """Base async HTTP client for inter-service communication."""
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._client: httpx.AsyncClient | None = None
+
+    async def _ensure_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                timeout=httpx.Timeout(self.timeout),
+            )
+        return self._client
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        headers: dict[str, str] | None = None,
+        *,
+        max_attempts: int | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Send one request, retrying transport errors up to ``max_retries`` attempts.
+
+        ``max_attempts`` overrides ``max_retries`` for this call only. Pass ``1``
+        for a non-idempotent POST (e.g. a job submit), where a retry after a
+        read timeout would start the work a second time.
+        """
+        client = await self._ensure_client()
+        attempts = self.max_retries if max_attempts is None else max_attempts
+        log = logger.bind(method=method, path=path, base_url=self.base_url)
+
+        async for attempt in AsyncRetrying(
+            stop=stop_after_attempt(attempts),
+            wait=wait_exponential(multiplier=1, min=0.5, max=10),
+            retry=retry_if_exception_type(
+                (httpx.ConnectError, httpx.ReadTimeout, httpx.PoolTimeout)
+            ),
+            reraise=True,
+        ):
+            with attempt:
+                log.debug("http_request", attempt=attempt.retry_state.attempt_number)
+                response = await client.request(method, path, headers=headers, **kwargs)
+
+        if response.status_code >= 400:
+            body = None
+            try:
+                body = response.json()
+            except Exception:
+                body = response.text
+            msg = f"{method} {self.base_url}{path} returned {response.status_code}"
+            log.error("service_error", status_code=response.status_code, body=body)
+            raise ServiceError(response.status_code, msg, body=body)
+
+        if response.status_code == 204 or not response.content:
+            return None
+
+        try:
+            return response.json()
+        except Exception:
+            return response.text
+
+    async def get(self, path: str, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        return await self._request("GET", path, headers=headers, **kwargs)
+
+    async def post(self, path: str, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        return await self._request("POST", path, headers=headers, **kwargs)
+
+    async def put(self, path: str, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        return await self._request("PUT", path, headers=headers, **kwargs)
+
+    async def delete(self, path: str, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        return await self._request("DELETE", path, headers=headers, **kwargs)
+
+    async def patch(self, path: str, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        return await self._request("PATCH", path, headers=headers, **kwargs)
+
+    async def health_check(self) -> bool:
+        try:
+            await self.get("/health")
+            return True
+        except Exception:
+            return False
+
+    async def close(self) -> None:
+        if self._client and not self._client.is_closed:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> ServiceClient:
+        await self._ensure_client()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.close()

coding_client/clients/coding_ai.py

@@ -0,0 +1,33 @@
+"""HTTP client for the coding-ai service."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .base import ServiceClient
+
+_ENV_VAR = "CODING_AI_URL"
+
+
+class CodingAIClient(ServiceClient):
+    """Client for coding-ai endpoints."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+        max_retries: int = 3,
+    ):
+        url = base_url or os.environ.get(_ENV_VAR, "")
+        if not url:
+            raise RuntimeError(
+                f"CodingAIClient requires base_url or {_ENV_VAR} env var. "
+                "See the platform configuration policy."
+            )
+        super().__init__(url, timeout=timeout, max_retries=max_retries)
+
+    async def analyze_failure(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        return await self.post(
+            "/api/ai/analysis/tests/failure-analysis", headers=headers, json=kwargs
+        )

coding_client/clients/coding_analysis.py

@@ -0,0 +1,36 @@
+"""HTTP client for the coding-analysis service."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .base import ServiceClient
+
+_ENV_VAR = "CODING_ANALYSIS_URL"
+
+
+class CodingAnalysisClient(ServiceClient):
+    """Client for coding-analysis endpoints."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ):
+        url = base_url or os.environ.get(_ENV_VAR, "")
+        if not url:
+            raise RuntimeError(
+                f"CodingAnalysisClient requires base_url or {_ENV_VAR} env var. "
+                "See the platform configuration policy."
+            )
+        super().__init__(url, timeout=timeout, max_retries=max_retries)
+
+    async def analyze_code(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        return await self.post("/api/analysis/analyze", headers=headers, json=kwargs)
+
+    async def get_analysis(
+        self, analysis_id: str, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.get(f"/api/analysis/status/{analysis_id}", headers=headers, **kwargs)

coding_client/clients/coding_containers.py

@@ -0,0 +1,45 @@
+"""Legacy container-named client for the coding-containers service."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .base import ServiceClient
+
+_ENV_VAR = "CODING_CONTAINERS_URL"
+
+
+class CodingContainersClient(ServiceClient):
+    """Compatibility client for the legacy ``/api/containers`` aliases.
+
+    New callers should use :class:`CodingWorkspacesClient`. This class remains
+    available so existing consumers can migrate without a flag day.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ):
+        url = base_url or os.environ.get(_ENV_VAR, "")
+        if not url:
+            raise RuntimeError(
+                f"CodingContainersClient requires base_url or {_ENV_VAR} env var. "
+                "See the platform configuration policy."
+            )
+        super().__init__(url, timeout=timeout, max_retries=max_retries)
+
+    async def create_container(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        return await self.post("/api/containers", headers=headers, json=kwargs)
+
+    async def get_container(
+        self, container_name: str, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.get(f"/api/containers/{container_name}", headers=headers, **kwargs)
+
+    async def delete_container(
+        self, container_name: str, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.delete(f"/api/containers/{container_name}", headers=headers, **kwargs)

coding_client/clients/coding_github.py

@@ -0,0 +1,127 @@
+"""HTTP client for the coding-github service."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .base import ServiceClient
+
+_ENV_VAR = "CODING_GITHUB_URL"
+
+
+class CodingGitHubClient(ServiceClient):
+    """Client for coding-github endpoints."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ):
+        url = base_url or os.environ.get(_ENV_VAR, "")
+        if not url:
+            raise RuntimeError(
+                f"CodingGitHubClient requires base_url or {_ENV_VAR} env var. "
+                "See the platform configuration policy."
+            )
+        super().__init__(url, timeout=timeout, max_retries=max_retries)
+
+    # -- Repository management ------------------------------------------------
+
+    async def list_repositories(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """List all provisioned repositories."""
+        return await self.get("/api/repositories/repositories", headers=headers, params=kwargs)
+
+    async def import_repository(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Import a GitHub repository as a canonical workspace."""
+        return await self.post("/api/repositories/import", headers=headers, json=kwargs)
+
+    async def provision(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Compatibility alias for :meth:`import_repository`."""
+        return await self.import_repository(headers=headers, **kwargs)
+
+    async def get_status(
+        self, container_name: str, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        """Get provisioning status for a specific container."""
+        return await self.get(
+            f"/api/repositories/status/{container_name}", headers=headers, params=kwargs
+        )
+
+    async def create_upstream_pr(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Create a pull request from the system fork to the user's original repo."""
+        return await self.post("/api/repositories/create-upstream-pr", headers=headers, json=kwargs)
+
+    # -- Pull request operations ----------------------------------------------
+
+    async def fork(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Fork a repository."""
+        return await self.post("/api/repositories/fork", headers=headers, json=kwargs)
+
+    async def apply_changes(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Apply code changes to a forked repository."""
+        return await self.post("/api/repositories/apply-changes", headers=headers, json=kwargs)
+
+    async def create_pull_request(
+        self, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        """Create a pull request."""
+        return await self.post(
+            "/api/repositories/create-pull-request", headers=headers, json=kwargs
+        )
+
+    async def validate_pull_request(
+        self, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        """Validate a pull request."""
+        return await self.post(
+            "/api/repositories/validate-pull-request", headers=headers, json=kwargs
+        )
+
+    # -- File / tree operations -----------------------------------------------
+
+    async def get_file(
+        self, container_name: str, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        """Read a single file from a container repository."""
+        return await self.get(
+            f"/api/repositories/{container_name}/file", headers=headers, params=kwargs
+        )
+
+    async def get_tree(
+        self, container_name: str, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        """Get the file tree for a container repository."""
+        return await self.get(
+            f"/api/repositories/{container_name}/tree", headers=headers, params=kwargs
+        )
+
+    async def get_directory(
+        self, container_name: str, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        """List directory contents in a container repository."""
+        return await self.get(
+            f"/api/repositories/{container_name}/directory", headers=headers, params=kwargs
+        )
+
+    async def search(
+        self, container_name: str, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        """Search files in a container repository."""
+        return await self.post(
+            f"/api/repositories/{container_name}/search", headers=headers, json=kwargs
+        )
+
+    # -- Webhooks -------------------------------------------------------------
+
+    async def create_webhook(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Register a GitHub webhook."""
+        return await self.post("/api/repositories/webhooks/webhook", headers=headers, json=kwargs)
+
+    # -- Backward-compatible aliases ------------------------------------------
+    # These keep the old method names working with corrected paths.
+
+    async def get_repo(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Alias for list_repositories (backward compatibility)."""
+        return await self.list_repositories(headers=headers, **kwargs)

coding_client/clients/coding_realtime.py

@@ -0,0 +1,127 @@
+"""HTTP client for the coding-realtime service."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .base import ServiceClient
+
+_ENV_VAR = "CODING_REALTIME_URL"
+
+
+class CodingRealtimeClient(ServiceClient):
+    """Client for coding-realtime endpoints."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+    ):
+        url = base_url or os.environ.get(_ENV_VAR, "")
+        if not url:
+            raise RuntimeError(
+                f"CodingRealtimeClient requires base_url or {_ENV_VAR} env var. "
+                "See the platform configuration policy."
+            )
+        super().__init__(url, timeout=timeout, max_retries=max_retries)
+
+    # -- Broadcast / messaging ------------------------------------------------
+
+    async def broadcast(
+        self,
+        *,
+        event_type: str,
+        data: dict[str, Any],
+        priority: str = "normal",
+        container_name: str | None = None,
+        tags: list[str] | None = None,
+        correlation_id: str | None = None,
+        ttl_seconds: int | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Publish a broadcast to all subscribers of a container.
+
+        POSTs to ``/api/broadcast/publish`` — the REST publish endpoint (D9).
+        (The old helper posted to ``/api/broadcast/subscribe``, a WebSocket-only
+        route, so every broadcast 404'd and was silently dropped.)
+
+        ``container_name`` may be omitted when ``data`` carries it as
+        ``data['container_name']`` (the shape coding-containers' lifecycle events
+        already use). Tenant-scoped: pass the owning tenant as
+        ``headers={'X-Tenant-Id': ...}`` so the publish resolves to the container's
+        owner (BOLA — the server rejects a container the tenant does not own).
+
+        Returns the publish result, including ``delivered`` and
+        ``subscriber_count`` so the caller can distinguish a real fan-out from a
+        no-op (no subscribers).
+        """
+        payload: dict[str, Any] = {
+            "event_type": event_type,
+            "data": data,
+            "priority": priority,
+        }
+        if container_name is not None:
+            payload["container_name"] = container_name
+        if tags is not None:
+            payload["tags"] = tags
+        if correlation_id is not None:
+            payload["correlation_id"] = correlation_id
+        if ttl_seconds is not None:
+            payload["ttl_seconds"] = ttl_seconds
+        return await self.post("/api/broadcast/publish", headers=headers, json=payload)
+
+    # -- Stats / monitoring ---------------------------------------------------
+
+    async def get_global_stats(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Get global rate-limiter statistics across all containers."""
+        return await self.get("/api/global-stats", headers=headers, params=kwargs)
+
+    async def get_stats(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Get rate-limit stats for all containers."""
+        return await self.get("/api/stats", headers=headers, params=kwargs)
+
+    async def get_container_stats(
+        self, container_name: str, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        """Get rate-limit stats for a specific container."""
+        return await self.get(f"/api/stats/{container_name}", headers=headers, params=kwargs)
+
+    async def get_violations(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Get rate-limit violations."""
+        return await self.get("/api/violations", headers=headers, params=kwargs)
+
+    # -- Connection / health --------------------------------------------------
+
+    async def get_connections(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Get active realtime analysis connections."""
+        return await self.get("/api/realtime/connections", headers=headers, params=kwargs)
+
+    async def get_global_health(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Get global WebSocket health statistics."""
+        return await self.get("/api/ws-health/global", headers=headers, params=kwargs)
+
+    async def get_container_health(
+        self, container_name: str, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        """Get WebSocket health statistics for a specific container."""
+        return await self.get(
+            f"/api/ws-health/container/{container_name}", headers=headers, params=kwargs
+        )
+
+    async def get_containers_health(
+        self, headers: dict[str, str] | None = None, **kwargs: Any
+    ) -> Any:
+        """Get health statistics for all containers."""
+        return await self.get("/api/ws-health/containers", headers=headers, params=kwargs)
+
+    async def cleanup_stale(self, headers: dict[str, str] | None = None, **kwargs: Any) -> Any:
+        """Trigger cleanup of stale WebSocket connections."""
+        return await self.post("/api/ws-health/cleanup", headers=headers, json=kwargs)
+
+    # -- Health ---------------------------------------------------------------
+
+    async def health(self, **kwargs: Any) -> Any:
+        """Service-level health check."""
+        return await self.get("/api/health/live", **kwargs)