freepod 0.1.1__py3-none-any.whl

freepod/__init__.py

@@ -0,0 +1,86 @@
+"""freepod — the Freepod command-line client.
+
+The package is a pure client of the public Freepod REST API. It shares no code
+with the API server and imports nothing from it.
+
+This module holds only the error hierarchy, because every other module raises
+from it and a leaf module keeps the imports acyclic. Each error carries the
+exit code its class maps onto; see `cli-distribution` § *Exit codes
+distinguish failure classes*.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "FreepodError",
+    "UsageError",
+    "AuthenticationError",
+    "PermissionError_",
+    "BuildFailed",
+    "RolloutFailed",
+    "EXIT_OK",
+    "EXIT_ERROR",
+    "EXIT_USAGE",
+    "EXIT_NOT_AUTHENTICATED",
+    "EXIT_BUILD_FAILED",
+    "EXIT_ROLLOUT_FAILED",
+]
+
+__version__ = "0.1.1"
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+EXIT_NOT_AUTHENTICATED = 3
+EXIT_BUILD_FAILED = 4
+EXIT_ROLLOUT_FAILED = 5
+
+
+class FreepodError(Exception):
+    """Anything that should end the run with a readable message.
+
+    Subclasses override `exit_code` to select their row of the exit-code
+    table. The base class is the "unexpected error" row.
+    """
+
+    exit_code = EXIT_ERROR
+
+
+class UsageError(FreepodError):
+    """The command was invoked wrongly. Nothing was attempted."""
+
+    exit_code = EXIT_USAGE
+
+
+class AuthenticationError(FreepodError):
+    """No usable credential, or one the platform will not accept.
+
+    Raised for the 401 row of the status-code contract, where re-authenticating
+    would succeed and change nothing, as well as for the ordinary "you are not
+    logged in" case.
+    """
+
+    exit_code = EXIT_NOT_AUTHENTICATED
+
+
+class PermissionError_(FreepodError):
+    """Authenticated, but not permitted to act on the resource.
+
+    Named with a trailing underscore so it cannot shadow the builtin. This is
+    the API's own 403 — a credential problem no refresh can fix — and it is
+    deliberately *not* an `AuthenticationError`, so it never triggers a login.
+    """
+
+    exit_code = EXIT_ERROR
+
+
+class BuildFailed(FreepodError):
+    """The build reached a non-successful terminal status."""
+
+    exit_code = EXIT_BUILD_FAILED
+
+
+class RolloutFailed(FreepodError):
+    """The rollout failed, or waiting for it timed out."""
+
+    exit_code = EXIT_ROLLOUT_FAILED

freepod/__main__.py

@@ -0,0 +1,10 @@
+"""Support `python -m freepod` alongside the installed `freepod` script."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

freepod/api.py

@@ -0,0 +1,306 @@
+"""The HTTP client for the Freepod API, and the status-code contract it obeys.
+
+The platform's authentication statuses invert the conventional reading, for
+reasons recorded in design Appendix A. The short version:
+
+| Status                                 | Answered by | Client action                      |
+|----------------------------------------|-------------|------------------------------------|
+| 401                                    | edge        | stop and explain; do not re-auth   |
+| 403, non-JSON body                     | edge        | refresh once and retry             |
+| 403, JSON `detail`                     | API         | stop — a permission error          |
+| 404, `{"detail": "Not authenticated"}` | API         | report a platform condition        |
+
+The two 403 rows are why the rule cannot simply be "403 means refresh": the API
+issues its own 403s from `require_self` / `require_admin`, and an unbounded
+refresh rule would refresh, fail, re-login, and loop on a request that no
+credential can satisfy. Hence: **refresh at most once per request**.
+
+One asymmetry worth knowing while reading this module: most of the reads the
+client performs later — products, plans, hostnames, domains — are on the edge's
+`skip_auth_routes` list and are answered anonymously whatever credential the
+request carried. They cannot return 401 or 403, so none of the machinery below
+ever fires on them. That is exactly why `GET /api/me` must come first.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+from urllib.parse import quote
+
+import httpx
+
+from . import AuthenticationError, FreepodError, PermissionError_
+from .auth import Session
+from .config import DEFAULT_HTTP_TIMEOUT, USER_AGENT, Environment
+
+#: Methods whose repetition cannot create or duplicate state.
+SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+#: Total attempts for a safe request, including the first.
+MAX_ATTEMPTS = 3
+
+#: First backoff interval; doubles per attempt.
+BACKOFF_BASE_SECONDS = 0.5
+
+
+def _json_detail(response: httpx.Response) -> Optional[str]:
+    """The `detail` of a JSON error body, or None if the body is not one.
+
+    Identification is by *body shape*, not by `Content-Type`: the edge's
+    refusals are a bare `http.Error` with a plain-text body and no reliable
+    content type, while every refusal the API itself issues is a FastAPI JSON
+    document carrying `detail`.
+    """
+    try:
+        payload = response.json()
+    except ValueError:
+        return None
+    if isinstance(payload, dict) and isinstance(payload.get("detail"), str):
+        return payload["detail"]
+    return None
+
+
+class ApiClient:
+    """Authenticated access to one environment's REST API."""
+
+    def __init__(
+        self,
+        env: Environment,
+        session: Session,
+        *,
+        timeout: int = DEFAULT_HTTP_TIMEOUT,
+        verbose: bool = False,
+        client: Optional[httpx.Client] = None,
+        backoff_base: float = BACKOFF_BASE_SECONDS,
+    ):
+        self.env = env
+        self.session = session
+        self.timeout = timeout
+        self.verbose = verbose
+        self.backoff_base = backoff_base
+        self._client = client if client is not None else httpx.Client()
+        self._owns_client = client is None
+
+    # -- lifecycle --------------------------------------------------------
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "ApiClient":
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self.close()
+
+    # -- requests ---------------------------------------------------------
+
+    def request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """Perform a request, applying the status-code contract.
+
+        Returns the response for any status the contract does not claim, so a
+        caller that needs to distinguish, say, the two causes of a 409 still
+        can. Raises for every credential-related status.
+        """
+        url = self.env.url(path)
+        refreshed = False
+
+        while True:
+            response = self._send(method, url, **kwargs)
+            status = response.status_code
+
+            if status == 401:
+                # Either no credential reached the edge, or — on dev only — a
+                # perfectly valid one belongs to a non-member of the gating
+                # group. Re-authenticating succeeds and changes nothing, so
+                # this never triggers a login.
+                raise AuthenticationError(self._unauthenticated_message(url))
+
+            if status == 403:
+                detail = _json_detail(response)
+                if detail is not None:
+                    # The API answered: authenticated, but not permitted here.
+                    raise PermissionError_(f"403 from {url} — {detail}")
+                if refreshed:
+                    # Bounded refresh: a second 403 is reported, never retried.
+                    raise PermissionError_(
+                        f"403 from {url} even after refreshing — the token is still not "
+                        f"verifiable. Run `freepod login --env {self.env.name}` to "
+                        f"re-authenticate from scratch."
+                    )
+                refreshed = True
+                self._renew()
+                continue
+
+            if status == 404 and _json_detail(response) == "Not authenticated":
+                # Only reachable on a route the edge skips. A bug report, not a
+                # login prompt.
+                raise FreepodError(
+                    f"404 'Not authenticated' from {url} — no identity reached the API. "
+                    "This is an unexpected platform condition, not a credential problem; "
+                    "please report it."
+                )
+
+            return response
+
+    def get(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("PUT", path, **kwargs)
+
+    def get_json(self, path: str, **kwargs: Any) -> Any:
+        """GET and decode, raising on any non-successful status."""
+        return self._decode(self.get(path, **kwargs))
+
+    def me(self) -> dict:
+        """`GET /api/me` — the first request that actually exercises the token.
+
+        Every command that requires authentication calls this before its public
+        reads, so a bad credential is reported here rather than surfacing later
+        as an unrelated-looking failure. See design D15.
+        """
+        body = self.get_json("/api/me")
+        if not isinstance(body, dict) or "id" not in body:
+            raise FreepodError(f"unexpected /api/me response: {body!r}")
+        return body
+
+    # -- public reads -----------------------------------------------------
+    #
+    # Everything below is on the edge's `skip_auth_routes` list and is answered
+    # anonymously. Call `me()` before any of them, or a credential problem
+    # surfaces later as an unrelated-looking failure.
+
+    def products(self) -> list:
+        body = self.get_json("/api/products")
+        if not isinstance(body, list):
+            raise FreepodError(f"unexpected /api/products response: {body!r}")
+        return body
+
+    def find_product(self, slug: str) -> Optional[dict]:
+        """The first product carrying `slug`, or None.
+
+        By slug, never by display name: `slug` is written only by the catalog
+        reconciler and is the product's stable identity, while the name is
+        presentation and can be retitled at any time.
+        """
+        for product in self.products():
+            if isinstance(product, dict) and product.get("slug") == slug:
+                return product
+        return None
+
+    def domains(self) -> list:
+        """The platform's wildcard domains, most preferred first."""
+        body = self.get_json("/api/domains")
+        if not isinstance(body, list):
+            raise FreepodError(f"unexpected /api/domains response: {body!r}")
+        return [entry for entry in body if isinstance(entry, str)]
+
+    def check_hostname(self, fqdn: str) -> dict:
+        """`GET /api/hostnames/{fqdn}` — always 200 with `{fqdn, usable, reason}`.
+
+        Advisory only: the name is claimed when the deployment is created, so a
+        usable answer here is not a reservation. Note the check runs without
+        `exclude_deployment_id`, so re-checking a name we already hold reports
+        `in_use` against ourselves — see design D14.
+        """
+        body = self.get_json(f"/api/hostnames/{quote(fqdn, safe='')}")
+        if not isinstance(body, dict):
+            raise FreepodError(f"unexpected hostname check response: {body!r}")
+        return body
+
+    # -- internals --------------------------------------------------------
+
+    def _headers(self) -> dict:
+        headers = {"Accept": "application/json", "User-Agent": USER_AGENT}
+        if self.session.access_token:
+            headers["Authorization"] = f"Bearer {self.session.access_token}"
+        return headers
+
+    def _send(self, method: str, url: str, **kwargs: Any) -> httpx.Response:
+        """Send one request, retrying only what is safe to repeat.
+
+        A request that could create or mutate state gets exactly one attempt:
+        a duplicate build or deployment is worse than a reported failure.
+        """
+        attempts = MAX_ATTEMPTS if method.upper() in SAFE_METHODS else 1
+        # Load-bearing, not incidental: caller-supplied headers are *read*,
+        # never written. The copy is what lets `request()` replay this call
+        # after a refresh with the caller's headers intact and a fresh
+        # Authorization. Merging the other way — injecting auth into the
+        # caller's dict, or dropping this `dict()` so `update` writes into a
+        # hoisted base — reintroduces two bugs at once: a stale token that the
+        # bounded-refresh rule then misreports as a permission error, and a
+        # `Range` from one request leaking into the next.
+        headers = dict(self._headers())
+        headers.update(kwargs.pop("headers", None) or {})
+        timeout = kwargs.pop("timeout", self.timeout)
+
+        last_error: Optional[Exception] = None
+        for attempt in range(1, attempts + 1):
+            try:
+                response = self._client.request(
+                    method, url, headers=headers, timeout=timeout, **kwargs
+                )
+            except httpx.HTTPError as exc:
+                last_error = exc
+                if attempt >= attempts:
+                    raise FreepodError(f"cannot reach {url}: {exc}") from None
+                self._backoff(attempt)
+                continue
+
+            if response.status_code >= 500 and attempt < attempts:
+                self._backoff(attempt)
+                continue
+            return response
+
+        # Unreachable: the loop either returns or raises.
+        raise FreepodError(f"cannot reach {url}: {last_error}")
+
+    def _backoff(self, attempt: int) -> None:
+        delay = self.backoff_base * (2 ** (attempt - 1))
+        if delay > 0:
+            time.sleep(delay)
+
+    def _renew(self) -> None:
+        """Recover from an edge 403 — the token is expired or unverifiable.
+
+        A refused refresh falls back to a full login rather than failing
+        outright, which is what makes an idle-expired offline session recover
+        without the user being told to do anything.
+        """
+        if self.session.refresh():
+            self.session.credential_source = "refreshed token"
+            return
+        self.session.login()
+        self.session.credential_source = "fresh login (after failed refresh)"
+
+    def _unauthenticated_message(self, url: str) -> str:
+        if self.env.requires_group:
+            return (
+                f"401 from {url} — no credential, or your account lacks access to "
+                f"'{self.env.name}'.\n"
+                f"  {self.env.api_base} requires membership of the "
+                f"'{self.env.requires_group}' Keycloak group.\n"
+                f"  Re-authenticating will succeed and change nothing — check the "
+                f"group membership first."
+            )
+        return (
+            f"401 from {url} — no credential reached the API.\n"
+            f"  Run `freepod login --env {self.env.name}` to authenticate."
+        )
+
+    @staticmethod
+    def _decode(response: httpx.Response) -> Any:
+        if not response.is_success:
+            detail = _json_detail(response)
+            body = detail if detail is not None else response.text.strip()[:300]
+            raise FreepodError(f"HTTP {response.status_code} from {response.url}: {body}")
+        try:
+            return response.json()
+        except ValueError:
+            raise FreepodError(f"unparseable response from {response.url}") from None