leancpms-cli 0.1.0__py3-none-any.whl

cpms/cli/client.py

@@ -0,0 +1,126 @@
+"""Configuration and the HTTP client of the `cpms` command. No framework.
+
+The CLI is a thin client of the JSON API (architecture §3), so it works the
+same against a local and a hosted instance. Credentials come from
+`CPMS_URL` and `CPMS_API_KEY`, or from a profile in
+`~/.config/cpms/config.toml`:
+
+    [default]
+    url = "http://localhost:8000"
+    api_key = "lcp_…"
+
+    [hosted]
+    url = "https://cpms.example.com"
+    api_key = "lcp_…"
+
+`--profile NAME` (or `CPMS_PROFILE`) picks a profile; without one the
+environment wins, then `[default]`. `cpms login` writes a profile
+(`cpms.cli.login`).
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+
+class UsageError(Exception):
+    """Exit code 2: the command line or the configuration is wrong."""
+
+
+class ApiError(Exception):
+    """Exit code 1: the server (or the network) said no."""
+
+    def __init__(self, message: str, status: int | None = None, detail: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.detail = detail
+
+
+def config_path() -> Path:
+    if os.environ.get("CPMS_CONFIG"):
+        return Path(os.environ["CPMS_CONFIG"])
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "cpms" / "config.toml"
+
+
+@dataclass(frozen=True)
+class Config:
+    url: str
+    api_key: str
+
+
+def load_config(profile: str | None) -> Config:
+    profile = profile or os.environ.get("CPMS_PROFILE") or None
+    url, key = os.environ.get("CPMS_URL", ""), os.environ.get("CPMS_API_KEY", "")
+    if profile or not (url and key):
+        path = config_path()
+        section: dict[str, Any] = {}
+        if path.exists():
+            try:
+                data = tomllib.loads(path.read_text())
+            except tomllib.TOMLDecodeError as e:
+                raise UsageError(f"{path}: {e}") from None
+            section = data.get(profile or "default") or {}
+            if profile and not section:
+                raise UsageError(f"no profile [{profile}] in {path}")
+        elif profile:
+            raise UsageError(f"no profile [{profile}]: {path} does not exist")
+        if profile:
+            url, key = str(section.get("url", "")), str(section.get("api_key", ""))
+        else:
+            url, key = url or str(section.get("url", "")), key or str(section.get("api_key", ""))
+    if not url or not key:
+        raise UsageError(f"set CPMS_URL and CPMS_API_KEY, or a profile in {config_path()}")
+    return Config(url.rstrip("/"), key)
+
+
+class Api:
+    """The JSON API. Without a key (`cpms login` starting) only the routes that need none answer.
+    `transport` is for tests."""
+
+    def __init__(self, cfg: Config, timeout: float = 30.0, transport: httpx.BaseTransport | None = None):
+        self.config = cfg
+        headers = {"Authorization": f"Bearer {cfg.api_key}"} if cfg.api_key else {}
+        self._http = httpx.Client(base_url=f"{cfg.url}/api/v1", timeout=timeout, headers=headers, transport=transport)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def call(self, method: str, path: str, json: Any = None, params: dict[str, Any] | None = None) -> Any:
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        try:
+            r = self._http.request(method, path, json=json, params=clean)
+        except httpx.HTTPError as e:
+            raise ApiError(f"{method} {path}: {e}") from None
+        try:
+            body = r.json() if r.content else None
+        except ValueError:
+            body = None
+        if r.status_code >= 400:
+            msg = body.get("error") or body.get("detail") if isinstance(body, dict) else None
+            raise ApiError(f"{r.status_code} {msg or r.text[:200]}", r.status_code,
+                           body.get("detail") if isinstance(body, dict) else None)
+        return body
+
+    def answer(self, method: str, path: str, json: Any = None) -> tuple[int, Any]:
+        """The status and the body, whatever the status (`cpms login` polling); only the network raises."""
+        try:
+            r = self._http.request(method, path, json=json)
+        except httpx.HTTPError as e:
+            raise ApiError(f"{method} {path}: {e}") from None
+        try:
+            return r.status_code, r.json() if r.content else None
+        except ValueError:
+            return r.status_code, None
+
+    def get(self, path: str, **params: Any) -> Any:
+        return self.call("GET", path, params=params)
+
+    def post(self, path: str, body: Any = None) -> Any:
+        return self.call("POST", path, json=body if body is not None else {})

cpms/cli/login.py

@@ -0,0 +1,232 @@
+"""`cpms login`: the device flow from the command line's side, and the profile it writes.
+
+The server's side is `cpms.actions.login`. Here: start a login, poll until
+the person has approved it in the portal (RFC 8628: every `interval`
+seconds, five more after each `slow_down`), and save the key as a profile
+in the config file (`client.config_path`).
+
+The config file is edited as text, not rewritten from parsed data, so the
+other profiles, their comments and their order stay as they were: in the
+profile's own table, the `url` and `api_key` lines are replaced where they
+stand and missing ones added after its last line; a new profile goes at the
+end. The result is parsed back and checked before it is written, and it is
+written whole (a temporary file, then a rename), mode 0600; a directory it
+creates is 0700. No TOML writer is needed, so the CLI keeps its three
+dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import socket
+import sys
+import tempfile
+import time
+import tomllib
+import webbrowser
+from pathlib import Path
+from typing import Any, Callable
+
+import httpx
+
+from .client import Api, ApiError, Config, UsageError
+
+PROFILE = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+HEADER = re.compile(r"^\s*\[")
+TABLE = re.compile(r"""^\s*\[\s*(?:"([^"]*)"|'([^']*)'|([A-Za-z0-9_.-]+))\s*\]\s*(?:#.*)?$""")
+FIELD = re.compile(r"^\s*(url|api_key)\s*=")
+CONTENT = re.compile(r"^\s*[^\s#]")
+USER_CODE = re.compile(r"^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$")
+PORTAL_PAGE = "/portal/cli/"
+MAX_INTERVAL_S = 60
+
+sleep: Callable[[float], None] = time.sleep  # tests replace these two
+clock: Callable[[], float] = time.monotonic
+TRANSPORT: httpx.BaseTransport | None = None  # tests: a fake server
+
+
+# --- the config file -------------------------------------------------------------------------
+
+
+def profile_name(name: str) -> str:
+    if not PROFILE.match(name):
+        raise UsageError(f"profile names are letters, digits, - and _: {name!r}")
+    return name
+
+
+def _lines(text: str) -> list[str]:
+    lines = text.splitlines(keepends=True)
+    if lines and not lines[-1].endswith("\n"):
+        lines[-1] += "\n"
+    return lines
+
+
+def _table(lines: list[str], name: str) -> tuple[int, int] | None:
+    """Where the table [name] is: its header's index and the index after its last line of content."""
+    for i, line in enumerate(lines):
+        m = TABLE.match(line)
+        if m and next(g for g in m.groups() if g is not None) == name:
+            end = next((j for j in range(i + 1, len(lines)) if HEADER.match(lines[j])), len(lines))
+            while end > i + 1 and not CONTENT.match(lines[end - 1]):
+                end -= 1  # blank lines and comments before the next table belong to it
+            return i, end
+    return None
+
+
+def _parse(path: Path, text: str) -> dict[str, Any]:
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as e:
+        raise UsageError(f"{path}: {e}") from None
+
+
+def set_profile(path: Path, text: str, name: str, url: str, api_key: str) -> str:
+    """`text` with [name] holding `url` and `api_key`; everything else as it was."""
+    before = _parse(path, text)
+    lines = _lines(text)
+    values = {"url": f"url = {json.dumps(url)}\n", "api_key": f"api_key = {json.dumps(api_key)}\n"}
+    where = _table(lines, name)
+    if where is None:
+        lines += (["\n"] if lines and lines[-1].strip() else []) + [f"[{name}]\n", *values.values()]
+    else:
+        start, end = where
+        for i in range(start + 1, end):
+            m = FIELD.match(lines[i])
+            if m and m.group(1) in values:
+                lines[i] = values.pop(m.group(1))
+        lines[end:end] = list(values.values())
+    out = "".join(lines)
+    after = _parse(path, out)
+    if after.get(name, {}).get("url") != url or after[name].get("api_key") != api_key or \
+            {k: v for k, v in after.items() if k != name} != {k: v for k, v in before.items() if k != name}:
+        raise UsageError(f"{path}: could not update [{name}] safely; edit the file by hand")
+    return out
+
+
+def drop_profile(path: Path, text: str, name: str) -> str | None:
+    """`text` without [name], or None if it has no such table."""
+    before = _parse(path, text)
+    lines = _lines(text)
+    where = _table(lines, name)
+    if where is None:
+        return None
+    start, end = where
+    while end < len(lines) and not lines[end].strip():
+        end += 1
+    del lines[start:end]
+    out = "".join(lines)
+    after = _parse(path, out)
+    if name in after or after != {k: v for k, v in before.items() if k != name}:
+        raise UsageError(f"{path}: could not remove [{name}] safely; edit the file by hand")
+    return out
+
+
+def write(path: Path, text: str) -> None:
+    """Replace the file whole, readable by its owner only. The temporary file is new (mkstemp: a fresh
+    name, created exclusively, mode 0600), so nothing planted beside the config is written through."""
+    if not path.parent.exists():
+        path.parent.mkdir(mode=0o700, parents=True)
+    fd, name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    tmp = Path(name)
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(text)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def read(path: Path) -> str:
+    try:
+        return path.read_text() if path.exists() else ""
+    except OSError as e:
+        raise UsageError(f"{path}: {e}") from None
+
+
+def profile_value(path: Path, text: str, name: str, key: str) -> str:
+    section = _parse(path, text).get(name)
+    return str(section.get(key, "")) if isinstance(section, dict) else ""
+
+
+# --- the flow ------------------------------------------------------------------------------
+
+
+def client_name() -> str:
+    """What the key is called on the server: the command and the machine, which the person sees when
+    approving."""
+    return f"cpms on {socket.gethostname() or 'unknown host'}"[:200]
+
+
+def can_open_browser() -> bool:
+    if sys.platform in ("darwin", "win32"):
+        return True
+    return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+
+
+def open_browser(url: str) -> bool:
+    try:
+        return webbrowser.open(url)
+    except Exception:  # a browser that will not start is no reason to stop; the URL is printed
+        return False
+
+
+def verification_url(url: str, user_code: str) -> str:
+    """The page to open, made here from the instance the person named and the code: never an address the
+    server sent, which a server that is not what it seems could point anywhere."""
+    if not USER_CODE.match(user_code):
+        raise ApiError(f"the server sent an odd code ({user_code[:20]!r}); not a LeanCPMS instance?")
+    return f"{url}{PORTAL_PAGE}?code={user_code}"
+
+
+def start(url: str, scope: str) -> tuple[Api, dict[str, Any]]:
+    """Ask the instance for a login. The client it returns has no key: the token route needs none."""
+    api = Api(Config(url, ""), transport=TRANSPORT)
+    status, body = api.answer("POST", "/auth/device", {"client_name": client_name(), "scope": scope})
+    if status != 200 or not isinstance(body, dict):
+        api.close()
+        raise ApiError(f"{status} {body.get('error') if isinstance(body, dict) else 'not a LeanCPMS instance?'}",
+                       status)
+    return api, body
+
+
+def revoke(url: str, api_key: str) -> None:
+    """Best effort: a key that could not be saved."""
+    api = Api(Config(url, api_key), transport=TRANSPORT)
+    try:
+        api.answer("POST", "/auth/logout")
+    except ApiError:
+        pass
+    finally:
+        api.close()
+
+
+def poll(api: Api, started: dict[str, Any]) -> dict[str, Any]:
+    """Until the person decides or the code expires. A network error or a busy server is waited out."""
+    interval = int(started.get("interval") or 5)
+    deadline = clock() + int(started["expires_in"])
+    while True:
+        sleep(interval)
+        if clock() > deadline:
+            raise ApiError("the code expired before anyone approved it; run cpms login again")
+        try:
+            status, body = api.answer("POST", "/auth/device/token", {"device_code": started["device_code"]})
+        except ApiError:
+            continue
+        error = body.get("error") if isinstance(body, dict) else None
+        if status == 200 and isinstance(body, dict):
+            return body
+        if error == "authorization_pending" or status >= 500:
+            continue
+        if error == "slow_down" or status == 429:
+            interval = min(interval + 5, MAX_INTERVAL_S)
+            continue
+        if error == "access_denied":
+            raise ApiError("denied in the portal; no key was issued", status)
+        if error == "expired_token":
+            raise ApiError("the code expired before anyone approved it; run cpms login again", status)
+        raise ApiError(f"{status} {error or body}", status)