mayhem-cli 0.5.1__py3-none-any.whl

mayhem/topology/providers/podman_adapter.py

@@ -0,0 +1,328 @@
+"""PodmanAdapter — concrete RuntimeAdapter for the Podman engine (ADR-M3-1, ADR-M3-4).
+
+Handles rootful and rootless Podman.  Rootless mode downgrades NETNS to
+ALTERNATIVE and RESOURCE_LIMITS to UNSUPPORTED.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from typing import Any
+
+from mayhem.domain.identity import RuntimeIdentity, RuntimeMetadata
+from mayhem.domain.runtime_adapter import (
+    AdapterCapabilities,
+    RuntimeAdapter,
+    RuntimeCapability,
+)
+from mayhem.topology.providers.base import PartialGraph, TopologyProvider
+
+# Module-level helpers from the original provider — unchanged.
+from mayhem.topology.providers.docker_runtime import (
+    _container_id,
+    _container_name,
+    _inspect_meta,
+    _inspect_pid,
+    _labels,
+    _networks,
+    _parse_ports,
+    _ps,
+)
+
+
+def _detect_rootless(engine: str = "podman") -> bool:
+    """Detect whether Podman is running rootless via ``podman info``."""
+    try:
+        out = subprocess.run(
+            [engine, "info", "--format", "json"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        data = json.loads(out.stdout.strip())
+        host = data.get("host") or {}
+        security = host.get("security") or {}
+        return bool(security.get("rootless", False))
+    except (subprocess.TimeoutExpired, OSError, json.JSONDecodeError, ValueError):
+        return False
+
+
+class PodmanAdapter(RuntimeAdapter, TopologyProvider):
+    """RuntimeAdapter for the local Podman engine.
+
+    Handles both rootful and rootless modes.  Rootless detection is performed
+    once at construction time and cached in the ``AdapterCapabilities``.
+    """
+
+    ENGINE = "podman"
+
+    def __init__(
+        self,
+        engine: str = ENGINE,
+        *,
+        filter_project: str | None = None,
+        filter_services: tuple[str, ...] | None = None,
+        filter_names: tuple[str, ...] | None = None,
+    ) -> None:
+        self._engine = engine
+        self._filter_project = filter_project
+        self._filter_services = filter_services
+        self._filter_names = filter_names
+        self._rootless = _detect_rootless(engine)
+
+    # -- identity ------------------------------------------------------------
+
+    @property
+    def id(self) -> str:
+        suffix = f"+{self._filter_project}" if self._filter_project else ""
+        return f"{self._engine}{suffix}"
+
+    def is_available(self) -> bool:
+        return shutil.which(self._engine) is not None
+
+    # -- capabilities --------------------------------------------------------
+
+    def capabilities(self) -> AdapterCapabilities:
+        if self._rootless:
+            # Rootless: NETNS=ALTERNATIVE, RESOURCE_LIMITS=UNSUPPORTED (ADR-M3-4)
+            return AdapterCapabilities(
+                engine=self._engine,
+                rootless=True,
+                supported=frozenset(
+                    {
+                        RuntimeCapability.EXEC,
+                        RuntimeCapability.PID,
+                        RuntimeCapability.SIGNAL,
+                        RuntimeCapability.INSPECT,
+                        RuntimeCapability.COMPOSE_FILTER,
+                    }
+                ),
+                alternatives=frozenset({RuntimeCapability.NETNS}),
+            )
+        # Rootful: all SUPPORTED (same as docker)
+        return AdapterCapabilities(
+            engine=self._engine,
+            rootless=False,
+            supported=frozenset(RuntimeCapability),
+            alternatives=frozenset(),
+        )
+
+    # -- container operations ------------------------------------------------
+
+    def ps(self) -> list[dict[str, Any]]:
+        return _ps(self._engine)
+
+    def inspect(self, container_id: str) -> tuple[RuntimeIdentity, RuntimeMetadata | None]:
+        container_name, created_at, started_at = _inspect_meta(self._engine, container_id)
+        metadata = RuntimeMetadata.from_inspect(
+            {
+                "created_at": created_at,
+                "started_at": started_at,
+            },
+            name=container_name,
+        )
+        identity = RuntimeIdentity(
+            runtime=self._engine,
+            host_id="host",
+            runtime_id=container_id,
+        )
+        return identity, metadata
+
+    def exec(self, container_id: str, cmd: list[str], *, timeout_s: float = 30) -> str:
+        out = subprocess.run(
+            [self._engine, "exec", container_id, *cmd],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=timeout_s,
+        )
+        return out.stdout
+
+    def pid(self, container_id: str) -> int | None:
+        return _inspect_pid(self._engine, container_id)
+
+    def signal(self, container_id: str, signo: int) -> None:
+        import signal as _signal
+
+        try:
+            sig = _signal.Signals(signo)
+            signame = sig.name
+        except (ValueError, AttributeError):
+            signame = "SIGKILL"
+        subprocess.run(
+            [self._engine, "kill", "-s", signame, container_id],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=10,
+        )
+
+    def netns(self, container_id: str) -> str | None:
+        """Return network-namespace path.
+
+        In rootless mode this may require ``podman unshare nsenter`` — the
+        caller receives ALTERNATIVE verdict and must degrade gracefully.
+        """
+        pid = _inspect_pid(self._engine, container_id)
+        if pid is None:
+            return None
+        return f"/proc/{pid}/ns/net"
+
+    # -- filtering -----------------------------------------------------------
+
+    def filter_by_compose(
+        self,
+        project: str,
+        services: tuple[str, ...] | None = None,
+    ) -> None:
+        self._filter_project = project
+        self._filter_services = services
+
+    def filter_by_names(self, names: list[str]) -> None:
+        self._filter_names = tuple(names)
+
+    # -- discovery (TopologyProvider) ----------------------------------------
+
+    def _filter_rows(
+        self,
+        rows: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        allowed_names: set[str] | None = (
+            {n.strip().lower() for n in self._filter_names} if self._filter_names else None
+        )
+        result: list[dict[str, Any]] = []
+        for row in rows:
+            labels = _labels(row)
+            if self._filter_project is not None:
+                project = labels.get("com.docker.compose.project", "")
+                if project != self._filter_project:
+                    continue
+            if self._filter_services is not None:
+                svc = labels.get("com.docker.compose.service", "")
+                if svc and svc not in self._filter_services:
+                    continue
+            if allowed_names is not None:
+                raw_name = _container_name(row)
+                container_names = [n.strip().lower() for n in raw_name.strip("[]").split(",")]
+                if not any(n in allowed_names for n in container_names):
+                    continue
+            result.append(row)
+        return result
+
+    def discover(self) -> PartialGraph:
+        from mayhem.domain.topology import (
+            ContainerNode,
+            Edge,
+            EdgeKind,
+            HostNode,
+        )
+
+        try:
+            rows = _ps(self._engine)
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            return PartialGraph(source=self._engine, notes=(str(exc),))
+
+        rows = self._filter_rows(rows)
+
+        nodes: list[Any] = []
+        edges: list[Any] = []
+        notes: list[str] = []
+
+        host_id = f"h-{self._engine}-local"
+        nodes.append(HostNode(id=host_id, name=self._engine, transport="local"))
+
+        all_networks: set[str] = set()
+        for row in rows:
+            nets = row.get("Networks") or []
+            if isinstance(nets, list):
+                all_networks.update(nets)
+        network_info = _networks(self._engine, sorted(all_networks))
+
+        container_ips: dict[str, str] = {}
+        for _net_name, net_data in network_info.items():
+            for cid_key, ip_val in net_data.items():
+                if cid_key != "subnet" and isinstance(ip_val, str) and "." in ip_val:
+                    container_ips[cid_key] = ip_val
+
+        for row in rows:
+            labels = _labels(row)
+            service_name = labels.get("com.docker.compose.service")
+            ports = _parse_ports(row)
+            container_id = _container_id(row)
+            short_id = container_id[:12]
+            ip_str = container_ips.get(short_id)
+            ip_addr = None
+            if ip_str:
+                from pydantic.networks import IPvAnyAddress
+
+                ip_addr = IPvAnyAddress(ip_str)
+
+            nets = row.get("Networks") or []
+            net_names = tuple(nets) if isinstance(nets, list) else ()
+
+            container_name, created_at, started_at = _inspect_meta(self._engine, container_id)
+            metadata = RuntimeMetadata.from_inspect(
+                {
+                    "labels": labels,
+                    "created_at": created_at,
+                    "started_at": started_at,
+                    "image": str(row.get("Image") or ""),
+                },
+                name=container_name,
+            )
+
+            node = ContainerNode(
+                id=f"ctr-{short_id}",
+                name=_container_name(row),
+                engine=self._engine,
+                runtime_identity=RuntimeIdentity(
+                    runtime=self._engine,
+                    host_id=host_id,
+                    runtime_id=container_id,
+                ),
+                runtime_metadata=metadata,
+                state=str(row.get("State") or row.get("Status") or "unknown"),
+                ports=ports,
+                container_name=container_name,
+                ip_address=ip_addr,
+                image=str(row.get("Image") or ""),
+                networks=net_names,
+            )
+            nodes.append(node)
+            edges.append(Edge(src=node.id, dst=host_id, kind=EdgeKind.RUNS_ON))
+
+            if service_name:
+                edges.append(
+                    Edge(src=node.id, dst=f"svc-{service_name}", kind=EdgeKind.CONTAINED_IN)
+                )
+
+            # Emit a ProcessNode for the container's main PID so process-addressed
+            # faults (proc.pause / process.stop / process.kill) resolve a real PID
+            # carried with the container's runtime address — the same contract as
+            # the docker provider (ADR-0020 / ADR-M1-1).
+            from mayhem.domain.topology import ProcessNode  # noqa: PLC0415
+
+            process_name = service_name or _container_name(row)
+            pid = _inspect_pid(self._engine, container_id)
+            if pid is not None and process_name:
+                proc_id = f"proc-{process_name}-{short_id}"
+                proc_node = ProcessNode(
+                    id=proc_id,
+                    name=process_name,
+                    pid=pid,
+                    host_id=host_id,
+                    cmdline=f"{self._engine} container {short_id}",
+                    container_id=short_id,
+                    container_name=container_name,
+                )
+                nodes.append(proc_node)
+                edges.append(Edge(src=proc_id, dst=node.id, kind=EdgeKind.RUNS_ON))
+
+        return PartialGraph(
+            source=self._engine,
+            nodes=tuple(nodes),
+            edges=tuple(edges),
+            notes=tuple(notes),
+        )

mayhem/topology/resolve.py

@@ -0,0 +1,196 @@
+"""Container resolution — get current PID and IP from container names.
+
+Resolution is invoked at execution time, not discovery time, so the PID is
+never older than the injection syscall. A single ``inspect`` per container
+returns the current main PID, IP address, and state (ADR-0020).
+
+Import of this module is confined to ``topology`` per the import rule
+([ADR-0013]) — it shells out to the container engine binary.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from mayhem.domain.identity import ProcessRuntimeIdentity, RuntimeIdentity, RuntimeMetadata
+
+__all__ = [
+    "ContainerInfo",
+    "resolve_all",
+    "resolve_container",
+    "resolve_identity",
+    "resolve_ip",
+    "resolve_metadata",
+    "resolve_pid",
+    "resolve_process_identity",
+]
+
+
+@dataclass(frozen=True)
+class ContainerInfo:
+    pid: int
+    ip_address: str
+    state: str  # "running", "exited", etc.
+
+
+def _detect_engine() -> str:
+    """Return 'podman' or 'docker', preferring podman."""
+    for engine in ("podman", "docker"):
+        if shutil.which(engine):
+            return engine
+    raise RuntimeError("neither podman nor docker found in PATH")
+
+
+def _inspect(engine: str, container_name: str, fmt: str) -> str:
+    """Run ``engine inspect`` with a Go template format string."""
+    cmd = [engine, "inspect", "--format", fmt, container_name]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError(f"{engine} inspect timed out for {container_name}") from exc
+    if result.returncode != 0:
+        raise RuntimeError(f"{engine} inspect failed for {container_name}: {result.stderr.strip()}")
+    return result.stdout.strip()
+
+
+def _host_for_engine(engine: str) -> str:
+    """Local host identity for the active engine (ADR-M1-1)."""
+    return f"h-{engine}-local"
+
+
+def resolve_identity(container_name: str, engine: str | None = None) -> RuntimeIdentity:
+    """Resolve the live ``RuntimeIdentity`` for a named container.
+
+    The engine reports the container's full id via ``inspect .Id``; combined with
+    the engine label and the local host identity this IS the equality key
+    (ADR-M1-1). Raises :class:`RuntimeError` if the container is gone.
+    """
+    engine = engine or _detect_engine()
+    runtime_id = _inspect(engine, container_name, "{{.Id}}")
+    if not runtime_id:
+        raise RuntimeError(f"container {container_name} has no runtime id")
+    return RuntimeIdentity(runtime=engine, host_id=_host_for_engine(engine), runtime_id=runtime_id)
+
+
+def resolve_metadata(container_name: str, engine: str | None = None) -> RuntimeMetadata:
+    """Resolve descriptive metadata for a named container (ADR-M1-2)."""
+    engine = engine or _detect_engine()
+    fmt = "{{json .Config.Labels}}|{{.Created}}|{{.State.StartedAt}}|{{.Image}}"
+    raw = _inspect(engine, container_name, fmt)
+    labels_part, _, rest = raw.partition("|")
+    created, _, rest2 = rest.partition("|")
+    started, _, image = rest2.partition("|")
+    try:
+        labels = json.loads(labels_part) if labels_part else {}
+    except json.JSONDecodeError:
+        labels = {}
+    return RuntimeMetadata.from_inspect(
+        {
+            "labels": labels if isinstance(labels, dict) else {},
+            "created_at": created or None,
+            "started_at": started or None,
+            "image": image or None,
+        },
+        name=container_name,
+    )
+
+
+def resolve_pid(container_name: str, engine: str | None = None) -> int:
+    """Get the current host PID for a named container."""
+    engine = engine or _detect_engine()
+    out = _inspect(engine, container_name, "{{.State.Pid}}")
+    try:
+        pid = int(out)
+    except ValueError as exc:
+        raise RuntimeError(
+            f"{engine} inspect returned non-numeric pid {out!r} for {container_name}"
+        ) from exc
+    if pid <= 0:
+        raise RuntimeError(f"container {container_name} has no running process (pid={pid})")
+    return pid
+
+
+def resolve_process_identity(
+    pid: int,
+    host_id: str,
+    container_name: str | None = None,
+) -> ProcessRuntimeIdentity:
+    """Resolve the live process identity for a PID (ADR-M2 Phase 2.4).
+
+    The boot time (``/proc/<pid>/stat`` field 22 — start time in clock ticks
+    since boot) is read on Linux hosts to disambiguate PID recycling. On
+    platforms without a procfs the boot time is ``None`` and the identity
+    degrades to a pid-only key (the PID-reuse guard then cannot distinguish a
+    recycled PID, so container-addressed faults still carry their runtime id).
+    """
+    boot_time: int | None = None
+    if sys.platform.startswith("linux"):
+        stat_path = f"/proc/{pid}/stat"
+        try:
+            raw = Path(stat_path).read_text()
+            # field 22 is starttime; fields 3.. are comm (may contain spaces in
+            # parentheses), so split AFTER the closing ')' of the comm field.
+            rest = raw.split(")", maxsplit=1)[1]
+            fields = rest.split()
+            boot_time = int(fields[19]) if len(fields) > 19 else None
+        except (OSError, ValueError, IndexError):
+            boot_time = None
+    return ProcessRuntimeIdentity(
+        host_id=host_id,
+        pid=pid,
+        boot_time=boot_time,
+        container_name=container_name,
+    )
+
+
+def resolve_ip(container_name: str, engine: str | None = None) -> str:
+    """Get the current IP address for a named container."""
+    engine = engine or _detect_engine()
+    fmt_ip = "{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}"
+    return _inspect(engine, container_name, fmt_ip)
+
+
+def resolve_container(container_name: str, engine: str | None = None) -> ContainerInfo:
+    """Resolve PID, IP, and state for a named container in one inspect pass.
+
+    May raise :class:`RuntimeError` if the container is missing or stopped.
+    """
+    engine = engine or _detect_engine()
+    pid = resolve_pid(container_name, engine)
+    ip = resolve_ip(container_name, engine)
+    state = resolve_status(container_name, engine)
+    return ContainerInfo(pid=pid, ip_address=ip, state=state)
+
+
+def resolve_status(container_name: str, engine: str | None = None) -> str:
+    """Resolve the current ``State.Status`` for a named container.
+
+    Unlike :func:`resolve_container` this never inspects the host PID, so it
+    also succeeds on VM-contained engines (podman-machine on macOS, Docker
+    Desktop) where ``.State.Pid`` is ``0`` while the container is running.
+    Raises :class:`RuntimeError` only when the container itself is gone.
+    """
+    engine = engine or _detect_engine()
+    return _inspect(engine, container_name, "{{.State.Status}}")
+
+
+def resolve_all(
+    container_names: tuple[str, ...], engine: str | None = None
+) -> dict[str, ContainerInfo]:
+    """Resolve several containers by name, returning a name → info mapping.
+
+    Containers that fail to resolve are omitted; no exception is raised.
+    """
+    engine = engine or _detect_engine()
+    result: dict[str, ContainerInfo] = {}
+    for name in container_names:
+        try:
+            result[name] = resolve_container(name, engine)
+        except RuntimeError:
+            continue
+    return result

mayhem/topology/service.py

@@ -0,0 +1,158 @@
+"""TopologyService — merge provider fragments into one graph + drift report."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from mayhem.domain.topology import ContainerNode, Edge, NodeKind, TopologyGraph
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from mayhem.domain.topology import TopologyNode
+    from mayhem.topology.providers.base import PartialGraph, TopologyProvider
+
+
+@dataclass(frozen=True)
+class DiscoveryResult:
+    graph: TopologyGraph
+    drift_report: dict[str, object] = field(default_factory=dict)
+    partial: bool = False
+    errors: tuple[str, ...] = ()
+
+
+def _find_extra_containers(
+    all_live: list[ContainerNode],
+    services: Mapping[str, TopologyNode],
+) -> list[dict[str, str]]:
+    """Return live containers whose service isn't in the blueprint."""
+    extras: list[dict[str, str]] = []
+    for c in all_live:
+        svc = c.runtime_metadata.service if c.runtime_metadata else None
+        if svc and svc not in services:
+            extras.append({"name": c.name, "engine": c.engine, "image": str(c.image or "")})
+    return extras
+
+
+def _find_image_drift(
+    services: Mapping[str, TopologyNode],
+    live_by_service: Mapping[str, list[ContainerNode]],
+) -> list[dict[str, str]]:
+    """Return services whose running image differs from the blueprint."""
+    changed: list[dict[str, str]] = []
+    for name, svc in services.items():
+        expected = getattr(svc, "image", None)
+        if expected is None:
+            continue
+        for container in live_by_service.get(name, []):
+            actual = getattr(container, "image", None)
+            if actual and str(expected) != str(actual):
+                changed.append({"service": name, "expected": str(expected), "actual": str(actual)})
+    return changed
+
+
+class TopologyService:
+    """Blueprint (compose) ↔ live (runtime) merge; drift is recorded, never hidden."""
+
+    def discover(self, providers: list[TopologyProvider]) -> DiscoveryResult:
+        fragments = []
+        errors: list[str] = []
+        for provider in providers:
+            if not provider.is_available():
+                errors.append(f"{provider.id}: not available")
+                continue
+            try:
+                fragment = provider.discover()
+                fragments.append(fragment)
+            except Exception as exc:
+                errors.append(f"{provider.id}: discovery failed: {exc}")
+
+        blueprint = next((f for f in fragments if f.source == "compose"), None)
+        live = [f for f in fragments if f.source != "compose"]
+
+        nodes: dict[str, TopologyNode] = {}
+        edges: list[Edge] = []
+        for fragment in fragments:
+            for node in fragment.nodes:
+                nodes.setdefault(node.id, node)
+            edges.extend(fragment.edges)
+
+        drift: dict[str, object] = {}
+        if blueprint is not None:
+            drift = self._diff(blueprint, live)
+        notes = [n for f in fragments for n in f.notes]
+        if notes:
+            drift["notes"] = list(notes)
+
+        graph_nodes = tuple(nodes.values())
+        known_ids = set(nodes)
+        safe_edges = tuple(e for e in edges if e.src in known_ids and e.dst in known_ids)
+        graph = _graph(graph_nodes, safe_edges)
+
+        # Validate every ContainerNode has a container_name (ADR-0020).
+        for node in graph_nodes:
+            if isinstance(node, ContainerNode) and not node.container_name:
+                node_service = node.runtime_metadata.service if node.runtime_metadata else None
+                errors.append(
+                    f"container {node.id} (service={node_service or 'unknown'}) has no "
+                    "container_name — add 'name:' to docker-compose.yml"
+                )
+
+        return DiscoveryResult(
+            graph=graph,
+            drift_report=drift,
+            partial=bool(errors),
+            errors=tuple(errors),
+        )
+
+    @staticmethod
+    def _diff(
+        blueprint: PartialGraph,
+        live_fragments: list[PartialGraph],
+    ) -> dict[str, object]:
+        services = {n.name: n for n in blueprint.nodes if n.kind is NodeKind.SERVICE}
+        live_by_service: dict[str, list[ContainerNode]] = {}
+        all_live_containers: list[ContainerNode] = []
+        for fragment in live_fragments:
+            for node in fragment.nodes:
+                if isinstance(node, ContainerNode):
+                    all_live_containers.append(node)
+                    svc_name = node.runtime_metadata.service if node.runtime_metadata else None
+                    if svc_name:
+                        live_by_service.setdefault(svc_name, []).append(node)
+
+        # --- matched services ---
+        matched_services: list[str] = []
+        for name in sorted(set(services) & set(live_by_service)):
+            matched_services.append(name)
+
+        # --- missing services ---
+        missing_services = sorted(set(services) - set(live_by_service))
+
+        # --- extra containers (runtime containers with no matching service) ---
+        extra_containers = _find_extra_containers(all_live_containers, services)
+
+        # --- image drift ---
+        changed_images = _find_image_drift(services, live_by_service)
+
+        # --- state anomalies (stopped, paused, restarting) ---
+        unhealthy: list[dict[str, str]] = []
+        for name, containers in live_by_service.items():
+            for c in containers:
+                state = c.state.lower() if c.state else ""
+                if state not in ("running", "up", ""):
+                    unhealthy.append({"service": name, "name": c.name, "state": c.state})
+
+        report: dict[str, object] = {
+            "matched_services": matched_services,
+            "missing_services": missing_services,
+            "extra_containers": extra_containers,
+            "changed_images": changed_images,
+            "unhealthy": unhealthy,
+        }
+        return {k: v for k, v in report.items() if v}
+
+
+def _graph(nodes: tuple[TopologyNode, ...], edges: tuple[Edge, ...]) -> TopologyGraph:
+    return TopologyGraph(nodes=nodes, edges=edges)