csrd-versioning 0.1.0__py3-none-any.whl

csrd/versioning/__init__.py

@@ -0,0 +1,99 @@
+"""API versioning, dispatch, docs, and actuator for FastAPI."""
+
+from ._constants import (
+    API_VERSION_HEADER_NAME,
+    APP_ID_HEADER_NAME,
+    AUTH_HEADER_NAME,
+    HIT_ID_HEADER_NAME,
+    HTTP_METHODS,
+    UNVERSIONED,
+    UNVERSIONED_DISPLAY_LABEL,
+    VERSIONING_SETTINGS_STATE_KEY,
+)
+from ._core import (
+    map_version_path,
+    normalize_prefix,
+    normalize_unversioned_label,
+    normalize_version,
+    resolve_prefix,
+    resolve_version,
+    validate_version_mapping_keys,
+)
+from ._dependencies import (
+    ApiVersionDep,
+    AppIdDep,
+    HitIdDep,
+    param_factory,
+    uuid_id_factory,
+)
+from ._fastapi_types import (
+    ExceptionHandlerProvider,
+    ExHandler,
+    Middleware,
+    NormalizedDependencySpec,
+    PathParamDependencies,
+    PathParamDependencySpec,
+    VersionedAppConfigurer,
+    VersionedAppLifespan,
+)
+from ._helpers import (
+    HeadersGetter,
+    find_bearer,
+    find_token,
+)
+from ._orchestration import (
+    configure_versioned_api,
+    create_versioned_app,
+    default_exception_handlers_provider,
+    get_current_user_claims,
+)
+from ._settings import VersioningSettings, load_app_name, load_versioning_settings
+from ._swagger_ui_version import SWAGGER_UI_VERSION
+from ._types import VersionedAppState, VersionKey, VersionMap
+from .actuator import register_actuator_router
+
+__all__ = (
+    "API_VERSION_HEADER_NAME",
+    "APP_ID_HEADER_NAME",
+    "AUTH_HEADER_NAME",
+    "HIT_ID_HEADER_NAME",
+    "HTTP_METHODS",
+    "SWAGGER_UI_VERSION",
+    "UNVERSIONED",
+    "UNVERSIONED_DISPLAY_LABEL",
+    "VERSIONING_SETTINGS_STATE_KEY",
+    "ApiVersionDep",
+    "AppIdDep",
+    "ExHandler",
+    "ExceptionHandlerProvider",
+    "HeadersGetter",
+    "HitIdDep",
+    "Middleware",
+    "NormalizedDependencySpec",
+    "PathParamDependencies",
+    "PathParamDependencySpec",
+    "VersionKey",
+    "VersionMap",
+    "VersionedAppConfigurer",
+    "VersionedAppLifespan",
+    "VersionedAppState",
+    "VersioningSettings",
+    "configure_versioned_api",
+    "create_versioned_app",
+    "default_exception_handlers_provider",
+    "find_bearer",
+    "find_token",
+    "get_current_user_claims",
+    "load_app_name",
+    "load_versioning_settings",
+    "map_version_path",
+    "normalize_prefix",
+    "normalize_unversioned_label",
+    "normalize_version",
+    "param_factory",
+    "register_actuator_router",
+    "resolve_prefix",
+    "resolve_version",
+    "uuid_id_factory",
+    "validate_version_mapping_keys",
+)

csrd/versioning/_constants.py

@@ -0,0 +1,28 @@
+from csrd.context._constants import APP_ID_HEADER_NAME, HIT_ID_HEADER_NAME
+
+AUTH_HEADER_NAME = "authorization"
+API_VERSION_HEADER_NAME = "x-api-version"
+VERSIONING_SETTINGS_STATE_KEY = "_versioning_settings"
+UNVERSIONED_DISPLAY_LABEL = "Unversioned"
+UNVERSIONED = "unv"
+"""Sentinel for unversioned routes in version mappings.
+
+Use as a key in ``version_mapping`` or as the ``default_version`` argument
+to indicate routes that do not belong to any numbered API version.
+This is the canonical normalized form — ``normalize_version(None)``
+and ``normalize_version("unversioned")`` both produce this value.
+"""
+
+HTTP_METHODS = frozenset({"get", "post", "put", "delete", "patch", "options", "head"})
+
+
+__all__ = (
+    "API_VERSION_HEADER_NAME",
+    "APP_ID_HEADER_NAME",
+    "AUTH_HEADER_NAME",
+    "HIT_ID_HEADER_NAME",
+    "HTTP_METHODS",
+    "UNVERSIONED",
+    "UNVERSIONED_DISPLAY_LABEL",
+    "VERSIONING_SETTINGS_STATE_KEY",
+)

csrd/versioning/_core.py

@@ -0,0 +1,240 @@
+import logging
+import re
+from enum import Enum
+
+from ._constants import UNVERSIONED_DISPLAY_LABEL
+from ._types import VersionKey, VersionMap
+
+logger = logging.getLogger(__name__)
+
+_UNVERSIONED_ALIASES: frozenset[str] = frozenset({"null", "unv", "none", "unversioned"})
+
+
+def normalize_version(version: VersionKey) -> str:
+    """Normalize version-like values to lowercase canonical routing keys.
+
+    - ``Enum`` members are unwrapped via ``.value`` before normalization.
+    - ``None``, empty strings, whitespace-only strings, and the aliases
+      ``"null"``, ``"unv"``, ``"none"``, ``"unversioned"`` (case-insensitive)
+      all normalize to ``"unv"``.
+    - All other values are stripped, then lowercased via ``str(version).lower()``,
+      including bare integers (e.g. ``3`` → ``"3"``).
+    """
+    if isinstance(version, Enum):
+        version = version.value
+    stringified = str(version).strip() if version is not None else ""
+    if version is None or not stringified or stringified.lower() in _UNVERSIONED_ALIASES:
+        return "unv"
+    return stringified.lower()
+
+
+def normalize_prefix(prefix: str) -> str:
+    """Return an API prefix guaranteed to start with ``/``.
+
+    Raises ``ValueError`` for empty strings — use ``"/"`` explicitly
+    if you intend to match all paths.
+    """
+    if not prefix:
+        raise ValueError("prefix must not be empty; pass '/' explicitly to match all paths")
+    normalized = prefix if prefix.startswith("/") else f"/{prefix}"
+    if normalized != "/":
+        normalized = normalized.rstrip("/")
+    return normalized
+
+
+def normalize_unversioned_label(version: VersionKey) -> str:
+    """Map unversioned-like keys to a stable display label."""
+    normalized = normalize_version(version)
+    if normalized == "unv":
+        return UNVERSIONED_DISPLAY_LABEL
+    return normalized
+
+
+def validate_version_mapping_keys(version_mapping: VersionMap) -> None:
+    """Ensure version keys do not collide after normalization."""
+    seen: dict[str, str] = {}
+    for key in version_mapping:
+        normalized = normalize_version(key)
+        if normalized in seen:
+            existing_key = seen[normalized]
+            raise ValueError(
+                "Duplicate version keys after normalization: "
+                f"{existing_key!r} and {key!r} both normalize to '{normalized}'."
+            )
+        seen[normalized] = str(key)
+
+
+def _latest_mapped_version(version_values: list[str]) -> str:
+    """Pick the latest mapped version deterministically.
+
+    Comparison uses only numeric segments (e.g. ``"v2"`` → ``(2,)``).
+    Non-numeric characters between digits are ignored, so versions
+    like ``"v1a2"`` and ``"v1b1"`` are compared as ``(1, 2)`` vs ``(1, 1)``.
+    """
+    candidates = [v for v in version_values if v != "unv"]
+    if not candidates:
+        return "unv"
+
+    numeric_candidates = [v for v in candidates if re.search(r"\d", v)]
+    if numeric_candidates:
+        return max(
+            numeric_candidates,
+            key=lambda value: (tuple(int(x) for x in re.findall(r"\d+", value)), value),
+        )
+
+    return sorted(candidates)[-1]
+
+
+def _default_mapped_version(
+    *, version_values: set[str], default_version: VersionKey | None
+) -> str | None:
+    """Return a normalized default version only when it exists in the mapping."""
+    if default_version is None:
+        return None
+
+    normalized_default = normalize_version(default_version)
+    if normalized_default in version_values:
+        return normalized_default
+
+    return None
+
+
+def _resolve_missing_requested_version(
+    *,
+    version_values: set[str],
+    mapped_default: str | None,
+) -> str:
+    """Resolve version when the request does not include a version header."""
+    if "unv" in version_values:
+        return "unv"
+
+    if mapped_default is not None:
+        return mapped_default
+
+    return _latest_mapped_version(list(version_values))
+
+
+def _resolve_unknown_requested_version(
+    *,
+    version_values: set[str],
+    mapped_default: str | None,
+) -> str:
+    """Resolve version when the request header is present but not mapped."""
+    if mapped_default is not None:
+        return mapped_default
+
+    if "unv" in version_values:
+        return "unv"
+
+    return _latest_mapped_version(list(version_values))
+
+
+def resolve_version(
+    *,
+    requested_version: str | None,
+    version_mapping: VersionMap | None = None,
+    default_version: VersionKey | None = None,
+    strict: bool = False,
+) -> str:
+    """Resolve request version using explicit, deterministic fallback precedence.
+
+    Fallback order when the requested version is not in *version_mapping*:
+
+    1. *default_version* (if provided and present in the mapping)
+    2. ``"unv"`` (if present in the mapping)
+    3. Latest numeric version
+
+    When *strict* is ``True``, an unrecognised requested version raises
+    ``ValueError`` instead of falling back.  Missing headers (``None``)
+    still fall back normally — strict mode only rejects explicit but
+    unknown version values.
+
+    .. important::
+
+    Raises ``ValueError`` if *version_mapping* keys collide after
+    normalization (e.g. ``None`` and ``"unversioned"`` both normalize
+    to ``"unv"``).
+    """
+    if version_mapping is None:
+        if requested_version is None:
+            return "unv"
+        return normalize_version(requested_version)
+
+    version_values = {normalize_version(key) for key in version_mapping}
+    if len(version_values) < len(version_mapping):
+        validate_version_mapping_keys(version_mapping)
+    mapped_default = _default_mapped_version(
+        version_values=version_values,
+        default_version=default_version,
+    )
+    requested_normalized = (
+        normalize_version(requested_version) if requested_version is not None else None
+    )
+
+    if requested_normalized in version_values:
+        return requested_normalized
+
+    if requested_normalized is None:
+        return _resolve_missing_requested_version(
+            version_values=version_values,
+            mapped_default=mapped_default,
+        )
+
+    if strict:
+        raise ValueError(
+            f"Requested API version {requested_normalized!r} is not available. "
+            f"Available versions: {', '.join(sorted(version_values))}"
+        )
+
+    resolved = _resolve_unknown_requested_version(
+        version_values=version_values,
+        mapped_default=mapped_default,
+    )
+    logger.warning(
+        "Requested API version %r is not mapped (available: %s); falling back to %r",
+        requested_normalized,
+        ", ".join(sorted(version_values)),
+        resolved,
+    )
+    return resolved
+
+
+def map_version_path(path: str, *, version: str, prefix: str) -> str:
+    """Rewrite an incoming path to include resolved version under the API prefix.
+
+    The prefix precondition is also enforced upstream by the dispatch guard
+    ``_should_dispatch_request``, but the check here is intentional
+    defense-in-depth — do not remove it.
+    """
+    if prefix == "/":
+        if not path.startswith("/"):
+            raise ValueError(f"path {path!r} does not start with prefix {prefix!r}")
+    elif not (path == prefix or path.startswith(f"{prefix}/")):
+        raise ValueError(f"path {path!r} does not start with prefix {prefix!r}")
+    normalized_version = normalize_version(version)
+    remainder = path[len(prefix) :]
+    if remainder and not remainder.startswith("/"):
+        remainder = f"/{remainder}"
+    # Normalize bare trailing slash so /api/ behaves identically to /api.
+    if remainder == "/":
+        remainder = ""
+    return f"{prefix.rstrip('/')}/{normalized_version}{remainder}"
+
+
+def resolve_prefix(prefix: str | None) -> str:
+    """Return normalized API prefix, defaulting to `/api`."""
+    if prefix is None:
+        prefix = "/api"
+
+    return normalize_prefix(prefix)
+
+
+__all__ = (
+    "map_version_path",
+    "normalize_prefix",
+    "normalize_unversioned_label",
+    "normalize_version",
+    "resolve_prefix",
+    "resolve_version",
+    "validate_version_mapping_keys",
+)

csrd/versioning/_dependencies.py

@@ -0,0 +1,67 @@
+"""FastAPI dependency functions for injecting versioning context values."""
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import Depends, HTTPException, Path
+
+from csrd.context import get_api_version, get_app_id, get_hit_id
+
+
+def param_factory(name: str = "value", validator=None):
+    """Create a FastAPI dependency that extracts a string path parameter and,
+    optionally, validates it using a user-provided callable.
+    """
+
+    def dependency(value: Annotated[str, Path(alias=name)]):
+        if validator is not None:
+            try:
+                validator(value)
+            except (ValueError, TypeError, AssertionError) as exc:
+                raise HTTPException(
+                    status_code=422, detail=f"Invalid path parameter {name}: {exc}"
+                ) from exc
+        return str(value)
+
+    return dependency
+
+
+def uuid_id_factory(name: str = "id"):
+    def dependency(value: Annotated[str, Path(alias=name)]):
+        try:
+            return UUID(str(value))
+        except (ValueError, TypeError, AttributeError) as exc:
+            raise HTTPException(
+                status_code=422, detail=f"{name} is not a valid UUID: {value}"
+            ) from exc
+
+    return dependency
+
+
+def api_version_dependency() -> str | None:
+    """Return the resolved API version for the current request context."""
+    return get_api_version()
+
+
+def app_id_dependency() -> str | None:
+    """Return the current request app-id header value."""
+    return get_app_id()
+
+
+def hit_id_dependency() -> str | None:
+    """Return the current request hit-id header value."""
+    return get_hit_id()
+
+
+ApiVersionDep = Annotated[str | None, Depends(api_version_dependency)]
+AppIdDep = Annotated[str | None, Depends(app_id_dependency)]
+HitIdDep = Annotated[str | None, Depends(hit_id_dependency)]
+
+
+__all__ = (
+    "ApiVersionDep",
+    "AppIdDep",
+    "HitIdDep",
+    "param_factory",
+    "uuid_id_factory",
+)

csrd/versioning/_dependency_wiring.py

@@ -0,0 +1,272 @@
+"""Dependency injection wiring for versioned FastAPI routes."""
+
+import logging
+import re
+from collections.abc import AsyncIterator, Callable
+from http import HTTPStatus
+from typing import Any
+
+from fastapi import Depends, FastAPI
+from fastapi.routing import APIRoute
+from fastapi.security import HTTPBearer
+from starlette.requests import Request
+from starlette.routing import Route
+
+from csrd.context import (
+    PathValue,
+    reset_path_params,
+    reset_query_params,
+    set_path_params,
+    set_query_params,
+)
+from csrd.versioning._core import normalize_prefix, normalize_version
+
+from ._dependencies import param_factory
+from ._fastapi_types import (
+    NormalizedDependencySpec,
+    PathParamDependencies,
+    VersionMap,
+)
+from ._helpers import (
+    DependsParam,
+    _dep_already_present,
+    _extract_param_names,
+    _normalize_dep,
+    _rebuild_route,
+    _route_has_param,
+)
+
+logger = logging.getLogger(__name__)
+
+_PATH_PARAM_RE = re.compile(r"\{(\w+)(?::\w+)?\}")
+
+
+def _get_route_param_names(route: APIRoute) -> set[str]:
+    """Extract path parameter names from the route path template."""
+    return set(_PATH_PARAM_RE.findall(route.path))
+
+
+class PathParamParser:
+    """FastAPI dependency that captures path/query params into core contextvars."""
+
+    async def __call__(self, request: Request) -> AsyncIterator[None]:
+        path_token = set_path_params(PathValue(request.path_params))
+        query_token = set_query_params(PathValue(request.query_params))
+
+        try:
+            yield
+        finally:
+            reset_path_params(path_token)
+            reset_query_params(query_token)
+
+
+def _status_description(status_code: int) -> str:
+    """Return a friendly description for an HTTP status code."""
+    try:
+        return HTTPStatus(status_code).phrase
+    except ValueError:
+        return f"HTTP {status_code}"
+
+
+def _documented_error_statuses_from_handlers(
+    resolved_handler_map: dict[int | type[Exception], Any],
+) -> set[int]:
+    """Extract numeric status codes from resolved exception handler keys."""
+    status_codes = {key for key in resolved_handler_map if isinstance(key, int)}
+    status_codes.update({401, 403})
+    return status_codes
+
+
+def _uncovered_route_params(
+    route: APIRoute, existing: list[NormalizedDependencySpec] | None = None
+) -> set[str]:
+    if existing is None:
+        existing = []
+
+    covered: set[str] = set()
+    for _, __, required_params in existing:
+        if all(_route_has_param(route, name) for name in required_params):
+            covered.update(required_params)
+
+    return _get_route_param_names(route) - covered
+
+
+def _route_bearer_guard_opt_out(route: APIRoute) -> bool:
+    """Return True when a route opts out of bearer dependency enforcement."""
+    openapi_extra = route.openapi_extra or {}
+    return openapi_extra.get("x-bearer-guard") is False
+
+
+def _remove_bearer_dependencies(
+    dependencies: list[DependsParam],
+) -> tuple[list[DependsParam], bool]:
+    """Remove HTTPBearer-based dependencies from a dependency list."""
+    filtered_dependencies: list[DependsParam] = []
+    removed_any = False
+
+    for dependency in dependencies:
+        dep_callable = getattr(dependency, "dependency", None)
+        if isinstance(dep_callable, HTTPBearer):
+            removed_any = True
+            continue
+        filtered_dependencies.append(dependency)
+
+    return filtered_dependencies, removed_any
+
+
+def _has_dependency(dependencies: list[DependsParam], dependency: Callable[..., Any]) -> bool:
+    """Return True when a dependency callable is already present by identity."""
+    return any(dep.dependency is dependency for dep in dependencies)
+
+
+def _build_normalized_dependency_specs(
+    path_param_dependencies: PathParamDependencies | None,
+) -> list[NormalizedDependencySpec]:
+    """Normalize and filter path-param dependency specs for route injection."""
+    normalized_specs: list[NormalizedDependencySpec] = []
+
+    if path_param_dependencies:
+        for spec in path_param_dependencies:
+            dep_param, dep_callable = _normalize_dep(spec)
+            required_params = _extract_param_names(dep_callable)
+            if not required_params:
+                continue
+            normalized_specs.append((dep_param, dep_callable, required_params))
+
+    return normalized_specs
+
+
+def _strip_prefix_from_versioned_routes(versioned_app: FastAPI, prefix: str) -> None:
+    """Remove already-present API prefix from mounted versioned route paths."""
+    normalized_prefix = normalize_prefix(prefix)
+    if normalized_prefix == "/":
+        return
+
+    for route in versioned_app.routes:
+        if isinstance(route, Route):
+            if route.path == normalized_prefix:
+                route.path = "/"
+                continue
+
+            if route.path.startswith(f"{normalized_prefix}/"):
+                route.path = route.path[len(normalized_prefix) :]
+
+
+def _apply_path_param_deps_to_route(
+    route: APIRoute,
+    dependencies: list[DependsParam],
+    normalized_specs: list[NormalizedDependencySpec],
+) -> bool:
+    """Inject path-param dependencies for route-matching parameter names."""
+    if not normalized_specs:
+        return False
+
+    changed = False
+    route_specs = list(normalized_specs)
+    params = _uncovered_route_params(route, route_specs)
+
+    for param in params:
+        factory = param_factory(param)
+        route_specs.append((Depends(factory), factory, {param}))
+
+    for dep_param, _dep_callable, required_params in route_specs:
+        if all(
+            _route_has_param(route, name) for name in required_params
+        ) and not _dep_already_present(dependencies, dep_param):
+            dependencies.append(dep_param)
+            changed = True
+
+    return changed
+
+
+def _ensure_path_param_parser_dependency(dependencies: list[DependsParam]) -> bool:
+    """Ensure `PathParamParser` exists in route dependencies."""
+    if any(isinstance(dep.dependency, PathParamParser) for dep in dependencies):
+        return False
+
+    dependencies.append(Depends(PathParamParser()))
+    return True
+
+
+def _process_versioned_route(
+    route: APIRoute,
+    *,
+    normalized_specs: list[NormalizedDependencySpec],
+    documented_error_statuses: set[int] | None,
+) -> tuple[list[DependsParam], bool]:
+    """Apply dependency mutations to a single versioned route."""
+    dependencies = list(route.dependencies or [])
+    dependencies_changed = False
+
+    if _route_bearer_guard_opt_out(route):
+        dependencies, removed_bearer_dependency = _remove_bearer_dependencies(dependencies)
+        if removed_bearer_dependency:
+            dependencies_changed = True
+            logger.debug("Bearer dependency removed (opt-out) from route: %s", route.path)
+
+    if _apply_path_param_deps_to_route(
+        route,
+        dependencies,
+        normalized_specs,
+    ):
+        dependencies_changed = True
+
+    if _ensure_path_param_parser_dependency(dependencies):
+        dependencies_changed = True
+
+    return dependencies, dependencies_changed
+
+
+def _apply_route_dependency_updates(
+    app: FastAPI,
+    versioned_app: FastAPI,
+    route_index: int,
+    route: APIRoute,
+    dependencies: list[DependsParam],
+) -> None:
+    """Replace route with a new instance carrying updated dependencies."""
+    versioned_app.routes[route_index] = _rebuild_route(route, dependencies)
+    versioned_app.openapi_schema = None
+    app.openapi_schema = None
+
+
+def _mount_and_wire_versions(
+    app: FastAPI,
+    version_mapping: VersionMap,
+    prefix: str,
+    path_param_dependencies: PathParamDependencies | None = None,
+    documented_error_statuses: set[int] | None = None,
+) -> None:
+    """Mount versioned apps and inject dependencies required for routing."""
+    normalized_specs = _build_normalized_dependency_specs(path_param_dependencies)
+
+    for api, versioned_app in version_mapping.items():
+        _strip_prefix_from_versioned_routes(versioned_app, prefix)
+
+        for i, route in enumerate(versioned_app.routes):
+            if not isinstance(route, APIRoute):
+                continue
+
+            dependencies, dependencies_changed = _process_versioned_route(
+                route,
+                normalized_specs=normalized_specs,
+                documented_error_statuses=documented_error_statuses,
+            )
+
+            if dependencies_changed:
+                _apply_route_dependency_updates(
+                    app,
+                    versioned_app,
+                    i,
+                    route,
+                    dependencies,
+                )
+
+        app.include_router(versioned_app.router, prefix=f"{prefix}/{normalize_version(api)}")
+        logger.debug(
+            "Mounted version %s at %s/%s with %d routes",
+            api,
+            prefix,
+            normalize_version(api),
+            sum(1 for r in versioned_app.routes if isinstance(r, APIRoute)),
+        )