mayhem-cli 0.5.1__py3-none-any.whl

mayhem/topology/providers/compose.py

@@ -0,0 +1,207 @@
+"""ComposeFileProvider — docker-compose.yaml as first-class blueprint (ADR-0006).
+
+Extracts services, images, networks, ports, healthcheck-gated ``depends_on``
+(weight ≥ 2), and heuristically infers external dependencies from service env
+vars. Inferred nodes are flagged and never targetable until allowlisted
+([ADR-0012]).
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from mayhem.domain.topology import (
+    Edge,
+    EdgeKind,
+    ExternalDependencyNode,
+    NodeKind,
+    PortBinding,
+    ServiceNode,
+)
+from mayhem.topology.providers.base import PartialGraph
+
+_URL_KEYS = re.compile(r"(DATABASE_URL|REDIS_URL|.*_URL|.*_ENDPOINT)$")
+_URL_RE = re.compile(r"^[a-z][a-z0-9+.-]*://([^/@]+@)?(?P<host>[^/:?#]+)")
+
+
+def _interpolate(value: str, env: dict[str, str]) -> str:
+    """Minimal ${VAR} / ${VAR:-default} interpolation from .env."""
+
+    def sub(match: re.Match[str]) -> str:
+        expr = match.group(1)
+        name, sep, default = expr.partition(":-")
+        return env.get(name.strip(), default if sep else "")
+
+    return re.sub(r"\$\{([^}]+)\}", sub, value)
+
+
+def _load_env_file(path: Path) -> dict[str, str]:
+    env: dict[str, str] = {}
+    if not path.exists():
+        return env
+    for raw_line in path.read_text().splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        env[key.strip()] = value.strip().strip("'\"")
+    return env
+
+
+def _parse_ports(raw: Any) -> tuple[PortBinding, ...]:
+    """Parse Compose port mappings into PortBinding objects.
+
+    Compose ports are in the form ``host:container`` or ``host:container/protocol``.
+    If only one port is given, it is used as both host and container port.
+    """
+    bindings: list[PortBinding] = []
+    for item in raw or []:
+        text = str(item)
+        protocol = "tcp"
+        if "/" in text:
+            text, _, protocol = text.rpartition("/")
+        parts = text.split(":")
+        if len(parts) == 2:
+            host_port, container_port = int(parts[0]), int(parts[1])
+        elif len(parts) == 1:
+            host_port = container_port = int(parts[0])
+        else:
+            continue
+        bindings.append(
+            PortBinding(
+                host_port=host_port,
+                container_port=container_port,
+                protocol=protocol.strip(),
+            )
+        )
+    return tuple(bindings)
+
+
+def _depends_pairs(depends: Any) -> list[tuple[str, float]]:
+    """Normalize depends_on (dict with conditions, or plain list) to weighted pairs."""
+    pairs: list[tuple[str, float]] = []
+    if isinstance(depends, dict):
+        for dep_name, cfg in depends.items():
+            condition = (cfg or {}).get("condition", "service_started")
+            weight = 2.0 if condition == "service_healthy" else 1.0
+            pairs.append((dep_name, weight))
+    elif isinstance(depends, list):
+        pairs.extend((dep_name, 1.0) for dep_name in depends)
+    return pairs
+
+
+def _env_dict(environment: Any) -> dict[str, str]:
+    """Compose allows environment as a mapping or a list of KEY=VALUE strings."""
+    if isinstance(environment, list):
+        return {
+            entry.split("=", 1)[0]: entry.split("=", 1)[1] for entry in environment if "=" in entry
+        }
+    return {str(k): str(v) for k, v in (environment or {}).items()}
+
+
+class ComposeFileProvider:
+    id = "compose"
+
+    def __init__(self, compose_path: str | Path) -> None:
+        self._path = Path(compose_path)
+
+    def is_available(self) -> bool:
+        return self._path.exists()
+
+    @property
+    def project_name(self) -> str:
+        """Compose project name — explicit ``name:`` field or directory name.
+
+        Normalized to lowercase because Docker and Podman always lowercase
+        the ``com.docker.compose.project`` label.
+        """
+        document: dict[str, Any] = yaml.safe_load(self._path.read_text()) or {}
+        return str(document.get("name") or self._path.resolve().parent.name).lower()
+
+    @property
+    def service_names(self) -> tuple[str, ...]:
+        """Ordered service names declared in the compose file."""
+        document: dict[str, Any] = yaml.safe_load(self._path.read_text()) or {}
+        return tuple((document.get("services") or {}).keys())
+
+    def discover(self) -> PartialGraph:
+        document: dict[str, Any] = yaml.safe_load(self._path.read_text()) or {}
+        services: dict[str, Any] = document.get("services") or {}
+        env = _load_env_file(self._path.parent / ".env")
+
+        nodes: list[Any] = []
+        edges: list[Edge] = []
+        notes: list[str] = []
+
+        for name, svc in services.items():
+            image = svc.get("image")
+            # Explicit container identity — prefer the standard ``container_name:``
+            # field, falling back to the newer per-service ``name:`` alias.
+            container_name = svc.get("container_name") or svc.get("name")
+            nodes.append(
+                ServiceNode(
+                    id=f"svc-{name}",
+                    name=name,
+                    image=image,
+                    exposed_ports=_parse_ports(svc.get("ports")),
+                    container_name=container_name,
+                )
+            )
+
+            pairs = _depends_pairs(svc.get("depends_on"))
+            for dep_name, weight in pairs:
+                edges.append(
+                    Edge(
+                        src=f"svc-{name}",
+                        dst=f"svc-{dep_name}",
+                        kind=EdgeKind.DEPENDS_ON,
+                        weight=weight,
+                    )
+                )
+
+            environment = _env_dict(svc.get("environment"))
+            for key, raw_value in environment.items():
+                value = _interpolate(str(raw_value), env)
+                if not _URL_KEYS.match(key):
+                    continue
+                match = _URL_RE.match(value)
+                if match is None:
+                    continue
+                host = match.group("host")
+                node_id = f"ext-{host}"
+                if any(getattr(n, "id", None) == node_id for n in nodes):
+                    continue
+                nodes.append(
+                    ExternalDependencyNode(
+                        id=node_id,
+                        name=host,
+                        endpoint=value.split("://", 1)[0] + "://" + host,
+                        inferred=True,
+                    )
+                )
+                notes.append(f"inferred external dependency {host!r} from {name}.{key}")
+
+        known_service_ids = {n.id for n in nodes}
+        kept: list[Edge] = []
+        dropped_dep: list[str] = []
+        for edge in edges:
+            if edge.kind is EdgeKind.DEPENDS_ON and edge.dst not in known_service_ids:
+                dropped_dep.append(edge.dst)
+                continue
+            kept.append(edge)
+        if dropped_dep:
+            notes.append(
+                "depends_on references unknown services (dropped): "
+                + ", ".join(sorted(set(dropped_dep)))
+            )
+
+        return PartialGraph(
+            source=self.id, nodes=tuple(nodes), edges=tuple(kept), notes=tuple(notes)
+        )
+
+
+__all__ = ["ComposeFileProvider", "NodeKind", "PortBinding"]

mayhem/topology/providers/docker_adapter.py

@@ -0,0 +1,277 @@
+"""DockerAdapter — concrete RuntimeAdapter for the Docker engine (ADR-M3-1).
+
+Extracted from ``ContainerRuntimeProvider`` in docker_runtime.py.  Module-level
+helpers are imported from that file; ``DockerAdapter`` wraps them behind the
+normalised ``RuntimeAdapter`` and ``TopologyProvider`` interfaces.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import Any
+
+from pydantic.networks import IPvAnyAddress
+
+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_name,
+    _inspect_pid,
+    _labels,
+    _networks,
+    _parse_ports,
+    _ps,
+)
+
+
+class DockerAdapter(RuntimeAdapter, TopologyProvider):
+    """RuntimeAdapter for the local Docker engine."""
+
+    ENGINE = "docker"
+
+    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
+
+    @classmethod
+    def best_effort(cls, engine: str | None = None) -> DockerAdapter | None:
+        """Return a DockerAdapter if the engine is available, else None.
+
+        Preserved for backward compat with callers that used
+        ``ContainerRuntimeProvider.best_effort()``.
+        """
+        target = engine or cls.ENGINE
+        adapter = cls(target)
+        return adapter if adapter.is_available() else None
+
+    # -- 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:
+        """Rootful Docker: all capabilities SUPPORTED."""
+        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]:
+        _inspect_name(self._engine, container_id)
+        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:
+        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]]:
+        """Apply compose / name filters to the raw ps rows."""
+        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"))
+
+        # Discover network info for IP addresses.
+        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))
+
+        # Resolve container short_id -> IP from network info.
+        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 = IPvAnyAddress(ip_str) if ip_str else None
+
+            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)
+                )
+
+        return PartialGraph(
+            source=self._engine,
+            nodes=tuple(nodes),
+            edges=tuple(edges),
+            notes=tuple(notes),
+        )