feat: Spring Boot parity for observability, actuator & configuration (v26.06.00) (#25)

Spring Boot parity for metrics (Micrometer names + auto-instrumentation), the full /actuator/* surface, Spring-style YAML config + admin display, health-indicator wiring, FastAPI/Starlette adapter parity, plus mongo/installer test fixes. CI green (3.12 + 3.13). See CHANGELOG v26.06.00.

Author: ancongui

.gitignore

@@ -18,3 +18,6 @@ venv/
 .worktrees/
 .idea/
 docs/plans/
+
+# Playwright MCP verification artifacts
+.playwright-mcp/

CHANGELOG.md

@@ -6,6 +6,44 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## v26.06.00 (2026-06-04)
+
+### Spring Boot parity — observability, actuator & configuration
+
+Brings pyfly's observability, actuator, and configuration to drop-in Spring Boot
+parity: identical Micrometer metric names, the full `/actuator/*` endpoint surface,
+and Spring-style YAML config semantics (Spring's `management.*` key structure under
+the `pyfly.*` namespace; legacy keys still work).
+
+- **Observability.** HTTP auto-instrumentation now emits Micrometer's
+  `http_server_requests_seconds` (count/sum + `_max` gauge; optional histogram)
+  tagged `method`/`uri` (templated, cardinality-safe)/`status`/`outcome`/`exception`.
+  The metrics filter is wired directly in `create_app` (it was previously a bean
+  built too late to ever join the chain, so HTTP metrics were silently never
+  collected). Process/system meters use Micrometer names (`process_uptime_seconds`,
+  `process_cpu_usage`, `system_cpu_count`, …). `@timed`/`@counted` follow Micrometer
+  naming + tags (`class`/`method`/`exception`, `result` for counters).
+- **Actuator.** On by default with Spring-exact secure exposure
+  (`pyfly.management.endpoints.web.exposure.include`, default `health,info`),
+  configurable base-path, and a now-registered `/actuator/prometheus`
+  (pinned to `version=0.0.4`). `/actuator/metrics` returns Micrometer JSON
+  (dot names, `COUNT`/`TOTAL_TIME`/`MAX`, `availableTags`, `?tag=` drill-down).
+  New endpoints: `configprops`, `mappings`, `scheduledtasks`, `threaddump`,
+  `caches`, `conditions`, `httpexchanges`; `/actuator/beans` uses the `contexts`
+  envelope; loggers use the Spring shape (`WARN`/`OFF`, `GET`/`POST /loggers/{name}`,
+  groups). The Starlette and FastAPI adapters share one wiring path.
+- **Health.** Severity-based status aggregation (`UP`/`UNKNOWN`/`OUT_OF_SERVICE`/`DOWN`),
+  503 for down states, `show-details`/`show-components` config, `/health/{component|group}`.
+  The DB and CQRS health indicators are now registered and conform to the protocol.
+- **Configuration.** Relaxed binding (kebab→snake), env-var overrides visible to
+  `@config_properties` binding and type-coerced, ordered property sources, and secret
+  masking (incl. URI userinfo passwords). The admin Configuration/Environment views
+  are sorted, grouped, source-attributed, and masked; the admin Metrics view uses the
+  Prometheus names and is now SSE-push driven.
+- **Fixes.** mongomock + beanie 2.x test compatibility shim; `install.sh` now probes
+  version-suffixed interpreters (`python3.13`/`3.12`) so it no longer aborts when the
+  bare `python3` is an older build.
+
 ## v26.05.12 (2026-05-31)
 
 ### Admin dashboard — responsive cards, fullscreen, navbar polish

install.sh

@@ -164,7 +164,10 @@ uninstall_pyfly() {
 # ── Prerequisite checks ───────────────────────────────────────────────────────
 
 find_python() {
-    for cmd in python3 python; do
+    # Probe version-suffixed interpreters first: on macOS/Homebrew/uv setups the
+    # bare `python3` is often an old system build (e.g. 3.9) while a newer
+    # `python3.12`/`python3.13` is installed alongside it.
+    for cmd in python3.14 python3.13 python3.12 python3 python; do
         if command -v "$cmd" &>/dev/null; then
             local version
             version=$("$cmd" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>/dev/null) || continue

pyproject.toml

@@ -7,7 +7,7 @@ name = "pyfly"
 # CalVer YY.MM.PATCH — package metadata uses PEP 440 normalized form (26.5.4);
 # git tag, GitHub release and human-readable display use leading-zero form
 # (v26.05.04) to match the Java/.NET/Go siblings.
-version = "26.5.12"
+version = "26.6.0"
 description = "The official Python implementation of the Firefly Framework — DI, CQRS, EDA, hexagonal architecture, and more."
 readme = "README.md"
 license = "Apache-2.0"

src/pyfly/__init__.py

@@ -13,4 +13,4 @@
 # limitations under the License.
 """PyFly — Enterprise Python Framework."""
 
-__version__ = "26.05.12"
+__version__ = "26.06.00"

src/pyfly/actuator/adapters/starlette.py

@@ -29,37 +29,49 @@
 
 def make_starlette_actuator_routes(
     registry: ActuatorRegistry,
+    exposed_ids: set[str] | None = None,
+    base_path: str = "/actuator",
 ) -> list[Route]:
-    """Build Starlette ``Route`` objects from all enabled endpoints in *registry*."""
+    """Build Starlette ``Route`` objects from all enabled endpoints in *registry*.
+
+    *exposed_ids* — if provided, only endpoints whose id is in the set are mounted
+    over HTTP (Spring Boot ``management.endpoints.web.exposure``). ``None`` exposes
+    every enabled endpoint (used by low-level callers/tests).
+    *base_path* — the actuator base path (Spring ``management.endpoints.web.base-path``).
+    """
     enabled = registry.get_enabled_endpoints()
+    if exposed_ids is not None:
+        enabled = {eid: ep for eid, ep in enabled.items() if eid in exposed_ids}
+
+    bp = base_path.rstrip("/")
     routes: list[Route] = []
 
-    # Index endpoint: /actuator — lists all enabled endpoints with _links
+    # Index endpoint: /actuator — lists all exposed endpoints with _links
     async def index_endpoint(request: Request) -> JSONResponse:
-        links: dict[str, dict[str, str]] = {"self": {"href": "/actuator"}}
+        links: dict[str, dict[str, str]] = {"self": {"href": bp or "/"}}
         for eid in enabled:
-            links[eid] = {"href": f"/actuator/{eid}"}
+            links[eid] = {"href": f"{bp}/{eid}"}
         if "health" in enabled:
-            links["health/liveness"] = {"href": "/actuator/health/liveness"}
-            links["health/readiness"] = {"href": "/actuator/health/readiness"}
+            links["health/liveness"] = {"href": f"{bp}/health/liveness"}
+            links["health/readiness"] = {"href": f"{bp}/health/readiness"}
         return JSONResponse({"_links": links})
 
-    routes.append(Route("/actuator", index_endpoint, methods=["GET"]))
+    routes.append(Route(bp or "/", index_endpoint, methods=["GET"]))
 
     for eid, ep in enabled.items():
         if isinstance(ep, HealthEndpoint):
-            routes.extend(_make_health_routes(ep))
+            routes.extend(_make_health_routes(ep, bp))
         elif isinstance(ep, LoggersEndpoint):
-            routes.extend(_make_loggers_routes(ep))
+            routes.extend(_make_loggers_routes(ep, bp))
         elif isinstance(ep, PrometheusEndpoint):
-            routes.append(_make_prometheus_route(ep))
+            routes.append(_make_prometheus_route(ep, bp))
         else:
-            routes.append(_make_generic_route(eid, ep))
+            routes.extend(_make_generic_routes(eid, ep, bp))
 
     return routes
 
 
-def _make_prometheus_route(ep: PrometheusEndpoint) -> Route:
+def _make_prometheus_route(ep: PrometheusEndpoint, bp: str) -> Route:
     """Prometheus scrape endpoint — must serve the raw text exposition format
     (``text/plain; version=0.0.4``), not a JSON wrapper."""
 
@@ -70,11 +82,15 @@ async def handler(request: Request) -> Response:
             media_type=data.get("content_type") or "text/plain; version=0.0.4; charset=utf-8",
         )
 
-    return Route("/actuator/prometheus", handler, methods=["GET"])
+    return Route(f"{bp}/prometheus", handler, methods=["GET"])
+
 
+def _make_health_routes(ep: HealthEndpoint, bp: str) -> list[Route]:
+    """Health endpoint returns dynamic status codes (200/503).
 
-def _make_health_routes(ep: HealthEndpoint) -> list[Route]:
-    """Health endpoint returns dynamic status codes (200/503)."""
+    Supports the built-in ``liveness``/``readiness`` probe groups plus a generic
+    ``/health/{path}`` selector for any other group or single component.
+    """
 
     async def handler(request: Request) -> JSONResponse:
         data = await ep.handle()
@@ -91,41 +107,77 @@ async def readiness_handler(request: Request) -> JSONResponse:
         status_code = await ep.get_readiness_status_code()
         return JSONResponse(data, status_code=status_code)
 
+    async def selector_handler(request: Request) -> JSONResponse:
+        # /actuator/health/{path} — a configured group, or a single component.
+        path = request.path_params["path"]
+        data, status_code = await ep.handle_path(path)
+        if data is None:
+            return JSONResponse({"error": f"No such health component or group: {path}"}, status_code=404)
+        return JSONResponse(data, status_code=status_code)
+
     return [
-        Route("/actuator/health", handler, methods=["GET"]),
-        Route("/actuator/health/liveness", liveness_handler, methods=["GET"]),
-        Route("/actuator/health/readiness", readiness_handler, methods=["GET"]),
+        Route(f"{bp}/health", handler, methods=["GET"]),
+        Route(f"{bp}/health/liveness", liveness_handler, methods=["GET"]),
+        Route(f"{bp}/health/readiness", readiness_handler, methods=["GET"]),
+        Route(f"{bp}/health/{{path:path}}", selector_handler, methods=["GET"]),
     ]
 
 
-def _make_loggers_routes(ep: LoggersEndpoint) -> list[Route]:
-    """Loggers endpoint supports GET (list) and POST (change level)."""
+def _make_loggers_routes(ep: LoggersEndpoint, bp: str) -> list[Route]:
+    """Loggers endpoint — Spring Boot shape.
+
+    GET  /loggers            -> levels + loggers + groups
+    GET  /loggers/{name}     -> {configuredLevel, effectiveLevel}
+    POST /loggers/{name}     -> body {"configuredLevel": "DEBUG"} (or null to reset), 204
+    """
 
     async def get_handler(request: Request) -> JSONResponse:
         data = await ep.handle()
         return JSONResponse(data)
 
-    async def post_handler(request: Request) -> JSONResponse:
+    async def get_named_handler(request: Request) -> JSONResponse:
+        name = request.path_params["name"]
+        return JSONResponse(await ep.get_logger(name))
+
+    async def post_named_handler(request: Request) -> Response:
+        name = request.path_params["name"]
         body = await request.body()
         payload = json.loads(body) if body else {}
-        logger_name = payload.get("logger", "ROOT")
-        level = payload.get("level", "INFO")
-        result = await ep.set_logger_level(logger_name, level)
-        if "error" in result:
+        level = payload.get("configuredLevel")
+        result = await ep.set_logger_level(name, level)
+        if isinstance(result, dict) and "error" in result:
             return JSONResponse(result, status_code=400)
-        return JSONResponse(result)
+        return Response(status_code=204)
 
     return [
-        Route("/actuator/loggers", get_handler, methods=["GET"]),
-        Route("/actuator/loggers", post_handler, methods=["POST"]),
+        Route(f"{bp}/loggers", get_handler, methods=["GET"]),
+        Route(f"{bp}/loggers/{{name}}", get_named_handler, methods=["GET"]),
+        Route(f"{bp}/loggers/{{name}}", post_named_handler, methods=["POST"]),
     ]
 
 
-def _make_generic_route(eid: str, ep: object) -> Route:
-    """Generic endpoint — calls ``handle()`` and returns 200 JSON."""
+def _make_generic_routes(eid: str, ep: object, bp: str) -> list[Route]:
+    """Generic endpoint — ``GET /actuator/{id}`` plus an optional
+    ``GET /actuator/{id}/{selector}`` drill-down when the endpoint opts in via
+    ``supports_selector = True``."""
 
     async def handler(request: Request) -> JSONResponse:
-        data = await ep.handle()  # type: ignore[attr-defined]
+        data = await ep.handle({"query": dict(request.query_params)})  # type: ignore[attr-defined]
         return JSONResponse(data)
 
-    return Route(f"/actuator/{eid}", handler, methods=["GET"])
+    routes = [Route(f"{bp}/{eid}", handler, methods=["GET"])]
+
+    if getattr(ep, "supports_selector", False):
+
+        async def selector_handler(request: Request) -> JSONResponse:
+            selector = request.path_params["selector"]
+            data = await ep.handle(  # type: ignore[attr-defined]
+                {"selector": selector, "query": dict(request.query_params)}
+            )
+            if data is None:
+                return JSONResponse({"error": f"No such {eid}: {selector}"}, status_code=404)
+            return JSONResponse(data)
+
+        routes.append(Route(f"{bp}/{eid}/{{selector:path}}", selector_handler, methods=["GET"]))
+
+    return routes

src/pyfly/actuator/endpoints/__init__.py

@@ -14,19 +14,33 @@
 """Built-in actuator endpoint implementations."""
 
 from pyfly.actuator.endpoints.beans_endpoint import BeansEndpoint
+from pyfly.actuator.endpoints.caches_endpoint import CachesEndpoint
+from pyfly.actuator.endpoints.conditions_endpoint import ConditionsEndpoint
+from pyfly.actuator.endpoints.configprops_endpoint import ConfigPropsEndpoint
 from pyfly.actuator.endpoints.env_endpoint import EnvEndpoint
 from pyfly.actuator.endpoints.health_endpoint import HealthEndpoint
+from pyfly.actuator.endpoints.httpexchanges_endpoint import HttpExchangesEndpoint
 from pyfly.actuator.endpoints.info_endpoint import InfoEndpoint
 from pyfly.actuator.endpoints.loggers_endpoint import LoggersEndpoint
+from pyfly.actuator.endpoints.mappings_endpoint import MappingsEndpoint
 from pyfly.actuator.endpoints.metrics_endpoint import MetricsEndpoint
 from pyfly.actuator.endpoints.prometheus_endpoint import PrometheusEndpoint
+from pyfly.actuator.endpoints.scheduledtasks_endpoint import ScheduledTasksEndpoint
+from pyfly.actuator.endpoints.threaddump_endpoint import ThreadDumpEndpoint
 
 __all__ = [
     "BeansEndpoint",
+    "CachesEndpoint",
+    "ConditionsEndpoint",
+    "ConfigPropsEndpoint",
     "EnvEndpoint",
     "HealthEndpoint",
+    "HttpExchangesEndpoint",
     "InfoEndpoint",
     "LoggersEndpoint",
+    "MappingsEndpoint",
     "MetricsEndpoint",
     "PrometheusEndpoint",
+    "ScheduledTasksEndpoint",
+    "ThreadDumpEndpoint",
 ]

src/pyfly/actuator/endpoints/beans_endpoint.py

@@ -11,18 +11,19 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Beans actuator endpoint — lists all registered DI beans."""
+"""Beans actuator endpoint — Spring Boot ``/actuator/beans`` parity."""
 
 from __future__ import annotations
 
+import inspect
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from pyfly.context.application_context import ApplicationContext
 
 
 class BeansEndpoint:
-    """Exposes DI bean registry at ``/actuator/beans``."""
+    """Exposes the DI bean registry at ``/actuator/beans`` (contexts envelope)."""
 
     def __init__(self, context: ApplicationContext) -> None:
         self._context = context
@@ -36,12 +37,39 @@ def enabled(self) -> bool:
         return True
 
     async def handle(self, context: Any = None) -> dict[str, Any]:
+        registrations = self._context.container._registrations
+        type_to_name = {cls: (reg.name or cls.__name__) for cls, reg in registrations.items()}
+
         beans: dict[str, Any] = {}
-        for cls, reg in self._context.container._registrations.items():
+        for cls, reg in registrations.items():
             bean_name = reg.name or cls.__name__
             beans[bean_name] = {
+                "aliases": [],
+                "scope": reg.scope.name.lower(),
                 "type": f"{cls.__module__}.{cls.__qualname__}",
-                "scope": reg.scope.name,
+                "resource": getattr(cls, "__module__", ""),
+                "dependencies": self._dependencies(cls, type_to_name),
+                # pyfly extension — handy in the admin/UI, ignored by Spring tooling.
                 "stereotype": getattr(cls, "__pyfly_stereotype__", "none"),
             }
-        return {"beans": beans}
+
+        return {"contexts": {"application": {"beans": beans}}}
+
+    @staticmethod
+    def _dependencies(cls: type, type_to_name: dict[type, str]) -> list[str]:
+        """Resolve constructor dependency bean names from ``__init__`` type hints."""
+        deps: list[str] = []
+        try:
+            signature = inspect.signature(cls)
+        except (ValueError, TypeError):
+            return deps
+        for name, param in signature.parameters.items():
+            if name == "self":
+                continue
+            annotation = param.annotation
+            dep_name = type_to_name.get(annotation)
+            if dep_name:
+                deps.append(dep_name)
+            elif annotation is not inspect.Parameter.empty:
+                deps.append(getattr(annotation, "__name__", str(annotation)))
+        return deps