csrd-versioning 0.1.0__py3-none-any.whl

csrd/versioning/_settings.py

@@ -0,0 +1,88 @@
+import logging
+from functools import lru_cache
+
+from pydantic import AliasChoices, Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+logger = logging.getLogger(__name__)
+
+
+class VersioningSettings(BaseSettings):
+    """Environment-backed settings required for the versioning system to operate.
+
+    This includes identity and auth values (e.g. ``jwt_secret``) that
+    versioned endpoints depend on, not just version-routing configuration.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    app_name: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("APP_NAME", "app_name"),
+    )
+    jwt_secret: SecretStr | None = Field(
+        default=None,
+        validation_alias=AliasChoices("JWT_SECRET", "JAVELIN_JWT_KEY_CREDENTIALS_JAVELIN_JWT_KEY"),
+    )
+    service_root_domain: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("SERVICE_ROOT_DOMAIN"),
+    )
+    build_tag: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("BUILD_TAG"),
+    )
+
+
+@lru_cache(maxsize=1)
+def load_versioning_settings() -> VersioningSettings:
+    """Return cached settings read from environment variables.
+
+    The result is cached for the lifetime of the process — only add
+    fields here for values that are fixed at startup (e.g. ``APP_NAME``,
+    ``JWT_SECRET``). Environment variable changes after the first call
+    will not be reflected.
+    """
+    return VersioningSettings()
+
+
+def load_app_name(override: str | None = None) -> str:
+    """Resolve application name with an explicit override or environment fallback.
+
+    When *override* is a non-empty string it is returned immediately.
+    When *override* is ``None``, the function reads ``APP_NAME`` from
+    environment-backed Pydantic settings. If ``APP_NAME`` is missing, or any
+    error occurs, the function falls back to ``"UNKNOWN_APP"``.
+
+    Raises:
+        ValueError: If *override* is an empty string.
+    """
+    if isinstance(override, str):
+        if not override:
+            raise ValueError("override must be a non-empty string or None")
+        return override
+
+    fallback = "UNKNOWN_APP"
+
+    try:
+        settings = load_versioning_settings()
+        if settings.app_name:
+            logger.debug("App name loaded from settings: %s", settings.app_name)
+            return settings.app_name
+
+        logger.warning("No APP_NAME value found in settings, defaulting to %s", fallback)
+        return fallback
+    except Exception as e:
+        logger.warning(
+            "error retrieving app_name from settings defaulting to %s: %s",
+            fallback,
+            e,
+        )
+        return fallback
+
+
+__all__ = ("VersioningSettings", "load_app_name", "load_versioning_settings")

csrd/versioning/_swagger_ui_version.py

@@ -0,0 +1,12 @@
+# Pinned Swagger UI version and SRI hashes for jsDelivr CDN assets.
+#
+# Auto-generated — do not edit manually.
+# Regenerate with::
+#   python scripts/update_swagger_ui.py <version>
+#
+# Example:
+#   python scripts/update_swagger_ui.py 5.18.2
+
+SWAGGER_UI_VERSION = "5.18.2"
+SWAGGER_UI_CSS_SRI = "rcbEi6xgdPk0iWkAQzT2F3FeBJXdG+ydrawGlfHAFIZG7wU6aKbQaRewysYpmrlW"
+SWAGGER_UI_JS_SRI = "NXtFPpN61oWCuN4D42K6Zd5Rt2+uxeIT36R7kpXBuY9tLnZorzrJ4ykpqwJfgjpZ"

csrd/versioning/_types.py

@@ -0,0 +1,14 @@
+from collections.abc import Mapping
+from enum import Enum
+from typing import Any
+
+VersionKey = Enum | str | int | None
+VersionMap = Mapping[VersionKey, Any]
+VersionedAppState = Mapping[str, Any]
+
+
+__all__ = (
+    "VersionKey",
+    "VersionMap",
+    "VersionedAppState",
+)

csrd/versioning/actuator/README.md

@@ -0,0 +1,261 @@
+# Actuator Extension Model
+
+This package provides Spring Boot-style management endpoints under `/actuator`.
+
+## Defaults
+
+- `register_actuator_router(app)` mounts `/actuator` and auto-wires built-in plugins.
+- `/_info` and `/_info/health` are separate versioning introspection endpoints and remain unchanged.
+- Consumers can pass plugin overrides via `configure_versioned_api(..., actuator_plugins=[...])`
+  or `create_versioned_app(..., actuator_plugins=[...])`. On name conflicts,
+  consumer plugins override built-in plugins.
+
+## Plugin Contract
+
+Implement the `ActuatorPlugin` protocol from `plugins/base.py`:
+
+- `name`: short plugin identifier
+- `register(router, app=..., prefix=...)`: add routes and return link metadata
+
+The returned link metadata is merged into the root payload:
+
+```json
+{
+  "_links": {
+    "self": {"href": ".../actuator", "templated": false}
+  }
+}
+```
+
+When the info plugin is active and the metadata file exists, the root
+payload also includes an `info` link.
+
+When the env plugin is active, the root payload includes an `env` link.
+When the env plugin is active, the root payload also includes a templated
+`env-toMatch` link.
+
+## Built-in Plugin
+
+`InfoActuatorPlugin` serves `/actuator/info` by reading JSON metadata from:
+
+1. `ACTUATOR_INFO_PATH` environment variable
+2. `service_info.json` (default, relative to the process working directory)
+
+If the resolved file does not exist, `/actuator/info` is not registered.
+If the file exists but is invalid JSON, the endpoint returns `{}`.
+
+`EnvActuatorPlugin` serves `/actuator/env` with runtime profile metadata:
+
+```json
+{
+  "activeProfiles": ["dev", "stage"],
+  "defaultProfiles": [],
+  "propertySources": []
+}
+```
+
+Profiles are read from `SPRING_PROFILES_ACTIVE` as a comma-separated list.
+
+`EnvActuatorPlugin` also serves `/actuator/env/{toMatch}` and filters
+environment variables by case-insensitive key match into `propertySources`.
+
+`HealthActuatorPlugin` serves `/actuator/health` with composable health
+indicators:
+
+```json
+{
+  "status": "UP",
+  "groups": ["liveness", "readiness"],
+  "components": {
+    "ping": {"status": "UP"},
+    "diskSpace": {"status": "UP", "details": {"total": ..., "free": ..., "threshold": 10485760, "path": ".", "exists": true}},
+    "livenessState": {"status": "UP"},
+    "readinessState": {"status": "UP"}
+  }
+}
+```
+
+Default indicators: `PingHealthIndicator`, `DiskSpaceHealthIndicator`,
+`LivenessIndicator`, `ReadinessIndicator`.
+
+Default health groups:
+- `liveness` → `["livenessState"]`
+- `readiness` → `["readinessState", "ping", "diskSpace"]`
+
+`/actuator/health/{component}` returns an individual indicator's status.
+`/actuator/health/{group}` returns the aggregated status for a health group.
+
+### Custom Indicators
+
+Extend `BaseHealthIndicator` for exception-safe custom indicators.
+Override `_check()` — the base class wraps it in try/except automatically:
+
+```python
+from api_versioning.fastapi.versioning.actuator.plugins import BaseHealthIndicator
+
+class MyDatabaseIndicator(BaseHealthIndicator):
+    _name = "db"
+
+    def __init__(self, pool):
+        self._pool = pool
+
+    def _check(self):
+        self._pool.execute("SELECT 1")
+        return {"status": "UP"}
+```
+
+Both sync and async `_check()` are supported:
+
+```python
+class MyAsyncIndicator(BaseHealthIndicator):
+    _name = "myService"
+
+    async def _check(self):
+        result = await some_client.ping()
+        return {"status": "UP", "details": result}
+```
+
+Register via `HealthActuatorPlugin.with_indicators()`:
+
+```python
+HealthActuatorPlugin.with_indicators(db=MyDatabaseIndicator(pool))
+```
+
+### Auto-Discovery
+
+When `auto_discover=True` (the default), the health plugin inspects
+`app.state` on each request and registers indicators for detected services:
+
+| Indicator        | `app.state` key                   | Source package                      |
+|------------------|-----------------------------------|-------------------------------------|
+| `rabbit`         | `rabbit`                          | RabbitMQ client                     |
+| `kafka`          | `kafka_producer_manager` / `kafka_consumer_manager` | Kafka client |
+| `mongo`          | `mongo_client`                    | MongoDB client                      |
+| `launchDarkly`   | `launchdarkly_client`             | LaunchDarkly client                 |
+
+Auto-discovered indicators are appended to the `readiness` group.
+Consumer-provided indicators with the same name take precedence.
+
+To build custom `app.state`-based indicators, extend `AppStateHealthIndicator`
+which adds `_get_state(key)` and `_require_attr(obj, attr)` helpers with
+one-time attribute-missing warnings:
+
+```python
+from api_versioning.fastapi.versioning.actuator.plugins import AppStateHealthIndicator
+
+class ElasticHealthIndicator(AppStateHealthIndicator):
+    _name = "elastic"
+
+    def _check(self):
+        client = self._get_state("elastic_client")
+        if client is None:
+            return {"status": "DOWN", "details": {"error": "State removed"}}
+        ok, ping = self._require_attr(client, "ping")
+        if not ok:
+            return {"status": "DOWN", "details": {"error": "No ping method"}}
+        ping()
+        return {"status": "UP"}
+```
+
+Disable auto-discovery with `auto_discover=False`:
+
+```python
+HealthActuatorPlugin(auto_discover=False)
+```
+
+### Indicator Class Hierarchy
+
+```
+HealthIndicator (Protocol — duck-typing contract)
+│
+BaseHealthIndicator (exception-safe template method)
+├── PingHealthIndicator
+├── LivenessIndicator
+├── ReadinessIndicator
+├── DiskSpaceHealthIndicator
+│
+└── AppStateHealthIndicator (adds app.state helpers + attribute guards)
+    ├── RabbitHealthIndicator
+    ├── KafkaHealthIndicator
+    ├── MongoHealthIndicator
+    └── LaunchDarklyHealthIndicator
+```
+
+### ShowDetails
+
+`ShowDetails` controls component visibility:
+
+- `ALWAYS` (default) – include `components` with per-indicator details
+- `NEVER` – only return `{"status": "UP"}`
+- `WHEN_AUTHORIZED` – reserved; currently behaves like `NEVER`
+
+Build-time generation patterns (including Docker multi-stage examples) live in
+`tools/README.md`.
+
+## Property Sources
+
+`EnvActuatorPlugin` uses a `PropertySourceRegistry` to collect environment
+metadata from composable providers.
+
+Built-in providers (registered when `with_defaults=True`):
+
+- `SystemEnvironmentProvider` – `os.environ` snapshot
+- `SystemPropertiesProvider` – Python runtime info (`sys.version`, platform, etc.)
+- `DockerConfigProvider` – Docker-related env vars (when present)
+
+All values are wrapped in `{"value": ...}` dicts, matching Spring Boot format.
+
+### Custom Providers
+
+Implement the `PropertySourceProvider` protocol:
+
+```python
+class PropertySourceProvider(Protocol):
+    def get_sources(self, to_match: str | None = None) -> list[dict[str, Any]]: ...
+```
+
+Register via `EnvActuatorPlugin.with_providers()`:
+
+```python
+EnvActuatorPlugin.with_providers(
+    myFeatures=MyFeatureProvider(),
+)
+```
+
+### Auto-Wiring
+
+Plugins that extend `BaseActuatorPlugin` can contribute property source
+providers via `register_property_source_provider(name=..., provider=...)`.
+During plugin resolution, `_wire_env_property_sources()` collects all
+contributions and injects them into the env plugin automatically.
+
+## Sanitization
+
+Property values are redacted by default. Control behavior with
+`SanitizationConfig`:
+
+```python
+from api_versioning.fastapi.versioning.actuator.plugins import (
+    EnvActuatorPlugin, SanitizationConfig, ShowValues,
+)
+
+EnvActuatorPlugin.with_providers(
+    sanitization=SanitizationConfig(show_values=ShowValues.ALWAYS),
+)
+```
+
+`ShowValues` modes:
+
+- `NEVER` (default) – redact **all** values to `"******"`
+- `ALWAYS` – show benign values; sensitive keys still redacted
+- `WHEN_AUTHORIZED` – reserved; currently behaves like `NEVER` (safe default until auth is wired)
+
+Sensitive keys matched by default: `password`, `secret`, `key`, `token`,
+`.*credentials.*`, `vcap_services`. Extend with `additional_keys_to_sanitize`
+or replace entirely with `keys_to_sanitize`.
+
+## Adding a Plugin
+
+1. Add a module under `plugins/`.
+2. Implement `ActuatorPlugin`.
+3. Add it to `default_actuator_plugins()` in `plugins/__init__.py`.

csrd/versioning/actuator/__init__.py

@@ -0,0 +1,3 @@
+from .actuator import register_actuator_router
+
+__all__ = ("register_actuator_router",)

csrd/versioning/actuator/actuator.py

@@ -0,0 +1,111 @@
+"""Spring Boot-style ``/actuator`` management endpoints for FastAPI."""
+
+import logging
+from collections.abc import Mapping, Sequence
+
+from fastapi import APIRouter, FastAPI, Request
+
+from .plugins import ActuatorLink, ActuatorPlugin, default_actuator_plugins
+
+logger = logging.getLogger(__name__)
+
+
+def register_actuator_router(
+    app: FastAPI,
+    *,
+    plugins: Sequence[ActuatorPlugin] | None = None,
+    prefix: str = "/actuator",
+) -> None:
+    """Register actuator routes directly on *app*."""
+    router = APIRouter(prefix=prefix, tags=["Actuator"], include_in_schema=False)
+
+    plugin_links = _register_plugins(
+        router,
+        app=app,
+        prefix=prefix,
+        plugins=_resolve_plugins(plugins),
+    )
+
+    @router.get("", include_in_schema=False)
+    async def actuator_root(
+        request: Request,
+    ) -> dict[str, dict[str, dict[str, bool | str]]]:
+        base = str(request.base_url).rstrip("/")
+        links: dict[str, dict[str, bool | str]] = {
+            "self": {"href": f"{base}{prefix}", "templated": False}
+        }
+        for name, link in plugin_links.items():
+            links[name] = {
+                "href": f"{base}{link.href}",
+                "templated": link.templated,
+            }
+        return {"_links": links}
+
+    app.include_router(router)
+
+
+def _register_plugins(
+    router: APIRouter,
+    *,
+    app: FastAPI,
+    prefix: str,
+    plugins: Sequence[ActuatorPlugin],
+) -> dict[str, ActuatorLink]:
+    links: dict[str, ActuatorLink] = {}
+    for plugin in plugins:
+        plugin_links = plugin.register(router, app=app, prefix=prefix)
+        _merge_plugin_links(links, plugin_links)
+    return links
+
+
+def _merge_plugin_links(
+    links: dict[str, ActuatorLink],
+    plugin_links: Mapping[str, ActuatorLink],
+) -> None:
+    for name, link in plugin_links.items():
+        links[name] = link
+
+
+def _resolve_plugins(
+    plugins: Sequence[ActuatorPlugin] | None,
+) -> tuple[ActuatorPlugin, ...]:
+    resolved: dict[str, ActuatorPlugin] = {
+        plugin.name: plugin for plugin in default_actuator_plugins()
+    }
+
+    if plugins is not None:
+        for plugin in plugins:
+            if plugin.name in resolved:
+                logger.debug("Actuator plugin '%s' overridden by consumer", plugin.name)
+            resolved[plugin.name] = plugin
+
+    _wire_env_property_sources(resolved)
+
+    return tuple(resolved.values())
+
+
+def _wire_env_property_sources(resolved: dict[str, ActuatorPlugin]) -> None:
+    contributed: dict[str, object] = {}
+
+    for plugin in resolved.values():
+        providers_getter = getattr(plugin, "property_source_providers", None)
+        if callable(providers_getter):
+            providers = providers_getter()
+            if isinstance(providers, Mapping):
+                contributed.update(providers)
+
+    if not contributed:
+        return
+
+    env_plugin = resolved.get("env")
+    if env_plugin is None:
+        return
+
+    register_providers = getattr(env_plugin, "register_property_source_providers", None)
+    if callable(register_providers):
+        register_providers(contributed)
+        logger.debug(
+            "Auto-wired %d property source provider(s) into env plugin: %s",
+            len(contributed),
+            ", ".join(contributed),
+        )

csrd/versioning/actuator/plugins/__init__.py

@@ -0,0 +1,65 @@
+from collections.abc import Sequence
+
+from .base import ActuatorLink, ActuatorPlugin, BaseActuatorPlugin
+from .env import (
+    EnvActuatorPlugin,
+    PropertySourceProvider,
+    PropertySourceRegistry,
+    SanitizationConfig,
+    ShowValues,
+    create_property_source_registry,
+)
+from .health import (
+    AppStateHealthIndicator,
+    BaseHealthIndicator,
+    DiskSpaceHealthIndicator,
+    HealthActuatorPlugin,
+    HealthIndicator,
+    KafkaHealthIndicator,
+    LaunchDarklyHealthIndicator,
+    LivenessIndicator,
+    MongoHealthIndicator,
+    PingHealthIndicator,
+    RabbitHealthIndicator,
+    ReadinessIndicator,
+    ShowDetails,
+    Status,
+    discover_indicators,
+)
+from .info import InfoActuatorPlugin
+
+
+def default_actuator_plugins() -> Sequence[ActuatorPlugin]:
+    """Return the built-in actuator plugins auto-wired by default."""
+
+    return (InfoActuatorPlugin(), EnvActuatorPlugin(), HealthActuatorPlugin())
+
+
+__all__ = (
+    "ActuatorLink",
+    "ActuatorPlugin",
+    "AppStateHealthIndicator",
+    "BaseActuatorPlugin",
+    "BaseHealthIndicator",
+    "DiskSpaceHealthIndicator",
+    "EnvActuatorPlugin",
+    "HealthActuatorPlugin",
+    "HealthIndicator",
+    "InfoActuatorPlugin",
+    "KafkaHealthIndicator",
+    "LaunchDarklyHealthIndicator",
+    "LivenessIndicator",
+    "MongoHealthIndicator",
+    "PingHealthIndicator",
+    "PropertySourceProvider",
+    "PropertySourceRegistry",
+    "RabbitHealthIndicator",
+    "ReadinessIndicator",
+    "SanitizationConfig",
+    "ShowDetails",
+    "ShowValues",
+    "Status",
+    "create_property_source_registry",
+    "default_actuator_plugins",
+    "discover_indicators",
+)

csrd/versioning/actuator/plugins/base.py

@@ -0,0 +1,77 @@
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from fastapi import APIRouter, FastAPI
+
+
+@dataclass(frozen=True)
+class ActuatorLink:
+    """Link metadata rendered by the actuator root endpoint."""
+
+    href: str
+    templated: bool = False
+
+
+class ActuatorPlugin(Protocol):
+    """Contract for actuator plugins that register routes and expose links."""
+
+    name: str
+
+    def register(
+        self,
+        router: APIRouter,
+        *,
+        app: FastAPI,
+        prefix: str,
+    ) -> Mapping[str, ActuatorLink]:
+        """Register endpoints on *router* and return link entries."""
+
+
+class BaseActuatorPlugin:
+    """Shared helpers for actuator plugins.
+
+    Provides optional in-memory memoization of endpoint payloads and a
+    consistent link-construction helper.
+    """
+
+    def __init__(self, *, cache_enabled: bool = True) -> None:
+        self._cache_enabled = cache_enabled
+        self._payload_cache: dict[str, dict[str, Any]] = {}
+        self._property_source_providers: dict[str, Any] = {}
+
+    def memoized_payload(
+        self,
+        *,
+        cache_key: str,
+        loader: Callable[[], dict[str, Any]],
+    ) -> dict[str, Any]:
+        if not self._cache_enabled:
+            return loader()
+
+        cached = self._payload_cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        payload = loader()
+        self._payload_cache[cache_key] = payload
+        return payload
+
+    def clear_payload_cache(self) -> None:
+        self._payload_cache.clear()
+
+    def register_property_source_provider(self, *, name: str, provider: Any) -> None:
+        """Register a property source provider contribution from this plugin.
+
+        Contributions are auto-wired into the env actuator plugin when
+        ``register_actuator_router`` resolves the plugin set.
+        """
+        self._property_source_providers[name] = provider
+
+    def property_source_providers(self) -> Mapping[str, Any]:
+        """Return this plugin's property source provider contributions."""
+        return dict(self._property_source_providers)
+
+    @staticmethod
+    def build_link(*, prefix: str, route_path: str) -> ActuatorLink:
+        return ActuatorLink(href=f"{prefix}{route_path}")

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

@@ -0,0 +1,31 @@
+"""Spring Boot-style env actuator with property source registry."""
+
+from .plugin import EnvActuatorPlugin
+from .providers import (
+    DockerConfigProvider,
+    PropertySourceProvider,
+    SystemEnvironmentProvider,
+    SystemPropertiesProvider,
+)
+from .registry import (
+    DEFAULT_KEYS_TO_SANITIZE,
+    REDACTED_VALUE,
+    PropertySourceRegistry,
+    SanitizationConfig,
+    ShowValues,
+    create_property_source_registry,
+)
+
+__all__ = (
+    "DEFAULT_KEYS_TO_SANITIZE",
+    "REDACTED_VALUE",
+    "DockerConfigProvider",
+    "EnvActuatorPlugin",
+    "PropertySourceProvider",
+    "PropertySourceRegistry",
+    "SanitizationConfig",
+    "ShowValues",
+    "SystemEnvironmentProvider",
+    "SystemPropertiesProvider",
+    "create_property_source_registry",
+)