multicloud-cli 0.1.0__py3-none-any.whl

multicloud_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

multicloud_cli/api.py

@@ -0,0 +1,152 @@
+"""One HTTP call to the Multicloud API, shared by the command groups.
+
+The URL is ``{api_url}/api/v1/orgs/{slug}{path}``, or ``{api_url}/api/v1{path}`` for an ``org_scoped=False`` call
+(the catalog). The credential is, in this order: ``MULTICLOUD_API_KEY``,
+the SSO session (``Authorization: Bearer``), the stored API key (``X-API-Key``). It travels only to the https
+URL that ``config.get_api_url`` accepted.
+"""
+import os
+from typing import Any, Dict, Iterable, Optional, Tuple
+from urllib.parse import quote
+
+import requests
+
+from . import auth, config, exitcodes, sso
+
+TIMEOUT_S = 30
+
+
+class ApiError(Exception):
+    """The call failed. ``status`` is the HTTP status, or None when there was no answer.
+    ``exit_code`` is the exit code of ``mctl`` for it (see ``exitcodes``)."""
+
+    def __init__(self, message: str, status: Optional[int] = None, exit_code: Optional[int] = None):
+        super().__init__(message)
+        self.status = status
+        self.exit_code = exit_code if exit_code is not None else exitcodes.for_status(status)
+
+
+def _detail_text(data: Any) -> Optional[str]:
+    """The text of a Multicloud API error body: ``detail: {code, message}``, ``detail: {error: {message}}``,
+    ``detail: "<text>"`` or the list of a 422 validation error."""
+    detail = data.get("detail") if isinstance(data, dict) else None
+    if isinstance(detail, str):
+        return detail or None
+    if isinstance(detail, dict):
+        inner = detail.get("error")
+        if isinstance(inner, dict):
+            detail = inner
+        if detail.get("message"):
+            code = detail.get("code")
+            return f"{code}: {detail['message']}" if code else str(detail["message"])
+        if detail.get("code"):
+            return str(detail["code"])
+    if isinstance(detail, list):
+        parts = []
+        for item in detail:
+            if isinstance(item, dict) and item.get("msg"):
+                where = ".".join(str(p) for p in item.get("loc", []) if p != "body")
+                parts.append(f"{where}: {item['msg']}" if where else str(item["msg"]))
+        return "; ".join(parts) or None
+    return None
+
+
+def _send(method: str, url: str, body: Optional[Dict[str, Any]], headers: Dict[str, str],
+          params: Optional[Dict[str, Any]] = None) -> requests.Response:
+    extra = {"params": params} if params else {}  # a list value becomes one repeated key
+    try:
+        # No redirects: requests would carry the credential header to another host.
+        return requests.request(method, url, json=body, timeout=TIMEOUT_S, allow_redirects=False, headers=headers,
+                                **extra)
+    except requests.RequestException as ex:
+        raise ApiError(f"Could not reach the API: {ex}")
+
+
+def _sso_org(slug: Optional[str], token: str, explicit: bool = True) -> str:
+    """The organization of this call: ``--org`` (or env, or saved) when it is in the token, else the only one.
+    A SAVED org that the token lacks (left from an API-key login) is ignored; an explicit one is an error."""
+    orgs = sso.orgs_in_token(token)
+    if slug and not explicit and slug not in orgs:
+        slug = None
+    if not orgs:
+        raise auth.AuthError("Your sign-in holds no organization. Ask an owner of your organization to add you, "
+                             "then run: mctl auth login")
+    if slug:
+        if slug not in orgs:
+            raise auth.AuthError(f"You are not a member of '{slug}'. Your organizations: {', '.join(orgs)}.")
+        return slug
+    if len(orgs) > 1:
+        raise auth.AuthError(f"You belong to several organizations ({', '.join(orgs)}). "
+                             "Name one with --org or MULTICLOUD_ORG.")
+    return orgs[0]
+
+
+def call(method: str, org: Optional[str], path: str = "", *, body: Optional[Dict[str, Any]] = None,
+         headers: Optional[Dict[str, str]] = None, accept: Iterable[int] = (200, 201, 202),
+         scope: Optional[str] = None, pass_codes: Iterable[str] = (),
+         params: Optional[Dict[str, Any]] = None, org_scoped: bool = True) -> Dict[str, Any]:
+    """One API call. Returns the JSON body with ``_status`` added; raises ``ApiError`` on other statuses.
+
+    ``scope`` names the API key scope this call needs; a 401 or 403 then says that it may be missing.
+    A failed answer whose error code is in ``pass_codes`` is returned like a success.
+    ``params`` are query parameters. ``org_scoped=False`` calls ``/api/v1{path}`` with no organization in the URL:
+    an SSO call then needs no organization, and ``MULTICLOUD_API_KEY`` needs none either (a stored key still
+    needs one to be found)."""
+    slug = config.get_org(org)
+    try:
+        use_sso = False
+        if not os.environ.get("MULTICLOUD_API_KEY"):  # the key path needs no issuer
+            issuer = config.get_issuer()
+            use_sso = auth.load_sso(issuer) is not None
+            if use_sso and not org_scoped and slug and auth.get_key(slug)[0]:
+                # A stored key of the named org wins for the platform routes (the catalog): it holds its scope
+                # explicitly, while an SSO token may not reach them.
+                use_sso = False
+        base = config.get_api_url()
+        if use_sso:
+            token = auth.fresh_access_token(issuer)
+            if org_scoped:
+                slug = _sso_org(slug, token, explicit=config.org_is_explicit(org))
+            credential = {"Authorization": f"Bearer {token}"}
+        else:
+            env_key = os.environ.get("MULTICLOUD_API_KEY")
+            if not slug and not org_scoped and not env_key:
+                raise ApiError("No sign-in. Run: mctl auth login (or set MULTICLOUD_API_KEY, or name the "
+                               "organization of a stored key with --org).", exit_code=exitcodes.AUTH)
+            if not slug and org_scoped:
+                raise ApiError("Name the organization with --org or MULTICLOUD_ORG.")
+            key = auth.get_key(slug)[0] if slug else env_key
+            if not key:
+                raise ApiError(f"No sign-in for {slug}. Run: mctl auth login", exit_code=exitcodes.AUTH)
+            credential = {"X-API-Key": key}
+    except auth.AuthError as ex:
+        raise ApiError(str(ex), exit_code=exitcodes.AUTH)
+    except config.ConfigError as ex:
+        raise ApiError(str(ex))
+    url = f"{base}/api/v1/orgs/{quote(slug, safe='')}{path}" if org_scoped else f"{base}/api/v1{path}"
+    r = _send(method, url, body, {**credential, **(headers or {})}, params)
+    if r.status_code == 401 and use_sso:
+        # The access token was refused (the session may have ended on the server): refresh once and retry once.
+        try:
+            token = auth.fresh_access_token(issuer, rejected=token)
+        except auth.AuthError as ex:
+            raise ApiError(str(ex), 401)
+        r = _send(method, url, body, {"Authorization": f"Bearer {token}", **(headers or {})}, params)
+    try:
+        data = r.json() if r.text else {}
+    except ValueError:
+        data = {}
+    if r.status_code not in accept:
+        detail = data.get("detail") if isinstance(data, dict) else None
+        if isinstance(detail, dict) and detail.get("code") in set(pass_codes):
+            data = dict(data)
+            data["_status"] = r.status_code
+            return data
+        text = _detail_text(data) or f"HTTP {r.status_code}"
+        # A 401 is a bad or expired credential, not a missing scope.
+        if r.status_code == 403 and scope and not use_sso:
+            text += f" (HTTP {r.status_code}. The API key may lack the '{scope}' scope.)"
+        raise ApiError(text, r.status_code)
+    data = dict(data) if isinstance(data, dict) else {"body": data}
+    data["_status"] = r.status_code
+    return data