csrd-versioning 0.1.0__py3-none-any.whl

csrd/versioning/_fastapi_types.py

@@ -0,0 +1,44 @@
+"""Type aliases for versioned FastAPI application configuration.
+
+Defines the public type vocabulary used by ``configure_versioned_api`` and
+``create_versioned_app``: version maps, middleware specs, exception handler
+providers, context-guard callables, and path-parameter dependency descriptors.
+"""
+
+from collections.abc import Callable, Mapping, Sequence
+from contextlib import AbstractAsyncContextManager
+from typing import Annotated, Any
+
+from fastapi import FastAPI
+from fastapi.params import Depends as DependsParam
+from starlette.types import ExceptionHandler
+
+from csrd.versioning._types import VersionedAppState, VersionKey
+
+VersionMap = Mapping[VersionKey, FastAPI]
+VersionedAppConfigurer = Callable[[FastAPI], None]
+VersionedAppLifespan = Callable[[FastAPI], AbstractAsyncContextManager[Any]]
+
+Middleware = type | tuple[type, dict[str, Any] | None]
+
+ExHandler = tuple[int | type[Exception], ExceptionHandler]
+ExceptionHandlerProvider = Callable[[], Mapping[int | type[Exception], ExceptionHandler]]
+
+
+PathParamDependencySpec = DependsParam | Callable[..., Any] | Annotated[Any, DependsParam]
+PathParamDependencies = Sequence[PathParamDependencySpec]
+NormalizedDependencySpec = tuple[DependsParam, Callable[..., Any], set[str]]
+
+__all__ = (
+    "ExHandler",
+    "ExceptionHandlerProvider",
+    "Middleware",
+    "NormalizedDependencySpec",
+    "PathParamDependencies",
+    "PathParamDependencySpec",
+    "VersionKey",
+    "VersionMap",
+    "VersionedAppConfigurer",
+    "VersionedAppLifespan",
+    "VersionedAppState",
+)

csrd/versioning/_helpers.py

@@ -0,0 +1,149 @@
+import inspect
+from collections.abc import Callable
+from http import HTTPStatus
+from typing import Annotated, Any, get_args, get_origin
+
+from fastapi import Depends, HTTPException
+from fastapi.params import Depends as DependsParam
+from fastapi.params import Param as PathParam
+from fastapi.routing import APIRoute
+from starlette.datastructures import Headers
+
+from csrd.context import get_headers
+from csrd.versioning._constants import AUTH_HEADER_NAME
+
+HeadersGetter = Callable[[], Headers | dict] | Headers | dict
+
+
+def find_bearer(
+    headers_or_getter: HeadersGetter | None = None, *, fail_on_missing: bool = True
+) -> str | None:
+    """Return the bearer/authorization header value from provided or contextual headers."""
+    if headers_or_getter is not None and callable(headers_or_getter):
+        headers = headers_or_getter()
+    elif headers_or_getter is not None and isinstance(headers_or_getter, (Headers, dict)):
+        headers = headers_or_getter
+    else:
+        headers = get_headers()
+
+    if headers:
+        bearer = headers.get(AUTH_HEADER_NAME) or headers.get("Authorization")
+        if bearer is not None:
+            return bearer
+
+    if fail_on_missing:
+        raise HTTPException(status_code=HTTPStatus.UNAUTHORIZED, detail="Unauthorized")
+
+    return None
+
+
+def find_token() -> str:
+    """Extract and return raw token from bearer header value."""
+    bearer = find_bearer()
+    if bearer is None:
+        raise HTTPException(status_code=HTTPStatus.UNAUTHORIZED, detail="Unauthorized")
+
+    bearer = bearer.strip()
+    if bearer == "":
+        raise HTTPException(status_code=HTTPStatus.UNAUTHORIZED, detail="Unauthorized")
+
+    if bearer.lower() == "bearer":
+        raise HTTPException(status_code=HTTPStatus.UNAUTHORIZED)
+
+    if bearer.lower().startswith("bearer "):
+        token = bearer[7:].strip()
+        if token == "":
+            raise HTTPException(status_code=HTTPStatus.UNAUTHORIZED)
+        return token
+
+    return bearer
+
+
+def _route_path_template(route: APIRoute) -> str:
+    """Return canonical route path template used for dependency calculations."""
+    return str(getattr(route, "path_format", None) or route.path)
+
+
+def _route_has_param(route: APIRoute, name: str) -> bool:
+    """Return True when route path template contains a named path parameter."""
+    return f"{{{name}}}" in _route_path_template(route)
+
+
+def _unwrap_depends_from_annotated(obj: Any) -> DependsParam | None:
+    """Extract `Depends` metadata from `typing.Annotated`, if present."""
+    if get_origin(obj) is not Annotated:
+        return None
+    meta = get_args(obj)[1:]
+    for m in meta:
+        if isinstance(m, DependsParam):
+            return m
+    return None
+
+
+def _normalize_dep(obj: Any) -> tuple[DependsParam, Callable[..., Any]]:
+    """Normalize supported dependency forms into `(DependsParam, callable)`."""
+    if isinstance(obj, DependsParam):
+        if obj.dependency is None:
+            raise TypeError("Depends(...) must wrap a callable dependency.")
+        return obj, obj.dependency
+
+    ann = _unwrap_depends_from_annotated(obj)
+    if ann is not None:
+        if ann.dependency is None:
+            raise TypeError("Annotated Depends(...) must wrap a callable dependency.")
+        return ann, ann.dependency
+
+    if callable(obj):
+        d = Depends(obj)
+        return d, obj
+
+    raise TypeError(f"Object is not a valid dependency: {obj!r}")
+
+
+def _extract_param_names(dep_callable: Callable[..., Any]) -> set[str]:
+    """Collect path-parameter names consumed by a dependency callable."""
+    names: set[str] = set()
+    sig = inspect.signature(dep_callable)
+
+    for p in sig.parameters.values():
+        if isinstance(p.default, PathParam):
+            alias = getattr(p.default, "alias", None)
+            names.add(alias or p.name)
+            continue
+
+        ann = p.annotation
+        if get_origin(ann) is Annotated:
+            meta = get_args(ann)[1:]
+            for m in meta:
+                if isinstance(m, PathParam):
+                    alias = getattr(m, "alias", None)
+                    names.add(alias or p.name)
+
+    return names
+
+
+def _dep_already_present(deps: list[Any], dep: DependsParam) -> bool:
+    """Return True when dependency list already contains the same callable."""
+    return any(isinstance(d, DependsParam) and d.dependency is dep.dependency for d in deps)
+
+
+def _rebuild_route(route: APIRoute, dependencies: list[DependsParam]) -> APIRoute:
+    """Create a new APIRoute with updated dependencies."""
+    sig = inspect.signature(APIRoute.__init__)
+    kwargs: dict[str, Any] = {}
+    for name in sig.parameters:
+        if name == "self":
+            continue
+        if name == "dependencies":
+            kwargs["dependencies"] = dependencies
+            continue
+        if hasattr(route, name):
+            kwargs[name] = getattr(route, name)
+    return APIRoute(**kwargs)
+
+
+__all__ = (
+    "HeadersGetter",
+    "find_bearer",
+    "find_token",
+)

csrd/versioning/_orchestration.py

@@ -0,0 +1,399 @@
+import inspect
+import logging
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from fastapi import FastAPI
+from starlette.types import ExceptionHandler
+
+from csrd.context import (
+    configure_headers_context_provider,
+    get_api_version,
+)
+from csrd.context._fastapi_headers import get_headers as fastapi_get_headers
+from csrd.context._fastapi_headers import headers_context as fastapi_headers_context
+from csrd.context.platform import user_info_context
+from csrd.models.claims import UserClaims
+from csrd.versioning._constants import (
+    APP_ID_HEADER_NAME,
+    HIT_ID_HEADER_NAME,
+    UNVERSIONED,
+    VERSIONING_SETTINGS_STATE_KEY,
+)
+from csrd.versioning._core import (
+    normalize_version,
+    resolve_prefix,
+    validate_version_mapping_keys,
+)
+from csrd.versioning._settings import load_app_name, load_versioning_settings
+
+from . import _dependency_wiring as dependency_wiring
+from . import _docs as docs
+from ._dispatch import VersionDispatchMiddleware
+from ._fastapi_types import (
+    ExceptionHandlerProvider,
+    ExHandler,
+    Middleware,
+    PathParamDependencies,
+    VersionedAppConfigurer,
+    VersionedAppLifespan,
+    VersionedAppState,
+    VersionKey,
+    VersionMap,
+)
+from .actuator import register_actuator_router
+from .actuator.plugins import ActuatorPlugin
+
+logger = logging.getLogger(__name__)
+
+_VERSIONING_CONFIGURED_KEY = "_versioning_configured"
+
+
+def default_exception_handlers_provider() -> Mapping[int | type[Exception], ExceptionHandler]:
+    """Return the default exception-handler map used by versioning integrations."""
+    from csrd.versioning.exception_handlers import EXCEPTION_HANDLERS
+
+    return EXCEPTION_HANDLERS  # type: ignore[return-value]
+
+
+def get_current_user_claims() -> UserClaims | None:
+    """Return current request user claims from FastAPI/platform contextvars."""
+    return user_info_context.get()  # type: ignore[return-value]
+
+
+def configure_versioned_api(
+    app: FastAPI,
+    version_mapping: VersionMap,
+    *,
+    default_version: VersionKey | None = None,
+    app_name: str | None = None,
+    middleware: list[Middleware] | None = None,
+    ex_handlers: list[ExHandler] | None = None,
+    exception_handler_provider: ExceptionHandlerProvider | None = None,
+    prefix: str | None = None,
+    hit_id_header: str | None = None,
+    app_id_header: str | None = None,
+    path_param_dependencies: PathParamDependencies | None = None,
+    current_user_claims_provider: Callable[[], Any] | None = None,
+    strict_version_matching: bool = False,
+    include_info_endpoints: bool = True,
+    include_root_favicon_alias: bool = True,
+    include_actuator_endpoints: bool = True,
+    actuator_plugins: list[ActuatorPlugin] | None = None,
+    swagger_plugins: list | None = None,
+) -> None:
+    """Configure versioned routing, docs, middleware, and exception handling."""
+    if getattr(app.state, _VERSIONING_CONFIGURED_KEY, False):
+        logger.warning("configure_versioned_api() already called on this app; skipping.")
+        return
+
+    if exception_handler_provider is None:
+        exception_handler_provider = default_exception_handlers_provider
+    if current_user_claims_provider is None:
+        current_user_claims_provider = get_current_user_claims
+
+    configure_headers_context_provider(
+        get_headers=fastapi_get_headers,
+        set_headers=fastapi_headers_context.set,
+        reset_headers=fastapi_headers_context.reset,
+    )
+
+    if getattr(app.state, VERSIONING_SETTINGS_STATE_KEY, None) is None:
+        setattr(app.state, VERSIONING_SETTINGS_STATE_KEY, load_versioning_settings())
+    versioning_settings = getattr(app.state, VERSIONING_SETTINGS_STATE_KEY, None)
+
+    if not version_mapping:
+        raise ValueError("version_mapping cannot be empty. Provide at least one version mapping.")
+
+    validate_version_mapping_keys(version_mapping)
+    _propagate_state_to_versioned_apps(app, version_mapping)
+
+    app_name = load_app_name(app_name)
+    prefix = resolve_prefix(prefix)
+
+    logger.info(
+        "Configuring versioned API: app_name=%s, prefix=%s, versions=%s",
+        app_name,
+        prefix,
+        [str(k) for k in version_mapping],
+    )
+
+    if default_version is None:
+        default_version = UNVERSIONED
+
+    if path_param_dependencies is None:
+        path_param_dependencies = []
+    else:
+        path_param_dependencies = list(path_param_dependencies)
+
+    if hit_id_header is None:
+        hit_id_header = HIT_ID_HEADER_NAME
+
+    if app_id_header is None:
+        app_id_header = APP_ID_HEADER_NAME
+
+    resolved_handler_map = _resolve_exception_handlers(
+        exception_handler_provider=exception_handler_provider,
+        version_mapping=version_mapping,
+        exception_handlers=ex_handlers,
+    )
+
+    documented_error_statuses = dependency_wiring._documented_error_statuses_from_handlers(
+        resolved_handler_map=resolved_handler_map,
+    )
+
+    docs._register_custom_docs(
+        app=app,
+        version_mapping=version_mapping,
+        prefix=prefix,
+        app_name=app_name,
+        hit_id_header=hit_id_header,
+        app_id_header=app_id_header,
+        default_version=default_version,
+        strict_version_matching=strict_version_matching,
+        include_info_endpoints=include_info_endpoints,
+        build_tag=getattr(versioning_settings, "build_tag", None),
+        include_root_favicon_alias=include_root_favicon_alias,
+        swagger_plugins=swagger_plugins,
+    )
+
+    if include_actuator_endpoints:
+        register_actuator_router(app, plugins=actuator_plugins)
+
+    dependency_wiring._mount_and_wire_versions(
+        app=app,
+        version_mapping=version_mapping,
+        prefix=prefix,
+        path_param_dependencies=path_param_dependencies,
+        documented_error_statuses=documented_error_statuses,
+    )
+    _apply_middleware(
+        app,
+        prefix,
+        version_mapping,
+        middleware,
+        default_version,
+        hit_id_header,
+        app_id_header,
+        strict_version_matching,
+    )
+    _apply_exception_handlers(app, resolved_handler_map)
+
+    setattr(app.state, _VERSIONING_CONFIGURED_KEY, True)
+
+
+def create_versioned_app(
+    version_mapping: VersionMap,
+    *,
+    title: str | None = None,
+    lifespan: VersionedAppLifespan | None = None,
+    app_state: VersionedAppState | None = None,
+    configure_app: VersionedAppConfigurer | None = None,
+    default_version: VersionKey | None = None,
+    app_name: str | None = None,
+    middleware: list[Middleware] | None = None,
+    ex_handlers: list[ExHandler] | None = None,
+    exception_handler_provider: ExceptionHandlerProvider | None = None,
+    prefix: str | None = None,
+    hit_id_header: str | None = None,
+    app_id_header: str | None = None,
+    path_param_dependencies: PathParamDependencies | None = None,
+    current_user_claims_provider: Callable[[], Any] | None = None,
+    strict_version_matching: bool = False,
+    include_info_endpoints: bool = True,
+    include_root_favicon_alias: bool = True,
+    include_actuator_endpoints: bool = True,
+    actuator_plugins: list[ActuatorPlugin] | None = None,
+    swagger_plugins: list | None = None,
+) -> FastAPI:
+    """Create and configure a versioned root FastAPI app."""
+    app_kwargs: dict[str, Any] = {}
+    app_kwargs["title"] = title or load_app_name()
+    if lifespan is not None:
+        app_kwargs["lifespan"] = lifespan
+
+    # Disable FastAPI's built-in /docs — the versioning framework registers
+    # its own per-version OpenAPI schemas at /openapi/{version}.json and a
+    # custom Swagger UI at /swagger-ui/.
+    # Disable FastAPI's built-in /docs and /redoc — the versioning framework
+    # registers its own per-version equivalents at /swagger-ui/ and /redoc.
+    app_kwargs.setdefault("docs_url", None)
+    app_kwargs.setdefault("redoc_url", None)
+
+    app = FastAPI(**app_kwargs)
+
+    if app_state is not None:
+        for state_key, state_value in app_state.items():
+            setattr(app.state, state_key, state_value)
+
+    if configure_app is not None:
+        configure_app(app)
+
+    configure_versioned_api(
+        app=app,
+        version_mapping=version_mapping,
+        default_version=default_version,
+        app_name=app_name,
+        middleware=middleware,
+        ex_handlers=ex_handlers,
+        exception_handler_provider=exception_handler_provider,
+        prefix=prefix,
+        hit_id_header=hit_id_header,
+        app_id_header=app_id_header,
+        path_param_dependencies=path_param_dependencies,
+        current_user_claims_provider=current_user_claims_provider,
+        strict_version_matching=strict_version_matching,
+        include_info_endpoints=include_info_endpoints,
+        include_root_favicon_alias=include_root_favicon_alias,
+        include_actuator_endpoints=include_actuator_endpoints,
+        actuator_plugins=actuator_plugins,
+        swagger_plugins=swagger_plugins,
+    )
+
+    return app
+
+
+def _apply_middleware(
+    app: FastAPI,
+    prefix: str,
+    version_mapping: VersionMap,
+    middleware: list[Middleware] | None = None,
+    default_version: VersionKey | None = None,
+    hit_id_header: str = HIT_ID_HEADER_NAME,
+    app_id_header: str = APP_ID_HEADER_NAME,
+    strict_version_matching: bool = False,
+) -> None:
+    _register_middleware(app, middleware)
+
+    app.add_middleware(
+        VersionDispatchMiddleware,
+        prefix=prefix,
+        version_mapping=version_mapping,
+        default_version=default_version,
+        hit_id_header=hit_id_header,
+        app_id_header=app_id_header,
+        strict_version_matching=strict_version_matching,
+    )
+
+
+def _register_middleware(
+    app: FastAPI,
+    middleware: list[Middleware] | None,
+) -> None:
+    if middleware is None:
+        return
+
+    for m in middleware:
+        if isinstance(m, tuple):
+            cls, kwargs = m
+            app.add_middleware(cls, **(kwargs or {}))  # type: ignore[arg-type]
+        elif isinstance(m, type):
+            app.add_middleware(m)  # type: ignore[arg-type]
+        else:
+            raise TypeError(
+                f"middleware entries must be a class or (class, kwargs) tuple, got {type(m).__name__}"
+            )
+
+    logger.debug("Registered %d user-provided middleware entries", len(middleware))
+
+
+def _is_builtin_exception_handler(handler: ExceptionHandler) -> bool:
+    return getattr(handler, "__module__", "").startswith("fastapi.")
+
+
+def _resolve_exception_handlers(
+    *,
+    exception_handler_provider: ExceptionHandlerProvider,
+    version_mapping: VersionMap,
+    exception_handlers: list[ExHandler] | None,
+) -> dict[int | type[Exception], ExceptionHandler]:
+    resolved_handler_map = dict(exception_handler_provider())
+
+    per_version_handlers = _collect_sub_app_exception_handlers(version_mapping)
+    for exc_key, version_handlers in per_version_handlers.items():
+        fallback = resolved_handler_map.get(exc_key)
+        resolved_handler_map[exc_key] = _make_version_scoped_handler(version_handlers, fallback)
+
+    if exception_handlers is not None:
+        for ex in exception_handlers:
+            resolved_handler_map[ex[0]] = ex[1]
+
+    return resolved_handler_map
+
+
+def _make_version_scoped_handler(
+    version_handlers: dict[str, ExceptionHandler],
+    fallback: ExceptionHandler | None,
+) -> ExceptionHandler:
+    async def handler(request: Any, exc: Any) -> Any:
+        version = get_api_version()
+        version_handler = version_handlers.get(version) if version else None
+        if version_handler is not None:
+            result = version_handler(request, exc)
+            return await result if inspect.isawaitable(result) else result
+        if fallback is not None:
+            result = fallback(request, exc)
+            return await result if inspect.isawaitable(result) else result
+        raise exc
+
+    return handler
+
+
+def _collect_sub_app_exception_handlers(
+    version_mapping: VersionMap,
+) -> dict[int | type[Exception], dict[str, ExceptionHandler]]:
+    collected: dict[int | type[Exception], dict[str, ExceptionHandler]] = {}
+
+    for version_key, versioned_app in version_mapping.items():
+        normalized = normalize_version(version_key)
+        for exc_key, handler in versioned_app.exception_handlers.items():
+            if _is_builtin_exception_handler(handler):
+                continue
+            if exc_key not in collected:
+                collected[exc_key] = {}
+            collected[exc_key][normalized] = handler
+
+    if collected:
+        logger.debug(
+            "Collected %d version-scoped exception handler(s) from sub-apps: %s",
+            len(collected),
+            [str(k) for k in collected],
+        )
+
+    return collected
+
+
+def _apply_exception_handlers(
+    app: FastAPI,
+    resolved_handler_map: dict[int | type[Exception], ExceptionHandler],
+) -> None:
+    for exception_key, handler in resolved_handler_map.items():
+        app.add_exception_handler(exception_key, handler)
+
+    logger.debug(
+        "Registered %d exception handlers: %s",
+        len(resolved_handler_map),
+        [str(k) for k in resolved_handler_map],
+    )
+
+
+def _propagate_state_to_versioned_apps(
+    app: FastAPI,
+    version_mapping: VersionMap,
+) -> None:
+    if not len(app.state):
+        return
+
+    for versioned_app in version_mapping.values():
+        for key in app.state:
+            if not hasattr(versioned_app.state, key):
+                setattr(versioned_app.state, key, app.state[key])
+
+
+__all__ = (
+    "VersionMap",
+    "configure_versioned_api",
+    "create_versioned_app",
+    "default_exception_handlers_provider",
+    "get_current_user_claims",
+)

csrd/versioning/_redoc.py

@@ -0,0 +1,98 @@
+"""Per-version ReDoc UI route registration."""
+
+from html import escape
+
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+
+
+def _register_redoc_routes(
+    app: FastAPI,
+    *,
+    version_list: list[str],
+    default_version: str | None = None,
+) -> None:
+    """Register per-version ReDoc UI at ``/redoc`` with a version query param.
+
+    Usage::
+
+        /redoc                        → latest (or default) version
+        /redoc?version=2025-06-20     → specific version
+
+    Points to existing ``/openapi/{version}.json`` routes registered by
+    :func:`_docs._register_openapi_json_routes`.
+    """
+
+    _SECURITY_HEADERS = {
+        "X-Content-Type-Options": "nosniff",
+        "X-Frame-Options": "DENY",
+    }
+
+    def _build_redoc_html(version: str, versions: list[str]) -> str:
+        title = escape(f"ReDoc - {version}")
+        openapi_url = f"/openapi/{version}.json"
+        options = "\n".join(
+            f'        <option value="{v}"{" selected" if v == version else ""}>{escape(v)}</option>'
+            for v in versions
+        )
+        return f"""<!DOCTYPE html>
+<html><head>
+<title>{title}</title>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700"
+      rel="stylesheet">
+<style>
+  body {{ margin: 0; padding: 0; }}
+  .version-bar {{
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 8px 16px;
+    background: #32329f;
+    color: #fff;
+    font-family: Montserrat, sans-serif;
+    font-size: 14px;
+  }}
+  .version-bar select {{
+    padding: 4px 8px;
+    border-radius: 4px;
+    border: 1px solid #5757c0;
+    background: #fff;
+    font-size: 14px;
+    cursor: pointer;
+  }}
+  .version-bar a {{
+    color: #ccc;
+    text-decoration: none;
+    margin-left: auto;
+    font-size: 13px;
+  }}
+  .version-bar a:hover {{ color: #fff; }}
+</style>
+</head><body>
+<div class="version-bar">
+  <label for="api-version"><strong>API Version:</strong></label>
+  <select id="api-version" onchange="switchVersion(this.value)">
+{options}
+  </select>
+  <a href="/swagger-ui/index.html">← Swagger UI</a>
+</div>
+<redoc spec-url="{openapi_url}" id="redoc-container"></redoc>
+<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
+<script>
+function switchVersion(v) {{
+  const url = new URL(window.location);
+  url.searchParams.set('version', v);
+  window.location.href = url.toString();
+}}
+</script>
+</body></html>"""
+
+    @app.get("/redoc", include_in_schema=False)
+    async def redoc_ui(version: str | None = None) -> HTMLResponse:
+        resolved = version or default_version or (version_list[-1] if version_list else "latest")
+        return HTMLResponse(
+            _build_redoc_html(resolved.lower(), version_list),
+            headers=_SECURITY_HEADERS,
+        )