databay-cli 0.1.0__py3-none-any.whl

databay/compat.py

@@ -0,0 +1,161 @@
+"""
+Whether this client may call an operation on a server, from the server's ``/api/auth/client-config``.
+
+The answer is cached per server in the state dir for ``client_config_ttl_s``. A server running
+another product, another API major, or an older minor than the operation's ``since`` is refused
+before the operation is sent.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from databay.errors import DatabayResponseInvalid, DatabayVersionError
+from databay.paths import state_dir
+from databay.spec import API_VERSION
+from databay.transport import Request, error_from
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from databay.operation import Operation
+    from databay.transport import Transport
+
+CLIENT_CONFIG_PATH = "/api/auth/client-config"
+SUPPORTED_PRODUCT = "core"
+
+
+@dataclass(frozen=True, slots=True)
+class ServerInfo:
+    product: str
+    api_version: str
+    issuer: str
+    client_id: str
+
+
+def _version(value: str) -> tuple[int, int]:
+    major, _, minor = value.partition(".")
+    return int(major), int(minor)
+
+
+def _parse(body: Any) -> ServerInfo:  # noqa: ANN401 — any JSON value
+    fields = ("product", "api_version", "issuer", "client_id")
+    if not isinstance(body, dict) or not all(isinstance(body.get(f), str) for f in fields):
+        missing = [f for f in fields if not isinstance(body, dict) or not isinstance(body.get(f), str)]
+        raise DatabayResponseInvalid(f"GET {CLIENT_CONFIG_PATH}: the answer has no string {missing}")
+    try:
+        _version(body["api_version"])
+    except ValueError as exc:
+        raise DatabayResponseInvalid(f"GET {CLIENT_CONFIG_PATH}: api_version is not major.minor") from exc
+    return ServerInfo(**{f: body[f] for f in fields})
+
+
+def _cache_file(server: str) -> Path:
+    return state_dir() / "client-config" / f"{hashlib.sha256(server.encode()).hexdigest()[:24]}.json"
+
+
+def _cached(transport: Transport) -> ServerInfo | None:
+    path = _cache_file(transport.server)
+    if not path.exists():
+        return None
+    try:
+        entry = json.loads(path.read_text(encoding="utf-8"))
+        if time.time() - float(entry["fetched_at"]) > transport.settings.client_config_ttl_s:
+            return None
+        return _parse(entry["body"])
+    except (ValueError, KeyError, TypeError, DatabayResponseInvalid) as exc:
+        transport.events("cache_invalid", {"file": str(path), "error": type(exc).__name__})
+        return None
+
+
+def _store(transport: Transport, body: Any) -> None:  # noqa: ANN401
+    path = _cache_file(transport.server)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(f".{os.getpid()}.tmp")
+        tmp.write_text(json.dumps({"fetched_at": time.time(), "body": body}), encoding="utf-8")
+        tmp.replace(path)
+    except OSError as exc:
+        # The cache only saves a request; a read-only state dir still lets the command run.
+        transport.events("cache_write_failed", {"file": str(path), "error": type(exc).__name__})
+
+
+def server_info(transport: Transport, *, fresh: bool = False) -> tuple[ServerInfo, bool]:
+    """The server's client-config and whether it came from the cache; ``fresh`` reads the server."""
+    cached = None if fresh else _cached(transport)
+    if cached is not None:
+        return cached, True
+    request = Request("GET", CLIENT_CONFIG_PATH)
+    answer = transport.exchange(request)
+    if answer.status == 404 and answer.is_json:  # noqa: PLR2004
+        # A Databay server without client-config predates the API; a non-JSON 404 is not Databay at all.
+        raise DatabayVersionError(
+            f"the server has no {CLIENT_CONFIG_PATH}: it predates API {API_VERSION}; upgrade the server",
+            code="server_too_old",
+            details={"client_api_version": API_VERSION},
+        )
+    if answer.status >= 400:  # noqa: PLR2004
+        raise error_from(answer, request)
+    try:
+        body = answer.json()
+    except ValueError as exc:
+        raise DatabayResponseInvalid(f"GET {CLIENT_CONFIG_PATH}: the answer is not JSON") from exc
+    info = _parse(body)
+    _store(transport, body)
+    return info, False
+
+
+def ensure_compatible(
+    transport: Transport, known: tuple[ServerInfo, bool] | None, op: Operation
+) -> tuple[ServerInfo, bool]:
+    """
+    Check ``op`` against the server; ``known`` is an earlier ``(info, from_cache)``, else client-config is read.
+
+    A refusal based on a cached answer reads the server once more first: it may have been upgraded.
+    Returns the ``(info, from_cache)`` to keep for the next operation.
+    """
+    info, from_cache = known if known is not None else server_info(transport)
+    try:
+        check(info, op)
+    except DatabayVersionError:
+        if not from_cache:
+            raise
+        info, from_cache = server_info(transport, fresh=True)
+        check(info, op)
+    return info, from_cache
+
+
+def check(info: ServerInfo, op: Operation) -> None:
+    """Refuse a server this client cannot call ``op`` on: product, API major, then the operation's ``since``."""
+    check_server(info)
+    server_major, server_minor = _version(info.api_version)
+    if _version(op.since) > (server_major, server_minor):
+        raise DatabayVersionError(
+            f"`{op.command}` needs server API {op.since}; the server is on {info.api_version}",
+            code="server_too_old",
+            details={"server_api_version": info.api_version, "client_api_version": API_VERSION, "since": op.since},
+        )
+
+
+def check_server(info: ServerInfo) -> None:
+    """Refuse a server this client cannot talk to at all: another product, or another API major."""
+    if info.product != SUPPORTED_PRODUCT:
+        raise DatabayVersionError(
+            f"this server runs the {info.product!r} product; the CLI supports {SUPPORTED_PRODUCT!r} only",
+            code="unsupported_product",
+            details={"product": info.product},
+        )
+    server_major, _ = _version(info.api_version)
+    client_major, _ = _version(API_VERSION)
+    versions = {"server_api_version": info.api_version, "client_api_version": API_VERSION}
+    if server_major != client_major:
+        side = "the CLI" if server_major > client_major else "the server"
+        raise DatabayVersionError(
+            f"the server speaks API {info.api_version} and this CLI speaks {API_VERSION}; upgrade {side}",
+            details=versions,
+        )

databay/credentials.py

@@ -0,0 +1,217 @@
+"""
+Stored credentials: what ``databay login`` keeps for one server and one user, and where.
+
+A credential is keyed ``databay-cli:<server>:<sub>``; profiles name it in ``credential``. It
+holds the access token with its expiry and either a refresh token (a person's login) or an API
+key's client secret. It lives in one of two stores, which the profile names in ``token_store``:
+
+- ``keyring``: the OS keyring, the default. No usable keyring is ``keyring_unavailable``.
+- ``file``: ``<config dir>/credentials/<sha256 of the key>.json``, mode 0600, chosen with
+  ``--token-store file``. A file anyone else may read is ``token_file_insecure``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+from dataclasses import asdict, dataclass, fields, replace
+from typing import TYPE_CHECKING, Literal, Protocol
+
+from databay.errors import DatabayProfileError
+from databay.paths import config_dir
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+CredentialKind = Literal["login", "api_key"]
+TokenStoreKind = Literal["keyring", "file"]
+TOKEN_STORES: tuple[TokenStoreKind, ...] = ("keyring", "file")
+KEY_PREFIX = "databay-cli"
+KEYRING_SERVICE = "databay-cli"
+
+
+def credential_key(server: str, sub: str) -> str:
+    return f"{KEY_PREFIX}:{server}:{sub}"
+
+
+def key_sub(key: str) -> str:
+    """The ``sub`` a credential key names: what follows its last ``:`` (a URL holds colons, a sub none)."""
+    return key.rpartition(":")[2]
+
+
+#: Fields a credential saved by an earlier CLI also holds. They are dropped on read: the endpoints come
+#: from the issuer's discovery document when they are needed, so a server that moves one never breaks
+#: a stored login.
+PINNED_ENDPOINT_FIELDS = frozenset({"token_endpoint", "revocation_endpoint"})
+
+
+@dataclass(frozen=True, slots=True)
+class Credential:
+    kind: CredentialKind
+    server: str
+    sub: str
+    #: Where renewal and logout discover Keycloak's endpoints.
+    issuer: str
+    client_id: str
+    access_token: str
+    #: Unix time the access token expires at.
+    expires_at: float
+    #: A person's login only.
+    refresh_token: str | None = None
+    #: An API key only: the key's client secret.
+    client_secret: str | None = None
+
+    def with_tokens(self, access_token: str, expires_at: float, refresh_token: str | None) -> Credential:
+        """A copy holding newly issued tokens; a refresh answer without a refresh token keeps the current one."""
+        return replace(
+            self,
+            access_token=access_token,
+            expires_at=expires_at,
+            refresh_token=refresh_token if refresh_token is not None else self.refresh_token,
+        )
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self))
+
+    @classmethod
+    def from_json(cls, text: str, where: str) -> Credential:
+        names = {f.name for f in fields(cls)}
+        try:
+            data = json.loads(text)
+        except ValueError as exc:
+            raise _unreadable(where, "not JSON") from exc
+        if isinstance(data, dict) and set(data) == names | PINNED_ENDPOINT_FIELDS:
+            data = {name: data[name] for name in names}
+        if not isinstance(data, dict) or set(data) != names:
+            raise _unreadable(where, f"expected the fields {sorted(names)}")
+        kind = data["kind"]
+        if kind not in ("login", "api_key"):
+            raise _unreadable(where, f"unknown kind {kind!r}")
+        renews_with = "refresh_token" if kind == "login" else "client_secret"
+        if not isinstance(data[renews_with], str) or not data[renews_with]:
+            raise _unreadable(where, f"a {kind} credential without its {renews_with}")
+        return cls(**data)
+
+
+def _unreadable(where: str, problem: str) -> DatabayProfileError:
+    return DatabayProfileError(
+        f"the stored credential in {where} is unreadable ({problem}); sign in again with databay login",
+        code="credential_missing",
+    )
+
+
+class TokenStore(Protocol):
+    kind: TokenStoreKind
+
+    def ready(self) -> None:
+        """Raise when the store cannot be used, before anyone signs in."""
+        ...
+
+    def get(self, key: str) -> Credential | None: ...
+
+    def put(self, key: str, credential: Credential) -> None: ...
+
+    def delete(self, key: str) -> None: ...
+
+
+def _keyring_unavailable(reason: str) -> DatabayProfileError:
+    return DatabayProfileError(
+        f"no usable OS keyring ({reason}); pass --token-store file to keep tokens in a 0600 file instead",
+        code="keyring_unavailable",
+    )
+
+
+class KeyringStore:
+    kind: TokenStoreKind = "keyring"
+
+    def _backend(self):  # noqa: ANN202 — a keyring backend
+        import keyring  # noqa: PLC0415 — keyring scans its backends at import
+        from keyring.backends import fail  # noqa: PLC0415
+
+        backend = keyring.get_keyring()
+        if isinstance(backend, fail.Keyring):
+            raise _keyring_unavailable("no keyring backend is installed or running")
+        return backend
+
+    def _call(self, action: str, *args: str, absent_ok: bool = False) -> str | None:
+        """
+        Call the backend; a keyring error is ``keyring_unavailable``.
+
+        ``absent_ok`` lets a delete of an entry that is not there succeed: ``PasswordDeleteError``
+        is a ``KeyringError`` too.
+        """
+        from keyring.errors import KeyringError, PasswordDeleteError  # noqa: PLC0415
+
+        backend = self._backend()
+        try:
+            return getattr(backend, action)(KEYRING_SERVICE, *args)
+        except PasswordDeleteError:
+            if absent_ok:
+                return None
+            raise _keyring_unavailable(f"PasswordDeleteError on {action}") from None
+        except KeyringError as exc:
+            raise _keyring_unavailable(f"{type(exc).__name__} on {action}") from exc
+
+    def ready(self) -> None:
+        self._backend()
+
+    def get(self, key: str) -> Credential | None:
+        text = self._call("get_password", key)
+        return None if text is None else Credential.from_json(text, f"the keyring entry {key}")
+
+    def put(self, key: str, credential: Credential) -> None:
+        self._call("set_password", key, credential.to_json())
+
+    def delete(self, key: str) -> None:
+        self._call("delete_password", key, absent_ok=True)
+
+
+class FileStore:
+    kind: TokenStoreKind = "file"
+
+    def __init__(self, directory: Path | None = None) -> None:
+        self.directory = directory if directory is not None else config_dir() / "credentials"
+
+    def ready(self) -> None:
+        return
+
+    def path(self, key: str) -> Path:
+        return self.directory / f"{hashlib.sha256(key.encode()).hexdigest()}.json"
+
+    def get(self, key: str) -> Credential | None:
+        path = self.path(key)
+        try:
+            mode = path.stat().st_mode
+        except FileNotFoundError:
+            return None
+        if stat.S_IMODE(mode) & 0o077:
+            raise DatabayProfileError(
+                f"{path} holds tokens and others may read it (mode {stat.S_IMODE(mode):o}); run chmod 600 {path}",
+                code="token_file_insecure",
+                details={"path": str(path)},
+            )
+        return Credential.from_json(path.read_text(encoding="utf-8"), str(path))
+
+    def put(self, key: str, credential: Credential) -> None:
+        self.directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        path = self.path(key)
+        tmp = path.with_suffix(f".{os.getpid()}.tmp")
+        descriptor = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        # A temp file a crashed run left keeps its old mode through O_CREAT.
+        os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(credential.to_json())
+        tmp.replace(path)
+
+    def delete(self, key: str) -> None:
+        self.path(key).unlink(missing_ok=True)
+
+
+def open_store(kind: str) -> TokenStore:
+    if kind == "keyring":
+        return KeyringStore()
+    if kind == "file":
+        return FileStore()
+    raise DatabayProfileError(f"token_store must be one of {list(TOKEN_STORES)}, got {kind!r}", code="profile_invalid")

databay/error_catalog.py

@@ -0,0 +1,226 @@
+"""
+Exit codes, and the errors the client itself raises.
+
+Every error the CLI ends with has one code, and every code one exit code (the table below). Server
+codes come from the generated ``databay.error_codes`` registry; their exit is ``server_exit``. The
+client's own codes are ``LOCAL_CODES``. ``errors.md`` is rendered from both. Standard library only:
+``python/tools/gen_client.py`` reads it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Action = Literal["retry", "fix_and_retry", "do_first", "ask_human"]
+SideEffects = Literal["none", "partial", "complete", "unknown"]
+
+#: Exit code -> what it means and what to do next: one next action per exit code.
+EXIT_CODES: dict[int, str] = {
+    0: "ok",
+    1: "the server refused; fix the input or ask a human",
+    2: "usage: the command line is incomplete or inconsistent",
+    3: "a profile or a token is needed",
+    4: "still pending: run `next`, the same wait",
+    5: "the wait ended in failure",
+    6: "transient: retry later",
+    7: "version mismatch: upgrade the side the message names",
+    8: "the client is outdated or hit a bug: upgrade it or report it",
+    9: "not ready: fix what the answer names, then check again",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class LocalCode:
+    exit_code: int
+    action: Action
+    side_effects: SideEffects
+    hint: str
+    #: How many times an agent may retry the same call before asking a human.
+    max_retries: int | None = None
+    #: The code is also a server code: its registry entry gives the hint, and this exit applies to both.
+    server_code: bool = False
+
+
+LOCAL_CODES: dict[str, LocalCode] = {
+    "usage_invalid": LocalCode(2, "fix_and_retry", "none", "Read the command's --help and pass the flags it names."),
+    "project_conflict": LocalCode(2, "fix_and_retry", "none", "", server_code=True),
+    "no_active_project": LocalCode(
+        2, "fix_and_retry", "none", "Pass --project <project_id>, or set active_project in the profile."
+    ),
+    "secret_required": LocalCode(
+        2, "fix_and_retry", "none", "Pass the secret with --<field>-env NAME or --<field>-stdin; it is never a flag."
+    ),
+    "confirmation_required": LocalCode(
+        2, "ask_human", "none", "This command removes or overwrites state. Pass --yes once a human has agreed."
+    ),
+    "unsupported_platform": LocalCode(2, "ask_human", "none", "Run databay on Linux or macOS; on Windows, use WSL."),
+    "skill_exists": LocalCode(
+        2,
+        "ask_human",
+        "none",
+        "A skill from another CLI version is installed there. Pass --force to replace it with this version's.",
+    ),
+    "skill_write_failed": LocalCode(
+        2,
+        "ask_human",
+        "none",
+        "Nothing changed. Make the folder the message names writable, or install with the other --scope.",
+    ),
+    "unsupported_target": LocalCode(
+        2,
+        "fix_and_retry",
+        "none",
+        "Pass --target claude or --target codex; no other agent has a verified skill format.",
+    ),
+    "org_choice_required": LocalCode(
+        2,
+        "fix_and_retry",
+        "partial",
+        "You are signed in, but you belong to several organizations and none is active. "
+        "Run databay org switch <organization>, or sign in again with --org.",
+    ),
+    "org_not_in_token": LocalCode(
+        1,
+        "ask_human",
+        "complete",
+        "The server stored the organization, but the new token names another one. Run databay status; "
+        "if it persists, ask whoever runs the server.",
+    ),
+    "cancelled": LocalCode(1, "ask_human", "none", "Nothing was changed. Run the command again and answer y."),
+    "feature_disabled": LocalCode(
+        1,
+        "ask_human",
+        "none",
+        "This feature is off for you or on this server; `details` names it and why. Ask whoever runs the server.",
+    ),
+    "stopped": LocalCode(
+        1, "retry", "none", "Stopped while only reading; nothing changed. Run it again, or run `next` to resume a wait."
+    ),
+    "interrupted": LocalCode(
+        1,
+        "ask_human",
+        "unknown",
+        "Stopped after the request was sent: check its result before running it again. "
+        "A create is safe to repeat only with the --idempotency-key it printed.",
+    ),
+    "no_profile": LocalCode(3, "do_first", "none", "Sign in with databay login --server URL, or pass --profile NAME."),
+    "profile_invalid": LocalCode(3, "fix_and_retry", "none", "Fix config.toml as the message says."),
+    "token_source_conflict": LocalCode(
+        2,
+        "fix_and_retry",
+        "none",
+        "Unset DATABAY_TOKEN, or pass --profile with a profile whose auth is env; the CLI never picks one for you.",
+    ),
+    "login_required": LocalCode(
+        3, "do_first", "none", "Sign in again with the command `next` names, then run this command again."
+    ),
+    "credential_missing": LocalCode(
+        3, "do_first", "none", "The profile has no stored sign-in. Run the command `next` names."
+    ),
+    "keyring_unavailable": LocalCode(
+        3,
+        "fix_and_retry",
+        "none",
+        "No usable OS keyring. Pass --token-store file to keep tokens in a 0600 file under the config dir.",
+    ),
+    "token_file_insecure": LocalCode(
+        3, "fix_and_retry", "none", "Run chmod 600 on the file the message names; it holds tokens."
+    ),
+    "offline_access_not_granted": LocalCode(
+        3,
+        "ask_human",
+        "none",
+        "Keycloak did not grant offline_access: ask whoever runs the server to give your user that role "
+        "(docs/cli.md, Sign in).",
+    ),
+    "expired_token": LocalCode(
+        3, "retry", "none", "The sign-in code expired before it was approved. Run databay login again.", 1
+    ),
+    "access_denied": LocalCode(
+        3, "ask_human", "none", "The sign-in was refused in the browser. Run databay login again to retry."
+    ),
+    "login_timeout": LocalCode(
+        3, "retry", "none", "The browser did not come back in time. Run databay login again, or pass --device.", 1
+    ),
+    "login_failed": LocalCode(
+        3, "ask_human", "none", "Keycloak refused the sign-in; the message names its OAuth error."
+    ),
+    "revoke_failed": LocalCode(
+        1,
+        "ask_human",
+        "partial",
+        "The local credential is deleted, but Keycloak may still hold the session: ask whoever runs the "
+        "server to revoke it (docs/cli.md, Sign out).",
+    ),
+    "token_missing": LocalCode(
+        3, "do_first", "none", "Set DATABAY_TOKEN to an access token; the profile reads it from there."
+    ),
+    "wait_pending": LocalCode(
+        4, "retry", "complete", "Run `next`: it resumes the same wait and starts nothing again.", 3
+    ),
+    "wait_failed": LocalCode(
+        5, "ask_human", "complete", "The operation ran and ended in a failure state; read the error it reports."
+    ),
+    "wait_feature_disabled": LocalCode(
+        5,
+        "ask_human",
+        "unknown",
+        "What the wait polled is behind a feature that is off, so it cannot tell how the operation ended. "
+        "Ask whoever runs the server, then check the result before running a write again.",
+    ),
+    "unexpected_wait_state": LocalCode(
+        5, "ask_human", "complete", "The server reported a state this CLI does not know. Upgrade the CLI."
+    ),
+    "wait_target_gone": LocalCode(
+        5, "ask_human", "unknown", "What the wait polled no longer exists; it was deleted while waiting."
+    ),
+    "non_databay_answer": LocalCode(
+        1,
+        "fix_and_retry",
+        "none",
+        "Something other than Databay answered (a proxy, a gateway or a wrong server URL): check the profile's server.",
+    ),
+    "network_error": LocalCode(6, "retry", "unknown", "Check the server URL and the network, then run it again.", 3),
+    "server_unavailable": LocalCode(
+        6, "retry", "unknown", "The server answered without a Databay error body. Try again later.", 3
+    ),
+    "server_version_mismatch": LocalCode(
+        7, "ask_human", "none", "The CLI and the server speak different API majors. Upgrade the older side."
+    ),
+    "server_too_old": LocalCode(
+        7, "ask_human", "none", "This command needs a newer server. Upgrade the server or use an older CLI."
+    ),
+    "unsupported_product": LocalCode(
+        7, "ask_human", "none", "This server runs Databay for Shopify, which the CLI does not support."
+    ),
+    "unknown_error_code": LocalCode(
+        8, "ask_human", "unknown", "The server answered a code this CLI does not know. Upgrade the CLI."
+    ),
+    "response_invalid": LocalCode(
+        8, "ask_human", "unknown", "The answer does not match this CLI's models. Upgrade the CLI or report it."
+    ),
+    "uncoded_error": LocalCode(
+        8, "ask_human", "unknown", "The server answered an error without a code. Report it with the request id."
+    ),
+    "internal_error": LocalCode(
+        8, "ask_human", "unknown", "The CLI failed unexpectedly. Report it with the crash log it names."
+    ),
+    "not_ready": LocalCode(9, "fix_and_retry", "none", "Fix what the answer names, then run the check again."),
+}
+
+#: The hint of ``uncoded_error`` on a 404: the feature gate sends no header to a caller it could not identify.
+UNCODED_404_HINT = (
+    "A 404 without a code can be a route this server does not have, a sign-in it no longer accepts, or a feature "
+    "that is off where the server does not say so. Sign in again, then report it with the request id."
+)
+
+#: Server codes whose exit is not the default: the caller must sign in again, or fix the command line.
+SERVER_EXIT_OVERRIDES: dict[str, int] = {"token_invalid": 3, "token_stale": 3, "project_conflict": 2}
+
+
+def server_exit(code: str, action: Action) -> int:
+    """The exit code of a server error code: an override, else 6 when the registry says retry, else 1."""
+    if code in SERVER_EXIT_OVERRIDES:
+        return SERVER_EXIT_OVERRIDES[code]
+    return 6 if action == "retry" else 1