csrd-versioning 0.1.0__py3-none-any.whl

csrd/versioning/actuator/plugins/info.py

@@ -0,0 +1,120 @@
+"""Default actuator plugin that serves build-time service metadata."""
+
+import json
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, FastAPI
+
+from .base import ActuatorLink, BaseActuatorPlugin
+
+_DEFAULT_INFO_PATH = "service_info.json"
+_INFO_SECTIONS = ("git", "build")
+
+# Nested key-order schema — mirrors the JSON shape so preferred insertion
+# order is readable at a glance.  ``None`` leaves mean "no child ordering".
+_KEY_ORDER: dict[str, dict | None] = {
+    "git": {
+        "branch": None,
+        "commit": {
+            "time": None,
+            "message": {"full": None, "short": None},
+            "id": {"describe": None, "abbrev": None, "full": None},
+            "user": {"email": None, "name": None},
+        },
+        "build": {
+            "version": None,
+            "user": {"name": None, "email": None},
+            "host": None,
+        },
+        "dirty": None,
+        "tags": None,
+        "total": {"commit": {"count": None}},
+        "closest": {"tag": {"commit": {"count": None}, "name": None}},
+        "remote": {"origin": {"url": None}},
+    },
+    "build": {
+        "artifact": None,
+        "name": None,
+        "time": None,
+        "version": None,
+        "group": None,
+    },
+}
+
+
+def _reorder(value: Any, order: dict | None = None) -> Any:
+    """Recursively reorder dict keys according to *order*, preserving extras."""
+    if isinstance(value, dict):
+        result: dict[str, Any] = {}
+        if order:
+            for key in order:
+                if key in value:
+                    result[key] = _reorder(value[key], order[key])
+        for key, child in value.items():
+            if key not in result:
+                result[key] = _reorder(child)
+        return result
+
+    if isinstance(value, list):
+        return [_reorder(item) for item in value]
+
+    return value
+
+
+def _build_info_payload(loaded: dict[str, Any]) -> dict[str, Any]:
+    payload: dict[str, Any] = {}
+
+    for section in _INFO_SECTIONS:
+        section_value = loaded.get(section)
+        if isinstance(section_value, dict):
+            payload[section] = section_value
+
+    return dict(_reorder(payload, _KEY_ORDER))
+
+
+class InfoActuatorPlugin(BaseActuatorPlugin):
+    """Expose Spring-style ``/actuator/info`` from a baked JSON file."""
+
+    name = "info"
+
+    def register(
+        self,
+        router: APIRouter,
+        *,
+        app: FastAPI,
+        prefix: str,
+    ) -> Mapping[str, ActuatorLink]:
+        path = self._resolve_info_path()
+
+        if not path.exists():
+            return {}
+
+        @router.get("/info", include_in_schema=False)
+        async def info() -> dict[str, Any]:
+            return self._load_info(path)
+
+        return {"info": self.build_link(prefix=prefix, route_path="/info")}
+
+    def _resolve_info_path(self) -> Path:
+        path_value = os.getenv("ACTUATOR_INFO_PATH")
+        return Path(path_value or _DEFAULT_INFO_PATH)
+
+    def _load_info(self, path: Path) -> dict[str, Any]:
+        def _load() -> dict[str, Any]:
+            if not path.exists():
+                return {}
+
+            try:
+                loaded = json.loads(path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                return {}
+
+            if isinstance(loaded, dict):
+                return _build_info_payload(loaded)
+
+            return {}
+
+        return self.memoized_payload(cache_key=str(path), loader=_load)

csrd/versioning/actuator/tools/README.md

@@ -0,0 +1,54 @@
+# Actuator Tools
+
+This folder contains build-time tools that generate metadata consumed by
+runtime actuator plugins.
+
+Current tool:
+
+- `generate_service_info_from_git.py`
+  - Source: git repository metadata
+  - Output: `ACTUATOR_INFO_OUTPUT_PATH` (defaults to `service_info.json`)
+  - Runtime consumer: `InfoActuatorPlugin` (`/actuator/info`)
+
+This script is Docker-build-only. It exits unless
+`ACTUATOR_INFO_DOCKER_BUILD=1` is set.
+
+Use this script during Docker build stages where `.git` is available, then copy
+`service_info.json` into the runtime image.
+
+## Docker Build Pattern
+
+Expected usage is a multi-stage Docker build that generates `service_info.json`
+while `.git` is still available, then copies that file into the runtime image.
+
+The CI pipeline injects `BUILD_VERSION` as a Docker build-arg. Pass it through
+to the script via `--build-version` so the release version is recorded in
+`build.version` and `git.build.version`. The argument is optional — when
+omitted the script falls back to `git describe --tags --always`.
+
+Example (drop-in for a consuming repository):
+
+```dockerfile
+FROM python:3.13-slim AS service-info
+ARG BUILD_VERSION=""
+RUN apt-get update && apt-get install -y --no-install-recommends git && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+
+# Install runtime dependencies for the service, including api_versioning.
+# Use the install flow your repository already uses.
+COPY pyproject.toml poetry.lock* ./
+RUN pip install --no-cache-dir poetry \
+  && poetry config virtualenvs.create false \
+  && poetry install --only main --no-interaction --no-ansi
+
+COPY .git ./.git
+RUN ACTUATOR_INFO_DOCKER_BUILD=1 \
+  python -m api_versioning.fastapi.versioning.actuator.tools.generate_service_info_from_git \
+  --build-version="${BUILD_VERSION}"
+
+FROM base AS runtime
+COPY --from=service-info /app/service_info.json ./
+```
+
+If you place the file somewhere else at runtime, set `ACTUATOR_INFO_PATH`
+so `InfoActuatorPlugin` can resolve it.

csrd/versioning/actuator/tools/generate_service_info_from_git.py

@@ -0,0 +1,126 @@
+"""Generate service metadata from git for the actuator ``/actuator/info`` endpoint.
+
+Run this script at build time to write a JSON file consumed by
+``InfoActuatorPlugin``.
+"""
+
+import argparse
+import json
+import os
+import subprocess
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+_DEFAULT_OUTPUT_PATH = "service_info.json"
+_DOCKER_BUILD_ENV = "ACTUATOR_INFO_DOCKER_BUILD"
+_DOCKER_BUILD_ENV_VALUE = "1"
+
+
+def _git(*cmd: str, default: str = "") -> str:
+    try:
+        return subprocess.check_output(["git", *cmd], stderr=subprocess.DEVNULL, text=True).strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return default
+
+
+def _iso_utc(value: str) -> str:
+    if not value:
+        return ""
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError:
+        return ""
+    return parsed.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _resolve_output_path() -> Path:
+    return Path(os.getenv("ACTUATOR_INFO_OUTPUT_PATH", _DEFAULT_OUTPUT_PATH))
+
+
+def _normalize_build_version(build_version: str) -> str:
+    return build_version.strip()
+
+
+def _assert_docker_build_context() -> None:
+    if os.getenv(_DOCKER_BUILD_ENV) != _DOCKER_BUILD_ENV_VALUE:
+        raise SystemExit(
+            "generate_service_info_from_git.py is build-only and must run from Docker "
+            f"with {_DOCKER_BUILD_ENV}={_DOCKER_BUILD_ENV_VALUE}."
+        )
+
+
+def _build_info(build_version: str = "") -> dict[str, Any]:
+    normalized_build_version = _normalize_build_version(build_version)
+    commit_time = _iso_utc(_git("log", "-1", "--format=%cI"))
+    commit_full = _git("rev-parse", "HEAD")
+    commit_abbrev = _git("rev-parse", "--short", "HEAD")
+    remote_url = _git("remote", "get-url", "origin")
+    service_name = remote_url.rsplit("/", 1)[-1].removesuffix(".git") if remote_url else ""
+
+    resolved_version = normalized_build_version or _git("describe", "--tags", "--always")
+
+    git_info: dict[str, Any] = {
+        "branch": _git("rev-parse", "--abbrev-ref", "HEAD"),
+        "commit": {
+            "time": commit_time,
+            "message": {
+                "full": _git("log", "-1", "--format=%B"),
+                "short": _git("log", "-1", "--format=%s"),
+            },
+            "id": {
+                "abbrev": commit_abbrev,
+                "full": commit_full,
+                "describe": _git("describe", "--tags"),
+            },
+            "user": {
+                "name": _git("log", "-1", "--format=%an"),
+                "email": _git("log", "-1", "--format=%ae"),
+            },
+        },
+        "dirty": str(bool(_git("status", "--porcelain"))).lower(),
+        "remote": {"origin": {"url": remote_url}},
+    }
+
+    if normalized_build_version:
+        git_info["build"] = {"version": normalized_build_version}
+
+    return {
+        "git": git_info,
+        "build": {
+            "artifact": service_name,
+            "name": service_name,
+            "group": "com.example",
+            "version": resolved_version,
+            "time": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z",
+        },
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate service metadata from git for InfoActuatorPlugin."
+    )
+    parser.add_argument(
+        "--build-version",
+        default="",
+        help=(
+            "Explicit release version injected by the CI pipeline "
+            '(e.g. --build-version="${BUILD_VERSION}"). '
+            "Populates build.version and git.build.version. "
+            "Falls back to `git describe --tags --always` when omitted."
+        ),
+    )
+    args = parser.parse_args()
+    _assert_docker_build_context()
+
+    info = _build_info(build_version=args.build_version)
+    output_path = _resolve_output_path()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(info, indent=2), encoding="utf-8")
+    abbrev = info.get("git", {}).get("commit", {}).get("id", {}).get("abbrev", "")
+    print(f"Wrote {output_path} (commit {abbrev})")
+
+
+if __name__ == "__main__":
+    main()

csrd/versioning/exception_handlers.py

@@ -0,0 +1,126 @@
+import datetime
+import re
+import uuid
+from datetime import UTC
+
+from fastapi import HTTPException, Request, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from csrd.context import get_api_version
+from csrd.context.middleware._logging import REQUEST_SCOPE_KEY
+from csrd.models.errors import APIErrorResponse, APIVersion, ErrorMeta
+from csrd.versioning._constants import API_VERSION_HEADER_NAME
+
+
+def _display_api_version(version: str | None) -> str | None:
+    if version is None:
+        return None
+    if str(version).lower() == "unv":
+        return "Unversioned"
+    return version
+
+
+_VERSION_SEGMENT_RE = re.compile(
+    r"(unv|unversioned|latest|v\d+(?:[._-]\d+)*)(?:/|$)",
+    flags=re.IGNORECASE,
+)
+
+
+def _get_served_api_version(request: Request) -> str | None:
+    # 1. Scope key set by VersionDispatchMiddleware
+    scope = getattr(request, "scope", None)
+    if isinstance(scope, dict):
+        scoped_version = scope.get("api_version")
+        if isinstance(scoped_version, str):
+            return _display_api_version(scoped_version)
+
+    # 2. Contextvar set by set_api_version_context()
+    ctx_version = get_api_version()
+    if ctx_version is not None:
+        return _display_api_version(ctx_version)
+
+    # 3. Path params resolved by FastAPI routing
+    path_params = getattr(request, "path_params", None)
+    if isinstance(path_params, dict):
+        version = path_params.get("version")
+        if isinstance(version, str):
+            return _display_api_version(version)
+
+    # 4. Best-effort path parsing (prefix-agnostic)
+    path = getattr(getattr(request, "url", None), "path", "")
+    if isinstance(path, str):
+        for segment in path.strip("/").split("/"):
+            if _VERSION_SEGMENT_RE.fullmatch(segment):
+                return _display_api_version(segment)
+
+    return None
+
+
+def _api_version_from_request(request: Request) -> APIVersion:
+    requested = None
+    headers = getattr(request, "headers", None)
+    if headers is not None:
+        requested_value = headers.get(API_VERSION_HEADER_NAME)
+        requested = requested_value if isinstance(requested_value, str) else None
+
+    served = _get_served_api_version(request)
+    return APIVersion(served=served, requested=requested)
+
+
+def _get_request_id(request: Request):
+    try:
+        return request.scope[REQUEST_SCOPE_KEY]["hit_id"]
+    except KeyError:
+        return str(uuid.uuid4())
+
+
+async def http_exception_handler(request: Request, exc: HTTPException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=APIErrorResponse(
+            meta=ErrorMeta(
+                status=exc.status_code,
+                error=exc.detail or "Unknown Error",
+                method=request.method,
+                path=request.url.path,
+                request_id=_get_request_id(request),
+                timestamp=datetime.datetime.now(UTC),
+                api_version=_api_version_from_request(request),
+            ),
+            errors=[],
+        ).as_dict(by_alias=True, mode="json"),
+    )
+
+
+async def request_validation_exception_handler(request: Request, exc: RequestValidationError):
+    return JSONResponse(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        content=APIErrorResponse(
+            meta=ErrorMeta(
+                status=status.HTTP_400_BAD_REQUEST,
+                error="Validation Error",
+                method=request.method,
+                path=request.url.path,
+                request_id=_get_request_id(request),
+                timestamp=datetime.datetime.now(UTC),
+                api_version=_api_version_from_request(request),
+            ),
+            errors=[],
+        ).as_dict(by_alias=True, mode="json"),
+    )
+
+
+EXCEPTION_HANDLERS = {
+    # the HTTPException is being intercepted for 404s likely in the instana middleware
+    # force a 404 to be handled by the http_exception_handler
+    404: http_exception_handler,
+    HTTPException: http_exception_handler,
+    RequestValidationError: request_validation_exception_handler,
+}
+
+__all__ = (
+    "EXCEPTION_HANDLERS",
+    "http_exception_handler",
+    "request_validation_exception_handler",
+)

csrd/versioning/swagger_plugins/__init__.py

@@ -0,0 +1,15 @@
+"""Swagger UI plugin system for extending the custom docs rendering pipeline."""
+
+from ._base import (
+    SchemaContext,
+    SwaggerPlugin,
+    SwaggerPluginContribution,
+    apply_schema_patchers,
+)
+
+__all__ = [
+    "SchemaContext",
+    "SwaggerPlugin",
+    "SwaggerPluginContribution",
+    "apply_schema_patchers",
+]

csrd/versioning/swagger_plugins/_base.py

@@ -0,0 +1,153 @@
+"""Swagger UI plugin protocol, contribution dataclass, and resolution logic."""
+
+import logging
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from fastapi import FastAPI
+
+from csrd.versioning._types import VersionKey
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class SchemaContext:
+    """Read-only metadata passed to schema patchers."""
+
+    app: FastAPI
+    """The versioned sub-app whose schema is being built."""
+
+    version_key: VersionKey
+    """The version key (e.g. ``Versions.V1``) being rendered."""
+
+    prefix: str
+    """Normalised API prefix, e.g. ``"/api"``."""
+
+
+@dataclass(frozen=True)
+class SwaggerPluginContribution:
+    """Static data returned by :meth:`SwaggerPlugin.contribute`."""
+
+    extra_css: str | None = None
+    extra_js: str = ""
+    bundle_plugins: tuple[str, ...] = ()
+    schema_patcher: Callable[[dict, SchemaContext], dict] | None = None
+
+
+@runtime_checkable
+class SwaggerPlugin(Protocol):
+    """Protocol for Swagger UI plugins."""
+
+    name: str
+
+    def contribute(self) -> SwaggerPluginContribution: ...
+
+
+def _extract_css_class_names(css: str) -> set[str]:
+    return set(re.findall(r"\.([\w-]+)", css))
+
+
+def _warn_css_conflicts(
+    contributions: dict[str, SwaggerPluginContribution],
+) -> None:
+    plugin_classes: dict[str, set[str]] = {}
+    for name, contrib in contributions.items():
+        if contrib.extra_css:
+            plugin_classes[name] = _extract_css_class_names(contrib.extra_css)
+
+    names = list(plugin_classes.keys())
+    for i, name_a in enumerate(names):
+        for name_b in names[i + 1 :]:
+            overlap = plugin_classes[name_a] & plugin_classes[name_b]
+            if overlap:
+                logger.warning(
+                    "SwaggerPlugins '%s' and '%s' both define CSS rules for: %s",
+                    name_a,
+                    name_b,
+                    ", ".join(f".{cls}" for cls in sorted(overlap)),
+                )
+
+
+def _resolve_swagger_plugins(
+    global_plugins: list[SwaggerPlugin] | None,
+    per_version_plugins: list[SwaggerPlugin] | None = None,
+) -> tuple[SwaggerPlugin, ...]:
+
+    if global_plugins is not None and len(global_plugins) == 0:
+        return ()
+
+    resolved: dict[str, SwaggerPlugin] = {p.name: p for p in _default_swagger_plugins()}
+    if global_plugins:
+        for p in global_plugins:
+            resolved[p.name] = p
+
+    if per_version_plugins is not None and len(per_version_plugins) == 0:
+        return ()
+    if per_version_plugins:
+        for p in per_version_plugins:
+            resolved[p.name] = p
+
+    return tuple(resolved.values())
+
+
+def _default_swagger_plugins() -> list[SwaggerPlugin]:
+    from .file_upload import FileUploadExamplesPlugin
+
+    return [FileUploadExamplesPlugin()]
+
+
+def _collect_contributions(
+    plugins: tuple[SwaggerPlugin, ...],
+) -> dict[str, SwaggerPluginContribution]:
+    contributions: dict[str, SwaggerPluginContribution] = {}
+    for plugin in plugins:
+        try:
+            contributions[plugin.name] = plugin.contribute()
+        except Exception:
+            logger.warning(
+                "SwaggerPlugin '%s' failed in contribute()",
+                plugin.name,
+                exc_info=True,
+            )
+    return contributions
+
+
+def _aggregate_css(contributions: dict[str, SwaggerPluginContribution]) -> str:
+    parts = [c.extra_css for c in contributions.values() if c.extra_css]
+    return "\n".join(parts)
+
+
+def _aggregate_js(contributions: dict[str, SwaggerPluginContribution]) -> str:
+    parts = [c.extra_js for c in contributions.values() if c.extra_js]
+    return "\n".join(parts)
+
+
+def _aggregate_bundle_plugins(
+    contributions: dict[str, SwaggerPluginContribution],
+) -> str:
+    names: list[str] = []
+    for c in contributions.values():
+        names.extend(c.bundle_plugins)
+    return ", ".join(names)
+
+
+def _collect_schema_patchers(
+    contributions: dict[str, SwaggerPluginContribution],
+) -> list[Callable[[dict, SchemaContext], dict]]:
+    return [c.schema_patcher for c in contributions.values() if c.schema_patcher]
+
+
+def apply_schema_patchers(
+    schema: dict,
+    ctx: SchemaContext,
+    patchers: list[Callable[[dict, SchemaContext], dict]],
+) -> dict:
+    for patcher in patchers:
+        try:
+            schema = patcher(schema, ctx)
+        except Exception:
+            logger.warning("schema_patcher from plugin failed", exc_info=True)
+    return schema

csrd/versioning/swagger_plugins/file_upload/__init__.py

@@ -0,0 +1,35 @@
+"""File Upload Examples — built-in Swagger UI plugin."""
+
+from importlib.resources import files
+
+from .._base import SwaggerPluginContribution
+from ._body_factory import file_upload_body, unwrap_json_schema
+from ._schema_patcher import patch_file_upload_examples
+
+__all__ = [
+    "FileUploadExamplesPlugin",
+    "file_upload_body",
+    "unwrap_json_schema",
+]
+
+_PACKAGE = "csrd.versioning.swagger_plugins.file_upload"
+
+
+class FileUploadExamplesPlugin:
+    """Built-in plugin that adds file upload example dropdowns to Swagger UI."""
+
+    name = "file_upload_examples"
+
+    def __init__(self) -> None:
+        pkg = files(_PACKAGE)
+        self._js = pkg.joinpath("file_upload_plugin.js").read_text(encoding="utf-8")
+        css_path = pkg.joinpath("file_upload_plugin.css")
+        self._css = css_path.read_text(encoding="utf-8")
+
+    def contribute(self) -> SwaggerPluginContribution:
+        return SwaggerPluginContribution(
+            extra_css=self._css,
+            extra_js=self._js,
+            bundle_plugins=("FileUploadExamplesPlugin",),
+            schema_patcher=patch_file_upload_examples,
+        )