databay-cli 0.1.0__py3-none-any.whl

databay/errors.py

@@ -0,0 +1,222 @@
+"""
+The SDK's exceptions: one per error code, each with its exit code and recovery.
+
+A server answer's ``code`` becomes the generated exception for that code (``databay.error_codes``),
+a subclass of ``DatabayApiError``. Answers that do not fit the error contract, and failures the
+client finds itself, are the named classes below; ``databay.error_catalog`` holds their codes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from databay.error_catalog import LOCAL_CODES, server_exit
+
+
+@dataclass(frozen=True, slots=True)
+class Recovery:
+    action: str
+    side_effects: str
+    max_retries: int | None
+
+
+class DatabayError(Exception):
+    """
+    Every error the SDK raises. ``code`` is stable; ``exit_code`` is the CLI's exit for it.
+
+    ``details`` holds the extra top-level fields of a server error body (``revision``, ``quota``, …),
+    and, for a client error, the values that explain it (the version, the state).
+    """
+
+    code: str = "internal_error"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        status: int | None = None,
+        hint: str | None = None,
+        next_command: str | None = None,
+        details: dict[str, Any] | None = None,
+        attempts: int | None = None,
+        support_ref: str | None = None,
+        docs: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        if code is not None:
+            self.code = code
+        self.message = message
+        self.status = status
+        self._hint = hint
+        self.next_command = next_command
+        self.details = details or {}
+        self.attempts = attempts
+        self.support_ref = support_ref
+        self.docs = docs
+        #: An answer the server did give before this failure: a not-ready verdict's body, or the
+        #: answer of an operation whose wait then failed.
+        self.result: Any = None
+
+    @property
+    def exit_code(self) -> int:
+        return LOCAL_CODES[self.code].exit_code
+
+    @property
+    def recovery(self) -> Recovery:
+        local = LOCAL_CODES[self.code]
+        return Recovery(local.action, local.side_effects, local.max_retries)
+
+    @property
+    def hint(self) -> str:
+        return self._hint or LOCAL_CODES[self.code].hint
+
+    def to_dict(self) -> dict[str, Any]:
+        """The error object the CLI prints (``{"error": ...}``)."""
+        recovery = self.recovery
+        body: dict[str, Any] = {
+            "code": self.code,
+            "message": self.message,
+            "hint": self.hint,
+            "next": self.next_command,
+            "docs": self.docs,
+            "support_ref": self.support_ref,
+            "status": self.status,
+            "attempts": self.attempts,
+            "details": self.details,
+            "recovery": {
+                "action": recovery.action,
+                "side_effects": recovery.side_effects,
+                "max_retries": recovery.max_retries,
+            },
+        }
+        return body
+
+
+class DatabayApiError(DatabayError):
+    """A refusal the server answered with a registered ``code``; the generated classes subclass it."""
+
+    def _info(self) -> Any:  # noqa: ANN401 — an ErrorInfo from the generated registry
+        from databay.error_codes import REGISTRY  # noqa: PLC0415 — loaded only on an error
+
+        return REGISTRY[self.code]
+
+    @property
+    def exit_code(self) -> int:
+        return server_exit(self.code, self._info().action)
+
+    @property
+    def recovery(self) -> Recovery:
+        info = self._info()
+        return Recovery(info.action, info.side_effects, info.max_retries)
+
+    @property
+    def hint(self) -> str:
+        return self._hint or self._info().hint
+
+
+def api_error(code: str, message: str, **kwargs: Any) -> DatabayApiError:  # noqa: ANN401
+    """The generated exception for a registered server ``code``; a code missing from the registry is a ``KeyError``."""
+    from databay.error_codes import EXCEPTIONS  # noqa: PLC0415 — loaded only on an error
+
+    return EXCEPTIONS[code](message, **kwargs)
+
+
+class DatabayUsageError(DatabayError):
+    """The command line or the SDK call is incomplete or inconsistent (exit 2)."""
+
+    code = "usage_invalid"
+
+
+class DatabayProfileError(DatabayError):
+    """No profile, a broken config file, or a token the profile names is not there (exit 3)."""
+
+    code = "no_profile"
+
+
+class DatabayCancelled(DatabayError):
+    code = "cancelled"
+
+
+class DatabayUncodedError(DatabayError):
+    """A JSON error body without a ``code``: the server broke the error contract."""
+
+    code = "uncoded_error"
+
+
+class DatabayFeatureDisabled(DatabayError):
+    """A gated route's feature is off for this caller; ``feature`` and ``source`` say which and why."""
+
+    code = "feature_disabled"
+
+    def __init__(self, message: str, *, feature: str, source: str, **kwargs: Any) -> None:  # noqa: ANN401
+        from databay.feature_header import FEATURE_SOURCE_HINTS  # noqa: PLC0415 — loaded only on an error
+
+        super().__init__(
+            message, hint=FEATURE_SOURCE_HINTS[source], details={"feature": feature, "source": source}, **kwargs
+        )
+        self.feature = feature
+        self.source = source
+
+
+class DatabayUnknownCodeError(DatabayError):
+    """A ``code`` this client version does not know: a newer server added it."""
+
+    code = "unknown_error_code"
+
+
+class DatabayServerUnavailable(DatabayError):
+    """A non-JSON error body: a proxy or a maintenance page answered, not Databay."""
+
+    code = "server_unavailable"
+
+
+class DatabayNetworkError(DatabayError):
+    code = "network_error"
+
+
+class DatabayResponseInvalid(DatabayError):
+    """A 2xx body that does not fit the generated model; it names the field, never the body."""
+
+    code = "response_invalid"
+
+
+class DatabayVersionError(DatabayError):
+    code = "server_version_mismatch"
+
+
+class DatabayWaitError(DatabayError):
+    """
+    A wait that did not succeed.
+
+    Its code is ``wait_pending`` (timed out, resumable), ``wait_failed``, ``unexpected_wait_state``,
+    ``wait_target_gone`` or ``wait_feature_disabled``. ``outcome`` is the wait's last state, which the
+    CLI prints on stdout.
+    """
+
+    code = "wait_failed"
+
+    def __init__(self, message: str, *, outcome: Any = None, **kwargs: Any) -> None:  # noqa: ANN401
+        super().__init__(message, **kwargs)
+        self.outcome = outcome
+
+
+class DatabayNotReady(DatabayError):
+    """A verdict route answered a not-ready verdict; ``result`` is the whole answer."""
+
+    code = "not_ready"
+
+    def __init__(self, message: str, *, result: Any = None, **kwargs: Any) -> None:  # noqa: ANN401
+        super().__init__(message, **kwargs)
+        self.result = result
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorInfo:
+    """One server code's registry entry (``contract/error_codes.json``)."""
+
+    hint: str
+    action: str
+    side_effects: str
+    max_retries: int | None

databay/feature_header.py

@@ -0,0 +1,40 @@
+"""
+The ``X-Databay-Feature`` header on the 404 a feature gate answers.
+
+A gated feature that is off answers ``404 {"detail": "Not Found"}``, and an authenticated caller also
+gets this header naming the feature and why it is off. Standard library only: the server's tests load
+this file to check that the header the gate sends parses here.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple
+
+FEATURE_HEADER = "x-databay-feature"
+
+#: What the caller can do, per the documented ``source``. A source not listed here is not parsed.
+FEATURE_SOURCE_HINTS: dict[str, str] = {
+    "plan": "Your organization's plan does not include this feature. Ask whoever runs this server about changing it.",
+    "override": "This feature was turned off for your organization. Ask whoever runs this server to turn it back on.",
+    "ceiling": "This server has the feature turned off for everyone on it. Ask whoever runs the server to turn it on.",
+    "prerequisite": "This feature needs another feature that is off. Ask whoever runs this server which one.",
+    "not_ready": "This feature is still being set up on this server. Ask whoever runs it when it will be ready.",
+    "refused": "This server turned the feature off because a check it runs did not pass. Ask whoever runs the server.",
+    "legacy": "No plan covers your account. Check that it belongs to an organization, or ask whoever runs the server.",
+}
+
+_FEATURE_OFF = re.compile(
+    rf"disabled; feature=(?P<feature>[a-z][a-z0-9_]*); source=(?P<source>{'|'.join(FEATURE_SOURCE_HINTS)})"
+)
+
+
+class FeatureOff(NamedTuple):
+    feature: str
+    source: str
+
+
+def parse_feature_header(value: str | None) -> FeatureOff | None:
+    """The feature a header names, or ``None`` when it is absent or not the documented shape."""
+    match = _FEATURE_OFF.fullmatch(value) if value is not None else None
+    return FeatureOff(match["feature"], match["source"]) if match is not None else None

databay/invoke.py

@@ -0,0 +1,225 @@
+"""
+Calling one operation: the project, the request, the answer's model, and the verdict.
+
+``Session`` is what the SDK resources and the CLI commands share. It checks the server once
+(``databay.compat``), places the project where the operation takes it, sends the request and
+validates the answer against the generated model before anyone reads it.
+"""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote
+
+from databay import compat
+from databay.errors import DatabayNotReady, DatabayResponseInvalid, DatabayUsageError, api_error
+from databay.transport import IDEMPOTENCY_HEADER, PROJECT_HEADER, Request
+
+if TYPE_CHECKING:
+    from databay.compat import ServerInfo
+    from databay.operation import Operation, Verdict
+    from databay.transport import Answer, Transport
+
+
+@dataclass(slots=True)
+class CallValues:
+    """
+    The caller's inputs to one operation, by wire name.
+
+    ``project_explicit`` is a project id the caller passed as the operation's own project
+    parameter; ``project_flag`` is ``--project`` (or the SDK's ``project=``).
+    """
+
+    path: dict[str, str] = field(default_factory=dict)
+    query: dict[str, Any] = field(default_factory=dict)
+    headers: dict[str, str] = field(default_factory=dict)
+    body: Any = None
+    has_body: bool = False
+    project_explicit: str | None = None
+    project_flag: str | None = None
+    idempotency_key: str | None = None
+
+
+@dataclass(slots=True)
+class Result:
+    raw: Any
+    parsed: Any
+    project: str | None
+    request_id: str
+    #: The path values the request was sent with, which a wait may bind.
+    path: dict[str, str]
+
+
+def resolve_project(op: Operation, values: CallValues, active: str | None) -> str | None:
+    """
+    The project ``op`` is sent for.
+
+    An explicit id and ``--project`` that differ are ``project_conflict``; otherwise the explicit
+    id, then ``--project``, then the profile's active project. None of them is ``no_active_project``.
+    """
+    if op.project is None:
+        return None
+    explicit, flag = values.project_explicit, values.project_flag
+    if explicit and flag and explicit != flag:
+        raise api_error(
+            "project_conflict",
+            f"the project id argument {explicit} and --project {flag} differ",
+            details={"argument": explicit, "flag": flag},
+        )
+    chosen = explicit or flag or active
+    if not chosen:
+        raise DatabayUsageError(
+            f"`{op.command}` acts on a project: pass --project <project_id> or set the profile's active_project",
+            code="no_active_project",
+        )
+    return chosen
+
+
+def pointer(document: Any, path: str) -> Any:  # noqa: ANN401 — any JSON value
+    """The value at a JSON pointer (``/a/b``); ``KeyError`` when a step is missing."""
+    value = document
+    for raw_step in path.lstrip("/").split("/"):
+        step = raw_step.replace("~1", "/").replace("~0", "~")
+        if isinstance(value, list):
+            value = value[int(step)]
+        elif isinstance(value, dict):
+            value = value[step]
+        else:
+            raise KeyError(path)
+    return value
+
+
+def json_text(value: Any) -> str:  # noqa: ANN401
+    """How a declaration spells a value: a string as is, anything else as JSON (``true``, ``null``, ``3``)."""
+    import json  # noqa: PLC0415
+
+    return value if isinstance(value, str) else json.dumps(value)
+
+
+def build_request(op: Operation, values: CallValues, project: str | None) -> Request:
+    path_values = dict(values.path)
+    query = dict(values.query)
+    headers = dict(values.headers)
+    body = values.body
+    location = op.project_location
+    if location is not None and project is not None:
+        where, name = location
+        if where == "header":
+            headers[PROJECT_HEADER] = project
+        elif where == "path":
+            path_values[name] = project
+        elif where == "query":
+            query[name] = project
+        else:
+            body = {**(body or {}), name: project}
+    missing = [p.name for p in op.path_params if p.name not in path_values]
+    if missing:
+        raise DatabayUsageError(f"`{op.command}` needs {', '.join(missing)}")
+    path = op.path
+    for name, value in path_values.items():
+        path = path.replace("{" + name + "}", quote(str(value), safe=""))
+    if values.idempotency_key is not None:
+        headers[IDEMPOTENCY_HEADER] = values.idempotency_key
+    pairs = [
+        (name, json_text(item))
+        for name, value in query.items()
+        for item in (value if isinstance(value, list) else [value])
+    ]
+    return Request(
+        method=op.method.upper(),
+        path=path,
+        query=pairs,
+        headers=headers,
+        json_body=body,
+        has_body=body is not None or values.has_body,
+        secret_fields=op.secret_fields,
+    )
+
+
+def model_type(reference: str) -> Any:  # noqa: ANN401 — a model class or a type alias
+    module, _, name = reference.partition(":")
+    return getattr(importlib.import_module(f"databay.models.{module}"), name)
+
+
+def validate(op: Operation, raw: Any, reference: str | None) -> Any:  # noqa: ANN401
+    """``raw`` as the generated model, or ``response_invalid`` naming the field, never the body."""
+    if reference is None:
+        return raw
+    from pydantic import TypeAdapter, ValidationError  # noqa: PLC0415
+
+    try:
+        return TypeAdapter(model_type(reference)).validate_python(raw)
+    except ValidationError as exc:
+        first = exc.errors(include_input=False, include_url=False)[0]
+        where = ".".join(str(part) for part in first["loc"]) or "(the body)"
+        raise DatabayResponseInvalid(
+            f"`{op.command}`: the answer does not fit {reference.partition(':')[2]} at {where} ({first['type']})",
+            details={"operation": op.operation_id, "field": where, "error": first["type"]},
+        ) from None
+
+
+def decode(op: Operation, answer: Answer) -> tuple[Any, Any]:
+    """The answer as ``(raw JSON or text, validated value)``."""
+    kind = op.response.kind
+    if kind == "empty" or answer.status == 204:  # noqa: PLR2004
+        return None, None
+    if kind == "text":
+        text = answer.text()
+        return text, text
+    try:
+        raw = answer.json()
+    except ValueError:
+        raise DatabayResponseInvalid(
+            f"`{op.command}`: HTTP {answer.status} answered a body that is not JSON",
+            details={"operation": op.operation_id},
+        ) from None
+    return raw, validate(op, raw, op.response.model)
+
+
+def check_verdict(op: Operation, verdict: Verdict, raw: Any) -> None:  # noqa: ANN401
+    try:
+        value = json_text(pointer(raw, verdict.field))
+    except (KeyError, IndexError, ValueError):
+        raise DatabayResponseInvalid(
+            f"`{op.command}`: the answer has no {verdict.field}", details={"operation": op.operation_id}
+        ) from None
+    if value in verdict.ok:
+        return
+    if value in verdict.not_ready:
+        raise DatabayNotReady(
+            f"`{op.command}`: {verdict.field.lstrip('/')} is {value}", result=raw, details={"value": value}
+        )
+    raise DatabayResponseInvalid(
+        f"`{op.command}`: {verdict.field.lstrip('/')} is {value!r}, which this CLI does not classify; upgrade it",
+        details={"operation": op.operation_id, "value": value},
+    )
+
+
+@dataclass
+class Session:
+    """One caller on one server: a transport, the profile's active project and the server's version."""
+
+    transport: Transport
+    active_project: str | None = None
+    profile: str | None = None
+    #: The server's client-config and whether it came from the cache, once read.
+    server: tuple[ServerInfo, bool] | None = None
+
+    def ensure_compatible(self, op: Operation) -> None:
+        self.server = compat.ensure_compatible(self.transport, self.server, op)
+
+    def call(self, op: Operation, values: CallValues, *, check_verdict_: bool = True) -> Result:
+        project = resolve_project(op, values, self.active_project)
+        request = build_request(op, values, project)
+        self.ensure_compatible(op)
+        answer = self.transport.send(request)
+        raw, parsed = decode(op, answer)
+        if check_verdict_ and op.verdict is not None:
+            check_verdict(op, op.verdict, raw)
+        path = {p.name: values.path[p.name] for p in op.path_params if p.name in values.path}
+        location = op.project_location
+        if location is not None and location[0] == "path" and project is not None:
+            path[location[1]] = project
+        return Result(raw=raw, parsed=parsed, project=project, request_id=answer.request_id, path=path)

databay/locks.py

@@ -0,0 +1,41 @@
+"""
+Exclusive file locks between databay processes: one per credential, one for ``config.toml``.
+
+``fcntl.flock`` on ``<config dir>/locks/<name>.lock``. The kernel drops the lock when the process
+exits, so a killed process never leaves a credential locked.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import os
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+from databay.paths import config_dir
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+CONFIG_LOCK = "config"
+
+
+def lock_path(name: str) -> Path:
+    """The lock file for ``name``; a credential key is hashed, since it holds a URL."""
+    stem = name if name == CONFIG_LOCK else hashlib.sha256(name.encode()).hexdigest()
+    return config_dir() / "locks" / f"{stem}.lock"
+
+
+@contextmanager
+def locked(name: str) -> Iterator[None]:
+    """Hold the exclusive lock ``name`` for the block; waits while another process holds it."""
+    path = lock_path(name)
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    descriptor = os.open(path, os.O_RDWR | os.O_CREAT, 0o600)
+    try:
+        fcntl.flock(descriptor, fcntl.LOCK_EX)
+        yield
+    finally:
+        os.close(descriptor)