spring-runtime-mcp 0.2.0__py3-none-any.whl

spring_runtime_mcp/adapters/health.py

@@ -0,0 +1,164 @@
+"""Normalize Boot 2.x details trees and 3.x/4.x component trees."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ..models.common import AnalysisBudget
+
+_ABNORMAL = {"DOWN", "OUT_OF_SERVICE", "UNKNOWN"}
+_CLASS = re.compile(r"(?:[A-Za-z_$][A-Za-z0-9_$]*\.)+[A-Za-z_$][A-Za-z0-9_$]*\Z")
+
+
+def _children(node: dict[str, Any]) -> dict[str, Any]:
+    components = node.get("components")
+    if isinstance(components, dict):
+        return components
+    details = node.get("details")
+    if isinstance(details, dict):
+        return {
+            str(key): value
+            for key, value in details.items()
+            if isinstance(value, dict) and "status" in value
+        }
+    return {}
+
+
+def _scalars(
+    node: dict[str, Any], gaps: set[str], *, report_limit: bool
+) -> list[dict[str, Any]]:
+    details = node.get("details")
+    if not isinstance(details, dict):
+        return []
+    rows: list[dict[str, Any]] = []
+    for key, value in sorted(details.items(), key=lambda item: str(item[0])):
+        if isinstance(value, dict) and "status" in value:
+            continue
+        finite = (
+            isinstance(value, bool) or not isinstance(value, float) or value == value
+        )
+        if (isinstance(value, (str, int, float, bool)) or value is None) and finite:
+            rows.append({"name": str(key)[:128], "value": value})
+    if len(rows) > 10:
+        if report_limit:
+            gaps.add("HEALTH_DETAILS_LIMIT")
+        return rows[:10]
+    return rows
+
+
+def _error_type(node: dict[str, Any]) -> str | None:
+    details = node.get("details")
+    raw = details.get("error") if isinstance(details, dict) else None
+    if not isinstance(raw, str) or not raw:
+        return None
+    tokens = raw.split(":", 1)[0].strip().split()
+    if not tokens:
+        return None
+    token = tokens[-1]
+    if len(token) <= 256 and _CLASS.fullmatch(token):
+        return token
+    return None
+
+
+def _codes(path: tuple[str, ...], hidden: bool) -> list[str]:
+    if hidden:
+        return ["REVIEW_HEALTH_DETAILS_VISIBILITY"]
+    names = " ".join(path).casefold()
+    if any(token in names for token in ("db", "database", "datasource", "sql")):
+        return ["REVIEW_DATABASE_CONNECTIVITY"]
+    if any(token in names for token in ("disk", "diskspace")):
+        return ["REVIEW_DISK_SPACE"]
+    if any(token in names for token in ("redis", "kafka", "rabbit", "mongo")):
+        return ["REVIEW_MESSAGE_DEPENDENCY"]
+    return ["REVIEW_HEALTH_COMPONENT"]
+
+
+def normalize_health(
+    body: Any,
+    *,
+    component_path: tuple[str, ...],
+    include_details: bool,
+    include_healthy: bool,
+    max_depth: int,
+) -> tuple[str | None, list[dict[str, Any]], list[str]]:
+    if not isinstance(body, dict):
+        raise ValueError("INVALID_HEALTH_SHAPE")
+    overall = body.get("status") if isinstance(body.get("status"), str) else None
+    found: list[dict[str, Any]] = []
+    gaps: set[str] = set()
+    budget = AnalysisBudget()
+
+    def walk(node: Any, path: tuple[str, ...], depth: int) -> None:
+        budget.consume()
+        if not isinstance(node, dict):
+            gaps.add("HEALTH_COMPONENT_UNREADABLE")
+            return
+        children = _children(node)
+        if "components" in node and not isinstance(node["components"], dict):
+            gaps.add("HEALTH_COMPONENT_UNREADABLE")
+        raw_status = node.get("status")
+        status = raw_status if isinstance(raw_status, str) and raw_status else "UNKNOWN"
+        if not isinstance(raw_status, str) or not raw_status:
+            gaps.add("HEALTH_STATUS_UNOBSERVED")
+        scalars = _scalars(node, gaps, report_limit=include_details)
+        # Root UP is an observed aggregate status, not evidence that components
+        # are absent. Explicit components={} is a reported empty inventory.
+        hidden_root = (
+            depth == 0 and "components" not in node and not children and not scalars
+        )
+        hidden = hidden_root or (status != "UP" and not children and not scalars)
+        if hidden:
+            gaps.add("HEALTH_DETAILS_NOT_VISIBLE")
+        if depth > max_depth:
+            gaps.add("HEALTH_DEPTH_LIMIT")
+            return
+        selected = (
+            not component_path or path[: len(component_path)] == component_path
+        ) and (depth > 0 or not children)
+        visible = not component_path or path[: len(component_path)] == component_path
+        if selected and visible and (include_healthy or status != "UP" or hidden):
+            found.append(
+                {
+                    "path": path,
+                    "status": status[:64],
+                    "details": scalars if include_details else [],
+                    "errorType": _error_type(node),
+                    "remediationCodes": _codes(path, hidden),
+                    "childrenComplete": not hidden and depth < max_depth,
+                }
+            )
+        if depth >= max_depth and children:
+            gaps.add("HEALTH_DEPTH_LIMIT")
+            return
+        for name in sorted(children):
+            if (
+                len(path) + 1 > 16
+                or len(name) > 128
+                or any(ord(char) < 32 for char in name)
+            ):
+                gaps.add("HEALTH_COMPONENT_UNREADABLE")
+                continue
+            walk(children[name], path + (name,), depth + 1)
+
+    walk(body, (), 0)
+    items = []
+    previous: dict[tuple[str, ...], str] = {}
+    for index, row in enumerate(found, start=1):
+        identifier = f"health_{index:06d}"
+        path = row["path"]
+        previous[path] = identifier
+        parent = previous.get(path[:-1]) if path else None
+        items.append(
+            {
+                "id": identifier,
+                "componentPath": list(path),
+                "parentId": parent,
+                "status": row["status"],
+                "details": row["details"],
+                "errorType": row["errorType"],
+                "remediationCodes": row["remediationCodes"],
+                "childrenComplete": row["childrenComplete"],
+            }
+        )
+    return overall[:64] if isinstance(overall, str) else None, items, sorted(gaps)

spring_runtime_mcp/adapters/mapping_predicates.py

@@ -0,0 +1,201 @@
+"""Bounded projection of known positive WebFlux predicate conjunctions."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ..models.common import AnalysisBudget
+
+HTTP_METHODS = frozenset(
+    {"GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "TRACE", "CONNECT"}
+)
+_MAX_LENGTH = 4096
+_MAX_DEPTH = 16
+_MAX_CLAUSES = 32
+_MAX_CONDITIONS = 16
+_LEGACY_CONDITION = re.compile(
+    r"(?P<kind>consumes|produces|headers|params)\s*\[(?P<value>.*)\]\Z"
+)
+_LEGACY_KIND = {
+    "consumes": "consumes",
+    "produces": "produces",
+    "headers": "header",
+    "params": "param",
+}
+# Quoted parameters and custom header predicates remain unsupported. Keeping
+# alternatives in one header row preserves their set rather than inventing ANDs.
+_TOKEN = r"[A-Za-z0-9!#$%&'*+.^_`|~-]+"
+_MEDIA = re.compile(rf"{_TOKEN}/{_TOKEN}(?:;{_TOKEN}={_TOKEN})*\Z")
+
+
+class _UnsupportedPredicate(Exception):
+    pass
+
+
+class _Conjunction:
+    def __init__(self, text: str) -> None:
+        self.text = text
+        self.position = 0
+        self.nodes = 0
+        self.leaves: list[str] = []
+        self.budget = AnalysisBudget()
+
+    def _space(self) -> None:
+        while self.position < len(self.text) and self.text[self.position] == " ":
+            self.position += 1
+
+    def expression(self, depth: int = 0) -> None:
+        self.atom(depth)
+        while True:
+            self._space()
+            if self.text.startswith("&&", self.position):
+                self.position += 2
+            elif self.text.startswith(",", self.position):
+                # Retain the existing flat request-mapping spelling as well.
+                self.position += 1
+            else:
+                return
+            self.atom(depth)
+
+    def atom(self, depth: int) -> None:
+        self.budget.consume()
+        self.nodes += 1
+        if depth > _MAX_DEPTH or self.nodes > 2 * _MAX_CLAUSES:
+            raise _UnsupportedPredicate
+        self._space()
+        if self.position >= len(self.text):
+            raise _UnsupportedPredicate
+        if self.text[self.position] == "(":
+            if depth >= _MAX_DEPTH:
+                raise _UnsupportedPredicate
+            self.position += 1
+            self.expression(depth + 1)
+            self._space()
+            if not self.text.startswith(")", self.position):
+                raise _UnsupportedPredicate
+            self.position += 1
+            return
+        start = self.position
+        delimiters: list[str] = []
+        while self.position < len(self.text):
+            char = self.text[self.position]
+            if not delimiters and (
+                char in "()," or self.text.startswith(("&&", "||"), self.position)
+            ):
+                break
+            if char in "[{" or (char == "(" and delimiters):
+                delimiters.append({"[": "]", "{": "}", "(": ")"}[char])
+                if depth + len(delimiters) > _MAX_DEPTH:
+                    raise _UnsupportedPredicate
+            elif char in "]})":
+                if not delimiters or delimiters.pop() != char:
+                    raise _UnsupportedPredicate
+            self.position += 1
+        leaf = self.text[start : self.position].strip()
+        if not leaf or delimiters or len(self.leaves) >= _MAX_CLAUSES:
+            raise _UnsupportedPredicate
+        self.leaves.append(leaf)
+
+    def parse(self) -> list[str]:
+        self.expression()
+        self._space()
+        if self.position != len(self.text):
+            raise _UnsupportedPredicate
+        return self.leaves
+
+
+def _media_condition(leaf: str) -> dict[str, Any] | None:
+    name, separator, value = leaf.partition(":")
+    if name not in {"Accept", "Content-Type"} or not separator:
+        return None
+    value = value.strip()
+    if value.startswith("[") and value.endswith("]"):
+        value = value[1:-1]
+    media = [part.strip() for part in value.split(",")]
+    value = ",".join(media)
+    if (
+        not media
+        or len(value) > 256
+        or any(not _MEDIA.fullmatch(part) for part in media)
+    ):
+        raise _UnsupportedPredicate
+    return {"kind": "header", "name": name, "value": value, "negated": False}
+
+
+def parse_predicate(
+    raw: Any,
+) -> tuple[list[str], list[str], list[dict[str, Any]], bool]:
+    """Return no asserted facts unless every positive AND clause is understood.
+
+    Different path predicates in an AND may describe intersections and cannot be
+    emitted as a list of alternative paths. OR/NOT/custom clauses likewise stay
+    unknown instead of turning branches into nonexistent method/path pairs.
+    """
+    if (
+        not isinstance(raw, str)
+        or not raw
+        or len(raw) > _MAX_LENGTH
+        or any(ord(char) < 32 or ord(char) == 127 for char in raw)
+    ):
+        return [], [], [], False
+    text = raw.strip()
+    if text.startswith("{") and text.endswith("}"):
+        text = text[1:-1]
+    paths: list[str] = []
+    methods: set[str] | None = None
+    conditions: list[dict[str, Any]] = []
+    try:
+        for leaf in _Conjunction(text).parse():
+            token, _, rest = leaf.partition(" ")
+            method_set: set[str] | None = None
+            if leaf.startswith("[") and leaf.endswith("]"):
+                values = [part.strip() for part in leaf[1:-1].split(",")]
+                if values and all(value in HTTP_METHODS for value in values):
+                    method_set = set(values)
+                    rest = ""
+            elif token.upper() in HTTP_METHODS:
+                method_set = {token.upper()}
+                rest = rest.strip()
+            if method_set is not None:
+                methods = method_set if methods is None else methods & method_set
+                if not methods:
+                    raise _UnsupportedPredicate
+                if not rest:
+                    continue
+                leaf = (
+                    rest[1:-1].strip()
+                    if rest.startswith("[") and rest.endswith("]")
+                    else rest
+                )
+                if not leaf.startswith("/"):
+                    raise _UnsupportedPredicate
+            if leaf.startswith("/"):
+                if len(leaf) > 1024 or any(char.isspace() for char in leaf):
+                    raise _UnsupportedPredicate
+                if paths and leaf not in paths:
+                    raise _UnsupportedPredicate
+                if not paths:
+                    paths.append(leaf)
+                continue
+            condition = _media_condition(leaf)
+            if condition is None:
+                matched = _LEGACY_CONDITION.fullmatch(leaf)
+                if matched is None or len(matched.group("value")) > 256:
+                    raise _UnsupportedPredicate
+                condition = {
+                    "kind": _LEGACY_KIND[matched.group("kind")],
+                    "name": None,
+                    "value": matched.group("value").strip() or None,
+                    "negated": False,
+                }
+            if len(conditions) >= _MAX_CONDITIONS:
+                raise _UnsupportedPredicate
+            conditions.append(condition)
+    except _UnsupportedPredicate:
+        return [], [], [], False
+    if not paths:
+        # A method/header-only predicate leaves the path unrestricted. The
+        # current route projection cannot express that for exact path queries.
+        return [], [], [], False
+    return paths, sorted(methods or ()), conditions, True

spring_runtime_mcp/adapters/mappings.py

@@ -0,0 +1,294 @@
+"""Normalize MVC dispatcherServlets and WebFlux dispatcherHandlers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..models.common import AnalysisBudget
+
+from ..contracts.definitions import glob_matches
+
+from .mapping_predicates import (
+    HTTP_METHODS as _METHODS,
+    parse_predicate as _parse_predicate,
+)
+
+
+def _servlet_may_cover(query: str | None, mapping: str) -> bool:
+    if query is None or mapping in {"/", "/*", "*"}:
+        return True
+    if not mapping.startswith("/"):
+        return False
+    mapping_prefix = mapping.split("*", 1)[0]
+    query_prefix = query.split("*", 1)[0]
+    if mapping_prefix.startswith(query_prefix) or query_prefix.startswith(
+        mapping_prefix
+    ):
+        return True
+    return glob_matches(mapping, query) or glob_matches(query, mapping)
+
+
+def _non_dispatcher_routes_unobserved(
+    mappings: dict[str, Any], path_pattern: str | None
+) -> bool:
+    """Actuator mappings only enumerate DispatcherServlet routes.
+
+    A Jersey/other ServletContainer registered under a matching URL space means
+    the absence of a DispatcherServlet record is not evidence of absence.
+    """
+    servlets = mappings.get("servlets")
+    if servlets is None:
+        return False
+    if not isinstance(servlets, list):
+        return True
+    for servlet in servlets:
+        if not isinstance(servlet, dict):
+            continue
+        if (
+            servlet.get("className")
+            == "org.springframework.web.servlet.DispatcherServlet"
+        ):
+            continue
+        raw = servlet.get("mappings")
+        if not isinstance(raw, list):
+            return True
+        for mapping in raw:
+            if isinstance(mapping, str) and _servlet_may_cover(path_pattern, mapping):
+                return True
+    return False
+
+
+def _conditions(raw: dict[str, Any]) -> tuple[list[dict[str, Any]], bool]:
+    rows: list[dict[str, Any]] = []
+    complete = True
+    for kind, key in (
+        ("consumes", "consumes"),
+        ("produces", "produces"),
+        ("header", "headers"),
+        ("param", "params"),
+    ):
+        values = raw.get(key, [])
+        if not isinstance(values, list):
+            complete = False
+            continue
+        for value in values:
+            if len(rows) >= 16:
+                complete = False
+                break
+            if isinstance(value, dict):
+                media = value.get("mediaType", value.get("value"))
+                rows.append(
+                    {
+                        "kind": kind,
+                        "name": value.get("name")
+                        if isinstance(value.get("name"), str)
+                        else None,
+                        "value": media
+                        if isinstance(media, str) and len(media) <= 256
+                        else None,
+                        "negated": bool(value.get("negated", False)),
+                    }
+                )
+            elif isinstance(value, str) and len(value) <= 256:
+                rows.append(
+                    {"kind": kind, "name": None, "value": value, "negated": False}
+                )
+    return rows, complete
+
+
+def normalize_mappings(
+    body: Any,
+    *,
+    path_pattern: str | None,
+    http_method: str | None,
+    controller_pattern: str | None,
+    context_id: str | None,
+) -> tuple[list[dict[str, Any]], list[str]]:
+    if not isinstance(body, dict) or not isinstance(body.get("contexts"), dict):
+        raise ValueError("INVALID_MAPPINGS_SHAPE")
+    gaps: set[str] = set()
+    budget = AnalysisBudget()
+    found: list[dict[str, Any]] = []
+    for context_name in sorted(body["contexts"]):
+        if not isinstance(context_name, str):
+            gaps.add("INVALID_CONTEXT_NAME")
+            continue
+        if context_id and context_name != context_id:
+            continue
+        context = body["contexts"][context_name]
+        if not isinstance(context, dict):
+            gaps.add("INVALID_CONTEXT")
+            continue
+        parent = context.get("parentId")
+        mappings = context.get("mappings")
+        if not isinstance(mappings, dict):
+            gaps.add("MAPPINGS_UNOBSERVED")
+            continue
+        if _non_dispatcher_routes_unobserved(mappings, path_pattern):
+            gaps.add("NON_DISPATCHER_SERVLET_ROUTES_UNOBSERVED")
+        trees = (
+            ("mvc", "dispatcherServlets"),
+            ("webflux", "dispatcherHandlers"),
+        )
+        for stack, tree_name in trees:
+            tree = mappings.get(tree_name)
+            if tree is None:
+                continue
+            if not isinstance(tree, dict):
+                gaps.add("MAPPINGS_UNOBSERVED")
+                continue
+            for dispatcher in sorted(tree):
+                records = tree[dispatcher]
+                if not isinstance(records, list):
+                    gaps.add("MAPPINGS_UNOBSERVED")
+                    continue
+                for record in records:
+                    budget.consume()
+                    if not isinstance(record, dict):
+                        gaps.add("MAPPING_RECORD_UNREADABLE")
+                        continue
+                    details = record.get("details")
+                    method = (
+                        details.get("handlerMethod")
+                        if isinstance(details, dict)
+                        else None
+                    )
+                    conditions_raw = (
+                        details.get("requestMappingConditions")
+                        if isinstance(details, dict)
+                        else None
+                    )
+                    handler_function = (
+                        details.get("handlerFunction")
+                        if isinstance(details, dict)
+                        else None
+                    )
+                    if not isinstance(handler_function, str):
+                        nested = record.get("handlerFunction")
+                        handler_function = nested if isinstance(nested, str) else None
+                    class_name = (
+                        method.get("className") if isinstance(method, dict) else None
+                    )
+                    method_name = (
+                        method.get("name") if isinstance(method, dict) else None
+                    )
+                    descriptor = (
+                        method.get("descriptor") if isinstance(method, dict) else None
+                    )
+                    handler = record.get("handler")
+                    if (
+                        not isinstance(class_name, str)
+                        and isinstance(handler, str)
+                        and "#" in handler
+                    ):
+                        class_name, _, method_name = handler.partition("#")
+                    patterns = []
+                    methods: list[str] = []
+                    condition_rows: list[dict[str, Any]] = []
+                    complete = isinstance(conditions_raw, dict)
+                    methods_complete = isinstance(conditions_raw, dict)
+                    predicate_parsed = False
+                    if isinstance(conditions_raw, dict):
+                        raw_patterns = conditions_raw.get("patterns")
+                        raw_methods = conditions_raw.get("methods")
+                        if isinstance(raw_patterns, list):
+                            for item in raw_patterns:
+                                if isinstance(item, str) and 0 < len(item) <= 1024:
+                                    patterns.append(item)
+                                else:
+                                    complete = False
+                                    gaps.add("MAPPING_PATTERN_UNREADABLE")
+                            if len(patterns) > 16:
+                                patterns = patterns[:16]
+                                complete = False
+                                gaps.add("MAPPING_PATH_LIMIT")
+                        else:
+                            complete = False
+                            gaps.add("MAPPING_PATTERN_UNREADABLE")
+                        if isinstance(raw_methods, list):
+                            for item in raw_methods:
+                                if isinstance(item, str) and item in _METHODS:
+                                    methods.append(item)
+                                else:
+                                    complete = False
+                                    methods_complete = False
+                                    gaps.add("MAPPING_METHOD_UNREADABLE")
+                            if len(methods) > 9:
+                                methods = methods[:9]
+                                complete = False
+                                gaps.add("MAPPING_METHOD_LIMIT")
+                        else:
+                            complete = False
+                            methods_complete = False
+                            gaps.add("MAPPING_METHOD_UNREADABLE")
+                        condition_rows, condition_complete = _conditions(conditions_raw)
+                        complete = complete and condition_complete
+                    elif isinstance(record.get("predicate"), str):
+                        (
+                            patterns,
+                            methods,
+                            condition_rows,
+                            predicate_parsed,
+                        ) = _parse_predicate(record["predicate"])
+                        if predicate_parsed:
+                            complete = True
+                            methods_complete = True
+                        else:
+                            patterns = []
+                            methods = []
+                            condition_rows = []
+                            complete = False
+                            methods_complete = False
+                            gaps.add("MAPPING_PREDICATE_UNPARSED")
+                    else:
+                        complete = False
+                        methods_complete = False
+                        gaps.add("MAPPING_CONDITIONS_UNOBSERVED")
+                    if path_pattern and not any(
+                        glob_matches(path_pattern, pattern) for pattern in patterns
+                    ):
+                        continue
+                    unrestricted = not methods and methods_complete
+                    if http_method and not unrestricted and http_method not in methods:
+                        continue
+                    if controller_pattern and not (
+                        isinstance(class_name, str)
+                        and glob_matches(controller_pattern, class_name)
+                    ):
+                        continue
+                    found.append(
+                        {
+                            "contextId": context_name,
+                            "parentContextId": parent
+                            if isinstance(parent, str)
+                            else None,
+                            "stack": stack,
+                            "dispatcherName": dispatcher
+                            if isinstance(dispatcher, str)
+                            else None,
+                            "paths": patterns,
+                            "httpMethods": methods,
+                            "methodsUnrestricted": unrestricted,
+                            "controllerClass": class_name
+                            if isinstance(class_name, str)
+                            else None,
+                            "handlerMethod": method_name
+                            if isinstance(method_name, str)
+                            else None,
+                            "descriptor": descriptor
+                            if isinstance(descriptor, str)
+                            else None,
+                            "handlerKind": "method"
+                            if isinstance(method, dict)
+                            else "function"
+                            if predicate_parsed or handler_function
+                            else "unknown",
+                            "conditions": condition_rows,
+                            "matchingComplete": complete,
+                        }
+                    )
+    items = []
+    for index, row in enumerate(found, start=1):
+        row["id"] = f"mapping_{index:06d}"
+        items.append(row)
+    return items, sorted(gaps)