corethink 1.0.0__py3-none-any.whl

corethink/client.py

@@ -0,0 +1,253 @@
+"""The Workbench's HTTP API, as the CLI calls it.
+
+Every console page is a client of the same API (`/app/api/v1/…`); the CLI signs in with a token of its own
+(`Authorization: Bearer ctcli_…`) and gets the same answers, with the same workspace and role checks. Errors come back as
+`{"error": {"code", "message"}}` and are raised as `ApiError` with that message, which is written for people.
+"""
+
+from __future__ import annotations
+
+import platform
+import random
+import time
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, BinaryIO
+
+import httpx
+
+from corethink._version import __version__
+
+API_PREFIX = "/app"
+RETRY_STATUSES = {429, 502, 503, 504}
+USER_AGENT = f"corethink-cli/{__version__} (python {platform.python_version()}; {platform.system().lower()})"
+
+
+class ApiError(Exception):
+    """The Workbench refused or failed a request."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        payload: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.payload = payload
+
+    @property
+    def exit_code(self) -> int:
+        """1 any failure, 3 signed out, 4 not allowed, 5 not found, 6 conflict, 7 rate limited / unavailable."""
+        return {401: 3, 403: 4, 404: 5, 409: 6, 429: 7, 502: 7, 503: 7, 504: 7}.get(self.status or 0, 1)
+
+
+class NotSignedIn(ApiError):
+    """No token, or the Workbench no longer accepts it."""
+
+
+def _error_of(response: httpx.Response) -> ApiError:
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+    error = payload.get("error") if isinstance(payload, dict) else None
+    code = error.get("code") if isinstance(error, dict) else None
+    message = error.get("message") if isinstance(error, dict) else None
+    if not message and isinstance(payload, dict) and isinstance(payload.get("message"), str):
+        message = payload["message"]
+    if not message and isinstance(payload, dict) and ("check" in payload or "report" in payload):
+        message = "The Workbench refused the files: see the check below (or --json for the full report)."
+    if not message:
+        message = {
+            401: "Not signed in.",
+            403: "Not allowed.",
+            404: "Not found.",
+            429: "Too many requests; wait a moment and try again.",
+            502: "The Workbench is unavailable right now; try again.",
+            503: "The Workbench is unavailable right now; try again.",
+            504: "The Workbench took too long to answer; try again.",
+        }.get(response.status_code, f"The Workbench answered HTTP {response.status_code}.")
+    kind = NotSignedIn if response.status_code == 401 else ApiError
+    if response.status_code == 401 and code in (None, "unauthorized", "signed_out"):
+        message = "Not signed in. Run `corethink login` (or set CORETHINK_TOKEN)."
+    return kind(str(message), status=response.status_code, code=code, payload=payload)
+
+
+class Client:
+    """A signed-in (or anonymous) connection to one Workbench."""
+
+    def __init__(
+        self,
+        url: str,
+        token: str | None = None,
+        *,
+        timeout: float = 60.0,
+        transport: httpx.BaseTransport | None = None,
+        retries: int = 3,
+    ) -> None:
+        self.url = url.rstrip("/")
+        self.token = token
+        self.retries = retries
+        headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        self._http = httpx.Client(
+            base_url=self.url + API_PREFIX,
+            headers=headers,
+            timeout=httpx.Timeout(timeout, connect=15.0),
+            transport=transport,
+            follow_redirects=False,
+        )
+        # uploads go straight to a signed Cloud Storage URL: never with our token
+        self._bare = httpx.Client(
+            headers={"User-Agent": USER_AGENT},
+            timeout=httpx.Timeout(600.0, connect=15.0),
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+        self._bare.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    # ---- requests -------------------------------------------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+        retry: bool | None = None,
+    ) -> Any:
+        """One API call; the parsed JSON answer (None when empty). GETs are retried on network errors and 429/5xx."""
+        method = method.upper()
+        if not path.startswith("/"):
+            path = "/" + path
+        retry = method in {"GET", "HEAD"} if retry is None else retry
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(
+                    method,
+                    path,
+                    json=json,
+                    params=clean or None,
+                    headers=dict(headers or {}),
+                )
+            except httpx.TransportError as error:
+                if retry and attempt < self.retries:
+                    attempt += 1
+                    _pause(attempt)
+                    continue
+                raise ApiError(
+                    f"Could not reach {self.url} ({error.__class__.__name__}). Check your connection, or --url."
+                ) from error
+            if (
+                response.status_code in RETRY_STATUSES
+                and attempt < self.retries
+                and (retry or response.status_code == 429)
+            ):
+                attempt += 1
+                _pause(attempt, response.headers.get("Retry-After"))
+                continue
+            if response.status_code >= 400:
+                raise _error_of(response)
+            if not response.content:
+                return None
+            content_type = response.headers.get("Content-Type", "")
+            if "json" in content_type:
+                return response.json()
+            return response.text
+
+    def get(self, path: str, **params: Any) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, body: Any = None, **kwargs: Any) -> Any:
+        return self.request("POST", path, json={} if body is None else body, **kwargs)
+
+    def put(self, path: str, body: Any = None, **kwargs: Any) -> Any:
+        return self.request("PUT", path, json={} if body is None else body, **kwargs)
+
+    def delete(self, path: str, body: Any = None, **kwargs: Any) -> Any:
+        return self.request("DELETE", path, json=body, **kwargs)
+
+    @contextmanager
+    def stream(self, method: str, path: str, **kwargs: Any) -> Iterator[httpx.Response]:
+        """A streamed answer (downloads); errors raised as ApiError."""
+        with self._http.stream(method.upper(), path, **kwargs) as response:
+            if response.status_code >= 400:
+                response.read()
+                raise _error_of(response)
+            yield response
+
+    def download(self, path: str, target: Path, params: Mapping[str, Any] | None = None) -> Path:
+        """Save a file the API serves; returns where it went."""
+        target.parent.mkdir(parents=True, exist_ok=True)
+        partial = target.with_name(target.name + ".part")
+        with self.stream("GET", path, params=params) as response, partial.open("wb") as out:
+            for chunk in response.iter_bytes():
+                out.write(chunk)
+        partial.replace(target)
+        return target
+
+    def put_signed(
+        self,
+        url: str,
+        data: bytes | BinaryIO,
+        *,
+        headers: Mapping[str, str] | None = None,
+        method: str = "PUT",
+    ) -> None:
+        """Send a file to a URL the Workbench signed (Cloud Storage), without our token."""
+        try:
+            response = self._bare.request(method, url, content=data, headers=dict(headers or {}))
+        except httpx.TransportError as error:
+            raise ApiError(f"The upload could not reach storage ({error.__class__.__name__}).") from error
+        if response.status_code >= 400:
+            raise ApiError(
+                f"Storage refused the upload (HTTP {response.status_code}): {response.text[:200]}",
+                status=response.status_code,
+            )
+
+    @property
+    def storage(self) -> httpx.Client:
+        """An httpx client for URLs the Workbench signed (Cloud Storage): it never carries our token."""
+        return self._bare
+
+    def signed_request(self, method: str, url: str, **kwargs: Any) -> httpx.Response:
+        """A request to a URL the Workbench signed (Cloud Storage), without our token; the response as it is (resumable
+        uploads read its Location and Range). Network failures are raised as ApiError; HTTP statuses are the caller's."""
+        try:
+            return self._bare.request(method.upper(), url, **kwargs)
+        except httpx.TransportError as error:
+            raise ApiError(f"Could not reach storage ({error.__class__.__name__}).") from error
+
+    def fetch_url(self, url: str) -> bytes:
+        """GET a signed URL (a download link the Workbench gave), without our token."""
+        response = self._bare.get(url)
+        if response.status_code >= 400:
+            raise ApiError(f"The download failed (HTTP {response.status_code}).", status=response.status_code)
+        return response.content
+
+
+def _pause(attempt: int, retry_after: str | None = None) -> None:
+    try:
+        wait = float(retry_after) if retry_after else 0.0
+    except ValueError:
+        wait = 0.0
+    time.sleep(min(30.0, max(wait, 0.5 * 2 ** (attempt - 1)) + random.uniform(0, 0.25)))