apache-aiops 0.2.0__py3-none-any.whl

apache_aiops/governance/undo.py

@@ -0,0 +1,259 @@
+"""Undo-token primitive — record the inverse of a write operation.
+
+Reversibility is a 2026 agentic-ops requirement: an operator (or an external orchestrator)
+needs to roll a change back to a known-good state. The inverse of an operation
+is domain-specific (power-off ↔ power-on, create-snapshot ↔ delete-snapshot,
+and some ops — like delete-vm — have NO safe inverse), so a tool *declares* its
+undo via ``@governed_tool(undo=...)``.
+
+This module only RECORDS the inverse descriptor (a replayable
+``{skill, tool, params}``) into ``~/.apache-aiops/undo.db`` and hands back an
+``undo_id``. It deliberately does NOT execute the inverse — coordinated,
+multi-step rollback is an external orchestrator's job. Keeping recording and execution
+separate matches the "separate the deterministic parts from the parts where the
+LLM reasons" guardrail.
+
+A tool's ``undo`` is a callable ``(params, result) -> dict | None``:
+
+    @governed_tool(risk_level="medium", undo=lambda p, r: {
+        "tool": "vm_power_on", "params": {"vm_name": p["vm_name"]}})
+    def vm_power_off(vm_name: str, target: str = "") -> dict: ...
+
+Returning ``None`` means "no inverse for this call" (nothing is recorded).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sqlite3
+import threading
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from apache_aiops.governance.paths import ops_path
+
+_log = logging.getLogger("apache-aiops.undo")
+
+_BUSY_TIMEOUT_MS = 5000
+
+_CREATE_TABLE = """\
+CREATE TABLE IF NOT EXISTS undo_log (
+    undo_id        TEXT PRIMARY KEY,
+    ts             TEXT NOT NULL,
+    skill          TEXT NOT NULL DEFAULT '',
+    tool           TEXT NOT NULL DEFAULT '',
+    undo_skill     TEXT NOT NULL DEFAULT '',
+    undo_tool      TEXT NOT NULL DEFAULT '',
+    undo_params    TEXT NOT NULL DEFAULT '{}',
+    orig_params    TEXT NOT NULL DEFAULT '{}',
+    status         TEXT NOT NULL DEFAULT 'recorded',
+    workflow_id    TEXT NOT NULL DEFAULT '',
+    note           TEXT NOT NULL DEFAULT '',
+    effect_verified INTEGER NOT NULL DEFAULT 1
+)
+"""
+
+_CREATE_INDEX = "CREATE INDEX IF NOT EXISTS idx_undo_status ON undo_log(status)"
+
+# Columns added after the first release. CREATE TABLE IF NOT EXISTS leaves an
+# existing DB untouched, so each one needs an explicit ALTER. The default must
+# describe the rows already there: every pre-existing token was recorded on the
+# confirmed path, so effect_verified=1 is accurate for them, not just convenient.
+_MIGRATIONS = (
+    (
+        "effect_verified",
+        "ALTER TABLE undo_log ADD COLUMN effect_verified INTEGER NOT NULL DEFAULT 1",
+    ),
+)
+
+
+class UndoStore:
+    """Append-and-update store for recorded undo descriptors (SQLite/WAL)."""
+
+    def __init__(self, db_path: Path | str | None = None) -> None:
+        self._path = Path(db_path).expanduser() if db_path else ops_path("undo.db")
+        self._ok = False
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+            conn = self._connect()
+            conn.execute(_CREATE_TABLE)
+            conn.execute(_CREATE_INDEX)
+            _migrate(conn)
+            conn.execute("PRAGMA journal_mode=WAL")
+            conn.commit()
+            conn.close()
+            self._harden()
+            self._ok = True
+        except Exception:
+            _log.warning("Cannot initialize undo DB at %s", self._path, exc_info=True)
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(self._path), timeout=_BUSY_TIMEOUT_MS / 1000)
+        conn.execute(f"PRAGMA busy_timeout={_BUSY_TIMEOUT_MS}")
+        return conn
+
+    def _harden(self) -> None:
+        try:
+            os.chmod(self._path.parent, 0o700)
+        except OSError:
+            pass
+        for suffix in ("", "-wal", "-shm"):
+            candidate = self._path.with_name(self._path.name + suffix)
+            try:
+                if candidate.exists():
+                    os.chmod(candidate, 0o600)
+            except OSError:
+                pass
+
+    def record(
+        self,
+        *,
+        skill: str,
+        tool: str,
+        undo_descriptor: dict[str, Any],
+        orig_params: dict[str, Any] | None = None,
+        workflow_id: str = "",
+        effect_verified: bool = True,
+    ) -> str | None:
+        """Persist an inverse descriptor; return its undo_id (or None on failure).
+
+        ``undo_descriptor`` must carry at least ``tool`` (the inverse tool) and
+        ``params``; ``skill`` defaults to the original skill. Never raises —
+        recording must not break the underlying tool call.
+
+        ``effect_verified=False`` marks a token whose *original* write lost
+        its response: the change is probably live but unconfirmed. The token
+        stays listable and appliable — an unconfirmed change is exactly when
+        a rollback is most wanted — but the flag travels with it so an
+        operator is never told a state was restored that was never reached.
+        """
+        if not self._ok:
+            return None
+        if not isinstance(undo_descriptor, dict) or not undo_descriptor.get("tool"):
+            _log.debug("undo descriptor for %s.%s missing 'tool' — not recorded", skill, tool)
+            return None
+        undo_id = uuid.uuid4().hex[:16]
+        try:
+            conn = self._connect()
+            conn.execute(
+                "INSERT INTO undo_log (undo_id, ts, skill, tool, undo_skill, undo_tool, "
+                "undo_params, orig_params, status, workflow_id, note, "
+                "effect_verified) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'recorded', ?, ?, ?)",
+                (
+                    undo_id,
+                    datetime.now(tz=UTC).isoformat(),
+                    skill,
+                    tool,
+                    str(undo_descriptor.get("skill", skill)),
+                    str(undo_descriptor["tool"]),
+                    _safe_json(undo_descriptor.get("params", {})),
+                    _safe_json(orig_params or {}),
+                    workflow_id,
+                    str(undo_descriptor.get("note", "")),
+                    1 if effect_verified else 0,
+                ),
+            )
+            conn.commit()
+            conn.close()
+            return undo_id
+        except Exception:
+            _log.warning("Failed to record undo for %s.%s", skill, tool, exc_info=True)
+            return None
+
+    def get(self, undo_id: str) -> dict[str, Any] | None:
+        if not self._ok:
+            return None
+        conn = self._connect()
+        try:
+            conn.row_factory = sqlite3.Row
+            row = conn.execute("SELECT * FROM undo_log WHERE undo_id = ?", (undo_id,)).fetchone()
+            return dict(row) if row else None
+        finally:
+            conn.close()
+
+    def list(self, *, status: str | None = None, limit: int = 50) -> list[dict[str, Any]]:
+        if not self._ok:
+            return []
+        conn = self._connect()
+        try:
+            conn.row_factory = sqlite3.Row
+            if status:
+                rows = conn.execute(
+                    "SELECT * FROM undo_log WHERE status = ? ORDER BY ts DESC LIMIT ?",
+                    (status, limit),
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT * FROM undo_log ORDER BY ts DESC LIMIT ?", (limit,)
+                ).fetchall()
+            return [dict(r) for r in rows]
+        finally:
+            conn.close()
+
+    def mark(self, undo_id: str, status: str) -> bool:
+        """Update an undo record's status (e.g. 'applied' / 'expired')."""
+        if not self._ok:
+            return False
+        conn = self._connect()
+        try:
+            cur = conn.execute(
+                "UPDATE undo_log SET status = ? WHERE undo_id = ?", (status, undo_id)
+            )
+            conn.commit()
+            return cur.rowcount > 0
+        finally:
+            conn.close()
+
+
+def _migrate(conn: sqlite3.Connection) -> None:
+    """Apply additive schema migrations to an already-created undo_log.
+
+    Idempotent and best-effort: a store that cannot be migrated still records
+    and lists tokens, which matters more than any single column.
+    """
+    try:
+        existing = {row[1] for row in conn.execute("PRAGMA table_info(undo_log)")}
+    except sqlite3.Error:
+        return
+    for column, statement in _MIGRATIONS:
+        if column in existing:
+            continue
+        try:
+            conn.execute(statement)
+        except sqlite3.Error:
+            _log.warning("undo schema migration for '%s' failed", column, exc_info=True)
+
+
+def _safe_json(obj: Any) -> str:
+    try:
+        return json.dumps(obj, ensure_ascii=False, default=str)
+    except Exception:
+        return json.dumps({"_raw": str(obj)})
+
+
+# ── Singleton ──────────────────────────────────────────────────────────
+
+_store: UndoStore | None = None
+_store_lock = threading.Lock()
+
+
+def get_undo_store(db_path: Path | str | None = None) -> UndoStore:
+    """Return the global UndoStore singleton (lazy, lock-guarded)."""
+    global _store
+    if _store is None:
+        with _store_lock:
+            if _store is None:
+                _store = UndoStore(db_path)
+    return _store
+
+
+def reset_undo_store() -> None:
+    """Reset the singleton. Tests use this between cases."""
+    global _store
+    with _store_lock:
+        _store = None

apache_aiops/mcp_server/__init__.py

@@ -0,0 +1 @@
+"""MCP server package for apache-aiops."""

apache_aiops/mcp_server/_annotations.py

@@ -0,0 +1,66 @@
+"""Derive MCP tool annotations from the governance risk level.
+
+Every tool already declares ``risk_level`` on ``@governed_tool``; this module
+publishes it to MCP clients as the standard ``ToolAnnotations`` hints plus the
+exact level under ``_meta``, so a client can gate approval without reading our
+docstrings.
+
+Only the safe direction is ever asserted:
+
+- ``low`` → ``readOnlyHint: true``. Backed by the smoke-test invariant that
+  ``risk_level == "low"`` exactly when the docstring says ``[READ]``.
+- anything else → ``readOnlyHint: false, destructiveHint: true``. The
+  ``medium`` tier is NOT non-destructive — it holds deletes, hard power-offs,
+  state kills and stat resets — so claiming ``destructiveHint: false`` from the
+  tier would tell a client it may skip approval for a delete. Over-warning
+  costs a confirmation prompt; under-warning costs data.
+- ``idempotentHint`` only echoes an explicit ``@governed_tool(idempotent=True)``
+  declaration; it is never inferred.
+- ``openWorldHint`` is left unset (spec default ``true``): every tool talks to
+  an external system.
+
+This file is identical across the AIops line; keep it that way.
+"""
+
+from typing import Any
+
+from mcp.types import ToolAnnotations
+
+RISK_META_KEY = "io.github.AIops-tools/riskLevel"
+RISK_LEVELS = frozenset({"low", "medium", "high", "critical"})
+
+
+def annotations_for(risk_level: str, idempotent: bool) -> ToolAnnotations:
+    """Return the MCP hints that a tool of ``risk_level`` may honestly claim."""
+    if risk_level not in RISK_LEVELS:
+        raise ValueError(
+            f"unknown risk_level {risk_level!r}; expected one of {sorted(RISK_LEVELS)}"
+        )
+    if risk_level == "low":
+        return ToolAnnotations(read_only_hint=True)
+    return ToolAnnotations(
+        read_only_hint=False,
+        destructive_hint=True,
+        idempotent_hint=idempotent,
+    )
+
+
+def apply_risk_annotations(server: Any) -> None:
+    """Replace every registered tool with a copy carrying its risk annotations.
+
+    Fails fast on a tool without ``@governed_tool`` metadata: an unannotated
+    tool would be advertised with the spec defaults, i.e. as a destructive
+    write with no stated risk level — wrong for a read, silent for a write.
+    """
+    tools = server._tool_manager._tools  # same private registry undo.py relies on
+    for name, tool in list(tools.items()):
+        risk_level = getattr(tool.fn, "_risk_level", None)
+        if risk_level is None:
+            raise RuntimeError(f"tool {name!r} has no @governed_tool risk_level")
+        idempotent = bool(getattr(tool.fn, "_idempotent", False))
+        tools[name] = tool.model_copy(
+            update={
+                "annotations": annotations_for(risk_level, idempotent),
+                "meta": {**(tool.meta or {}), RISK_META_KEY: risk_level},
+            }
+        )

apache_aiops/mcp_server/_shared.py

@@ -0,0 +1,67 @@
+"""Shared Apache MCP server and sanitized errors."""
+
+from __future__ import annotations
+
+import functools
+import logging
+import threading
+from collections.abc import Callable
+from typing import Any, Optional
+
+from mcp.server import MCPServer
+
+from apache_aiops import __version__
+from apache_aiops.connection import ApacheCommandError, ApacheWriteUncertainError, ConnectionManager
+from apache_aiops.governance import mark_unknown, sanitize
+
+logger = logging.getLogger(__name__)
+_ERROR_MAX = 800
+
+
+def tool_errors(shape: str = "dict") -> Callable:
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except Exception as exc:
+                logger.error("Tool %s failed", func.__name__, exc_info=True)
+                message = (
+                    sanitize(str(exc), _ERROR_MAX)
+                    if isinstance(
+                        exc, (ApacheCommandError, ValueError, KeyError, FileNotFoundError, OSError)
+                    )
+                    else f"{type(exc).__name__}: operation failed."
+                )
+                payload = {
+                    "error": message,
+                    "hint": "Run 'apache-aiops doctor' and check local command permissions.",
+                }
+                if isinstance(exc, ApacheWriteUncertainError):
+                    return mark_unknown(payload)
+                return payload
+
+        return wrapper
+
+    return decorator
+
+
+mcp = MCPServer(
+    "apache-aiops",
+    version=__version__,
+    instructions=(
+        "Governed Apache HTTP Server config, vhost, module and HTTP diagnosis. "
+        "Every tool is audited and budgeted."
+    ),
+)
+_manager: Optional[ConnectionManager] = None
+_lock = threading.Lock()
+
+
+def _get_connection(target: Optional[str] = None) -> Any:
+    global _manager
+    with _lock:
+        if _manager is None:
+            _manager = ConnectionManager()
+        manager = _manager
+    return manager.connect(target)

apache_aiops/mcp_server/server.py

@@ -0,0 +1,14 @@
+"""Apache AIops MCP entry point (stdio)."""
+
+import logging
+
+from apache_aiops.mcp_server._annotations import apply_risk_annotations
+from apache_aiops.mcp_server._shared import mcp
+from apache_aiops.mcp_server.tools import httpd, undo  # noqa: F401 — registration
+
+apply_risk_annotations(mcp)
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO)
+    mcp.run(transport="stdio")

apache_aiops/mcp_server/tools/__init__.py

@@ -0,0 +1 @@
+"""MCP tool modules. Importing each registers its @mcp.tool() functions."""

apache_aiops/mcp_server/tools/httpd.py

@@ -0,0 +1,143 @@
+"""Governed Apache HTTP Server read tools."""
+
+from typing import Optional
+
+from apache_aiops.governance import governed_tool, mark_unknown
+from apache_aiops.mcp_server._shared import _get_connection, mcp, tool_errors
+from apache_aiops.ops import httpd
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_config_includes(target: Optional[str] = None) -> dict:
+    """[READ] Show Apache's parsed config include tree with bounded output."""
+    return httpd.config_includes(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_compiled_modules(target: Optional[str] = None) -> dict:
+    """[READ] List modules compiled into Apache, excluding dynamic modules."""
+    return httpd.compiled_modules(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_static_directives(target: Optional[str] = None) -> dict:
+    """[READ] List directives from Apache's static modules with bounded output."""
+    return httpd.static_directives(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_build(target: Optional[str] = None) -> dict:
+    """[READ] Show Apache build options and compiled paths."""
+    return httpd.build(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_runtime_config(target: Optional[str] = None) -> dict:
+    """[READ] Dump Apache's parsed runtime configuration."""
+    return httpd.runtime_config(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_server_status(target: Optional[str] = None) -> dict:
+    """[READ] Get bounded machine-readable mod_status metrics from configured URL."""
+    return httpd.server_status(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_error_log(limit: int = 50, target: Optional[str] = None) -> dict:
+    """[READ] Tail an operator-configured Apache error log, with explicit truncation."""
+    return httpd.error_log(_get_connection(target), limit)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_access_status(limit: int = 200, target: Optional[str] = None) -> dict:
+    """[READ] Count HTTP statuses in recent common/combined access logs, without raw requests."""
+    return httpd.access_status(_get_connection(target), limit)
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium")
+@tool_errors()
+def apache_graceful_reload(dry_run: bool = False, target: Optional[str] = None) -> dict:
+    """[WRITE] Config-check then request a graceful reload; outcome needs operator check."""
+    conn = _get_connection(target)
+    check = httpd.config_check(conn)
+    before = httpd.probe(conn) if conn.target.probe_url else None
+    if dry_run:
+        return {"dryRun": True, "configCheck": check, "probeBefore": before,
+                "wouldRun": "apachectl graceful"}
+    response = conn.graceful()
+    try:
+        after = httpd.probe(conn) if conn.target.probe_url else None
+    except Exception as exc:
+        return mark_unknown({"accepted": True, "response": response, "probeAfter": None,
+                             "probeError": f"Probe failed after reload: {type(exc).__name__}"})
+    return mark_unknown({
+        "accepted": True, "response": response, "probeBefore": before,
+        "probeAfter": after,
+        "note": "A successful command/probe does not prove all workers loaded new config.",
+    })
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_version(target: Optional[str] = None) -> dict:
+    """[READ] Get Apache HTTP Server version from apachectl -v."""
+    return httpd.version(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_config_check(target: Optional[str] = None) -> dict:
+    """[READ] Run Apache's native config syntax test."""
+    return httpd.config_check(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_vhosts(target: Optional[str] = None) -> dict:
+    """[READ] Show Apache's parsed virtual-host mapping."""
+    return httpd.vhosts(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_modules(target: Optional[str] = None) -> dict:
+    """[READ] List Apache's loaded modules."""
+    return httpd.modules(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_probe(target: Optional[str] = None) -> dict:
+    """[READ] GET the configured health URL without downloading its body."""
+    return httpd.probe(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors()
+def apache_diagnose(target: Optional[str] = None) -> dict:
+    """[READ] Correlate version, config, vhosts, modules and optional HTTP probe."""
+    return httpd.diagnose(_get_connection(target))