queue-aiops 0.1.0__py3-none-any.whl

queue_aiops/ops/writes.py

@@ -0,0 +1,284 @@
+"""Governed broker writes — the only state-changing operations in the tool.
+
+Every reversible write reads the broker's current state **before** it changes
+anything, so the harness records a faithful undo / audit trail (the before-state
+is fetched via a real read, never guessed):
+
+  * ``config_set`` (redis) — reads the parameter's current value via CONFIG GET
+    first; undo sets it back.
+  * ``set_policy`` / ``delete_policy`` (rabbitmq) — read the current policy
+    first; undo restores the prior policy (or deletes a policy that did not
+    exist before).
+  * ``delete_queue`` (rabbitmq) — reads the queue's definition (durable /
+    auto_delete / arguments) first; undo re-declares the queue with the
+    captured properties. The *messages* in it are gone — the undo restores the
+    queue definition, not its contents, and says so.
+
+Irreversible writes record priorState only (no undo): ``kill_client`` (the
+connection is gone; priorState = the client row) and ``purge_queue`` (messages
+are destroyed; priorState = the message count).
+
+Each function returns a plain descriptor; the MCP layer adds dry-run + the
+governance harness (risk tier + audit + undo).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from queue_aiops.connection import QueueApiError
+from queue_aiops.ops._util import as_obj, num, s
+
+# CONFIG SET parameter names are plain words (e.g. maxmemory-policy); reject
+# anything else before it reaches the wire.
+_CONFIG_PARAM_RE = re.compile(r"^[A-Za-z0-9_.-]{1,64}$")
+
+
+# ── redis: config_set (reversible) ───────────────────────────────────────────
+
+
+def config_set(conn: Any, parameter: str, value: str) -> dict:
+    """[WRITE][med] Set one redis config parameter, capturing its prior value.
+
+    Reads the parameter first (CONFIG GET) so ``priorState.value`` reflects
+    what it *was* (drives a faithful undo). Runtime-only — CONFIG SET does not
+    persist to the config file unless CONFIG REWRITE is run out-of-band.
+    """
+    parameter = str(parameter).strip().lower()
+    if not _CONFIG_PARAM_RE.match(parameter):
+        raise ValueError(
+            f"Invalid config parameter name '{parameter[:64]}': expected a "
+            f"plain word like 'maxmemory-policy'."
+        )
+    prior = conn.redis_config_get(parameter)
+    if parameter not in prior:
+        raise KeyError(
+            f"Config parameter '{parameter}' does not exist on this instance — "
+            f"check the name with config_get first."
+        )
+    prior_value = s(prior.get(parameter), 128)
+    conn.redis_config_set(parameter, str(value))
+    return {
+        "action": "config_set",
+        "parameter": parameter,
+        "value": s(value, 128),
+        "priorState": {"value": prior_value},
+        "note": "Runtime change only — not persisted to the config file.",
+    }
+
+
+# ── redis: kill_client (irreversible; priorState only) ──────────────────────
+
+
+def kill_client(conn: Any, client_id: int = 0, addr: str = "") -> dict:
+    """[WRITE][med] Disconnect one client by id or addr. IRREVERSIBLE.
+
+    Captures the client's CLIENT LIST row as priorState before the kill (who it
+    was, from where, last command) — the connection itself cannot be restored,
+    so no undo is recorded. Most clients transparently reconnect.
+    """
+    if not client_id and not addr:
+        raise ValueError("Pass client_id (from list_clients) or addr ('ip:port').")
+    match: dict = {}
+    for c in conn.redis_client_list():
+        if (client_id and str(c.get("id")) == str(client_id)) or (
+            addr and str(c.get("addr")) == str(addr)
+        ):
+            match = {
+                "id": s(c.get("id"), 32),
+                "addr": s(c.get("addr"), 64),
+                "name": s(c.get("name"), 64),
+                "lastCommand": s(c.get("cmd"), 64),
+                "ageSeconds": num(c.get("age")),
+            }
+            break
+    killed = (
+        conn.redis_client_kill_id(int(client_id))
+        if client_id
+        else conn.redis_client_kill_addr(str(addr))
+    )
+    return {
+        "action": "kill_client",
+        "clientId": s(client_id, 32) if client_id else "",
+        "addr": s(addr, 64),
+        "killed": int(killed),
+        "priorState": {"client": match},
+    }
+
+
+# ── rabbitmq: purge_queue (irreversible; priorState only) ────────────────────
+
+
+def _queue_def(conn: Any, vhost: str, name: str) -> dict:
+    """Fetch a queue's current definition + counts (raises if it is missing)."""
+    obj = as_obj(
+        conn.platform.normalise(conn.get(conn.platform.path("queue", vhost=vhost, name=name)))
+    )
+    return {
+        "messages": num(obj.get("messages")),
+        "durable": bool(obj.get("durable")),
+        "autoDelete": bool(obj.get("auto_delete")),
+        "arguments": as_obj(obj.get("arguments")),
+    }
+
+
+def purge_queue(conn: Any, vhost: str, name: str) -> dict:
+    """[WRITE][high] Purge all ready messages from a queue. IRREVERSIBLE.
+
+    Reads the queue first so priorState carries the message count that is about
+    to be destroyed (audit evidence). Unacked messages are not purged.
+    """
+    prior = _queue_def(conn, vhost, name)
+    conn.delete(conn.platform.path("queue_purge", vhost=vhost, name=name))
+    return {
+        "action": "purge_queue",
+        "vhost": s(vhost, 64),
+        "queue": s(name, 128),
+        "priorState": {"messages": prior["messages"]},
+        "note": "Messages are destroyed — no undo. Unacked messages are not purged.",
+    }
+
+
+# ── rabbitmq: delete/declare queue (definition-reversible) ───────────────────
+
+
+def delete_queue(conn: Any, vhost: str, name: str) -> dict:
+    """[WRITE][high] Delete a queue, capturing its definition for the undo.
+
+    Reads the queue first so priorState carries the full definition (durable /
+    auto_delete / arguments) and the message count. The undo re-declares the
+    queue with the captured properties — the queue comes back, its messages do
+    not (that is stated in the descriptor, not hidden).
+    """
+    prior = _queue_def(conn, vhost, name)
+    conn.delete(conn.platform.path("queue", vhost=vhost, name=name))
+    return {
+        "action": "delete_queue",
+        "vhost": s(vhost, 64),
+        "queue": s(name, 128),
+        "priorState": prior,
+        "note": (
+            "Undo re-declares the queue with the captured definition; the "
+            f"{int(prior['messages'])} message(s) it held are NOT restored."
+        ),
+    }
+
+
+def declare_queue(
+    conn: Any,
+    vhost: str,
+    name: str,
+    durable: bool = True,
+    auto_delete: bool = False,
+    arguments: dict | None = None,
+) -> dict:
+    """[WRITE][med] Declare (create) a queue via PUT; idempotent when identical.
+
+    Reads first so priorState records whether the queue already existed. This
+    is also the replay target for delete_queue's undo descriptor.
+    """
+    existed = True
+    try:
+        _queue_def(conn, vhost, name)
+    except QueueApiError as exc:
+        if exc.status_code != 404:
+            raise
+        existed = False
+    body = {
+        "durable": bool(durable),
+        "auto_delete": bool(auto_delete),
+        "arguments": as_obj(arguments),
+    }
+    conn.put(conn.platform.path("queue", vhost=vhost, name=name), json=body)
+    return {
+        "action": "declare_queue",
+        "vhost": s(vhost, 64),
+        "queue": s(name, 128),
+        "durable": bool(durable),
+        "autoDelete": bool(auto_delete),
+        "arguments": as_obj(arguments),
+        "priorState": {"existed": existed},
+    }
+
+
+# ── rabbitmq: policies (reversible) ──────────────────────────────────────────
+
+
+def _policy_or_none(conn: Any, vhost: str, name: str) -> dict | None:
+    """Fetch a policy's current definition; None when it does not exist."""
+    try:
+        obj = as_obj(
+            conn.platform.normalise(
+                conn.get(conn.platform.path("policy", vhost=vhost, name=name))
+            )
+        )
+    except QueueApiError as exc:
+        if exc.status_code == 404:
+            return None
+        raise
+    return {
+        "pattern": s(obj.get("pattern"), 128),
+        "definition": as_obj(obj.get("definition")),
+        "priority": num(obj.get("priority")),
+        "applyTo": s(obj.get("apply-to") or obj.get("apply_to") or "all", 32),
+    }
+
+
+def set_policy(
+    conn: Any,
+    vhost: str,
+    name: str,
+    pattern: str,
+    definition: dict,
+    priority: int = 0,
+    apply_to: str = "all",
+) -> dict:
+    """[WRITE][med] Create/update a policy, capturing the prior one for undo.
+
+    Reads the policy first: if it existed, undo restores the prior fields; if
+    it is new, undo deletes it.
+    """
+    if not isinstance(definition, dict) or not definition:
+        raise ValueError(
+            "Policy 'definition' must be a non-empty object, e.g. "
+            "{'max-length': 100000} or {'message-ttl': 60000}."
+        )
+    prior = _policy_or_none(conn, vhost, name)
+    body = {
+        "pattern": str(pattern),
+        "definition": definition,
+        "priority": int(priority),
+        "apply-to": str(apply_to),
+    }
+    conn.put(conn.platform.path("policy", vhost=vhost, name=name), json=body)
+    return {
+        "action": "set_policy",
+        "vhost": s(vhost, 64),
+        "policy": s(name, 128),
+        "pattern": s(pattern, 128),
+        "definition": as_obj(definition),
+        "priority": int(priority),
+        "applyTo": s(apply_to, 32),
+        "priorState": {"existed": prior is not None, "policy": prior},
+    }
+
+
+def delete_policy(conn: Any, vhost: str, name: str) -> dict:
+    """[WRITE][med] Delete a policy, capturing its definition for the undo.
+
+    Reads the policy first so the undo can re-create it exactly.
+    """
+    prior = _policy_or_none(conn, vhost, name)
+    if prior is None:
+        raise KeyError(
+            f"Policy '{name}' does not exist in vhost '{vhost}' — list_policies "
+            f"shows what is defined."
+        )
+    conn.delete(conn.platform.path("policy", vhost=vhost, name=name))
+    return {
+        "action": "delete_policy",
+        "vhost": s(vhost, 64),
+        "policy": s(name, 128),
+        "priorState": {"policy": prior},
+    }

queue_aiops/platform.py

@@ -0,0 +1,217 @@
+"""Platform descriptors — the message/cache brokers queue-aiops speaks to.
+
+queue-aiops is multi-platform by construction. A registry maps a *platform
+name* to a :class:`Platform` descriptor that captures everything the connection
+and ops layers need to talk to that broker: which protocol it speaks, the
+default port, and — for an HTTP management plane — the concrete REST path for
+each *logical resource* plus how a raw response is normalised (injection-safe).
+
+v0.1 registers two platforms:
+
+  * **redis** — the Redis wire protocol (RESP) via the ``redis`` Python client.
+    Password auth (``AUTH``) is optional (an auth-less lab instance is common),
+    TLS optional. There are no REST paths; the connection layer exposes typed
+    command helpers (INFO / SLOWLOG / CLIENT LIST / CONFIG / MEMORY / SCAN).
+  * **rabbitmq** — the RabbitMQ management HTTP API (``/api/...``) with HTTP
+    Basic auth (management-plugin user). Queue and policy names — and the vhost,
+    whose default is literally ``/`` — are percent-encoded into every path.
+
+Additional brokers can ``register`` their own descriptor later without touching
+the ops / CLI / MCP layers — a registry keyed by ``platform`` name.
+
+The concrete REST paths below are modelled from the management API's public
+documentation and are exercised against mocked responses only; see the README's
+preview note.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import quote
+
+from queue_aiops.governance import sanitize
+
+
+def _seg(value: Any) -> str:
+    """URL-encode one path segment so agent-supplied identifiers (queue names,
+    policy names, and especially the default vhost ``/``) cannot smuggle ``/``,
+    ``../`` or query metacharacters into the request URL."""
+    return quote(str(value), safe="")
+
+
+# ─── registered platform names ──────────────────────────────────────────────
+REDIS = "redis"
+RABBITMQ = "rabbitmq"
+PLATFORMS = (REDIS, RABBITMQ)
+
+# Protocol kinds.
+KIND_CLIENT = "client"  # native wire protocol via a Python client (redis)
+KIND_HTTP = "http"  # HTTP management API (rabbitmq)
+
+# Bounds for the response normaliser (defensive against a hostile broker).
+_MAX_STR = 512
+_MAX_DEPTH = 8
+
+# Keys under which an HTTP platform wraps a list payload, tried in order before
+# falling back to a bare JSON array (the management API pages under ``items``).
+_LIST_KEYS = ("items", "rows", "data", "results")
+
+
+def _sanitize_obj(obj: Any, depth: int = 0) -> Any:
+    """Recursively fold broker-returned data into injection-safe values.
+
+    Every string leaf passes through ``sanitize`` (bounded length); numbers,
+    booleans and ``None`` pass through unchanged. Depth is capped so a
+    pathological nesting cannot exhaust the stack.
+    """
+    if depth > _MAX_DEPTH:
+        return None
+    if isinstance(obj, dict):
+        return {str(k): _sanitize_obj(v, depth + 1) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_sanitize_obj(v, depth + 1) for v in obj]
+    if isinstance(obj, str):
+        return sanitize(obj, _MAX_STR)
+    return obj
+
+
+@dataclass(frozen=True)
+class Platform:
+    """A broker's shape: protocol kind + logical-resource path map + normaliser."""
+
+    name: str
+    label: str
+    kind: str
+    default_port: int
+    paths: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def is_http(self) -> bool:
+        return self.kind == KIND_HTTP
+
+    def path(self, resource: str, **fmt: Any) -> str:
+        """Return the concrete REST path for a logical ``resource``.
+
+        Raises a teaching ``KeyError`` when the resource is not mapped for this
+        platform (so a caller asking for an unsupported surface fails fast with
+        the list of what *is* available, rather than hitting a confusing 404).
+
+        Every substituted value is URL-encoded (``quote(..., safe="")``) so an
+        agent-supplied identifier can never rewrite the path (e.g. via ``../``
+        or the vhost ``/``).
+        """
+        try:
+            template = self.paths[resource]
+        except KeyError as exc:
+            available = ", ".join(sorted(self.paths)) or "(none)"
+            raise KeyError(
+                f"Resource '{resource}' is not mapped for platform '{self.name}'. "
+                f"Mapped resources: {available}."
+            ) from exc
+        if not fmt:
+            return template
+        return template.format(**{k: _seg(v) for k, v in fmt.items()})
+
+    def supports(self, resource: str) -> bool:
+        return resource in self.paths
+
+    def rows(self, payload: Any) -> list[dict]:
+        """Normalise a list payload to a sanitised list of dict rows.
+
+        A bare JSON array passes through; a dict is unwrapped via the first of
+        ``items``/``rows``/``data``/``results`` that is present. Every row is
+        run through the injection-safe normaliser.
+        """
+        if isinstance(payload, dict):
+            items: Any = []
+            for key in _LIST_KEYS:
+                value = payload.get(key)
+                if isinstance(value, list):
+                    items = value
+                    break
+        else:
+            items = payload
+        return [_sanitize_obj(r) for r in (items or []) if isinstance(r, dict)]
+
+    def normalise(self, payload: Any) -> Any:
+        """Return an injection-safe copy of a raw response payload."""
+        return _sanitize_obj(payload)
+
+
+# ─── registry ───────────────────────────────────────────────────────────────
+_REGISTRY: dict[str, Platform] = {}
+
+
+def register(platform: Platform) -> None:
+    """Register a platform descriptor under its name (idempotent overwrite)."""
+    _REGISTRY[platform.name] = platform
+
+
+def get_platform(name: str) -> Platform:
+    """Return the descriptor for ``name`` or raise with the registered names."""
+    try:
+        return _REGISTRY[name]
+    except KeyError as exc:
+        available = ", ".join(sorted(_REGISTRY)) or "(none)"
+        raise ValueError(
+            f"Unknown platform '{name}'. Registered platforms: {available}."
+        ) from exc
+
+
+def platform_names() -> tuple[str, ...]:
+    """All registered platform names (sorted)."""
+    return tuple(sorted(_REGISTRY))
+
+
+# ─── RabbitMQ management HTTP API (/api/..., HTTP Basic) ─────────────────────
+_RABBITMQ_PATHS = {
+    # cluster / broker
+    "overview": "/api/overview",
+    "nodes": "/api/nodes",
+    "whoami": "/api/whoami",
+    # queues
+    "queues": "/api/queues",
+    "queues_vhost": "/api/queues/{vhost}",
+    "queue": "/api/queues/{vhost}/{name}",
+    "queue_purge": "/api/queues/{vhost}/{name}/contents",
+    # connections / channels / consumers
+    "connections": "/api/connections",
+    "channels": "/api/channels",
+    "consumers": "/api/consumers",
+    # policies
+    "policies": "/api/policies",
+    "policies_vhost": "/api/policies/{vhost}",
+    "policy": "/api/policies/{vhost}/{name}",
+}
+
+register(
+    Platform(
+        name=REDIS,
+        label="Redis (RESP client)",
+        kind=KIND_CLIENT,
+        default_port=6379,
+    )
+)
+register(
+    Platform(
+        name=RABBITMQ,
+        label="RabbitMQ management API",
+        kind=KIND_HTTP,
+        default_port=15672,
+        paths=_RABBITMQ_PATHS,
+    )
+)
+
+
+__all__ = [
+    "REDIS",
+    "RABBITMQ",
+    "PLATFORMS",
+    "KIND_CLIENT",
+    "KIND_HTTP",
+    "Platform",
+    "register",
+    "get_platform",
+    "platform_names",
+]