bootproof 0.2.0__py3-none-any.whl

bootproof/runners.py

@@ -0,0 +1,275 @@
+"""Boot runners: how a snapshot becomes a probeable target.
+
+Interface: ``boot(snapshot, timeout) -> Target``. The runner owns
+booting, readiness waiting, timeout, and teardown (``close()``).
+
+* QemuRunner — the real path. Builds a real qemu-system-x86_64
+  command (drive in snapshot mode so the guest never writes the
+  source image, user networking with one hostfwd per checklist
+  port, no display), starts it, waits for readiness, kills it on
+  timeout or teardown. On a host without QEMU/KVM this fails fast
+  with a specific BootError — it never silently falls back to
+  simulation. Probes run through a GuestTarget (forwarded ports,
+  SSH unit checks), never against the host's localhost by mistake.
+  Readiness is an SSH command success when credentials are given,
+  else a TCP connect to the forwarded SSH port; a host that
+  forwards different ports overrides ``ready_check``.
+* FixtureRunner — the simulated path. Returns a FixtureTarget from
+  fixture data, honouring a configured boot delay: if the delay
+  exceeds the timeout it raises BootTimeout, so timeout behaviour
+  is testable without a VM. Its boot_mode is always "simulated".
+
+A simulated boot is labelled simulated in every report. Nothing in
+this module lets a fixture result masquerade as a real boot.
+"""
+
+from __future__ import annotations
+
+import shutil
+import socket
+import subprocess
+import time
+from pathlib import Path
+
+from .errors import BootError, BootTimeout, SnapshotError
+from .probes import FixtureTarget, Target
+from .snapshots import Snapshot
+
+
+class BootRunner:
+    boot_mode: str = "unknown"
+
+    def boot(self, snapshot: Snapshot, timeout: float) -> Target:
+        raise NotImplementedError
+
+    def close(self) -> None:
+        pass
+
+
+def kvm_available() -> bool:
+    """True when the host offers KVM. Separated for testability —
+    tests monkeypatch this instead of faking /dev/kvm."""
+    return Path("/dev/kvm").exists()
+
+
+def disk_format_for(path: str) -> str:
+    """QEMU drive format from a disk-image suffix. Unknown suffixes
+    default to qcow2 (the common case); .img/.raw are raw images,
+    .vmdk is a VMware disk QEMU can read."""
+    suffix = Path(path).suffix.lower()
+    if suffix in (".img", ".raw"):
+        return "raw"
+    if suffix == ".vmdk":
+        return "vmdk"
+    return "qcow2"
+
+
+def free_port() -> int:
+    """An actually-free localhost port (bind port 0, read it back).
+    A small bind race remains, but it beats guessing a fixed port
+    that may already be taken — and a QEMU bind failure is still a
+    loud BootError, never a silent wrong target."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def guest_ports_for_checklist(checklist) -> list[int]:
+    """Guest ports a checklist needs forwarded: loopback port checks
+    plus loopback http URLs (explicit port, or 80/443 by scheme).
+    Non-loopback checks are NOT forwarded — GuestTarget errors them
+    instead of probing the host by mistake."""
+    import urllib.parse
+
+    from .probes import is_loopback
+
+    ports: list[int] = []
+    for check in checklist.checks:
+        if check.type == "port" and is_loopback(check.host):
+            if check.port not in ports:
+                ports.append(check.port)
+        elif check.type == "http":
+            parsed = urllib.parse.urlparse(check.url or "")
+            if parsed.scheme == "http" and is_loopback(parsed.hostname or ""):
+                port = parsed.port or 80
+                if port not in ports:
+                    ports.append(port)
+    return ports
+
+
+def build_qemu_command(snapshot: Snapshot, memory_mb: int = 1024,
+                       cpus: int = 1, ssh_host_port: int = 2222,
+                       qemu_binary: str = "qemu-system-x86_64",
+                       extra_args: list[str] | None = None,
+                       forward_ports: dict[int, int] | None = None,
+                       disk_format: str | None = None) -> list[str]:
+    """Build the QEMU command for a snapshot. Pure function, fully
+    unit-testable without QEMU installed. Raises SnapshotError when
+    the snapshot carries no disk path, BootError when the binary is
+    missing. ``forward_ports`` maps guest port -> host port and
+    becomes one hostfwd entry each, so checklist ports actually
+    reach the guest instead of hitting the host's localhost.
+    ``-machine accel=kvm`` is added only when /dev/kvm exists;
+    without KVM, QEMU falls back to TCG (slow, but functional)."""
+    if shutil.which(qemu_binary) is None:
+        raise BootError(f"QEMU binary not found: {qemu_binary} — "
+                        f"install qemu-system and enable KVM "
+                        f"(/dev/kvm) to run a real boot")
+    if snapshot.path is None:
+        raise SnapshotError(f"snapshot {snapshot.id} has no disk path — "
+                            f"QEMU boot needs a qcow2/img file "
+                            f"(directory snapshot source provides one)")
+    fmt = disk_format or disk_format_for(snapshot.path)
+    netdev = (f"user,id=net0,hostfwd=tcp::{ssh_host_port}-:22")
+    for guest_port, host_port in sorted((forward_ports or {}).items()):
+        netdev += f",hostfwd=tcp::{host_port}-:{guest_port}"
+    cmd = [qemu_binary,
+           "-m", str(memory_mb),
+           "-smp", str(cpus),
+           "-drive", f"file={snapshot.path},format={fmt},if=virtio,"
+                     f"snapshot=on",
+           "-netdev", netdev,
+           "-device", "virtio-net-pci,netdev=net0",
+           "-display", "none",
+           "-serial", "none",
+           "-monitor", "none"]
+    if kvm_available():
+        cmd += ["-machine", "accel=kvm"]
+    if extra_args:
+        cmd += extra_args
+    return cmd
+
+
+class QemuRunner(BootRunner):
+    """Real QEMU/KVM boot. Not runnable in this sandbox (no QEMU,
+    no /dev/kvm) — but the code is real: command construction,
+    process lifecycle, readiness loop, timeout kill, and teardown.
+    The returned target is a GuestTarget: checklist ports are
+    forwarded to host ports and remapped, so probes hit the GUEST,
+    never the host's localhost by mistake. Unit checks run over SSH
+    when credentials are given, and ERROR without them — host units
+    are never substituted for guest units. ``ready_check`` defaults
+    to an SSH ``true`` when credentials are configured (proves sshd
+    answers, not just that the port listens), else a TCP connect to
+    the forwarded SSH port; pass a custom callable for guests that
+    expose a different readiness signal."""
+
+    boot_mode = "qemu"
+
+    def __init__(self, memory_mb: int = 1024, cpus: int = 1,
+                 ssh_host_port: int = 2222,
+                 qemu_binary: str = "qemu-system-x86_64",
+                 ready_check=None, extra_args=None,
+                 checklist=None, ssh_user: str | None = None,
+                 ssh_key: str | None = None):
+        self.memory_mb = memory_mb
+        self.cpus = cpus
+        self.ssh_host_port = ssh_host_port
+        self.qemu_binary = qemu_binary
+        self.ready_check = ready_check
+        self.extra_args = extra_args
+        self.checklist = checklist
+        self.ssh_user = ssh_user
+        self.ssh_key = ssh_key
+        self._proc: subprocess.Popen | None = None
+        self.port_map: dict[int, int] = {}
+
+    def _ssh_ready(self) -> bool:
+        from .probes import ssh_systemctl_is_active
+
+        try:
+            outcome = ssh_systemctl_is_active(
+                self.ssh_user, self.ssh_key, self.ssh_host_port,
+                "__bootproof_ready__", 5)
+        except Exception:
+            return False
+        # Any answered systemctl call proves sshd works, even a
+        # "failed" answer for the nonsense unit name.
+        return outcome.status in ("pass", "fail")
+
+    def _wait_ready(self, timeout: float) -> None:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if self._proc is not None and self._proc.poll() is not None:
+                raise BootError(f"QEMU exited during boot (exit code "
+                                f"{self._proc.returncode}) — guest "
+                                f"failed to start")
+            try:
+                if self.ready_check is not None:
+                    if self.ready_check():
+                        return
+                elif self.ssh_user and self.ssh_key:
+                    if self._ssh_ready():
+                        return
+                else:
+                    with socket.create_connection(
+                            ("127.0.0.1", self.ssh_host_port),
+                            timeout=2):
+                        return
+            except OSError:
+                pass
+            time.sleep(2)
+        raise BootTimeout(f"guest did not become reachable within "
+                          f"{timeout}s — boot timed out")
+
+    def boot(self, snapshot: Snapshot, timeout: float) -> Target:
+        from .probes import GuestTarget
+
+        if self.checklist is not None:
+            for guest_port in guest_ports_for_checklist(self.checklist):
+                host_port = free_port()
+                while host_port == self.ssh_host_port \
+                        or host_port in self.port_map.values():
+                    host_port = free_port()
+                self.port_map[guest_port] = host_port
+        cmd = build_qemu_command(snapshot, self.memory_mb, self.cpus,
+                                 self.ssh_host_port, self.qemu_binary,
+                                 self.extra_args,
+                                 forward_ports=self.port_map)
+        try:
+            self._proc = subprocess.Popen(
+                cmd, stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL)
+        except OSError as e:
+            raise BootError(f"failed to start QEMU: {e}")
+        try:
+            self._wait_ready(timeout)
+        except Exception:
+            self.close()
+            raise
+        return GuestTarget(self.port_map, self.ssh_user, self.ssh_key,
+                           self.ssh_host_port)
+
+    def close(self) -> None:
+        if self._proc is not None and self._proc.poll() is None:
+            self._proc.terminate()
+            try:
+                self._proc.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                self._proc.kill()
+                self._proc.wait(timeout=10)
+        self._proc = None
+
+
+class FixtureRunner(BootRunner):
+    """Simulated boot from fixture data. ``boot_delay`` simulates a
+    slow guest; a delay past the timeout raises BootTimeout, exactly
+    like the real runner. boot_mode is always 'simulated'."""
+
+    boot_mode = "simulated"
+
+    def __init__(self, fixture_data: dict | None = None,
+                 boot_delay: float = 0.0, sleep: bool = True):
+        self.fixture_data = fixture_data or {}
+        self.boot_delay = boot_delay
+        self._sleep = sleep
+
+    def boot(self, snapshot: Snapshot, timeout: float) -> Target:
+        if self.boot_delay > timeout:
+            raise BootTimeout(f"simulated guest did not become ready "
+                              f"within {timeout}s (configured boot "
+                              f"delay {self.boot_delay}s) — boot "
+                              f"timed out")
+        if self._sleep and self.boot_delay > 0:
+            time.sleep(min(self.boot_delay, 5))
+        return FixtureTarget(self.fixture_data)

bootproof/snapshots.py

@@ -0,0 +1,129 @@
+"""Snapshot inventory: list/identify available snapshots.
+
+A snapshot source is an abstraction — v1 ships two:
+* FixtureSnapshotSource — reads a JSON file (or in-memory list) of
+  snapshots. This is what the sandbox uses.
+* DirectorySnapshotSource — scans a directory for disk images
+  (*.qcow2, *.img, *.raw). On a real host this is the on-disk
+  inventory a QEMU boot draws from; each entry carries its path.
+
+Future sources (restic/borg/Proxmox APIs) implement the same
+SnapshotSource interface; they are not built in v1.
+
+Selecting: ``select(snapshots, snapshot_id)`` returns the exact
+match, auto-selects when there is exactly one snapshot and no id
+was given, and raises SnapshotNotFound / AmbiguousSnapshot
+otherwise. A missing snapshot is exit 2, never a silent default.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import AmbiguousSnapshot, SnapshotError, SnapshotNotFound
+
+IMAGE_SUFFIXES = (".qcow2", ".img", ".raw", ".qcow")
+
+
+@dataclass
+class Snapshot:
+    id: str
+    name: str
+    source: str
+    path: str | None = None
+    created: str | None = None
+
+    def to_dict(self) -> dict:
+        d = {"id": self.id, "name": self.name, "source": self.source}
+        if self.path is not None:
+            d["path"] = self.path
+        if self.created is not None:
+            d["created"] = self.created
+        return d
+
+
+class SnapshotSource:
+    kind: str = "source"
+
+    def list_snapshots(self) -> list[Snapshot]:
+        raise NotImplementedError
+
+
+class FixtureSnapshotSource(SnapshotSource):
+    kind = "fixture"
+
+    def __init__(self, snapshots: list[dict] | None = None,
+                 path: str | Path | None = None):
+        if path is not None:
+            p = Path(path)
+            if not p.exists():
+                raise SnapshotError(f"snapshots file not found: {p}")
+            try:
+                raw = json.loads(p.read_text(encoding="utf-8"))
+            except json.JSONDecodeError as e:
+                raise SnapshotError(f"snapshots file {p} is not valid "
+                                    f"JSON: {e}")
+            if isinstance(raw, dict):
+                snapshots = raw.get("snapshots")
+            else:
+                snapshots = raw
+            if not isinstance(snapshots, list):
+                raise SnapshotError(f"snapshots file {p} must hold a "
+                                    f"list or a 'snapshots' list")
+        self._snapshots = [self._coerce(s) for s in (snapshots or [])]
+
+    @staticmethod
+    def _coerce(item: dict) -> Snapshot:
+        if not isinstance(item, dict) or "id" not in item:
+            raise SnapshotError(f"invalid snapshot entry (needs 'id'): "
+                                f"{item!r}")
+        return Snapshot(id=str(item["id"]),
+                        name=str(item.get("name", item["id"])),
+                        source=str(item.get("source", "fixture")),
+                        path=item.get("path"),
+                        created=item.get("created"))
+
+    def list_snapshots(self) -> list[Snapshot]:
+        return list(self._snapshots)
+
+
+class DirectorySnapshotSource(SnapshotSource):
+    kind = "directory"
+
+    def __init__(self, directory: str | Path):
+        self.directory = Path(directory)
+        if not self.directory.is_dir():
+            raise SnapshotError(f"snapshot directory not found: "
+                                f"{self.directory}")
+
+    def list_snapshots(self) -> list[Snapshot]:
+        found = []
+        for p in sorted(self.directory.iterdir()):
+            if p.is_file() and p.suffix.lower() in IMAGE_SUFFIXES:
+                found.append(Snapshot(id=p.stem, name=p.name,
+                                      source="directory",
+                                      path=str(p)))
+        return found
+
+
+def select(snapshots: list[Snapshot],
+           snapshot_id: str | None) -> Snapshot:
+    """Exact id match, or the single snapshot when no id is given.
+    Missing id and ambiguous inventory are errors, not guesses."""
+    if snapshot_id is not None:
+        for snap in snapshots:
+            if snap.id == snapshot_id:
+                return snap
+        available = ", ".join(s.id for s in snapshots) or "(none)"
+        raise SnapshotNotFound(f"snapshot not found: {snapshot_id} "
+                               f"(available: {available})")
+    if len(snapshots) == 1:
+        return snapshots[0]
+    if not snapshots:
+        raise SnapshotNotFound("no snapshots available in this source")
+    available = ", ".join(s.id for s in snapshots)
+    raise AmbiguousSnapshot(f"no --snapshot given and {len(snapshots)} "
+                            f"snapshots available ({available}) — "
+                            f"pass --snapshot <id>")

bootproof/verdict.py

@@ -0,0 +1,108 @@
+"""Verdict engine: one GO / NO-GO from a checklist and a target.
+
+Rules, stated plainly:
+* GO only if every check passes. One fail, one error — no GO.
+* A fail means the service was observed down (port closed, unit
+  failed, endpoint 500). Verdict NO-GO, exit 1.
+* An error means the check could not be determined (probe blew up,
+  target not booted). Verdict ERROR, exit 2 — the run proves
+  nothing, and it must not be mistaken for a clean NO-GO either.
+* Failing checks are named exactly: which port, which unit, which
+  endpoint, and what was observed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .checklist import Check, Checklist
+from .errors import ProbeError
+from .probes import ProbeOutcome, Target
+
+GO = "GO"
+NO_GO = "NO-GO"
+ERROR = "ERROR"
+
+EXIT_GO = 0
+EXIT_NO_GO = 1
+EXIT_ERROR = 2
+
+
+@dataclass
+class CheckResult:
+    check: Check
+    status: str  # "pass" | "fail" | "error"
+    observed: str
+    seconds: float = 0.0
+
+    def to_dict(self) -> dict:
+        return {"check": self.check.describe(),
+                "type": self.check.type,
+                "status": self.status,
+                "observed": self.observed,
+                "seconds": round(self.seconds, 3)}
+
+
+@dataclass
+class Verdict:
+    verdict: str
+    results: list[CheckResult]
+
+    @property
+    def passed(self) -> list[CheckResult]:
+        return [r for r in self.results if r.status == "pass"]
+
+    @property
+    def failed(self) -> list[CheckResult]:
+        return [r for r in self.results if r.status == "fail"]
+
+    @property
+    def errored(self) -> list[CheckResult]:
+        return [r for r in self.results if r.status == "error"]
+
+    @property
+    def exit_code(self) -> int:
+        if self.verdict == GO:
+            return EXIT_GO
+        if self.verdict == NO_GO:
+            return EXIT_NO_GO
+        return EXIT_ERROR
+
+    def to_dict(self) -> dict:
+        return {"verdict": self.verdict,
+                "passed": len(self.passed),
+                "failed": len(self.failed),
+                "errored": len(self.errored),
+                "total": len(self.results),
+                "checks": [r.to_dict() for r in self.results]}
+
+
+def evaluate(checklist: Checklist, target: Target) -> Verdict:
+    """Evaluate every check against the target. A probe raising
+    ProbeError becomes an error result, never a pass. Any other
+    exception also becomes an error result — a crashing probe must
+    not take down the verdict, and must not pass either. An empty
+    checklist is an ERROR verdict here too (defense in depth: the
+    loader already rejects empty checklists, but a verdict over
+    zero checks must never be a vacuous GO through any path)."""
+    if not checklist.checks:
+        return Verdict(verdict=ERROR, results=[])
+    results: list[CheckResult] = []
+    for check in checklist.checks:
+        try:
+            outcome: ProbeOutcome = target.probe(check)
+        except ProbeError as e:
+            outcome = ProbeOutcome("error", str(e))
+        except Exception as e:  # noqa: BLE001 — probe crash = error
+            outcome = ProbeOutcome("error",
+                                   f"probe failed: {e.__class__.__name__}: {e}")
+        results.append(CheckResult(check=check, status=outcome.status,
+                                   observed=outcome.observed,
+                                   seconds=outcome.seconds))
+    if any(r.status == "error" for r in results):
+        verdict = ERROR
+    elif any(r.status == "fail" for r in results):
+        verdict = NO_GO
+    else:
+        verdict = GO
+    return Verdict(verdict=verdict, results=results)