lr-lumenlabel-cli 3.0.0__py3-none-any.whl

lumenlabel/client.py

@@ -0,0 +1,362 @@
+"""HTTP client for the LumenLabel station API (doc/api-reference.md).
+
+A station URL is one of three kinds, and the kind decides authentication:
+
+- **relay** ``https://<fleet>/v1/s/<uid>``: ``X-Fleet-Authorization: Bearer``
+  with the technician's Fleet token from ``lr_fleet.auth.access_token()``.
+  Fleet's own refusals carry ``X-Fleet-Error`` and become :class:`FleetError`.
+- **loopback** ``http://127.0.0.1:<port>``: no authentication; Fleet is never
+  contacted.
+- **lan** any other URL: ``Authorization: Bearer <station token>``.
+
+The CLI never signs as the station: the station's Fleet identity belongs to
+the running app alone.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import sys
+from pathlib import Path
+from typing import Any, Callable, Iterator
+
+import httpx
+
+RELAY = "relay"
+LOOPBACK = "loopback"
+LAN = "lan"
+
+UPLOAD_TIMEOUT_S = 300.0
+COMMIT_TIMEOUT_S = 120.0
+
+
+class ClientError(RuntimeError):
+    """A request failed. The message is meant for the technician."""
+
+
+class NetworkError(ClientError):
+    """No response came back: refused, dropped or timed out."""
+
+
+class NotRunningError(NetworkError):
+    """Nothing listens on the loopback station URL."""
+
+
+class StatusError(ClientError):
+    """The station answered with a non-2xx status."""
+
+    def __init__(
+        self, message: str, status_code: int, code: str | None, body: Any
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.body = body
+
+
+class FleetError(StatusError):
+    """Fleet refused or could not relay the request (``X-Fleet-Error``)."""
+
+
+class FleetSignInError(ClientError):
+    """A relay URL needs a signed-in technician and there is none."""
+
+
+_RELAY_PATH = re.compile(r"^/v1/s/([0-9a-f]{32})/?$")
+
+# doc/fleet-wire-contract.md §12.7, the X-Fleet-Error table.
+FLEET_MESSAGES: dict[str, str] = {
+    "unauthorized": "not signed in to Fleet; run `fleet login`",
+    "forbidden": "your Fleet account lacks write access",
+    "unknown_device": "Fleet does not know station {uid}, or it is revoked",
+    "path_not_allowed": "Fleet does not relay this path to station {uid}",
+    "device_offline": (
+        "station {uid} is offline: its tunnel to Fleet is down. Check that "
+        "LumenLabel runs and remote access is on"
+    ),
+    "timeout": "station {uid} did not answer within Fleet's time limit",
+    "busy": "too many requests in flight to station {uid}; retry",
+    "device_protocol_error": "station {uid} sent Fleet an invalid reply",
+    "device_reset": "station {uid} dropped the request before answering; retry",
+    "headers_too_large": "the request headers are too large for the Fleet relay",
+    "fleet_unavailable": "Fleet is restarting; retry in a minute",
+    "gateway_timeout": "Fleet timed out waiting for station {uid}; retry",
+}
+
+# A load balancer answers 502/503 while Fleet has no healthy target and 504
+# on its idle timeout. Those pages carry no X-Fleet-Error and are not JSON.
+_GATEWAY_STATUSES = frozenset({502, 503, 504})
+
+
+def relay_uid(url: str) -> str | None:
+    """The station uid of a Fleet relay URL, else None."""
+    match = _RELAY_PATH.match(httpx.URL(url).path)
+    return match.group(1) if match else None
+
+
+def _is_loopback_host(host: str) -> bool:
+    if host.lower() == "localhost":
+        return True
+    try:
+        addr = ipaddress.ip_address(host.strip("[]"))
+    except ValueError:
+        return False
+    mapped = getattr(addr, "ipv4_mapped", None)
+    return addr.is_loopback or bool(mapped and mapped.is_loopback)
+
+
+def check_station_url(url: str) -> httpx.URL:
+    """*url* parsed; raises :class:`ClientError` unless it is an http(s) URL
+    with a host."""
+    try:
+        parsed = httpx.URL(url)
+    except httpx.InvalidURL as exc:
+        raise ClientError(f"{url!r} is not a valid station URL: {exc}") from exc
+    if parsed.scheme not in ("http", "https") or not parsed.host:
+        raise ClientError(
+            f"{url!r} is not a station URL; expected http(s)://<host>[:<port>]"
+        )
+    return parsed
+
+
+def station_kind(url: str) -> str:
+    """``relay``, ``loopback`` or ``lan`` for a station URL.
+
+    Raises :class:`ClientError` for a malformed URL.
+    """
+    parsed = check_station_url(url)
+    if relay_uid(url) is not None:
+        return RELAY
+    return LOOPBACK if _is_loopback_host(parsed.host) else LAN
+
+
+def fleet_message(code: str, uid: str | None) -> str:
+    template = FLEET_MESSAGES.get(code, "Fleet failed the request ({code})")
+    return template.format(uid=uid or "?", code=code)
+
+
+def _stdin_is_tty() -> bool:
+    try:
+        return bool(sys.stdin and sys.stdin.isatty())
+    except (ValueError, OSError):
+        return False
+
+
+def fleet_token(
+    interactive: bool, on_sign_in: Callable[[str], None] | None = None
+) -> str:
+    """The technician's Fleet token. Raises :class:`FleetSignInError`.
+
+    The cached sign-in is tried first. Only an interactive call with a
+    terminal starts the browser sign-in.
+    """
+    from lr_fleet import auth as fleet_auth
+
+    try:
+        return fleet_auth.access_token(interactive=False)
+    except fleet_auth.NotSignedIn as exc:
+        reason = str(exc)
+        hint = "" if "fleet login" in reason else "; run `fleet login`"
+        error = FleetSignInError(f"Fleet sign-in required: {reason}{hint}")
+        if not interactive or not _stdin_is_tty():
+            raise error from exc
+        if on_sign_in is not None:
+            on_sign_in(reason)
+    try:
+        return fleet_auth.access_token(interactive=True)
+    except fleet_auth.NotSignedIn as exc:
+        raise error from exc
+
+
+class _FleetAuth(httpx.Auth):
+    """Stamps each relay request with a fresh Fleet token.
+
+    A Fleet 401 ``unauthorized`` is retried once. The body is read first so
+    that a multipart upload can be resent too.
+    """
+
+    requires_request_body = True
+
+    def _stamp(self, request: httpx.Request) -> None:
+        request.headers["X-Fleet-Authorization"] = f"Bearer {fleet_token(False)}"
+
+    def auth_flow(self, request: httpx.Request) -> Iterator[httpx.Request]:
+        self._stamp(request)
+        response = yield request
+        if (
+            response.status_code == 401
+            and response.headers.get("X-Fleet-Error") == "unauthorized"
+        ):
+            self._stamp(request)
+            yield request
+
+
+def _json_or_none(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+class StationClient:
+    """Synchronous client for one station.
+
+    *transport* replaces the network, for tests.
+    """
+
+    def __init__(
+        self,
+        station: str,
+        token: str | None = None,
+        *,
+        timeout: float = 30.0,
+        interactive: bool = False,
+        on_fleet_sign_in: Callable[[str], None] | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self.station = station.rstrip("/")
+        self.kind = station_kind(self.station)
+        self.relay_uid = relay_uid(self.station)
+        headers: dict[str, str] = {}
+        auth: httpx.Auth | None = None
+        if self.kind == RELAY:
+            fleet_token(interactive, on_fleet_sign_in)
+            auth = _FleetAuth()
+        elif self.kind == LAN and token:
+            headers["Authorization"] = f"Bearer {token}"
+        self._client = httpx.Client(
+            base_url=self.station,
+            headers=headers,
+            auth=auth,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def __enter__(self) -> "StationClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # -- endpoints -------------------------------------------------------
+
+    def station_info(self) -> dict:
+        return self.request("GET", "/api/station")
+
+    def labels(self) -> list[dict]:
+        return self.request("GET", "/api/labels")
+
+    def label(self, article: str) -> dict:
+        return self.request("GET", f"/api/labels/{article}")
+
+    def delete_label(self, article: str) -> None:
+        self.request("DELETE", f"/api/labels/{article}")
+
+    def print_history(self, limit: int, before: str | None = None) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if before:
+            params["before"] = before
+        return self.request("GET", "/api/print-history", params=params)
+
+    def logs(self, tail: int) -> dict:
+        return self.request("GET", "/api/logs", params={"tail": tail})
+
+    def preflight(
+        self, article: str, revision: str, files: list[dict], invalidate: bool
+    ) -> list[dict]:
+        body = {
+            "article": article,
+            "revision": revision,
+            "files": files,
+            "invalidate": invalidate,
+        }
+        return self.request("POST", "/api/labels/preflight", json=body)["missing"]
+
+    def upload(self, article: str, revision: str, path: str, file: Path) -> dict:
+        """Streams one file into the station's staging folder."""
+        with file.open("rb") as fh:
+            return self.request(
+                "POST",
+                "/api/labels/import/upload",
+                data={"article": article, "revision": revision, "path": path},
+                files={"file": (Path(path).name, fh, "application/octet-stream")},
+                timeout=UPLOAD_TIMEOUT_S,
+            )
+
+    def commit(self, article: str, revision: str) -> dict:
+        return self.request(
+            "POST",
+            "/api/labels/import/commit",
+            json={"article": article, "revision": revision},
+            timeout=COMMIT_TIMEOUT_S,
+        )
+
+    # -- transport -------------------------------------------------------
+
+    def send(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """One request; any status. Raises :class:`NetworkError`."""
+        try:
+            return self._client.request(method, path, **kwargs)
+        except httpx.RequestError as exc:
+            raise self._network_error(exc) from exc
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """One request; the JSON body of a 2xx answer, else raises."""
+        response = self.send(method, path, **kwargs)
+        if not response.is_success:
+            raise self.status_error(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        body = _json_or_none(response)
+        return response.text if body is None else body
+
+    def _network_error(self, exc: httpx.RequestError) -> NetworkError:
+        if isinstance(exc, httpx.ConnectError) and self.kind == LOOPBACK:
+            return NotRunningError(
+                f"LumenLabel is not running: nothing answers on {self.station}. "
+                "Start LumenLabel on this station and retry."
+            )
+        if isinstance(exc, httpx.ConnectError) and self.kind == LAN:
+            return NetworkError(
+                f"Cannot reach the station at {self.station} ({exc}). Check that "
+                "LumenLabel runs there with instrumentation.host set to 0.0.0.0."
+            )
+        where = "Fleet" if self.kind == RELAY else f"the station at {self.station}"
+        return NetworkError(f"The connection to {where} failed: {exc}")
+
+    def status_error(self, response: httpx.Response) -> StatusError:
+        """The error for a non-2xx response; Fleet refusals speak about Fleet."""
+        status = response.status_code
+        body = _json_or_none(response)
+        fleet_code = response.headers.get("X-Fleet-Error")
+        if fleet_code:
+            message = fleet_message(fleet_code, self.relay_uid)
+            return FleetError(message, status, fleet_code, body)
+        if self.kind == RELAY and status in _GATEWAY_STATUSES and body is None:
+            code = "gateway_timeout" if status == 504 else "fleet_unavailable"
+            message = fleet_message(code, self.relay_uid)
+            return FleetError(
+                f"{message} (HTTP {status} from Fleet's load balancer)",
+                status,
+                code,
+                None,
+            )
+        code = body.get("code") if isinstance(body, dict) else None
+        return StatusError(_detail(response, body), status, code, body)
+
+
+def _detail(response: httpx.Response, body: Any) -> str:
+    if isinstance(body, dict):
+        for key in ("detail", "error"):
+            if body.get(key):
+                return str(body[key])
+    text = response.text.strip()
+    return (
+        f"HTTP {response.status_code}: {text}"
+        if text
+        else (f"HTTP {response.status_code}")
+    )

lumenlabel/commands/__init__.py

@@ -0,0 +1 @@
+"""Command groups of the lumenlabel CLI."""

lumenlabel/commands/api.py

@@ -0,0 +1,64 @@
+"""``lumenlabel api``: any ``/api/`` endpoint, with the CLI's authentication."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from ..client import ClientError
+from ..shared import emit_json, explain, fail, open_client
+
+METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE")
+
+
+def _body(data: str | None) -> Any:
+    if data is None:
+        return None
+    if data.startswith("@"):
+        try:
+            data = Path(data[1:]).read_text(encoding="utf-8")
+        except OSError as exc:
+            fail(f"cannot read {data[1:]}: {exc}")
+    try:
+        return json.loads(data)
+    except json.JSONDecodeError as exc:
+        fail(f"--data is not JSON: {exc}")
+
+
+def api(
+    ctx: typer.Context,
+    method: str = typer.Argument(..., help="GET, POST, PUT, PATCH or DELETE."),
+    path: str = typer.Argument(..., help="An /api/ path, e.g. /api/labels."),
+    data: str = typer.Option(
+        None, "--data", "-d", help="JSON request body, or @FILE to read it."
+    ),
+) -> None:
+    """Call a station API endpoint and print its JSON answer."""
+    method = method.upper()
+    if method not in METHODS:
+        fail(f"method must be one of {', '.join(METHODS)}")
+    if not path.startswith("/api/"):
+        fail("path must start with /api/")
+    body = _body(data)
+    client = open_client(ctx)
+    try:
+        kwargs = {"json": body} if body is not None else {}
+        response = client.send(method, path, **kwargs)
+        if not response.is_success:
+            error = client.status_error(response)
+            if response.content:
+                typer.echo(response.text)
+            fail(explain(error, client))
+    except ClientError as exc:
+        fail(explain(exc, client))
+    finally:
+        client.close()
+    if not response.content:
+        return
+    try:
+        emit_json(response.json())
+    except ValueError:
+        typer.echo(response.text)

lumenlabel/commands/auth.py

@@ -0,0 +1,59 @@
+"""``lumenlabel login`` and ``logout``."""
+
+from __future__ import annotations
+
+import typer
+
+from ..client import LAN, RELAY, ClientError, station_kind
+from ..config import LoginState, forget_login, save_login
+from ..shared import explain, fail, make_client
+
+
+def login(
+    station: str = typer.Option(
+        ...,
+        "--station",
+        "--base-url",
+        "-s",
+        help="Fleet relay URL (https://<fleet>/v1/s/<uid>), LAN URL or loopback "
+        "URL. --base-url is the same option, as in lumentest.",
+    ),
+    token: str = typer.Option(
+        None,
+        "--token",
+        help="Station token, for a LAN URL. Shown in admin mode on the station.",
+        envvar="LUMENLABEL_TOKEN",
+    ),
+) -> None:
+    """Check a station and remember it for the following commands."""
+    station = station.rstrip("/")
+    try:
+        kind = station_kind(station)
+    except ClientError as exc:
+        fail(str(exc))
+    if kind == LAN and not token:
+        token = typer.prompt("Station token", hide_input=True)
+    if kind != LAN:
+        token = None
+    client = make_client(station, token)
+    try:
+        info = client.station_info()
+        client.labels()  # needs the token on a LAN URL
+    except ClientError as exc:
+        fail(explain(exc, client))
+    finally:
+        client.close()
+    path = save_login(LoginState(station, token))
+    via = " through Fleet" if kind == RELAY else ""
+    typer.echo(
+        f"Station {info.get('hostname')} (LumenLabel {info.get('version')}) at "
+        f"{station}{via}. Saved to {path}."
+    )
+
+
+def logout() -> None:
+    """Forget the remembered station."""
+    if forget_login():
+        typer.echo("Forgot the remembered station.")
+    else:
+        typer.echo("No station was remembered.")