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

spring_runtime_mcp/transport/actuator_http.py

@@ -0,0 +1,459 @@
+"""Stdlib GET connector for one registered actuator origin.
+
+This is the only production module allowed to import http.client. It never
+follows redirects and never reads more than max_bytes + 1 bytes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import http.client
+import ipaddress
+import re
+import socket
+import ssl
+import threading
+import time
+import zlib
+from typing import Any, cast
+from urllib.parse import urlsplit
+
+from .response_gate import (
+    HEALTH_ENDPOINTS,
+    MAX_UPSTREAM_BYTES,
+    EndpointReadError,
+    HttpResponse,
+    _json_media,
+)
+from ..models.common import NormalizationError
+
+_PATHS = {
+    "beans": "/actuator/beans",
+    "conditions": "/actuator/conditions",
+    "health": "/actuator/health",
+    "health-liveness": "/actuator/health/liveness",
+    "health-readiness": "/actuator/health/readiness",
+    "mappings": "/actuator/mappings",
+    "flyway": "/actuator/flyway",
+    "liquibase": "/actuator/liquibase",
+    "startup": "/actuator/startup",
+    "openapi": "/actuator/openapi",
+    "env": "/actuator/env",
+    "configprops": "/actuator/configprops",
+}
+_MAX_HEADER_BYTES = 32 * 1024
+_CONNECT_TIMEOUT = 2.0
+
+
+class _HeaderReader:
+    """Limit status and header bytes before http.client accumulates them."""
+
+    def __init__(self, stream: Any) -> None:
+        self.stream = stream
+        self.remaining = _MAX_HEADER_BYTES
+
+    def readline(self, size: int = -1) -> bytes:
+        limit = self.remaining + 1
+        if size >= 0:
+            limit = min(limit, size)
+        line: bytes = self.stream.readline(limit)
+        if len(line) > self.remaining:
+            raise NormalizationError("RESPONSE_HEADERS_TOO_LARGE")
+        self.remaining -= len(line)
+        return line
+
+    def close(self) -> None:
+        self.stream.close()
+
+
+class _HeaderBoundedResponse(http.client.HTTPResponse):
+    def begin(self) -> None:
+        original = self.fp
+        if original is None:
+            raise http.client.ResponseNotReady()
+        bounded = _HeaderReader(original)
+        self.fp = bounded  # type: ignore[assignment]
+        try:
+            super().begin()
+        finally:
+            if cast(Any, self.fp) is bounded:
+                self.fp = original
+
+
+def _parse_base(url: str) -> tuple[str, str, int]:
+    if not isinstance(url, str) or not url or len(url) > 2048:
+        raise ValueError("INVALID_BASE_URL")
+    if any(ord(char) <= 32 or ord(char) == 127 for char in url) or "\\" in url:
+        raise ValueError("INVALID_BASE_URL")
+    parts = urlsplit(url)
+    host = parts.hostname
+    if (
+        parts.scheme not in {"http", "https"}
+        or host is None
+        or parts.username
+        or parts.password
+        or parts.path not in {"", "/"}
+        or parts.query
+        or parts.fragment
+    ):
+        raise ValueError("INVALID_BASE_URL")
+    port = parts.port
+    if port is None:
+        port = 443 if parts.scheme == "https" else 80
+    if not 1 <= port <= 65535 or "%" in host:
+        raise ValueError("INVALID_BASE_URL")
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        if re.fullmatch(
+            r"(?:0[xX][0-9a-fA-F]+|[0-9]+)(?:\.(?:0[xX][0-9a-fA-F]+|[0-9]+))*", host
+        ):
+            raise ValueError("INVALID_BASE_URL") from None
+        host = host.removesuffix(".").encode("idna").decode("ascii").lower()
+        if len(host) > 253 or any(
+            re.fullmatch(r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?", label) is None
+            for label in host.split(".")
+        ):
+            raise ValueError("INVALID_BASE_URL")
+    else:
+        _loopback(str(address))
+        host = str(address)
+    return parts.scheme, host, port
+
+
+def _loopback(host: str) -> str:
+    address = ipaddress.ip_address(host)
+    effective = (
+        address.ipv4_mapped
+        if isinstance(address, ipaddress.IPv6Address)
+        and address.ipv4_mapped is not None
+        else address
+    )
+    if not (
+        effective in ipaddress.ip_network("127.0.0.0/8")
+        if effective.version == 4
+        else effective == ipaddress.ip_address("::1")
+    ):
+        raise NormalizationError("ADDRESS_DENIED")
+    return str(effective)
+
+
+class _ExchangeState:
+    """Own the real socket even when HTTPResponse detaches it from the client."""
+
+    def __init__(self, timeout: float) -> None:
+        self.deadline = time.monotonic() + timeout
+        self.cancelled = threading.Event()
+        self.lock = threading.Lock()
+        self.connection: http.client.HTTPConnection | None = None
+        self.sock: socket.socket | None = None
+
+    def remaining(self) -> float:
+        remaining = self.deadline - time.monotonic()
+        if self.cancelled.is_set() or remaining <= 0:
+            raise TimeoutError()
+        return remaining
+
+    def bind(self, connection: http.client.HTTPConnection) -> None:
+        with self.lock:
+            self.connection = connection
+        if self.cancelled.is_set():
+            connection.close()
+            raise TimeoutError()
+
+    def bind_socket(self, sock: socket.socket) -> None:
+        with self.lock:
+            self.sock = sock
+        if self.cancelled.is_set():
+            sock.close()
+            raise TimeoutError()
+
+    def abort(self) -> None:
+        self.cancelled.set()
+        with self.lock:
+            connection, sock = self.connection, self.sock
+        if sock is not None:
+            with contextlib.suppress(OSError):
+                sock.shutdown(socket.SHUT_RDWR)
+            sock.close()
+        if connection is not None:
+            connection.close()
+
+
+class _VerifiedHTTPSConnection(http.client.HTTPSConnection):
+    def __init__(
+        self, host: str, port: int, timeout: float, state: _ExchangeState
+    ) -> None:
+        self._tls_context = ssl.create_default_context()
+        self._state = state
+        super().__init__(host, port, timeout=timeout, context=self._tls_context)
+
+    def connect(self) -> None:
+        # The injected connector pins and verifies the raw peer before TLS.
+        http.client.HTTPConnection.connect(self)
+        assert self.sock is not None
+        wrapped = self._tls_context.wrap_socket(
+            self.sock, server_hostname=self.host, do_handshake_on_connect=False
+        )
+        self.sock = wrapped
+        self._state.bind_socket(wrapped)
+        wrapped.settimeout(self._state.remaining())
+        wrapped.do_handshake()
+
+
+def _read_bounded(
+    response: http.client.HTTPResponse, max_bytes: int, state: _ExchangeState
+) -> bytes:
+    remaining = max_bytes + 1
+    chunks: list[bytes] = []
+    while remaining:
+        state.remaining()
+        chunk = response.read(min(65536, remaining))
+        if not chunk:
+            if response.length is not None and response.length > 0:
+                raise NormalizationError("INCOMPLETE_RESPONSE")
+            break
+        chunks.append(chunk)
+        remaining -= len(chunk)
+    return b"".join(chunks)
+
+
+def _read_gzip_bounded(
+    response: http.client.HTTPResponse, max_bytes: int, state: _ExchangeState
+) -> bytes:
+    decoder = zlib.decompressobj(16 + zlib.MAX_WBITS)
+    encoded = decoded = 0
+    chunks: list[bytes] = []
+    try:
+        while True:
+            state.remaining()
+            chunk = response.read(min(65536, max_bytes - encoded + 1))
+            if not chunk:
+                if response.length is not None and response.length > 0:
+                    raise NormalizationError("INCOMPLETE_RESPONSE")
+                break
+            encoded += len(chunk)
+            if encoded > max_bytes:
+                raise NormalizationError("RESPONSE_TOO_LARGE")
+            output = decoder.decompress(chunk, max_bytes - decoded + 1)
+            decoded += len(output)
+            if decoded > max_bytes or decoder.unconsumed_tail:
+                raise NormalizationError("RESPONSE_TOO_LARGE")
+            if decoder.unused_data:
+                raise NormalizationError("INVALID_COMPRESSED_DATA")
+            chunks.append(output)
+    except zlib.error:
+        raise NormalizationError("INVALID_COMPRESSED_DATA") from None
+    if not decoder.eof:
+        raise NormalizationError("INVALID_COMPRESSED_DATA")
+    return b"".join(chunks)
+
+
+class ActuatorHttpTransport:
+    """Map a logical endpoint id onto one configured origin. No caller URLs."""
+
+    def __init__(
+        self, base_url: str, *, targets: frozenset[str], bearer_token: str | None = None
+    ) -> None:
+        if not targets or any(not isinstance(target, str) for target in targets):
+            raise ValueError("INVALID_TARGET_REGISTRATION")
+        scheme, host, port = _parse_base(base_url)
+        self._scheme = scheme
+        self._host = host
+        self._port = port
+        self._targets = targets
+        if bearer_token is not None and (
+            not isinstance(bearer_token, str)
+            or not 1 <= len(bearer_token) <= 8192
+            or re.fullmatch(r"[A-Za-z0-9._~+/-]+=*", bearer_token) is None
+        ):
+            raise ValueError("INVALID_CREDENTIAL_REGISTRATION")
+        self._bearer_token = bearer_token
+
+    async def request(
+        self,
+        target_id: str,
+        endpoint_id: str,
+        *,
+        method: str,
+        follow_redirects: bool,
+        timeout: float,
+        max_bytes: int,
+    ) -> HttpResponse:
+        state = _ExchangeState(float(timeout))
+        worker = asyncio.create_task(
+            asyncio.to_thread(
+                self._exchange,
+                target_id,
+                endpoint_id,
+                method,
+                follow_redirects,
+                timeout,
+                max_bytes,
+                state,
+            )
+        )
+        try:
+            return await asyncio.wait_for(
+                asyncio.shield(worker), timeout=float(timeout)
+            )
+        except (TimeoutError, asyncio.CancelledError):
+            state.abort()
+            # Socket shutdown wakes a blocked body read; always collect worker
+            # exceptions. A resolver syscall itself is owned by the OS.
+            with contextlib.suppress(Exception, asyncio.CancelledError):
+                await asyncio.wait_for(asyncio.shield(worker), timeout=0.25)
+            if not worker.done():
+                worker.add_done_callback(
+                    lambda task: task.exception() if not task.cancelled() else None
+                )
+            raise
+        except ssl.SSLError:
+            raise NormalizationError("TLS_VERIFICATION_FAILED") from None
+
+    def _open(
+        self, timeout: float, state: _ExchangeState
+    ) -> http.client.HTTPConnection:
+        if self._scheme == "https":
+            connection: http.client.HTTPConnection = _VerifiedHTTPSConnection(
+                self._host, self._port, timeout, state
+            )
+        else:
+            connection = http.client.HTTPConnection(
+                self._host, self._port, timeout=timeout
+            )
+
+        def connect(
+            address: Any, timeout: Any = None, source_address: Any = None
+        ) -> socket.socket:
+            if source_address is not None or address != (self._host, self._port):
+                raise NormalizationError("ADDRESS_DENIED")
+            records: list[tuple[socket.AddressFamily, socket.SocketKind, int, str, Any]]
+            try:
+                literal = ipaddress.ip_address(self._host)
+            except ValueError:
+                records = socket.getaddrinfo(
+                    self._host, self._port, type=socket.SOCK_STREAM
+                )
+            else:
+                family = socket.AF_INET if literal.version == 4 else socket.AF_INET6
+                records = [
+                    (family, socket.SOCK_STREAM, 6, "", (str(literal), self._port))
+                ]
+            if not records or len(records) > 16:
+                raise NormalizationError("ADDRESS_DENIED")
+            for family, kind, _, _, endpoint in records:
+                resolved_host = endpoint[0]
+                if (
+                    family not in (socket.AF_INET, socket.AF_INET6)
+                    or kind != socket.SOCK_STREAM
+                    or endpoint[1] != self._port
+                    or not isinstance(resolved_host, str)
+                    or "%" in resolved_host
+                ):
+                    raise NormalizationError("ADDRESS_DENIED")
+                _loopback(resolved_host)
+            connect_deadline = min(state.deadline, time.monotonic() + _CONNECT_TIMEOUT)
+            for index, (family, _, _, _, endpoint) in enumerate(records):
+                sock = socket.socket(family, socket.SOCK_STREAM)
+                state.bind_socket(sock)
+                try:
+                    remaining_connect = connect_deadline - time.monotonic()
+                    if remaining_connect <= 0:
+                        raise TimeoutError()
+                    sock.settimeout(min(remaining_connect, state.remaining()))
+                    sock.connect(endpoint)
+                    peer = sock.getpeername()
+                    if (
+                        _loopback(peer[0]) != _loopback(endpoint[0])
+                        or peer[1] != self._port
+                    ):
+                        raise NormalizationError("PEER_MISMATCH")
+                    if connect_deadline <= time.monotonic():
+                        raise TimeoutError()
+                    sock.settimeout(state.remaining())
+                    return sock
+                except OSError:
+                    sock.close()
+                    if index == len(records) - 1:
+                        raise
+                except BaseException:
+                    sock.close()
+                    raise
+            raise NormalizationError("ADDRESS_DENIED")
+
+        # http.client's socket factory is the narrow seam that preserves its
+        # framing while preventing a second hostname lookup or proxy handling.
+        setattr(connection, "_create_connection", connect)
+        connection.response_class = _HeaderBoundedResponse
+        connection.set_debuglevel(0)
+        return connection
+
+    def _exchange(
+        self,
+        target_id: str,
+        endpoint_id: str,
+        method: str,
+        follow_redirects: bool,
+        timeout: float,
+        max_bytes: int,
+        state: _ExchangeState,
+    ) -> HttpResponse:
+        if method != "GET" or follow_redirects:
+            raise AssertionError("READ_ONLY_TRANSPORT")
+        if target_id not in self._targets or endpoint_id not in _PATHS:
+            raise AssertionError("UNREGISTERED_ENDPOINT")
+        if (
+            isinstance(timeout, bool)
+            or not isinstance(timeout, (int, float))
+            or not 0 < float(timeout) <= 60
+        ):
+            raise AssertionError("INVALID_TIMEOUT")
+        if (
+            isinstance(max_bytes, bool)
+            or not isinstance(max_bytes, int)
+            or not 0 <= max_bytes <= MAX_UPSTREAM_BYTES
+        ):
+            raise AssertionError("INVALID_MAX_BYTES")
+        path = _PATHS[endpoint_id]
+        connection = self._open(float(timeout), state)
+        state.bind(connection)
+        try:
+            state.remaining()
+            headers = {"Accept": "application/json", "Connection": "close"}
+            if self._bearer_token is not None:
+                headers["Authorization"] = "Bearer " + self._bearer_token
+            connection.request(
+                method="GET",
+                url=path,
+                headers=headers,
+            )
+            upstream = connection.getresponse()
+            if upstream.status != 200 and not (
+                upstream.status == 503 and endpoint_id in HEALTH_ENDPOINTS
+            ):
+                # The response gate maps rejected statuses without inspecting
+                # their bodies. Avoid spending the read budget on error pages.
+                return HttpResponse(upstream.status, "", b"")
+            content_type = upstream.getheader("Content-Type") or ""
+            if _json_media(content_type) is None:
+                return HttpResponse(upstream.status, content_type, b"")
+            content_encoding = upstream.getheader("Content-Encoding")
+            encoding = (
+                content_encoding.strip().lower()
+                if content_encoding is not None
+                else "identity"
+            )
+            if encoding not in {"identity", "gzip"}:
+                raise EndpointReadError(
+                    "UNSUPPORTED_CONTENT_ENCODING", endpoint_id, upstream.status
+                )
+            body = (
+                _read_gzip_bounded(upstream, max_bytes, state)
+                if encoding == "gzip"
+                else _read_bounded(upstream, max_bytes, state)
+            )
+            return HttpResponse(upstream.status, content_type, body)
+        finally:
+            connection.close()

spring_runtime_mcp/transport/bounded_json.py

@@ -0,0 +1,144 @@
+"""Strict bounded parsing for offline observations and future safe readers."""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+from ..models.common import NormalizationError, remaining_seconds
+
+
+def _pairs(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise NormalizationError("DUPLICATE_JSON_KEY")
+        result[key] = value
+    return result
+
+
+def _constant(value: str) -> None:
+    raise NormalizationError("INVALID_JSON_NUMBER")
+
+
+def _integer(value: str) -> int:
+    # No diagnostic identifier or checksum needs unbounded arbitrary precision.
+    # Limit before int() allocates a huge integer or hits interpreter limits.
+    if len(value.lstrip("-")) > 128:
+        raise NormalizationError("INVALID_JSON_NUMBER")
+    return int(value)
+
+
+def loads_bounded(
+    data: bytes,
+    *,
+    max_bytes: int = 8 * 1024 * 1024,
+    max_depth: int = 64,
+    max_nodes: int = 100_000,
+) -> dict[str, Any]:
+    if len(data) > max_bytes:
+        raise NormalizationError("RESPONSE_TOO_LARGE")
+    try:
+        text = data.decode("utf-8")
+        depth = nodes = index = 0
+        while index < len(text):
+            if index % 2048 == 0:
+                remaining_seconds()
+            char = text[index]
+            if char == '"':
+                nodes += 1
+                index += 1
+                while index < len(text):
+                    if text[index] == "\\":
+                        index += 2
+                    elif text[index] == '"':
+                        index += 1
+                        break
+                    else:
+                        index += 1
+            elif char in "{[":
+                depth += 1
+                nodes += 1
+                index += 1
+            elif char in "}]":
+                depth -= 1
+                index += 1
+            elif char in " \t\n\r,:":
+                index += 1
+            else:
+                nodes += 1
+                while index < len(text) and text[index] not in " \t\r\n,]}:":
+                    index += 1
+            if depth > max_depth or nodes > max_nodes:
+                raise NormalizationError("NORMALIZATION_LIMIT")
+        value = json.loads(
+            text, object_pairs_hook=_pairs, parse_constant=_constant, parse_int=_integer
+        )
+        if not isinstance(value, dict):
+            raise NormalizationError("UNSUPPORTED_SHAPE")
+        validate_tree(
+            value, max_bytes=max_bytes, max_depth=max_depth, max_nodes=max_nodes
+        )
+        return value
+    except (UnicodeError, ValueError, RecursionError) as exc:
+        if isinstance(exc, NormalizationError):
+            raise
+        raise NormalizationError("INVALID_JSON") from None
+
+
+def validate_tree(
+    value: Any,
+    *,
+    max_bytes: int = 8 * 1024 * 1024,
+    max_depth: int = 64,
+    max_nodes: int = 100_000,
+) -> None:
+    stack = [(value, 0)]
+    seen: set[int] = set()
+    nodes = size = 0
+    while stack:
+        if nodes % 256 == 0:
+            remaining_seconds()
+        item, depth = stack.pop()
+        nodes += 1
+        if depth > max_depth or nodes > max_nodes:
+            raise NormalizationError("NORMALIZATION_LIMIT")
+        if isinstance(item, (dict, list)):
+            if id(item) in seen:
+                raise NormalizationError("NON_TREE_JSON")
+            seen.add(id(item))
+            if nodes + len(item) > max_nodes:
+                raise NormalizationError("NORMALIZATION_LIMIT")
+            if isinstance(item, dict):
+                if any(not isinstance(k, str) for k in item):
+                    raise NormalizationError("INVALID_JSON")
+                stack.extend((k, depth + 1) for k in item)
+                stack.extend((v, depth + 1) for v in item.values())
+            else:
+                stack.extend((v, depth + 1) for v in item)
+            size += len(item) * 2 + 2
+        elif isinstance(item, str):
+            if len(item) > max_bytes:
+                raise NormalizationError("RESPONSE_TOO_LARGE")
+            try:
+                size += len(json.dumps(item, ensure_ascii=False).encode("utf-8"))
+            except UnicodeError:
+                raise NormalizationError("INVALID_JSON") from None
+        elif item is None:
+            size += 4
+        elif type(item) is bool:
+            size += 4 if item else 5
+        elif type(item) is int:
+            if item.bit_length() > 426:
+                raise NormalizationError("INVALID_JSON_NUMBER")
+            integer_text = str(item)
+            if len(integer_text.lstrip("-")) > 128:
+                raise NormalizationError("INVALID_JSON_NUMBER")
+            size += len(integer_text)
+        elif isinstance(item, float) and math.isfinite(item):
+            size += len(json.dumps(item, allow_nan=False))
+        else:
+            raise NormalizationError("INVALID_JSON")
+        if size > max_bytes:
+            raise NormalizationError("RESPONSE_TOO_LARGE")

spring_runtime_mcp/transport/replay_files.py

@@ -0,0 +1,71 @@
+"""Bounded, no-symlink replay file reads; not an arbitrary ingestion tool."""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+from ..models.common import NormalizationError
+
+
+def read_replay_file(
+    root: Path, path: Path, *, max_bytes: int = 8 * 1024 * 1024
+) -> bytes:
+    descriptors: list[int] = []
+    try:
+        relative = path.relative_to(root)
+        parts = relative.parts
+        if (
+            not parts
+            or any(p in ("", ".", "..") for p in parts)
+            or not hasattr(os, "O_NOFOLLOW")
+        ):
+            raise NormalizationError("FIXTURE_PATH_DENIED")
+        if type(max_bytes) is not int or not 0 < max_bytes <= 8 * 1024 * 1024:
+            raise NormalizationError("FIXTURE_PATH_DENIED")
+        absolute_root = root.absolute()
+        descriptors.append(
+            os.open(absolute_root.anchor, os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC)
+        )
+        for part in absolute_root.parts[1:]:
+            if part in (".", ".."):
+                raise NormalizationError("FIXTURE_PATH_DENIED")
+            descriptors.append(
+                os.open(
+                    part,
+                    os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC,
+                    dir_fd=descriptors[-1],
+                )
+            )
+        for part in parts[:-1]:
+            descriptors.append(
+                os.open(
+                    part,
+                    os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC,
+                    dir_fd=descriptors[-1],
+                )
+            )
+        descriptor = os.open(
+            parts[-1],
+            os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC,
+            dir_fd=descriptors[-1],
+        )
+        descriptors.append(descriptor)
+        if not stat.S_ISREG(os.fstat(descriptor).st_mode):
+            raise NormalizationError("FIXTURE_PATH_DENIED")
+        result = bytearray()
+        while True:
+            chunk = os.read(descriptor, min(65536, max_bytes + 1 - len(result)))
+            if not chunk:
+                return bytes(result)
+            result.extend(chunk)
+            if len(result) > max_bytes:
+                raise NormalizationError("RESPONSE_TOO_LARGE")
+    except NormalizationError:
+        raise
+    except (OSError, ValueError):
+        raise NormalizationError("FIXTURE_PATH_DENIED") from None
+    finally:
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)