mayhem-cli 0.5.1__py3-none-any.whl

mayhem/domain/faults.py

@@ -0,0 +1,239 @@
+"""Fault definitions and invocations (ADR-0004, fault-taxonomy contract).
+
+A ``FaultDefinition`` is exactly what safety/planning consumes; the coverage
+matrix in ``docs/fault-catalog/`` is generated from these definitions and only
+counts cells proven by tests.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from mayhem.domain.capabilities import Capability, Identifier
+from mayhem.domain.common import Duration
+from mayhem.domain.errors import SchemaValidationError
+from mayhem.domain.risks import EnvironmentClass, RiskLevel
+from mayhem.domain.topology import NodeKind
+
+
+class FaultCategory(StrEnum):
+    PROCESS = "process"
+    CPU = "cpu"
+    MEMORY = "memory"
+    STORAGE = "storage"
+    NETWORK = "network"
+    CONTAINER = "container"
+    NODE = "node"
+    HTTP_API = "http_api"
+    DATABASE = "database"
+    LOAD = "load"
+    FUZZ = "fuzz"
+    DNS = "dns"
+    TLS = "tls"
+    CLOCK = "clock"
+    FD = "fd"
+    DEPENDENCY = "dependency"
+    K8S = "k8s"  # ADR-M7-3: capacity / network / preemption sub-categories
+
+    @classmethod
+    def from_fault_id(cls, fault_id: str) -> FaultCategory:
+        prefix = fault_id.split(".", 1)[0]
+        category = _PREFIX_TO_CATEGORY.get(prefix)
+        if category is None:
+            raise SchemaValidationError(
+                "fault_id",
+                f"unknown category prefix {prefix!r} in {fault_id!r}; "
+                f"expected one of {sorted(_PREFIX_TO_CATEGORY)}",
+            )
+        return category
+
+
+_PREFIX_TO_CATEGORY: dict[str, FaultCategory] = {
+    "net": FaultCategory.NETWORK,
+    "cpu": FaultCategory.CPU,
+    "mem": FaultCategory.MEMORY,
+    "fs": FaultCategory.STORAGE,
+    "disk": FaultCategory.STORAGE,
+    "storage": FaultCategory.STORAGE,
+    "proc": FaultCategory.PROCESS,
+    "process": FaultCategory.PROCESS,
+    "container": FaultCategory.CONTAINER,
+    "node": FaultCategory.NODE,
+    "http": FaultCategory.HTTP_API,
+    "db": FaultCategory.DATABASE,
+    "load": FaultCategory.LOAD,
+    "fuzz": FaultCategory.FUZZ,
+    "dns": FaultCategory.DNS,
+    "tls": FaultCategory.TLS,
+    "clock": FaultCategory.CLOCK,
+    "fd": FaultCategory.FD,
+    "dependency": FaultCategory.DEPENDENCY,
+    "k8s": FaultCategory.K8S,
+}
+
+
+class ParamType(StrEnum):
+    STRING = "string"
+    INTEGER = "integer"
+    FLOAT = "float"
+    BOOLEAN = "boolean"
+    DURATION = "duration"
+    PERCENT = "percent"
+    BYTES = "bytes"
+
+
+class ParamSpec(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    name: Identifier
+    type: ParamType
+    required: bool = False
+    default: str | int | float | bool | None = None
+    minimum: float | None = None
+    maximum: float | None = None
+
+
+class FaultDefinition(BaseModel):
+    """Metadata contract for one fault (see docs/architecture/fault-taxonomy.md)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    category: FaultCategory
+    risk: RiskLevel
+    reversible: bool = True
+    required_caps: frozenset[Capability] = Field(default_factory=frozenset)
+    applicable_node_kinds: frozenset[NodeKind] = Field(default_factory=frozenset)
+    max_duration_s: float = 300.0
+    backends: tuple[Identifier, ...] = ()
+    safe_env_classes: frozenset[EnvironmentClass] = Field(
+        default_factory=lambda: frozenset(EnvironmentClass)
+    )
+    params_schema: tuple[ParamSpec, ...] = ()
+
+    @field_validator("id")
+    @classmethod
+    def _known_prefix(cls, value: str) -> str:
+        FaultCategory.from_fault_id(value)  # raises on unknown prefix
+        return value
+
+    @model_validator(mode="after")
+    def _category_matches_id(self) -> FaultDefinition:
+        expected = FaultCategory.from_fault_id(self.id)
+        if self.category is not expected:
+            raise SchemaValidationError(
+                "category",
+                f"fault {self.id!r} declares category {self.category.value!r} "
+                f"but prefix maps to {expected.value!r}",
+            )
+        return self
+
+    def validate_params(self, params: dict[str, object]) -> dict[str, object]:
+        """Validate raw params against ``params_schema``; returns normalized values.
+
+        Raises:
+            SchemaValidationError: On unknown, missing, or mistyped parameters.
+        """
+        known = {spec.name: spec for spec in self.params_schema}
+        normalized: dict[str, object] = {}
+        for name in params:
+            if name not in known:
+                raise SchemaValidationError(f"params[{self.id}]", f"unknown parameter {name!r}")
+        for spec in self.params_schema:
+            if spec.name not in params:
+                if spec.required and spec.default is None:
+                    raise SchemaValidationError(
+                        f"params[{self.id}]",
+                        f"missing required parameter {spec.name!r}",
+                    )
+                if spec.default is not None:
+                    normalized[spec.name] = spec.default
+                continue
+            normalized[spec.name] = _coerce(spec, params[spec.name])
+        return normalized
+
+
+class FaultInvocation(BaseModel):
+    """One concrete fault application against resolved targets."""
+
+    model_config = ConfigDict(frozen=True)
+
+    fault_id: str
+    targets: frozenset[str]  # resolved node ids; non-empty enforced below
+    params: dict[str, object] = Field(default_factory=dict)
+    duration: Duration
+    backend: Identifier | None = None  # None => executor picks via fallback group
+    lease_id: str | None = None  # set when recovery machinery takes ownership
+
+    @field_validator("targets")
+    @classmethod
+    def _at_least_one_target(cls, value: frozenset[str]) -> frozenset[str]:
+        if not value:
+            raise SchemaValidationError("targets", "fault invocation requires >= 1 target")
+        return value
+
+    @field_validator("fault_id")
+    @classmethod
+    def _valid_fault_id(cls, value: str) -> str:
+        FaultCategory.from_fault_id(value)
+        return value
+
+
+def _numeric(raw: object) -> float:
+    """Strict numeric coercion; bools are not numbers in fault params."""
+    if isinstance(raw, bool) or not isinstance(raw, (int, float, str)):
+        raise TypeError("expected a number")
+    return float(raw)
+
+
+def _convert(spec: ParamSpec, raw: object) -> object:
+    match spec.type:
+        case ParamType.STRING:
+            value: object = str(raw)
+        case ParamType.INTEGER:
+            number = _numeric(raw)
+            if not number.is_integer():
+                raise ValueError(f"{raw!r} is not an integer")
+            value = int(number)
+        case ParamType.FLOAT:
+            value = _numeric(raw)
+        case ParamType.BOOLEAN:
+            if not isinstance(raw, bool):
+                raise ValueError("expected boolean")
+            value = raw
+        case ParamType.DURATION:
+            from mayhem.domain.common import parse_duration  # noqa: PLC0415
+
+            if isinstance(raw, (int, float)):
+                value = float(raw)  # numeric seconds (e.g. a 10.0 catalog default)
+            else:
+                value = parse_duration(str(raw))
+        case ParamType.BYTES:
+            from mayhem.domain.common import parse_bytes  # noqa: PLC0415
+
+            value = parse_bytes(str(raw))
+        case ParamType.PERCENT:
+            number = _numeric(raw)
+            if not 0.0 <= number <= 100.0:
+                raise ValueError(f"{number} outside [0, 100]")
+            value = number
+        case _:
+            raise AssertionError(f"unhandled param type {spec.type}")
+    return value
+
+
+def _coerce(spec: ParamSpec, raw: object) -> object:
+    try:
+        result = _convert(spec, raw)
+    except (TypeError, ValueError) as exc:
+        raise SchemaValidationError(
+            f"params[{spec.name}]", f"{raw!r} is not a valid {spec.type.value}: {exc}"
+        ) from exc
+    if isinstance(result, (int, float)) and not isinstance(result, bool):
+        if spec.minimum is not None and float(result) < spec.minimum:
+            raise SchemaValidationError(f"params[{spec.name}]", f"below minimum {spec.minimum}")
+        if spec.maximum is not None and float(result) > spec.maximum:
+            raise SchemaValidationError(f"params[{spec.name}]", f"above maximum {spec.maximum}")
+    return result

mayhem/domain/identity.py

@@ -0,0 +1,200 @@
+"""Runtime identity and runtime metadata value objects (ADR-M1-1, ADR-M1-2).
+
+The container half of the codebase used to bind targets by authored name
+(``container_name``, ADR-0019/0020) plus ad-hoc scalars. Those are now split
+into two sharply different concepts:
+
+* :class:`RuntimeIdentity` **is** the identity — equality and hashing operate on
+  the three identity fields only. It is the key used by every persisted
+  plan/lease/execution/recovery record.
+* :class:`RuntimeMetadata` is descriptive context (project, service, labels,
+  lifecycle timestamps). It is explicitly excluded from equality: metadata churn
+  never changes the identity.
+
+``container_name``/``service`` are *authoring resolver keys* that resolve to a
+``RuntimeIdentity`` at planning time; they are never identity equality.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+class RuntimeIdentity(BaseModel):
+    """Equality key for a single running workload (a container, later a process).
+
+    Attributes:
+        runtime: Engine label (``"docker"``/``"podman"``) — label only, per
+            ADR-0013.
+        host_id: Host node the workload runs under (e.g. ``h-podman-local``).
+        runtime_id: Engine-reported runtime object id (full container id).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    runtime: str
+    host_id: str | None = None
+    runtime_id: str
+
+    @field_validator("runtime", "runtime_id")
+    @classmethod
+    def _non_empty(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("identity fields runtime and runtime_id must be non-empty")
+        return value
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, RuntimeIdentity):
+            return NotImplemented
+        # Equality on the three identity fields ONLY (ADR-M1-1); names, labels,
+        # and metadata never participate.
+        return (self.runtime, self.host_id, self.runtime_id) == (
+            other.runtime,
+            other.host_id,
+            other.runtime_id,
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.runtime, self.host_id, self.runtime_id))
+
+    def resolve_key(self) -> str:
+        """Canonical, opaque, store-safe identity key (round-trippable)."""
+        return f"{self.runtime}|{self.host_id or ''}|{self.runtime_id}"
+
+    def key(self) -> str:  # alias: key() == resolve_key()
+        """Short canonical key, usable as a SQL/store column value."""
+        return self.resolve_key()
+
+    @classmethod
+    def from_key(cls, key: str) -> RuntimeIdentity:
+        """Rebuild an identity from a canonical ``resolve_key()`` string."""
+        try:
+            runtime, host_id, runtime_id = key.split("|", maxsplit=2)
+        except ValueError as exc:
+            raise ValueError(f"not a canonical identity key: {key!r}") from exc
+        return cls(
+            runtime=runtime,
+            host_id=host_id or None,
+            runtime_id=runtime_id,
+        )
+
+
+class ProcessRuntimeIdentity(BaseModel):
+    """Equality key for a single running process (ADR-M2 Phase 2.4).
+
+    A PID alone is not an identity: the kernel recycles PIDs after exit, so a
+    short-lived process can exit and its PID be reused by an unrelated process
+    while a lease is still active. The boot time (process start time, ``/proc/
+    <pid>/stat`` field 22, expressed in clock ticks since boot) disambiguates.
+
+    Attributes:
+        host_id: Host node the process runs under (e.g. ``h-local``).
+        pid: Host PID (or container-namespace PID for container-addressed runs).
+        boot_time: Process start time in clock ticks since boot; ``None`` when
+            the platform does not expose it (e.g. non-Linux), in which case the
+            guard degrades to pid-only checks.
+        container_name: Owning container name where applicable (ADR-0019/0020),
+            part of the identity for container-addressed targets.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    host_id: str
+    pid: int
+    boot_time: int | None = None
+    container_name: str | None = None
+
+    @field_validator("pid")
+    @classmethod
+    def _positive_pid(cls, value: int) -> int:
+        if value <= 0:
+            raise ValueError("pid must be positive")
+        return value
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ProcessRuntimeIdentity):
+            return NotImplemented
+        return (self.host_id, self.pid, self.boot_time, self.container_name) == (
+            other.host_id,
+            other.pid,
+            other.boot_time,
+            other.container_name,
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.host_id, self.pid, self.boot_time, self.container_name))
+
+    def resolve_key(self) -> str:
+        """Canonical, opaque, store-safe identity key (round-trippable)."""
+        return f"{self.host_id}|{self.pid}|{self.boot_time or ''}|{self.container_name or ''}"
+
+    def key(self) -> str:  # alias: key() == resolve_key()
+        return self.resolve_key()
+
+    @classmethod
+    def from_key(cls, key: str) -> ProcessRuntimeIdentity:
+        """Rebuild an identity from a canonical ``resolve_key()`` string."""
+        try:
+            host_id, pid, boot_time, container_name = key.split("|", maxsplit=3)
+        except ValueError as exc:
+            raise ValueError(f"not a canonical process identity key: {key!r}") from exc
+        return cls(
+            host_id=host_id,
+            pid=int(pid),
+            boot_time=int(boot_time) if boot_time else None,
+            container_name=container_name or None,
+        )
+
+
+class RuntimeMetadata(BaseModel):
+    """Descriptive, non-identity runtime context (ADR-M1-2).
+
+    All fields are mutable/descriptive and explicitly excluded from identity
+    equality. ``project``/``service`` come from the engine's compose labels;
+    ``name`` is the container name; lifecycle timestamps come from inspect.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    project: str | None = None
+    service: str | None = None
+    name: str | None = None
+    labels: dict[str, str] = {}
+    created_at: str | None = None
+    started_at: str | None = None
+    image: str | None = None
+
+    @classmethod
+    def from_compose_labels(
+        cls, labels: Mapping[str, Any], name: str | None = None
+    ) -> RuntimeMetadata:
+        """Build metadata from engine compose labels (podman/docker)."""
+        raw = {str(k): str(v) for k, v in (labels or {}).items()}
+        return cls(
+            project=raw.get("com.docker.compose.project"),
+            service=raw.get("com.docker.compose.service"),
+            name=name,
+            labels=raw,
+        )
+
+    @classmethod
+    def from_inspect(cls, info: Mapping[str, Any], name: str | None = None) -> RuntimeMetadata:
+        """Build metadata from an engine ``inspect``-like mapping.
+
+        Recognized keys: ``"labels"``, ``"project"``, ``"service"``,
+        ``"created_at"``, ``"started_at"``, ``"image"``.
+        """
+        meta = cls.from_compose_labels(info.get("labels") or {}, name=name)
+        overrides: dict[str, Any] = {}
+        if info.get("created_at"):
+            overrides["created_at"] = str(info["created_at"])
+        if info.get("started_at"):
+            overrides["started_at"] = str(info["started_at"])
+        if info.get("image"):
+            overrides["image"] = str(info["image"])
+        return meta.model_copy(update=overrides)

mayhem/domain/k8s_adapter.py

@@ -0,0 +1,132 @@
+"""Kubernetes adapter interface (ADR-M7-1).
+
+Defines the ``RuntimeAdapter``-compatible seam for Kubernetes.  **No
+Kubernetes runtime is implemented in this milestone** — the adapter returns
+``UNSUPPORTED`` for every capability until a future cluster driver ships.
+
+Node-kind extensions (``NodeKind.POD`` / ``NodeKind.K8S_NODE``) are declared
+in the topology model (ADR-M7-2); this module provides the capability contract
+so the planner can refuse K8s plans with a clear, actionable message pointing
+back to this ADR.
+
+Design decisions
+----------------
+* ``is_available()`` returns ``False`` — no transport is wired yet.
+* ``capabilities()`` reports an empty supported set so that the verdict
+  matrix yields ``UNSUPPORTED`` for every ``RuntimeCapability``.
+* ``list_nodes`` / ``list_pods`` are stubs returning empty lists — real
+  discovery belongs to the cluster-driver implementation (M8).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from mayhem.domain.runtime_adapter import (
+    AdapterCapabilities,
+    CapabilityRequirements,
+    CapabilityVerdict,
+    RuntimeAdapter,
+    RuntimeCapability,
+    VerdictResult,
+)
+from mayhem.topology.providers.base import PartialGraph
+
+if TYPE_CHECKING:
+    from mayhem.domain.identity import RuntimeIdentity, RuntimeMetadata
+
+# ── ADR-M7 reference constants ──────────────────────────────────────────────
+
+ADR_M7_1 = "ADR-M7-1"
+"""k8s RuntimeAdapter interface contract."""
+
+ADR_M7_2 = "ADR-M7-2"
+"""Topology node-kind extensions (PodNode / K8sNode)."""
+
+ADR_M7_3 = "ADR-M7-3"
+"""k8s fault categories (capacity / network / preemption)."""
+
+ADR_M7_4 = "ADR-M7-4"
+"""Capability matrix rows for k8s (default UNSUPPORTED)."""
+
+UNSUPPORTED_MSG = (
+    "kubernetes execution not yet supported; see the RuntimeAdapter contract at ADR-M7-1"
+)
+
+
+class KubernetesAdapter(RuntimeAdapter):
+    """Stub Kubernetes adapter — every capability UNSUPPORTED (ADR-M7-1).
+
+    Registered in the adapter registry as ``"kubernetes"`` so that
+    ``best_effort("kubernetes")`` can locate the contract.  The adapter is
+    never *available* (``is_available() → False``) until a live-cluster
+    driver is implemented.
+    """
+
+    ENGINE = "kubernetes"
+
+    def __init__(self, engine: str = ENGINE) -> None:
+        self._engine = engine
+
+    # ── RuntimeAdapter contract ──────────────────────────────────────────────
+
+    @property
+    def id(self) -> str:
+        return self._engine
+
+    def is_available(self) -> bool:
+        """No transport implemented; never *available* for execution yet."""
+        return False
+
+    def capabilities(self) -> AdapterCapabilities:
+        """Empty capability set — all RuntimeCapabilities yield UNSUPPORTED."""
+        return AdapterCapabilities(
+            engine=self._engine,
+            supported=frozenset(),
+            alternatives=frozenset(),
+            version=None,
+        )
+
+    def evaluate(self, reqs: CapabilityRequirements) -> VerdictResult:
+        """Every capability returns UNSUPPORTED (ADR-M7-1, ADR-M7-4)."""
+        verdicts = {cap.value: CapabilityVerdict.UNSUPPORTED.value for cap in RuntimeCapability}
+        # Any explicit requirement makes this blocking.
+        blocking = bool(reqs.namespaces or reqs.tools or reqs.runtimes) or True
+        return VerdictResult(
+            engine=self._engine,
+            requirements=reqs,
+            verdicts=verdicts,
+            blocking=blocking,
+        )
+
+    # ── discovery stubs ─────────────────────────────────────────────────────
+
+    def ps(self) -> list[dict[str, Any]]:
+        return []
+
+    def inspect(self, container_id: str) -> tuple[RuntimeIdentity, RuntimeMetadata | None]:
+        raise NotImplementedError(f"{UNSUPPORTED_MSG}; inspect({container_id!r})")
+
+    def exec(self, container_id: str, cmd: list[str], *, timeout_s: float = 30) -> str:
+        raise NotImplementedError(f"{UNSUPPORTED_MSG}; exec({container_id!r}, {cmd!r})")
+
+    def pid(self, container_id: str) -> int | None:
+        return None
+
+    def signal(self, container_id: str, signo: int) -> None:
+        raise NotImplementedError(f"{UNSUPPORTED_MSG}; signal({container_id!r}, {signo})")
+
+    def netns(self, container_id: str) -> str | None:
+        return None
+
+    def filter_by_compose(self, project: str, services: tuple[str, ...] | None = None) -> None:
+        return None
+
+    def filter_by_names(self, names: list[str]) -> None:
+        return None
+
+    def discover(self) -> PartialGraph:
+        return PartialGraph(
+            source=self._engine,
+            notes=("kubernetes adapter is interface-only (ADR-M7-1)",),
+        )