duckhaven-cli 0.1.0__py3-none-any.whl

dh/config.py

@@ -0,0 +1,263 @@
+"""The profile file: where it lives, how it is read, and how it is written.
+
+A flat TOML document holding one table per profile:
+
+    default_profile = "prod"
+
+    [profile.prod]
+    host      = "https://duckhaven.internal"
+    token     = "dh_pat_..."
+    workspace = "analytics"
+
+It holds a live credential, so the permission rules here are not advisory.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from dh.errors import ConfigError
+
+if sys.version_info >= (3, 11):  # pragma: no cover - exercised by the 3.11+ matrix legs
+    import tomllib
+else:  # pragma: no cover - exercised by the 3.10 matrix leg
+    import tomli as tomllib
+
+#: Every profile field, in the order they are written back out.
+FIELDS = ("host", "token", "workspace", "catalog", "agent")
+
+#: Mode for the file and its directory. The token is a bearer credential: anything
+#: another account can read is a credential that account holds too.
+_FILE_MODE = 0o600
+_DIR_MODE = 0o700
+
+
+@dataclass(frozen=True)
+class Profile:
+    name: str
+    host: str | None = None
+    token: str | None = None
+    workspace: str | None = None
+    catalog: str | None = None
+    agent: str | None = None
+
+
+@dataclass(frozen=True)
+class Config:
+    path: Path
+    default_profile: str | None = None
+    profiles: dict[str, Profile] = None  # type: ignore[assignment]
+
+    def __post_init__(self) -> None:
+        if self.profiles is None:
+            object.__setattr__(self, "profiles", {})
+
+    def get(self, name: str) -> Profile | None:
+        return self.profiles.get(name)
+
+    def resolved_default(self) -> str | None:
+        """The profile used when none is named.
+
+        ``default_profile`` when it points at one that exists, else a profile
+        literally called ``default``, else the only profile there is -- a config
+        with exactly one profile should not need to name it.
+        """
+        if self.default_profile and self.default_profile in self.profiles:
+            return self.default_profile
+        if "default" in self.profiles:
+            return "default"
+        if len(self.profiles) == 1:
+            return next(iter(self.profiles))
+        return None
+
+
+def config_path() -> Path:
+    """Where the profile file lives.
+
+    ``DH_CONFIG_FILE`` wins, so a test or a CI job can point somewhere private
+    without touching the user's own. Otherwise XDG, then its documented default.
+    """
+    override = os.environ.get("DH_CONFIG_FILE")
+    if override:
+        return Path(override).expanduser()
+    base = os.environ.get("XDG_CONFIG_HOME") or "~/.config"
+    return Path(base).expanduser() / "duckhaven" / "config.toml"
+
+
+def assert_permissions(path: Path) -> None:
+    """Refuse a config that anyone but its owner can read or write.
+
+    Always, with no env flag to relax it. A warning about a world-readable token is
+    a warning nobody reads; the file is not usable, so the CLI treats it that way
+    and puts the fix in the message.
+    """
+    if os.name == "nt":  # pragma: no cover - POSIX modes do not apply on Windows
+        return
+    mode = path.stat().st_mode
+    if not mode & (stat.S_IRWXG | stat.S_IRWXO):
+        return
+    raise ConfigError(
+        "config_permissions",
+        f"{path} is readable or writable by other users and holds an access token. "
+        f"Fix it with: chmod 600 {path}",
+        {"path": str(path), "mode": oct(stat.S_IMODE(mode))},
+    )
+
+
+def load(path: Path | None = None) -> Config:
+    """Read the profile file. A missing file is an empty config, not an error.
+
+    Nothing has gone wrong the first time someone runs `dh`; the commands that
+    need a profile say so themselves, with something more useful than "no such
+    file".
+    """
+    path = path or config_path()
+    if not path.exists():
+        return Config(path=path)
+    assert_permissions(path)
+    try:
+        raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
+        raise ConfigError("config_invalid", f"{path} is not valid TOML: {exc}") from exc
+
+    profiles: dict[str, Profile] = {}
+    for name, table in (raw.get("profile") or {}).items():
+        if not isinstance(table, dict):
+            raise ConfigError("config_invalid", f"{path}: [profile.{name}] is not a table")
+        profiles[name] = Profile(name=name, **{f: _as_str(table.get(f), name, f) for f in FIELDS})
+    default = raw.get("default_profile")
+    return Config(
+        path=path,
+        default_profile=str(default) if default is not None else None,
+        profiles=profiles,
+    )
+
+
+def _as_str(value: object, profile: str, field: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ConfigError(
+            "config_invalid",
+            f"[profile.{profile}].{field} must be a string, got {type(value).__name__}",
+        )
+    return value
+
+
+def save(config: Config) -> None:
+    """Write the profile file back, creating it 0600 from the outset.
+
+    The mode is passed to ``os.open`` rather than applied with a later ``chmod``:
+    between the two there is a window in which the token is world-readable, and a
+    window is all an attacker on a shared box needs.
+    """
+    path = config.path
+    path.parent.mkdir(parents=True, exist_ok=True, mode=_DIR_MODE)
+    # Write beside the target and rename over it. Truncating in place means a
+    # crash, a full disk or an interrupt between truncate and write destroys
+    # every profile and the tokens with them; `os.replace` is atomic on POSIX and
+    # Windows alike, so the file is either the old one or the new one.
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, _FILE_MODE)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(dumps(config))
+            handle.flush()
+            os.fsync(handle.fileno())
+        if os.name != "nt":  # pragma: no branch - POSIX modes do not apply on Windows
+            os.chmod(tmp, _FILE_MODE)
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def dumps(config: Config) -> str:
+    """Render the config as TOML.
+
+    Hand-rolled rather than pulling in a writer: the document is a flat set of
+    string tables, and the whole grammar this needs is a quoted string.
+    """
+    lines: list[str] = []
+    default = config.default_profile
+    if default:
+        lines.append(f"default_profile = {_quote(default)}")
+        lines.append("")
+    for name in sorted(config.profiles):
+        profile = config.profiles[name]
+        lines.append(f"[profile.{_key(name)}]")
+        for field in FIELDS:
+            value = getattr(profile, field)
+            if value is not None:
+                lines.append(f"{field} = {_quote(value)}")
+        lines.append("")
+    return "\n".join(lines).rstrip("\n") + "\n"
+
+
+#: The escapes TOML spells out; everything else in C0/DEL becomes \\uXXXX.
+_SHORT_ESCAPES = {
+    "\\": "\\\\",
+    '"': '\\"',
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+}
+
+_BARE_KEY = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-")
+
+
+def _key(name: str) -> str:
+    """A bare key where TOML allows one, a quoted key otherwise."""
+    return name if name and set(name) <= _BARE_KEY else _quote(name)
+
+
+#: The escapes TOML spells out. Everything else in C0/DEL becomes \uXXXX.
+_SHORT_ESCAPES = {"\\": "\\\\", '"': '\\"', "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+
+
+def _quote(value: str) -> str:
+    """A TOML basic string.
+
+    TOML forbids raw U+0000-U+0008, U+000B-U+001F and U+007F in a basic string,
+    so anything in those ranges is escaped rather than written through. Emitting
+    one produced a file `tomllib` then refused to read -- and because `save`
+    replaces the whole file, every later `dh` invocation failed with
+    `config_invalid` until someone hand-edited it.
+    """
+    out = []
+    for char in value:
+        if char in _SHORT_ESCAPES:
+            out.append(_SHORT_ESCAPES[char])
+        elif char < " " or char == "\x7f":
+            out.append(f"\\u{ord(char):04X}")
+        else:
+            out.append(char)
+    return '"' + "".join(out) + '"'
+
+
+def upsert(config: Config, profile: Profile) -> Config:
+    """Add or replace a profile, making it the default when there was none."""
+    profiles = dict(config.profiles)
+    profiles[profile.name] = profile
+    default = config.default_profile or profile.name
+    return replace(config, profiles=profiles, default_profile=default)
+
+
+def set_default(config: Config, name: str) -> Config:
+    """Point the default at an existing profile."""
+    if name not in config.profiles:
+        raise ConfigError("no_such_profile", f"No profile named {name!r} in {config.path}")
+    return replace(config, default_profile=name)
+
+
+def remove(config: Config, name: str) -> Config:
+    """Drop a profile, and the default pointer with it when it named that one."""
+    if name not in config.profiles:
+        raise ConfigError("no_such_profile", f"No profile named {name!r} in {config.path}")
+    profiles = {k: v for k, v in config.profiles.items() if k != name}
+    default = None if config.default_profile == name else config.default_profile
+    return replace(config, profiles=profiles, default_profile=default)

dh/context.py

@@ -0,0 +1,166 @@
+"""Per-invocation state: the global flags, resolved settings, and how to emit.
+
+Lives apart from ``dh.main`` so command modules can depend on it without importing
+the app they are registered on.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import click
+import typer
+
+from dh import config as config_mod
+from dh.errors import Aborted, DhError
+from dh.output import Format, color_enabled, default_format, render
+from dh.resolve import Settings, resolve
+from dh.rest import RestClient
+
+#: Ways a confirmation prompt can end without an answer. Both classes because
+#: typer vendors its own click and `typer.confirm` raises the vendored `Abort`.
+_DECLINED = (EOFError, click.Abort, typer.Abort)
+
+#: The opt-out on every destructive command. One spelling everywhere, so nobody
+#: has to remember which command wanted `--force` instead.
+YES = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt.")
+
+
+def _interactive() -> bool:
+    """Whether there is a person here to answer a prompt.
+
+    Its own function because Click's test runner installs a non-tty stdin, so this
+    is the seam a test flips to exercise the branch where someone is asked.
+    """
+    return sys.stdin.isatty()
+
+
+@dataclass
+class CliContext:
+    overrides: dict[str, str | None] = field(default_factory=dict)
+    fmt: Format | None = None
+    output: Path | None = None
+    quiet: bool = False
+    no_color: bool = False
+    debug_enabled: bool = False
+
+    def format(self) -> Format:
+        """The chosen format, or the TTY-derived default."""
+        return self.fmt or default_format(sys.stdout)
+
+    def settings(self) -> Settings:
+        """Apply the precedence chain, reading the profile file once per command."""
+        return resolve(config_mod.load(), dict(os.environ), self.overrides)
+
+    def emit(self, data: Any, *, cursor: str | None = None, has_more: bool = False) -> None:
+        """Write a payload to stdout, or to ``--output`` when one was given."""
+        fmt = self.format()
+        # A file gets no escape codes regardless of where stdout points; rendering
+        # once with the right colour setting avoids doing the work twice.
+        to_file = self.output is not None
+        body = render(
+            data,
+            fmt,
+            cursor=cursor,
+            has_more=has_more,
+            color=False if to_file else color_enabled(sys.stdout, no_color=self.no_color),
+        )
+        if to_file:
+            self.output.write_text(body + "\n", encoding="utf-8")
+            return
+        if body:
+            sys.stdout.write(body + "\n")
+
+    def client(self, settings: Settings | None = None) -> RestClient:
+        """A REST client for the resolved host and token.
+
+        Both are required here rather than defaulted, so a command fails with
+        "no host configured, set it with ..." instead of a connection error
+        against nothing.
+        """
+        settings = settings or self.settings()
+        return RestClient(settings.require("host"), settings.require("token"))
+
+    def debug(self, message: str) -> None:
+        """A trace line, shown only under `--debug`.
+
+        Which catalog was resolved belongs here: a wrong default reads the wrong
+        data silently, and this is how someone finds out which one was used.
+        """
+        if self.debug_enabled:
+            typer.echo(f"[dh] {message}", err=True)
+
+    def page(
+        self,
+        client,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        limit: int | None = None,
+        fetch_all: bool = False,
+        translate=None,
+    ) -> None:
+        """Emit one page of a collection, or every page under ``--all``.
+
+        The same six lines appeared in every list command. ``translate`` lets a
+        caller reshape an error before it surfaces -- the session routes use it to
+        turn the disabled-surface 404 into something actionable.
+        """
+        try:
+            if fetch_all:
+                self.emit(list(client.walk(path, params=params, limit=limit)))
+                return
+            rows, cursor, has_more = client.collect(path, params=params, limit=limit)
+        except DhError as exc:
+            raise (translate(exc) if translate else exc) from exc
+        self.emit(rows, cursor=cursor, has_more=has_more)
+
+    def note(self, message: str) -> None:
+        """A diagnostic for a person, on stderr. Silenced by ``-q``.
+
+        Never stdout: a progress line in the payload stream is what makes a CLI
+        unpipeable.
+        """
+        if not self.quiet:
+            typer.echo(message, err=True)
+
+    def confirm(self, action: str, target: str, *, yes: bool) -> None:
+        """Stop a destructive command that nobody agreed to.
+
+        Three outcomes, and the middle one is the point. With ``--yes`` it returns.
+        At a terminal it asks. With neither -- a pipeline, a cron job, a CI step --
+        it *refuses*, because the alternatives are both wrong: prompting hangs the
+        job on a question no one will answer, and proceeding anyway makes ``--yes``
+        decorative and lets an unattended `dh table drop` delete data by accident.
+
+        Not silenced by ``-q``. A prompt is not a diagnostic; suppressing it would
+        turn `dh -q workspace delete` into the exact unattended deletion this
+        exists to prevent.
+        """
+        if yes:
+            return
+        if not _interactive():
+            raise Aborted(
+                "confirmation_required",
+                f"{action} {target}: refusing to act without confirmation. "
+                "Pass --yes to confirm, or run this from a terminal.",
+                {"action": action, "target": target},
+            )
+        try:
+            agreed = typer.confirm(f"{action} {target}?", default=False, err=True)
+        except _DECLINED:
+            # Ctrl-C or Ctrl-D at "are you sure?" means no, not "crash".
+            agreed = False
+        if not agreed:
+            raise Aborted("aborted", f"Not confirmed; {target} was left alone.")
+
+
+def of(ctx: typer.Context) -> CliContext:
+    """The CliContext for this invocation, creating one if the callback was skipped."""
+    if not isinstance(ctx.obj, CliContext):
+        ctx.obj = CliContext()
+    return ctx.obj

dh/errors.py

@@ -0,0 +1,175 @@
+"""Failures, and the exit status each one leaves behind.
+
+Every error the CLI surfaces is a :class:`DhError` carrying the same three fields
+DuckHaven's own error envelope uses -- ``error``, ``message``, ``details`` -- so a
+caller parses one shape whether the failure happened locally or on the server.
+
+Exit codes are differentiated by default rather than hidden behind a flag. The one
+that earns its keep is :attr:`ExitCode.QUERY_FAILED`: it separates "the SQL you sent
+was wrong" from "the CLI or the server broke".
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import Any
+
+
+class ExitCode(IntEnum):
+    OK = 0
+    #: An unhandled exception or a response the CLI could not make sense of.
+    FAILURE = 1
+    #: Bad flags or arguments. Typer exits with this on its own.
+    USAGE = 2
+    #: 401/403, a missing or rejected credential, an unreadable config.
+    AUTH = 3
+    NOT_FOUND = 4
+    #: 409/410/422 -- the request was understood and refused.
+    CONFLICT = 5
+    #: The query ran and reached `failed`. The CLI worked; the SQL did not.
+    QUERY_FAILED = 6
+    TIMEOUT = 7
+    #: 503, connection refused, DNS failure.
+    UNAVAILABLE = 8
+    #: A destructive command was not confirmed, so nothing was done.
+    ABORTED = 9
+    #: Conventional for SIGINT. The server-side query is cancelled first.
+    INTERRUPTED = 130
+
+
+class DhError(Exception):
+    """A failure with a machine code, a displayable message, and an exit status."""
+
+    exit_code: ExitCode = ExitCode.FAILURE
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.details = details
+
+    def envelope(self) -> dict[str, Any]:
+        """The wire form, identical in shape to the server's own error body."""
+        return {"error": self.code, "message": self.message, "details": self.details}
+
+
+class ConfigError(DhError):
+    """The profile file is missing, malformed, or too widely readable.
+
+    Grouped under ``AUTH`` because from the caller's side it is the same problem as
+    a rejected token: the CLI has no usable credential.
+    """
+
+    exit_code = ExitCode.AUTH
+
+
+class AuthError(DhError):
+    exit_code = ExitCode.AUTH
+
+
+class NotFoundError(DhError):
+    exit_code = ExitCode.NOT_FOUND
+
+
+class ConflictError(DhError):
+    """Understood and refused: 409, 410, 422, and other 4xx."""
+
+    exit_code = ExitCode.CONFLICT
+
+
+class TimeoutError(DhError):  # noqa: A001 - the CLI's timeout, not the builtin
+    exit_code = ExitCode.TIMEOUT
+
+
+class UnavailableError(DhError):
+    exit_code = ExitCode.UNAVAILABLE
+
+
+class QueryFailed(DhError):
+    """The query ran and reached ``failed``. The CLI worked; the SQL did not."""
+
+    exit_code = ExitCode.QUERY_FAILED
+
+
+class Aborted(DhError):
+    """A destructive command was declined, or could not ask. Nothing was done.
+
+    Its own status rather than a reuse of ``CONFLICT``: a pipeline needs to tell
+    "the server refused this" from "I never sent it", and the second is not a
+    failure of anything but the invocation.
+    """
+
+    exit_code = ExitCode.ABORTED
+
+
+#: HTTP status to the class that carries the right exit code.
+#:
+#: 5xx other than the three below stays ``FAILURE``: a 500 is the server breaking
+#: unexpectedly, which is not the same as it being unavailable, and telling a
+#: pipeline to retry a crash wastes its time.
+_BY_STATUS: dict[int, type[DhError]] = {
+    401: AuthError,
+    403: AuthError,
+    404: NotFoundError,
+    408: TimeoutError,
+    429: UnavailableError,
+    502: UnavailableError,
+    503: UnavailableError,
+    504: TimeoutError,
+}
+
+
+def _class_for(status: int) -> type[DhError]:
+    if status in _BY_STATUS:
+        return _BY_STATUS[status]
+    if 400 <= status < 500:
+        return ConflictError
+    return DhError
+
+
+def parse_envelope(body: object, status: int) -> tuple[str, str, dict[str, Any] | None]:
+    """Pull ``(error, message, details)` out of a response body.
+
+    DuckHaven answers every 4xx and 5xx with that envelope, including crashes, so
+    this normally just reads three keys. It still degrades gracefully: a proxy's
+    HTML error page or a truncated body yields the status line rather than a
+    parse failure, because the one moment a caller most needs a message is when
+    something upstream is misbehaving.
+    """
+    if isinstance(body, dict) and "error" in body:
+        code = str(body.get("error"))
+        message = str(body.get("message") or body.get("detail") or code)
+        details = body.get("details")
+        return code, message, details if isinstance(details, dict) else None
+    if isinstance(body, dict) and isinstance(body.get("detail"), str):
+        # api_version 1 shape, still emitted by servers predating the envelope.
+        return f"http_{status}", body["detail"], None
+    text = body if isinstance(body, str) else ""
+    return f"http_{status}", text.strip() or f"HTTP {status}", None
+
+
+def from_status(status: int, body: object) -> DhError:
+    """Build the right error for an HTTP failure."""
+    code, message, details = parse_envelope(body, status)
+    return _class_for(status)(code, message, details)
+
+
+def from_connector(exc: Exception) -> DhError:
+    """Translate a ``duckhaven-sql-connector`` DB-API exception.
+
+    The connector preserves the server's slug and status on the exception it
+    raises, so the CLI re-derives the same exit code it would have chosen from the
+    response itself rather than flattening every SQL failure to 1.
+    """
+    status = getattr(exc, "status_code", None)
+    code = getattr(exc, "code", None)
+    message = getattr(exc, "detail", None) or str(exc)
+    if status is None:
+        # A transport failure: no response was ever received.
+        return UnavailableError(code or "transport_error", message)
+    return _class_for(int(status))(code or f"http_{status}", message)