csrd-versioning 0.1.0__py3-none-any.whl

csrd/versioning/actuator/plugins/env/plugin.py

@@ -0,0 +1,145 @@
+"""Spring Boot-style env actuator plugin."""
+
+import os
+from collections.abc import Mapping
+from typing import Any
+
+from fastapi import APIRouter, FastAPI
+
+from ..base import ActuatorLink, BaseActuatorPlugin
+from .registry import (
+    PropertySourceRegistry,
+    SanitizationConfig,
+    create_property_source_registry,
+)
+
+
+def _active_profiles() -> list[str]:
+    """Parse SPRING_PROFILES_ACTIVE environment variable."""
+    return [
+        profile.strip()
+        for profile in os.environ.get("SPRING_PROFILES_ACTIVE", "").split(",")
+        if profile.strip()
+    ]
+
+
+def _default_profiles() -> list[str]:
+    """Parse SPRING_PROFILES_DEFAULT environment variable, defaulting to 'default'."""
+    return [
+        profile.strip()
+        for profile in os.environ.get("SPRING_PROFILES_DEFAULT", "default").split(",")
+        if profile.strip()
+    ]
+
+
+class EnvActuatorPlugin(BaseActuatorPlugin):
+    """Expose Spring-style ``/actuator/env`` runtime environment metadata.
+
+    The plugin aggregates property sources (environment variables, system info,
+    Docker config) and exposes them via the /env and /env/{toMatch} endpoints.
+    """
+
+    name = "env"
+
+    def __init__(
+        self,
+        registry: PropertySourceRegistry | None = None,
+        *,
+        sanitization: SanitizationConfig | None = None,
+    ) -> None:
+        """Initialize the env plugin.
+
+        Args:
+            registry: PropertySourceRegistry for aggregating property sources.
+                     If None, creates a default registry with built-in providers.
+            sanitization: Redaction configuration passed to the default registry.
+                         Ignored when ``registry`` is provided explicitly.
+
+        Note:
+            Runtime environment values may change during process lifetime,
+            so caching is disabled (cache_enabled=False).
+        """
+        super().__init__(cache_enabled=False)
+        self.registry = registry or create_property_source_registry(
+            sanitization=sanitization,
+        )
+
+    @classmethod
+    def with_providers(
+        cls,
+        *,
+        sanitization: SanitizationConfig | None = None,
+        **providers: Any,
+    ) -> "EnvActuatorPlugin":
+        """Create an EnvActuatorPlugin with custom property source providers.
+
+        Args:
+            sanitization: Redaction configuration for the registry.
+            **providers: Named property source providers to register.
+                        Each keyword argument becomes a provider name.
+
+        Returns:
+            A new EnvActuatorPlugin instance with the providers registered.
+
+        Example:
+            >>> plugin = EnvActuatorPlugin.with_providers(
+            ...     sanitization=SanitizationConfig(show_values=ShowValues.ALWAYS),
+            ...     database=DatabasePropertiesProvider(),
+            ...     features=FeatureFlagsProvider(),
+            ... )
+        """
+        plugin = cls(sanitization=sanitization)
+        plugin.register_property_source_providers(providers)
+        return plugin
+
+    def register_property_source_providers(
+        self,
+        providers: Mapping[str, Any],
+    ) -> None:
+        """Register or override property source providers in the plugin registry."""
+        for name, provider in providers.items():
+            self.registry.register(name, provider)
+
+    def register(
+        self,
+        router: APIRouter,
+        *,
+        app: FastAPI,
+        prefix: str,
+    ) -> Mapping[str, ActuatorLink]:
+        """Register env endpoints on the router.
+
+        Args:
+            router: APIRouter to register endpoints on.
+            app: FastAPI application instance.
+            prefix: URL prefix for actuator endpoints (e.g., '/actuator').
+
+        Returns:
+            Mapping of link names to ActuatorLink objects for the root endpoint.
+        """
+
+        @router.get("/env", include_in_schema=False)
+        async def env() -> dict[str, Any]:
+            """List all property sources and active profiles."""
+            return {
+                "activeProfiles": _active_profiles(),
+                "defaultProfiles": _default_profiles(),
+                "propertySources": self.registry.get_all_sources(),
+            }
+
+        @router.get("/env/{toMatch}", include_in_schema=False)
+        async def env_to_match(toMatch: str) -> dict[str, Any]:
+            """List property sources filtered by key, and active profiles."""
+            return {
+                "activeProfiles": _active_profiles(),
+                "defaultProfiles": _default_profiles(),
+                "propertySources": self.registry.get_all_sources(to_match=toMatch),
+            }
+
+        return {
+            "env": self.build_link(prefix=prefix, route_path="/env"),
+            "env-toMatch": ActuatorLink(
+                href=f"{prefix}/env/{{toMatch}}",
+                templated=True,
+            ),
+        }

csrd/versioning/actuator/plugins/env/providers.py

@@ -0,0 +1,105 @@
+"""Property source providers for the env actuator."""
+
+import os
+import platform
+import sys
+from typing import Any, Protocol
+
+
+class PropertySourceProvider(Protocol):
+    """Contract for objects that provide property sources.
+
+    Property sources are aggregated by the EnvActuatorPlugin and exposed
+    via the /actuator/env and /actuator/env/{toMatch} endpoints.
+    """
+
+    def get_sources(self, to_match: str | None = None) -> list[dict[str, Any]]:
+        """Return property sources, optionally filtered by to_match key.
+
+        Args:
+            to_match: Optional case-insensitive substring to filter property keys.
+                      If provided, only properties with matching keys are returned.
+
+        Returns:
+            List of property source dicts with 'name' and 'properties' keys.
+            Empty list if no sources match the filter.
+        """
+
+
+class SystemEnvironmentProvider:
+    """Expose OS environment variables as a property source."""
+
+    def get_sources(self, to_match: str | None = None) -> list[dict[str, Any]]:
+        """Return environment variables, optionally filtered by key."""
+        if not to_match:
+            # Return all env vars with Spring-style {"value": ...} wrapper
+            properties = {key: {"value": value} for key, value in os.environ.items()}
+            return [{"name": "systemEnvironment", "properties": properties}]
+
+        # Filter by to_match
+        needle = to_match.strip().lower()
+        matched = {
+            key: {"value": value} for key, value in os.environ.items() if needle in key.lower()
+        }
+
+        if not matched:
+            return []
+
+        return [{"name": "systemEnvironment", "properties": matched}]
+
+
+class SystemPropertiesProvider:
+    """Expose system information as a property source."""
+
+    def get_sources(self, to_match: str | None = None) -> list[dict[str, Any]]:
+        """Return system properties (Python version, platform, etc)."""
+        raw = {
+            "python.version": sys.version,
+            "python.implementation": sys.implementation.name,
+            "platform.system": platform.system(),
+            "platform.release": platform.release(),
+            "platform.machine": platform.machine(),
+            "os.name": os.name,
+            "process.pid": str(os.getpid()),
+        }
+
+        if not to_match:
+            properties = {k: {"value": v} for k, v in raw.items()}
+            return [{"name": "systemProperties", "properties": properties}]
+
+        # Filter by to_match
+        needle = to_match.strip().lower()
+        matched = {k: {"value": v} for k, v in raw.items() if needle in k.lower()}
+
+        if not matched:
+            return []
+
+        return [{"name": "systemProperties", "properties": matched}]
+
+
+class DockerConfigProvider:
+    """Expose Docker environment variables as a property source."""
+
+    def get_sources(self, to_match: str | None = None) -> list[dict[str, Any]]:
+        """Return Docker-related environment variables."""
+        docker_vars = {
+            key: value
+            for key, value in os.environ.items()
+            if key.startswith(("DOCKER_", "CONTAINER_"))
+        }
+
+        if not docker_vars:
+            return []
+
+        if not to_match:
+            properties = {k: {"value": v} for k, v in docker_vars.items()}
+            return [{"name": "dockerConfig", "properties": properties}]
+
+        # Filter by to_match
+        needle = to_match.strip().lower()
+        matched = {k: {"value": v} for k, v in docker_vars.items() if needle in k.lower()}
+
+        if not matched:
+            return []
+
+        return [{"name": "dockerConfig", "properties": matched}]

csrd/versioning/actuator/plugins/env/registry.py

@@ -0,0 +1,211 @@
+"""Property source registry for aggregating environment information."""
+
+import logging
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from .providers import (
+    DockerConfigProvider,
+    PropertySourceProvider,
+    SystemEnvironmentProvider,
+    SystemPropertiesProvider,
+)
+
+logger = logging.getLogger(__name__)
+
+# Spring Boot's default keys-to-sanitize patterns.
+DEFAULT_KEYS_TO_SANITIZE: tuple[str, ...] = (
+    "password",
+    "secret",
+    "key",
+    "token",
+    ".*credentials.*",
+    "vcap_services",
+)
+
+REDACTED_VALUE = "******"
+
+
+class ShowValues(Enum):
+    """Controls when property values are visible vs redacted.
+
+    Mirrors Spring Boot 3's ``management.endpoint.env.show-values`` setting.
+
+    Members:
+        NEVER: Redact ALL values — nothing is shown in the clear.
+        ALWAYS: Show benign values in the clear; sensitive keys are still redacted.
+        WHEN_AUTHORIZED: Reserved for future use with authentication checks.
+            Currently behaves like NEVER (safe default until auth is wired).
+    """
+
+    NEVER = "NEVER"
+    ALWAYS = "ALWAYS"
+    WHEN_AUTHORIZED = "WHEN_AUTHORIZED"
+
+
+@dataclass(frozen=True)
+class SanitizationConfig:
+    """Configuration for property value redaction.
+
+    Args:
+        keys_to_sanitize: Regex patterns for keys that are **always** redacted,
+            regardless of ``show_values``.  Defaults to Spring Boot's default set.
+        additional_keys_to_sanitize: Extra patterns appended to the defaults.
+        show_values: Controls visibility of *non-sensitive* values.
+            ``NEVER`` redacts everything; ``ALWAYS`` shows benign values.
+    """
+
+    keys_to_sanitize: tuple[str, ...] = DEFAULT_KEYS_TO_SANITIZE
+    additional_keys_to_sanitize: tuple[str, ...] = ()
+    show_values: ShowValues = ShowValues.NEVER
+
+    def __post_init__(self) -> None:
+        all_patterns = self.keys_to_sanitize + self.additional_keys_to_sanitize
+        pattern = re.compile("|".join(all_patterns), re.IGNORECASE) if all_patterns else None
+        # frozen=True requires object.__setattr__ for post-init assignment
+        object.__setattr__(self, "_sensitive_pattern", pattern)
+
+    _sensitive_pattern: re.Pattern[str] | None = field(init=False, default=None)
+
+    @property
+    def sensitive_pattern(self) -> re.Pattern[str] | None:
+        """Return the compiled sensitive-key regex (computed once at init)."""
+        return self._sensitive_pattern
+
+
+class PropertySourceRegistry:
+    """Manages all property source providers with built-in defaults.
+
+    The registry maintains a set of named property source providers and can
+    aggregate their outputs. It comes with sensible defaults but allows
+    registration and override of providers.
+
+    Sanitization is controlled via ``SanitizationConfig``:
+
+    - ``keys_to_sanitize`` — base patterns (default: password, secret, key, …)
+    - ``additional_keys_to_sanitize`` — extra patterns on top of defaults
+    - ``show_values`` — ``NEVER`` (default), ``ALWAYS``, or ``WHEN_AUTHORIZED``
+    """
+
+    def __init__(
+        self,
+        with_defaults: bool = True,
+        sanitization: SanitizationConfig | None = None,
+    ) -> None:
+        """Initialize the registry.
+
+        Args:
+            with_defaults: If True, register built-in providers (systemEnvironment,
+                          systemProperties, dockerConfig). If False, start empty.
+            sanitization: Redaction configuration. If None, uses default config
+                         (redact keys matching password, secret, key, token, etc.).
+        """
+        self._providers: dict[str, PropertySourceProvider] = {}
+        self._sanitization = sanitization or SanitizationConfig()
+        if with_defaults:
+            self._init_defaults()
+
+    def _init_defaults(self) -> None:
+        """Register built-in providers that are always included."""
+        self.register("systemEnvironment", SystemEnvironmentProvider())
+        self.register("systemProperties", SystemPropertiesProvider())
+        self.register("dockerConfig", DockerConfigProvider())
+
+    def register(self, name: str, provider: PropertySourceProvider) -> None:
+        """Register or override a property source provider.
+
+        If a provider with the given name already exists, it is replaced.
+
+        Args:
+            name: Unique identifier for the provider.
+            provider: Object implementing the PropertySourceProvider protocol.
+        """
+        self._providers[name] = provider
+
+    def unregister(self, name: str) -> None:
+        """Remove a provider by name.
+
+        Args:
+            name: Name of the provider to remove.
+        """
+        self._providers.pop(name, None)
+
+    def get_all_sources(self, to_match: str | None = None) -> list[dict[str, Any]]:
+        """Aggregate property sources from all registered providers.
+
+        Redaction is two-tier:
+        - Sensitive keys (matching ``keys_to_sanitize``) are **always** redacted.
+        - When ``show_values`` is ``NEVER``, *all* values are redacted.
+        - When ``show_values`` is ``ALWAYS``, only
+          sensitive keys are redacted and benign values are shown.
+
+        Args:
+            to_match: Optional case-insensitive substring filter applied to
+                     each provider's output.
+
+        Returns:
+            List of property source dicts aggregated from all providers.
+        """
+        sources = []
+        for name, provider in self._providers.items():
+            try:
+                sources.extend(provider.get_sources(to_match))
+            except Exception:
+                logger.exception("Provider '%s' failed in get_sources()", name)
+
+        redact_all = self._sanitization.show_values != ShowValues.ALWAYS
+        sensitive = self._sanitization.sensitive_pattern
+        return [
+            _sanitize_source(source, sensitive=sensitive, redact_all=redact_all)
+            for source in sources
+        ]
+
+
+def _sanitize_source(
+    source: dict[str, Any],
+    *,
+    sensitive: re.Pattern[str] | None,
+    redact_all: bool,
+) -> dict[str, Any]:
+    """Replace values of sensitive (or all) keys with the redacted placeholder."""
+    properties = source.get("properties")
+    if not isinstance(properties, dict):
+        return source
+
+    if not redact_all and sensitive is None:
+        return source
+
+    sanitized: dict[str, Any] = {}
+    for prop_key, prop_value in properties.items():
+        is_sensitive = sensitive is not None and sensitive.search(prop_key)
+        if redact_all or is_sensitive:
+            # Preserve the Spring-style {"value": ...} wrapper if present
+            if isinstance(prop_value, dict) and "value" in prop_value:
+                sanitized[prop_key] = {"value": REDACTED_VALUE}
+            else:
+                sanitized[prop_key] = REDACTED_VALUE
+        else:
+            sanitized[prop_key] = prop_value
+
+    return {**source, "properties": sanitized}
+
+
+def create_property_source_registry(
+    with_defaults: bool = True,
+    sanitization: SanitizationConfig | None = None,
+) -> PropertySourceRegistry:
+    """Create a new property source registry.
+
+    Args:
+        with_defaults: If True, include built-in providers. If False, start empty.
+        sanitization: Redaction configuration. If None, uses default config.
+
+    Returns:
+        A new PropertySourceRegistry instance.
+    """
+    return PropertySourceRegistry(
+        with_defaults=with_defaults,
+        sanitization=sanitization,
+    )

csrd/versioning/actuator/plugins/health/__init__.py

@@ -0,0 +1,37 @@
+"""Spring Boot-style health actuator with composable indicators."""
+
+from .auto import (
+    AppStateHealthIndicator,
+    KafkaHealthIndicator,
+    LaunchDarklyHealthIndicator,
+    MongoHealthIndicator,
+    RabbitHealthIndicator,
+    discover_indicators,
+)
+from .indicators import (
+    BaseHealthIndicator,
+    DiskSpaceHealthIndicator,
+    HealthIndicator,
+    LivenessIndicator,
+    PingHealthIndicator,
+    ReadinessIndicator,
+)
+from .plugin import HealthActuatorPlugin, ShowDetails, Status
+
+__all__ = (
+    "AppStateHealthIndicator",
+    "BaseHealthIndicator",
+    "DiskSpaceHealthIndicator",
+    "HealthActuatorPlugin",
+    "HealthIndicator",
+    "KafkaHealthIndicator",
+    "LaunchDarklyHealthIndicator",
+    "LivenessIndicator",
+    "MongoHealthIndicator",
+    "PingHealthIndicator",
+    "RabbitHealthIndicator",
+    "ReadinessIndicator",
+    "ShowDetails",
+    "Status",
+    "discover_indicators",
+)