csrd-context 0.1.0__py3-none-any.whl

csrd/context/__init__.py

@@ -0,0 +1,51 @@
+from ._contextvars import (
+    configure_headers_context_provider,
+    get_api_version,
+    get_app_id,
+    get_headers,
+    get_hit_id,
+    get_path_params,
+    get_query_params,
+    reset_api_version_context,
+    reset_global_configuration,
+    reset_headers_context,
+    reset_path_params,
+    reset_query_params,
+    set_api_version_context,
+    set_headers_context,
+    set_path_params,
+    set_query_params,
+)
+from ._models import PathValue
+from .middleware import HTTPLoggingMiddleware, RequestContextMiddleware
+from .platform import app_id_context, hit_id_context, user_info_context
+
+__all__ = (
+    "HTTPLoggingMiddleware",
+    # Models
+    "PathValue",
+    # Middleware
+    "RequestContextMiddleware",
+    "app_id_context",
+    # Context accessors
+    "configure_headers_context_provider",
+    "get_api_version",
+    "get_app_id",
+    "get_headers",
+    "get_hit_id",
+    "get_path_params",
+    "get_query_params",
+    "hit_id_context",
+    "reset_api_version_context",
+    "reset_global_configuration",
+    "reset_headers_context",
+    "reset_path_params",
+    "reset_query_params",
+    "set_api_version_context",
+    # Context setters
+    "set_headers_context",
+    "set_path_params",
+    "set_query_params",
+    # Platform contextvars
+    "user_info_context",
+)

csrd/context/_constants.py

@@ -0,0 +1,6 @@
+"""Header name constants used by context infrastructure."""
+
+APP_ID_HEADER_NAME = "x-client-app-id"
+HIT_ID_HEADER_NAME = "x-client-hit-id"
+
+__all__ = ("APP_ID_HEADER_NAME", "HIT_ID_HEADER_NAME")

csrd/context/_contextvars.py

@@ -0,0 +1,184 @@
+import logging
+from collections.abc import Callable
+from contextvars import ContextVar, Token
+from typing import Any
+
+from ._constants import APP_ID_HEADER_NAME, HIT_ID_HEADER_NAME
+from ._models import PathValue
+
+logger = logging.getLogger(__name__)
+
+# Request-scoped context variables and accessors.
+#
+# The ``configure_*`` functions below set module-level state and must be called
+# once during application startup, before any requests are served.
+
+_PATH_CONTEXT_KEY = "path_context"
+_QUERY_CONTEXT_KEY = "query_context"
+_API_VERSION_CONTEXT_KEY = "api_version_context"
+
+_path_context: ContextVar[PathValue | None] = ContextVar(_PATH_CONTEXT_KEY, default=None)
+_query_context: ContextVar[PathValue | None] = ContextVar(_QUERY_CONTEXT_KEY, default=None)
+_api_version_context: ContextVar[str | None] = ContextVar(_API_VERSION_CONTEXT_KEY, default=None)
+
+_headers_getter: Callable[[], Any] | None = None
+_headers_setter: Callable[[Any], Any] | None = None
+_headers_resetter: Callable[[Any], None] | None = None
+_unconfigured_headers_warned = False
+
+
+def reset_global_configuration() -> None:
+    """Reset all module-level configuration to defaults.
+
+    Intended for test teardown to prevent cross-test contamination.
+    """
+    global _headers_getter, _headers_setter, _headers_resetter
+    global _unconfigured_headers_warned
+    _headers_getter = None
+    _headers_setter = None
+    _headers_resetter = None
+    _unconfigured_headers_warned = False
+
+
+def configure_headers_context_provider(
+    *,
+    get_headers: Callable[[], Any],
+    set_headers: Callable[[Any], Any],
+    reset_headers: Callable[[Any], None],
+) -> None:
+    """Configure framework-provided header context accessors.
+
+    Must be called during application startup, before serving requests.
+    """
+
+    global _headers_getter, _headers_setter, _headers_resetter
+    if _headers_getter is not None:
+        logger.warning("Overwriting previously configured headers_context_provider")
+    _headers_getter = get_headers
+    _headers_setter = set_headers
+    _headers_resetter = reset_headers
+
+
+def set_headers_context(headers: Any) -> Any:
+    """Set current request headers in the configured framework context."""
+    if _headers_setter is None:
+        raise RuntimeError(
+            "Headers context not configured. "
+            "Call configure_headers_context_provider() "
+            "before using the context system."
+        )
+    return _headers_setter(headers)
+
+
+def reset_headers_context(token: Any) -> None:
+    """Reset current request headers from the configured framework context."""
+    if token is None:
+        return
+    if _headers_resetter is None:
+        raise RuntimeError(
+            "Headers context not configured. "
+            "Call configure_headers_context_provider() "
+            "before using the context system."
+        )
+    _headers_resetter(token)
+
+
+def set_path_params(path_params: PathValue) -> Token[PathValue | None]:
+    """Store path parameters for the current async context; returns a token for reset."""
+    return _path_context.set(path_params)
+
+
+def reset_path_params(token: Token[PathValue | None]) -> None:
+    """Restore path parameters to their previous value."""
+    _path_context.reset(token)
+
+
+def set_query_params(query_params: PathValue) -> Token[PathValue | None]:
+    """Store query parameters for the current async context; returns a token for reset."""
+    return _query_context.set(query_params)
+
+
+def reset_query_params(token: Token[PathValue | None]) -> None:
+    """Restore query parameters to their previous value."""
+    _query_context.reset(token)
+
+
+def set_api_version_context(version: str | None) -> Token[str | None]:
+    """Store the resolved API version for the current async context."""
+    return _api_version_context.set(version)
+
+
+def reset_api_version_context(token: Token[str | None]) -> None:
+    """Restore the API version to its previous value."""
+    _api_version_context.reset(token)
+
+
+def get_path_params() -> PathValue:
+    """Return request path parameters captured in the current context."""
+    params = _path_context.get()
+    if params is None:
+        return PathValue()
+    return params
+
+
+def get_query_params() -> PathValue:
+    """Return request query parameters captured in the current context."""
+    params = _query_context.get()
+    if params is None:
+        return PathValue()
+    return params
+
+
+def get_api_version() -> str | None:
+    """Return resolved API version for the current request context."""
+    return _api_version_context.get()
+
+
+def get_headers() -> Any:
+    """Return current request headers captured during dispatch."""
+    global _unconfigured_headers_warned
+    if _headers_getter is None:
+        if not _unconfigured_headers_warned:
+            _unconfigured_headers_warned = True
+            logger.warning(
+                "Headers context provider not configured. "
+                "get_headers(), get_app_id(), and get_hit_id() will return empty values. "
+                "Call configure_headers_context_provider() during startup."
+            )
+        return {}
+    headers = _headers_getter()
+    if headers is None:
+        return {}
+    return headers
+
+
+def get_app_id() -> str | None:
+    """Return the current request app-id header value."""
+    val = get_headers().get(APP_ID_HEADER_NAME, None)
+    return str(val) if val is not None else None
+
+
+def get_hit_id() -> str | None:
+    """Return the current request hit-id header value."""
+    val = get_headers().get(HIT_ID_HEADER_NAME, None)
+    return str(val) if val is not None else None
+
+
+__all__ = (
+    "configure_headers_context_provider",
+    "get_api_version",
+    "get_app_id",
+    "get_headers",
+    "get_hit_id",
+    "get_path_params",
+    "get_query_params",
+    "reset_api_version_context",
+    "reset_global_configuration",
+    "reset_headers_context",
+    "reset_path_params",
+    "reset_query_params",
+    "set_api_version_context",
+    "set_headers_context",
+    "set_path_params",
+    "set_query_params",
+)

csrd/context/_fastapi_headers.py

@@ -0,0 +1,19 @@
+"""FastAPI-specific context variable for request headers."""
+
+from contextvars import ContextVar
+
+from starlette.datastructures import Headers
+
+HEADERS_KEY = "request_headers"
+
+_EMPTY_HEADERS = Headers()
+
+headers_context: ContextVar[Headers] = ContextVar(HEADERS_KEY, default=_EMPTY_HEADERS)
+
+
+def get_headers() -> Headers:
+    """Return request headers stored in the current context."""
+    return headers_context.get()
+
+
+__all__ = ("HEADERS_KEY", "get_headers", "headers_context")

csrd/context/_models.py

@@ -0,0 +1,34 @@
+from typing import Any
+
+
+class PathValue(dict[str, Any]):
+    """Dictionary wrapper that also supports dot-notation for key access."""
+
+    def __getattr__(self, item: str) -> Any:
+        """Return dict values via dot-notation, raising AttributeError for missing keys."""
+        if item.startswith("__"):
+            raise AttributeError(item)
+        try:
+            return self[item]
+        except KeyError:
+            raise AttributeError(f"'{type(self).__name__}' has no key '{item}'") from None
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        """Map attribute assignment to dictionary item assignment."""
+        if key.startswith("__"):
+            super().__setattr__(key, value)
+            return
+        self[key] = value
+
+    def __delattr__(self, item: str) -> None:
+        """Map attribute deletion to dictionary item deletion."""
+        if item.startswith("__"):
+            super().__delattr__(item)
+            return
+        try:
+            del self[item]
+        except KeyError as exc:
+            raise AttributeError(item) from exc
+
+
+__all__ = ("PathValue",)

csrd/context/middleware/__init__.py

@@ -0,0 +1,4 @@
+from ._logging import REQUEST_SCOPE_KEY, HTTPLoggingMiddleware, RequestScope
+from ._request import RequestContextMiddleware
+
+__all__ = ("REQUEST_SCOPE_KEY", "HTTPLoggingMiddleware", "RequestContextMiddleware", "RequestScope")

csrd/context/middleware/_logging.py

@@ -0,0 +1,121 @@
+"""HTTP logging middleware for FastAPI applications.
+
+Implemented as a raw ASGI middleware (no ``BaseHTTPMiddleware``) so that
+``StreamingResponse`` and SSE endpoints are not buffered.
+"""
+
+import logging
+import time
+import uuid
+from collections import defaultdict
+from http import HTTPStatus
+from typing import Any, TypedDict
+
+from starlette.requests import Request
+from starlette.routing import Match
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from csrd.models.claims import UserClaims
+
+logger = logging.getLogger(__name__)
+
+REQUEST_SCOPE_KEY = "__DS__"
+
+
+class RequestScope(TypedDict, total=False):
+    hit_id: str
+    app_id: str
+    user_info: UserClaims | None
+
+
+class HTTPLoggingMiddleware:
+    """Raw ASGI middleware to log HTTP request details including timing,
+    user context, and response information.
+
+    Unlike ``BaseHTTPMiddleware``, this does **not** buffer the response
+    body, so ``StreamingResponse`` and SSE endpoints work correctly.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        request = Request(scope)
+        scope[REQUEST_SCOPE_KEY] = RequestScope()
+
+        elapsed = -time.perf_counter()
+
+        query_params: dict[str, list[str]] = defaultdict(list)
+        for key, value in request.query_params.multi_items():
+            query_params[key].append(value)
+
+        extras: dict[str, Any] = {
+            "method": request.method,
+            "uri": request.url.path,
+            "uri_mapping": self._get_route_path(request),
+            "query_params": query_params,
+            "hit_id": request.headers.get("x-client-hit-id") or str(uuid.uuid4()),
+            "app_id": request.headers.get("x-client-app-id", "unknown"),
+        }
+
+        logger.info("http.request.start", extra=extras)
+
+        # Track response status via a wrapper around send
+        status_holder: dict[str, int] = {"status": 0}
+
+        async def send_wrapper(message: Any) -> None:
+            if message["type"] == "http.response.start":
+                status_holder["status"] = message["status"]
+            await send(message)
+
+        exc_info = None
+        level = logging.INFO
+        try:
+            await self.app(scope, receive, send_wrapper)
+            status = status_holder["status"]
+            level = self._get_log_level(status)
+        except Exception as exc:
+            status = getattr(exc, "status_code", 500)
+            extras["error"] = exc.__cause__
+            exc_info = exc
+            level = logging.ERROR
+            raise
+        finally:
+            ds_scope = scope.get(REQUEST_SCOPE_KEY) or {}
+            extras.update(
+                hit_id=ds_scope.get("hit_id", "unknown"),
+                app_id=ds_scope.get("app_id", "unknown"),
+            )
+            if user_info := ds_scope.get("user_info"):
+                extras.update(
+                    user_id=user_info.sub,
+                    user_email=user_info.user_name,
+                )
+            elapsed += time.perf_counter()
+            extras["elapsed_millis"] = int(elapsed * 1000)
+            extras["status"] = status
+            logger.log(level, "http.request.complete", exc_info=exc_info, extra=extras)
+
+    @staticmethod
+    def _get_log_level(status: int) -> int:
+        http_status = HTTPStatus(status)
+        if http_status.is_informational or http_status.is_success or http_status.is_redirection:
+            return logging.INFO
+        if http_status.is_client_error:
+            return logging.WARNING
+        return logging.ERROR
+
+    @staticmethod
+    def _get_route_path(request: Request) -> str:
+        for route in request.app.routes:
+            match, _ = route.matches(request.scope)
+            if match == Match.FULL:
+                return str(route.path)
+        return request.url.path
+
+
+__all__ = ("REQUEST_SCOPE_KEY", "HTTPLoggingMiddleware", "RequestScope")

csrd/context/middleware/_request.py

@@ -0,0 +1,51 @@
+"""Request context middleware for setting up headers context.
+
+Implemented as a raw ASGI middleware (no ``BaseHTTPMiddleware``) so that
+``StreamingResponse`` and SSE endpoints are not buffered.
+"""
+
+from starlette.requests import Request
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from .._contextvars import (
+    configure_headers_context_provider,
+    reset_headers_context,
+    set_headers_context,
+)
+from .._fastapi_headers import headers_context
+
+
+def _setup_fastapi_headers_provider() -> None:
+    """Wire the FastAPI headers ContextVar as the headers provider."""
+    configure_headers_context_provider(
+        get_headers=headers_context.get,
+        set_headers=headers_context.set,
+        reset_headers=headers_context.reset,
+    )
+
+
+class RequestContextMiddleware:
+    """Raw ASGI middleware that captures request headers into context variables.
+
+    Unlike ``BaseHTTPMiddleware``, this does **not** buffer the response body,
+    so ``StreamingResponse`` and SSE endpoints work correctly.
+    """
+
+    def __init__(self, app: ASGIApp, **kwargs: object) -> None:
+        self.app = app
+        _setup_fastapi_headers_provider()
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        request = Request(scope)
+        token = set_headers_context(request.headers)
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            reset_headers_context(token)
+
+
+__all__ = ("RequestContextMiddleware",)

csrd/context/platform.py

@@ -0,0 +1,21 @@
+"""Platform-level context variables for user info, hit-id, and app-id."""
+
+from contextvars import ContextVar
+from typing import Any
+
+__all__ = (
+    "APP_ID_KEY",
+    "HIT_ID_KEY",
+    "USER_INFO_KEY",
+    "app_id_context",
+    "hit_id_context",
+    "user_info_context",
+)
+
+USER_INFO_KEY = "user_info"
+HIT_ID_KEY = "hit_id"
+APP_ID_KEY = "app_id"
+
+user_info_context: ContextVar[Any | None] = ContextVar(USER_INFO_KEY, default=None)
+hit_id_context: ContextVar[str] = ContextVar(HIT_ID_KEY, default="unknown")
+app_id_context: ContextVar[str] = ContextVar(APP_ID_KEY, default="unknown")

csrd_context-0.1.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: csrd-context
+Version: 0.1.0
+Summary: Request context, header utilities, and logging middleware for FastAPI
+Project-URL: Repository, https://github.com/csrd-api/fastapi-common
+Project-URL: Documentation, https://github.com/csrd-api/fastapi-common/tree/main/packages/context
+Project-URL: Changelog, https://github.com/csrd-api/fastapi-common/blob/main/CHANGELOG.md
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: csrd-models
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: starlette>=0.36

csrd_context-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+csrd/context/__init__.py,sha256=pKZhboGarvcEV2D_pdEtDNP6JMSCFYVKBM7KFiAh8QY,1276
+csrd/context/_constants.py,sha256=8pgg9TI3EOODbYnkKXSMvxaMOO0n4nsKvyphdXR0gak,195
+csrd/context/_contextvars.py,sha256=sRxi-0EwbUk8IwvdKYTCauLyHOt-4Han16_aE6VXlBg,5984
+csrd/context/_fastapi_headers.py,sha256=aJVhMHTjFPpaWU9q1CcwCkT8_jWCSTvdEZNhxCGlbtE,483
+csrd/context/_models.py,sha256=okTHUDODPi6GlLkmHHCHaEeNipT-Ab4TAdDkf7xZB70,1106
+csrd/context/platform.py,sha256=XMQRT7uvsQdRwR6PRyWbEvXbobAPdnG7E9TvjjXCDFQ,584
+csrd/context/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+csrd/context/middleware/__init__.py,sha256=kd3UP5e-lhEe825FDbaWwtHIGm3R3iakmX7JsvB7864,226
+csrd/context/middleware/_logging.py,sha256=ONKzJcdbJk8zmgnw7FsIcfb5B1M3FH2qLTfCGA378Gs,4051
+csrd/context/middleware/_request.py,sha256=wvJsL1xa7WXkvsVi2IVxLZRJ71NcrTA7_JRBcpv1bwI,1592
+csrd_context-0.1.0.dist-info/METADATA,sha256=g9FMm81C4hEu4PcFq-9q8qEBS-B-rPVfN4KAy9BiOpI,519
+csrd_context-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+csrd_context-0.1.0.dist-info/RECORD,,

csrd_context-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any