pixie-lab-dibs 0.1.0__py3-none-any.whl

dibs/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""dibs: call dibs on shared lab machines.
+
+People, ai-agents and automation-runners share lab machines. dibs keeps
+a list of the things they share, fed from sources such as a config file
+or a pixie server, and lets each of them see who is using a thing,
+claim it, and release it. A claim is a note, not a lock: it tells
+everyone who is on a machine, and it never stops anyone from logging
+in.
+"""
+
+__version__ = "0.1.0"

dibs/_sources.py

@@ -0,0 +1,153 @@
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Where things come from: the config file, and pixie servers.
+
+The config file (``/etc/dibs/dibs.toml`` by default) lists things by
+hand and names the pixie servers to poll::
+
+    sync_interval = 60          # seconds between syncs
+
+    [[pixie]]
+    url = "http://pixie:8080"   # every machine pixie knows becomes a thing
+
+    [[thing]]
+    name = "ryzen-01"           # a machine pixie does not boot
+    kind = "machine"            # default
+    mac = "aa:bb:cc:dd:ee:ff"   # any other key is kept as an attribute
+
+A ``[[thing]]`` with the name of a pixie machine adds its attributes to
+that machine rather than making a second thing.
+"""
+
+from __future__ import annotations
+
+import logging
+import tomllib
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from dibs._store import Store, Thing, ts, validate_thing_name
+
+log = logging.getLogger("dibs")
+
+CONFIG_SOURCE = "config"
+
+
+@dataclass
+class Config:
+    things: list[Thing] = field(default_factory=list)
+    pixies: list[str] = field(default_factory=list)
+    sync_interval: int = 60
+
+
+def load_config(path: Path) -> Config:
+    """Read the config file; a missing file is an empty config, so a
+    fresh install starts with no things rather than failing."""
+    if not path.exists():
+        return Config()
+    try:
+        raw = tomllib.loads(path.read_text())
+    except tomllib.TOMLDecodeError as exc:
+        raise ValueError(f"{path}: {exc}") from exc
+    interval = raw.get("sync_interval", 60)
+    if not isinstance(interval, int) or interval < 5:
+        raise ValueError(f"{path}: sync_interval must be a whole number of seconds, at least 5")
+    pixies = []
+    for i, entry in enumerate(raw.get("pixie", [])):
+        url = entry.get("url") if isinstance(entry, dict) else None
+        if not isinstance(url, str) or not url.startswith(("http://", "https://")):
+            raise ValueError(f'{path}: pixie #{i + 1} needs a url = "http://..."')
+        pixies.append(url.rstrip("/"))
+    things = []
+    seen: set[str] = set()
+    for i, entry in enumerate(raw.get("thing", [])):
+        if not isinstance(entry, dict) or "name" not in entry:
+            raise ValueError(f"{path}: thing #{i + 1} needs a name")
+        attrs = dict(entry)
+        try:
+            name = validate_thing_name(str(attrs.pop("name")))
+        except ValueError as exc:
+            raise ValueError(f"{path}: thing #{i + 1}: {exc}") from exc
+        if name in seen:
+            raise ValueError(f"{path}: thing {name!r} is listed twice")
+        seen.add(name)
+        kind = str(attrs.pop("kind", "machine"))
+        things.append(Thing(name, kind, CONFIG_SOURCE, attrs))
+    return Config(things, pixies, interval)
+
+
+class PixieSource:
+    """A pixie server's machines, as things of kind ``machine``."""
+
+    def __init__(self, url: str, client: httpx.Client | None = None) -> None:
+        self.url = url.rstrip("/")
+        self.id = f"pixie:{self.url}"
+        self._client = client or httpx.Client(timeout=10)
+
+    def fetch(self) -> list[Thing] | None:
+        """The machines pixie lists now, or ``None`` when pixie cannot
+        be reached, so the caller can keep what it had."""
+        try:
+            r = self._client.get(f"{self.url}/machines")
+            r.raise_for_status()
+            machines = r.json()["machines"]
+        except (httpx.HTTPError, ValueError, KeyError) as exc:
+            log.warning("pixie %s: %s; keeping its things from the last sync", self.url, exc)
+            return None
+        things = []
+        for m in machines:
+            try:
+                name = validate_thing_name(str(m.get("name", "")))
+            except ValueError:
+                continue  # a pixie from before machine names; nothing to call it
+            attrs: dict[str, Any] = {"mac": m["mac"], "pixie": self.url}
+            for key in ("boot_mode", "labels", "last_seen_ip"):
+                if m.get(key):
+                    attrs[key] = m[key]
+            things.append(Thing(name, "machine", self.id, attrs))
+        return things
+
+    def info(self, name: str) -> dict[str, Any] | None:
+        """pixie's description of one machine, or ``None`` if it has none."""
+        try:
+            r = self._client.get(f"{self.url}/machines/{name}/info")
+            if r.status_code == 404:
+                return None
+            r.raise_for_status()
+            info: dict[str, Any] = r.json()
+            return info
+        except (httpx.HTTPError, ValueError) as exc:
+            log.warning("pixie %s: info for %s: %s", self.url, name, exc)
+            return None
+
+
+def sync(
+    store: Store, config: Config, pixies: list[PixieSource], *, now: datetime | None = None
+) -> None:
+    """Rebuild the things table from every source."""
+    stamp = ts(now or datetime.now(UTC))
+    previous = store.list_things()
+    merged: dict[str, Thing] = {}
+    for source in pixies:
+        fetched = source.fetch()
+        if fetched is None:
+            fetched = [t for t in previous if t.source == source.id]
+        else:
+            for t in fetched:
+                t.synced_at = stamp
+        for t in fetched:
+            merged.setdefault(t.name, t)
+    for t in config.things:
+        base = merged.get(t.name)
+        if base is not None:
+            base.attrs = {**base.attrs, **t.attrs}
+            base.kind = t.kind
+        else:
+            merged[t.name] = Thing(t.name, t.kind, t.source, dict(t.attrs), stamp)
+    store.replace_things(sorted(merged.values(), key=lambda t: t.name))

dibs/_sshsig.py

@@ -0,0 +1,87 @@
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""SSH public keys and ``ssh-keygen -Y`` signatures.
+
+Signature checking is left to OpenSSH, the reference implementation of
+the format, rather than reimplemented here. Signatures are made and
+checked in the ``dibs`` namespace, so one made for dibs cannot be
+passed off as, say, a git commit signature, or the other way round.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+
+NAMESPACE = "dibs"
+
+_KEY_TYPES = frozenset(
+    {
+        "ssh-ed25519",
+        "ssh-rsa",
+        "ecdsa-sha2-nistp256",
+        "ecdsa-sha2-nistp384",
+        "ecdsa-sha2-nistp521",
+        "sk-ssh-ed25519@openssh.com",
+        "sk-ecdsa-sha2-nistp256@openssh.com",
+    }
+)
+_SIGNATURE_MAX = 8192
+
+
+def parse_pubkey(raw: str) -> tuple[str, str]:
+    """``(key, fingerprint)`` for one OpenSSH public key line. ``key`` is
+    the ``<type> <base64>`` pair with any comment dropped; raises
+    :class:`ValueError` on anything ``ssh-keygen`` does not accept."""
+    parts = (raw or "").strip().split()
+    if len(parts) < 2 or "\n" in raw.strip() or parts[0] not in _KEY_TYPES:
+        raise ValueError(
+            "pubkey must be one OpenSSH public key line, e.g. the contents of id_ed25519.pub"
+        )
+    key = f"{parts[0]} {parts[1]}"
+    out = subprocess.run(
+        ["ssh-keygen", "-l", "-E", "sha256", "-f", "-"],
+        input=key + "\n",
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    if out.returncode != 0:
+        raise ValueError("pubkey is not a valid OpenSSH public key")
+    return key, out.stdout.split()[1]
+
+
+def verify(*, principal: str, key: str, message: str, signature: str) -> bool:
+    """True when ``signature`` is a ``dibs``-namespace signature of
+    ``message`` by ``key``. ``principal`` must already be validated: it
+    is written into the ``allowed_signers`` line."""
+    if len(signature) > _SIGNATURE_MAX or "BEGIN SSH SIGNATURE" not in signature:
+        return False
+    with tempfile.TemporaryDirectory(prefix="dibs-sshsig-") as tmp:
+        allowed = Path(tmp) / "allowed_signers"
+        allowed.write_text(f'{principal} namespaces="{NAMESPACE}" {key}\n')
+        sig = Path(tmp) / "message.sig"
+        sig.write_text(signature)
+        out = subprocess.run(
+            [
+                "ssh-keygen",
+                "-Y",
+                "verify",
+                "-f",
+                str(allowed),
+                "-I",
+                principal,
+                "-n",
+                NAMESPACE,
+                "-s",
+                str(sig),
+            ],
+            input=message,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    return out.returncode == 0

dibs/_store.py

@@ -0,0 +1,327 @@
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Things and the claims on them.
+
+A **thing** is whatever people share and claim, mostly lab machines. The
+things table is rebuilt from the sources on every sync (see
+:mod:`dibs._sources`); dibs never edits it otherwise. **Claims** live in
+a table of their own, keyed by thing name, so a claim outlives a sync in
+which its source was unreachable or briefly forgot the thing.
+
+Every surface (``dibs``, the web page, the login hook on a machine)
+prints a claim as the same sentence, from :func:`sentence`.
+"""
+
+from __future__ import annotations
+
+import builtins
+import contextlib
+import json
+import re
+import sqlite3
+import threading
+from collections.abc import Generator, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+_WRITE_LOCK = threading.Lock()
+
+# What people type and put in configs next to the hostname, so a host
+# label: lowercase a-z, 0-9 and -, at most 63 chars.
+THING_NAME_RE = re.compile(r"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$")
+
+PURPOSE_MAX = 128
+ASSISTED_BY_MAX = 64
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS things (
+    name       TEXT PRIMARY KEY,
+    kind       TEXT NOT NULL,
+    source     TEXT NOT NULL,
+    attrs      TEXT NOT NULL DEFAULT '{}',
+    synced_at  TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS claims (
+    thing        TEXT PRIMARY KEY,
+    holder       TEXT NOT NULL,
+    assisted_by  TEXT NOT NULL DEFAULT '',
+    purpose      TEXT NOT NULL,
+    claimed_at   TEXT NOT NULL,
+    expires_at   TEXT NOT NULL DEFAULT ''
+);
+"""
+
+
+def ts(at: datetime) -> str:
+    return at.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def parse_ts(raw: str) -> datetime:
+    return datetime.strptime(raw, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=UTC)
+
+
+def validate_thing_name(raw: str) -> str:
+    name = (raw or "").strip().lower()
+    if not THING_NAME_RE.match(name):
+        raise ValueError(
+            f"name {name!r} must be a hostname label: a-z / 0-9 / -, "
+            "1-63 chars, no leading or trailing -"
+        )
+    return name
+
+
+def _one_line(field_name: str, raw: str, limit: int) -> str:
+    value = (raw or "").strip()
+    if not value:
+        raise ValueError(f"{field_name} must not be empty")
+    if len(value) > limit:
+        raise ValueError(f"{field_name} must be at most {limit} chars")
+    # Printed into other people's terminals by the login hook, so no
+    # control characters (an ESC would let a claim restyle the terminal).
+    if not value.isprintable():
+        raise ValueError(f"{field_name} must be a single line of printable text")
+    return value
+
+
+def validate_purpose(raw: str) -> str:
+    return _one_line("purpose", raw, PURPOSE_MAX)
+
+
+def validate_assisted_by(raw: str) -> str:
+    """Optional, so blank passes."""
+    return _one_line("assisted_by", raw, ASSISTED_BY_MAX) if (raw or "").strip() else ""
+
+
+@dataclass
+class Thing:
+    name: str
+    kind: str
+    source: str
+    """``config``, or ``pixie:<url>`` for a thing a pixie server reported."""
+    attrs: dict[str, Any] = field(default_factory=dict)
+    synced_at: str = ""
+
+
+@dataclass
+class Claim:
+    thing: str
+    holder: str
+    """The dibs user who holds the claim."""
+    purpose: str
+    claimed_at: str
+    assisted_by: str = ""
+    """The agent the holder claimed through, in ``Agent:model`` form like
+    an ``Assisted-by:`` trailer; blank for a claim made by hand."""
+    expires_at: str = ""
+    """Blank for a claim that never expires."""
+
+    def is_live(self, now: datetime) -> bool:
+        """A claim past its expiry counts as no claim: the thing is free
+        to take without ``force``, and nothing has to sweep it up."""
+        return not self.expires_at or parse_ts(self.expires_at) > now
+
+    def to_dict(self) -> dict[str, str]:
+        out = {
+            "holder": self.holder,
+            "purpose": self.purpose,
+            "claimed_at": self.claimed_at,
+        }
+        if self.assisted_by:
+            out["assisted_by"] = self.assisted_by
+        if self.expires_at:
+            out["expires_at"] = self.expires_at
+        return out
+
+
+class ClaimConflict(ValueError):
+    """One or more things are claimed by another user."""
+
+    def __init__(self, blockers: Sequence[Claim], now: datetime) -> None:
+        self.blockers = list(blockers)
+        self.sentences = [sentence(c.thing, c, now) for c in blockers]
+        super().__init__("; ".join(self.sentences))
+
+
+def remaining(expires_at: str, now: datetime) -> str:
+    """``never`` or the time left as ``2d 3h`` / ``1h 12m`` / ``4m``, to
+    the two largest units. Rounds up to the minute, so a claim made for
+    ``2h`` reads ``2h`` rather than ``1h 59m`` a second later."""
+    if not expires_at:
+        return "never"
+    secs = max(0, int((parse_ts(expires_at) - now).total_seconds()))
+    days, rest = divmod(-(-secs // 60), 1440)
+    hours, minutes = divmod(rest, 60)
+    parts = [f"{n}{u}" for n, u in ((days, "d"), (hours, "h"), (minutes, "m")) if n]
+    return " ".join(parts[:2]) or "<1m"
+
+
+def sentence(name: str, claim: Claim | None, now: datetime) -> str:
+    if claim is None or not claim.is_live(now):
+        return f"'{name}' is free"
+    who = f"'{claim.holder}'"
+    if claim.assisted_by:
+        who += f" assisted by '{claim.assisted_by}'"
+    return (
+        f"{who} has claimed '{name}' for '{claim.purpose}' "
+        f"expires in: '{remaining(claim.expires_at, now)}'"
+    )
+
+
+class Store:
+    def __init__(self, db_path: Path) -> None:
+        self.db_path = Path(db_path)
+        with self._conn() as conn:
+            conn.executescript(_SCHEMA)
+
+    @contextlib.contextmanager
+    def _conn(self) -> Generator[sqlite3.Connection]:
+        conn = sqlite3.connect(str(self.db_path))
+        conn.execute("PRAGMA busy_timeout = 5000")
+        conn.row_factory = sqlite3.Row
+        try:
+            yield conn
+            conn.commit()
+        finally:
+            conn.close()
+
+    # ---- things -----------------------------------------------------
+
+    def replace_things(self, things: Sequence[Thing]) -> None:
+        """Make ``things`` the whole list, in one transaction."""
+        with _WRITE_LOCK, self._conn() as conn:
+            conn.execute("DELETE FROM things")
+            conn.executemany(
+                "INSERT INTO things (name, kind, source, attrs, synced_at) VALUES (?, ?, ?, ?, ?)",
+                [(t.name, t.kind, t.source, json.dumps(t.attrs), t.synced_at) for t in things],
+            )
+
+    def list_things(self) -> builtins.list[Thing]:
+        with self._conn() as conn:
+            rows = conn.execute("SELECT * FROM things ORDER BY name").fetchall()
+        return [_thing(r) for r in rows]
+
+    def get_thing(self, name: str) -> Thing | None:
+        with self._conn() as conn:
+            row = conn.execute(
+                "SELECT * FROM things WHERE name = ?", ((name or "").strip().lower(),)
+            ).fetchone()
+        return _thing(row) if row else None
+
+    def thing_by_mac(self, macs: Sequence[str]) -> Thing | None:
+        wanted = {m.strip().lower() for m in macs if m.strip()}
+        for thing in self.list_things():
+            if str(thing.attrs.get("mac", "")).lower() in wanted:
+                return thing
+        return None
+
+    # ---- claims -----------------------------------------------------
+
+    def get_claim(self, name: str) -> Claim | None:
+        with self._conn() as conn:
+            row = conn.execute("SELECT * FROM claims WHERE thing = ?", (name,)).fetchone()
+        return Claim(**dict(row)) if row else None
+
+    def list_claims(self) -> dict[str, Claim]:
+        with self._conn() as conn:
+            rows = conn.execute("SELECT * FROM claims").fetchall()
+        return {r["thing"]: Claim(**dict(r)) for r in rows}
+
+    def claim(
+        self,
+        names: Sequence[str],
+        *,
+        holder: str,
+        purpose: str,
+        assisted_by: str = "",
+        expires_in: int | None = None,
+        force: bool = False,
+        now: datetime | None = None,
+    ) -> builtins.list[tuple[Claim | None, Claim]]:
+        """Claim every thing in ``names`` for ``holder``, or none of them:
+        if any holds a live claim by another user (and ``force`` is off)
+        this raises :class:`ClaimConflict` and changes nothing.
+        Ownership is the user's: claiming again as the same holder, with
+        or without an agent, updates the purpose, expiry and
+        ``assisted_by`` and keeps ``claimed_at``. ``expires_in`` is
+        seconds from now; ``None`` never expires. Returns ``(before,
+        after)`` pairs so the caller can log what a ``force`` took over.
+        Callers check that the things exist."""
+        purpose = validate_purpose(purpose)
+        assisted_by = validate_assisted_by(assisted_by)
+        if expires_in is not None and expires_in <= 0:
+            raise ValueError("expires_in must be a positive number of seconds")
+        at = now or datetime.now(UTC)
+        expires_at = ts(at + timedelta(seconds=expires_in)) if expires_in is not None else ""
+        unique = list(dict.fromkeys(names))
+        with _WRITE_LOCK, self._conn() as conn:
+            before = {n: self._claim_row(conn, n) for n in unique}
+            live = {n: c for n, c in before.items() if c is not None and c.is_live(at)}
+            blockers = [c for c in live.values() if c.holder != holder]
+            if blockers and not force:
+                raise ClaimConflict(blockers, at)
+            out: builtins.list[tuple[Claim | None, Claim]] = []
+            for n in unique:
+                prior = live.get(n)
+                since = prior.claimed_at if prior and prior.holder == holder else ts(at)
+                after = Claim(n, holder, purpose, since, assisted_by, expires_at)
+                conn.execute(
+                    "INSERT OR REPLACE INTO claims "
+                    "(thing, holder, assisted_by, purpose, claimed_at, expires_at) "
+                    "VALUES (?, ?, ?, ?, ?, ?)",
+                    (n, holder, assisted_by, purpose, since, expires_at),
+                )
+                out.append((prior, after))
+        return out
+
+    def release(
+        self,
+        names: Sequence[str],
+        *,
+        holder: str,
+        force: bool = False,
+        now: datetime | None = None,
+    ) -> builtins.list[Claim]:
+        """Release the claims on ``names``, all or nothing like
+        :meth:`claim`: releasing another user's live claim needs
+        ``force``. Expired claims are cleared whoever holds them. Returns
+        the live claims released."""
+        at = now or datetime.now(UTC)
+        unique = list(dict.fromkeys(names))
+        with _WRITE_LOCK, self._conn() as conn:
+            before = [c for c in (self._claim_row(conn, n) for n in unique) if c is not None]
+            blockers = [c for c in before if c.is_live(at) and c.holder != holder]
+            if blockers and not force:
+                raise ClaimConflict(blockers, at)
+            conn.executemany("DELETE FROM claims WHERE thing = ?", [(c.thing,) for c in before])
+        return [c for c in before if c.is_live(at)]
+
+    def claimed_by(
+        self, holder: str, assisted_by: str = "", *, now: datetime | None = None
+    ) -> builtins.list[Claim]:
+        """Live claims held by ``holder`` through exactly ``assisted_by``
+        (blank: claimed by hand), so an agent's ``release --mine`` leaves
+        its human's own claims alone."""
+        at = now or datetime.now(UTC)
+        with self._conn() as conn:
+            rows = conn.execute(
+                "SELECT * FROM claims WHERE holder = ? AND assisted_by = ? ORDER BY thing",
+                (holder, assisted_by.strip()),
+            ).fetchall()
+        return [c for c in (Claim(**dict(r)) for r in rows) if c.is_live(at)]
+
+    @staticmethod
+    def _claim_row(conn: sqlite3.Connection, name: str) -> Claim | None:
+        row = conn.execute("SELECT * FROM claims WHERE thing = ?", (name,)).fetchone()
+        return Claim(**dict(row)) if row else None
+
+
+def _thing(r: sqlite3.Row) -> Thing:
+    try:
+        attrs = json.loads(r["attrs"] or "{}")
+    except ValueError:
+        attrs = {}
+    return Thing(r["name"], r["kind"], r["source"], attrs, r["synced_at"])