reqkey 0.1.0__py3-none-any.whl

reqkey/django.py

@@ -0,0 +1,628 @@
+"""Django-native ReqKey middleware for synchronous and asynchronous deployments."""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import os
+import time
+import zlib
+from collections.abc import Awaitable, Callable, Iterable, Mapping
+from datetime import datetime
+from typing import Any, Protocol, cast
+from urllib.parse import urlencode
+
+from asgiref.sync import iscoroutinefunction, markcoroutinefunction
+from django.conf import settings
+from django.http import HttpRequest, HttpResponse, JsonResponse
+from django.http.response import HttpResponseBase
+
+from ._middleware import (
+    DEFAULT_ERROR_MESSAGES,
+    FailureMode,
+    KeyLocation,
+    KeyScheme,
+    Mode,
+    decision_headers,
+    denial,
+    excluded_header_names,
+    extract_credential,
+    filtered_headers,
+    path_matches,
+    validate_credit_cost,
+    validate_middleware_options,
+)
+from .client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT_SECONDS, AsyncReqKey, ReqKey
+from .exceptions import ReqKeyConfigurationError, ReqKeyError
+from .models import VerificationResult
+
+logger = logging.getLogger("reqkey")
+
+MAX_RESPONSE_BODY_CHARACTERS = 1000
+_MAX_CAPTURE_BYTES = MAX_RESPONSE_BODY_CHARACTERS * 4 + 4
+
+
+class SyncReqKeyLike(Protocol):
+    def verify(
+        self,
+        key: str,
+        *,
+        api_id: str | None = None,
+        credits: int = 1,
+        resource: str | None = None,
+    ) -> VerificationResult: ...
+
+    def ingest(
+        self,
+        request_id: str | None = None,
+        *,
+        api_id: str | None = None,
+        method: str | None = None,
+        endpoint: str | None = None,
+        path: str | None = None,
+        status_code: int | None = None,
+        latency_ms: int | None = None,
+        client_ip: str | None = None,
+        user_agent: str | None = None,
+        user_id: str | None = None,
+        query_params: Mapping[str, Any] | None = None,
+        request_headers: Mapping[str, str] | None = None,
+        response_headers: Mapping[str, str] | None = None,
+        request_body: str | None = None,
+        response_body: str | None = None,
+        timestamp: datetime | str | None = None,
+    ) -> None: ...
+
+
+class AsyncReqKeyLike(Protocol):
+    async def verify(
+        self,
+        key: str,
+        *,
+        api_id: str | None = None,
+        credits: int = 1,
+        resource: str | None = None,
+    ) -> VerificationResult: ...
+
+    async def ingest(
+        self,
+        request_id: str | None = None,
+        *,
+        api_id: str | None = None,
+        method: str | None = None,
+        endpoint: str | None = None,
+        path: str | None = None,
+        status_code: int | None = None,
+        latency_ms: int | None = None,
+        client_ip: str | None = None,
+        user_agent: str | None = None,
+        user_id: str | None = None,
+        query_params: Mapping[str, Any] | None = None,
+        request_headers: Mapping[str, str] | None = None,
+        response_headers: Mapping[str, str] | None = None,
+        request_body: str | None = None,
+        response_body: str | None = None,
+        timestamp: datetime | str | None = None,
+    ) -> None: ...
+
+
+SyncGetResponse = Callable[[HttpRequest], HttpResponseBase]
+AsyncGetResponse = Callable[[HttpRequest], Awaitable[HttpResponseBase]]
+CreditsResolver = Callable[[HttpRequest], int | Awaitable[int]]
+ProtectionResolver = Callable[[HttpRequest], bool | Awaitable[bool]]
+ConsumerKeyResolver = Callable[[HttpRequest], str | None | Awaitable[str | None]]
+RequestIdResolver = Callable[[HttpRequest], str | None | Awaitable[str | None]]
+PathResolver = Callable[[HttpRequest], str | Awaitable[str]]
+
+
+class ReqKeyMiddleware:
+    """Django middleware configured through the ``REQKEY`` Django setting."""
+
+    sync_capable = True
+    async_capable = True
+
+    def __init__(self, get_response: SyncGetResponse | AsyncGetResponse) -> None:
+        self.get_response = get_response
+        self._is_async = iscoroutinefunction(get_response)
+        if self._is_async:
+            markcoroutinefunction(self)
+
+        options = _django_options()
+        self.api_id = str(options.pop("api_id", ""))
+        self.mode = cast(Mode, options.pop("mode", "both"))
+        self.enabled = bool(options.pop("enabled", True))
+        self.key_location = cast(KeyLocation, options.pop("key_location", "header"))
+        self.key_name = str(options.pop("key_name", "X-API-Key"))
+        self.key_scheme = cast(KeyScheme, options.pop("key_scheme", "raw"))
+        self.get_consumer_key = cast(
+            ConsumerKeyResolver | None,
+            options.pop("get_consumer_key", None),
+        )
+        self.credits = cast(int | CreditsResolver, options.pop("credits", 1))
+        self.exclude_paths = tuple(cast(Iterable[str], options.pop("exclude_paths", ())))
+        self.skip_methods = frozenset(
+            method.upper()
+            for method in cast(Iterable[str], options.pop("skip_methods", ("OPTIONS",)))
+        )
+        self.should_protect = cast(
+            ProtectionResolver | None,
+            options.pop("should_protect", None),
+        )
+        self.request_id_resolver = cast(
+            RequestIdResolver | None,
+            options.pop("request_id_resolver", None),
+        )
+        self.path_resolver = cast(PathResolver | None, options.pop("path_resolver", None))
+        self.error_messages = {
+            **DEFAULT_ERROR_MESSAGES,
+            **dict(cast(Mapping[str, str], options.pop("error_messages", {}))),
+        }
+        self.capture_query_params = bool(options.pop("capture_query_params", False))
+        self.capture_request_headers = bool(options.pop("capture_request_headers", False))
+        self.capture_response_headers = bool(options.pop("capture_response_headers", False))
+        self.capture_response_body = bool(options.pop("capture_response_body", False))
+        self.capture_client_ip = bool(options.pop("capture_client_ip", False))
+        self.capture_user_agent = bool(options.pop("capture_user_agent", True))
+        self.excluded_headers = excluded_header_names(
+            self.key_name,
+            cast(Iterable[str], options.pop("excluded_headers", ())),
+        )
+        self.failure_mode = cast(FailureMode, options.pop("failure_mode", "closed"))
+
+        project_key = cast(str | None, options.pop("project_key", None))
+        root_key = cast(str | None, options.pop("root_key", None))
+        client = options.pop("client", None)
+        base_url = str(options.pop("base_url", DEFAULT_BASE_URL))
+        timeout = float(options.pop("timeout", DEFAULT_TIMEOUT_SECONDS))
+        if options:
+            unknown = ", ".join(sorted(options))
+            raise ReqKeyConfigurationError(f"Unknown REQKEY settings: {unknown}.")
+
+        validate_middleware_options(
+            api_id=self.api_id,
+            mode=self.mode,
+            key_location=self.key_location,
+            key_scheme=self.key_scheme,
+            failure_mode=self.failure_mode,
+            credits=self.credits,
+        )
+        if client is not None and (project_key is not None or root_key is not None):
+            raise ReqKeyConfigurationError("Pass CLIENT or PROJECT_KEY/ROOT_KEY, not both.")
+        if client is None:
+            if project_key is None and root_key is None:
+                project_key = os.getenv("REQKEY_PROJECT_KEY") or os.getenv(
+                    "REQKEY_ROOT_KEY"
+                )
+            self.client: SyncReqKeyLike | AsyncReqKeyLike = (
+                AsyncReqKey(
+                    project_key=project_key,
+                    root_key=root_key,
+                    base_url=base_url,
+                    timeout=timeout,
+                )
+                if self._is_async
+                else ReqKey(
+                    project_key=project_key,
+                    root_key=root_key,
+                    base_url=base_url,
+                    timeout=timeout,
+                )
+            )
+        else:
+            self.client = cast(SyncReqKeyLike | AsyncReqKeyLike, client)
+
+    def __call__(
+        self,
+        request: HttpRequest,
+    ) -> HttpResponseBase | Awaitable[HttpResponseBase]:
+        if self._is_async:
+            return self._acall(request)
+        return self._scall(request)
+
+    def _scall(self, request: HttpRequest) -> HttpResponseBase:
+        if not self.enabled or not self._applies_to_sync(request):
+            return cast(SyncGetResponse, self.get_response)(request)
+
+        decision: VerificationResult | None = None
+        validation_time_ms: float | None = None
+        client = cast(SyncReqKeyLike, self.client)
+
+        if self.mode in {"validate", "both"}:
+            consumer_key = self._consumer_key_sync(request)
+            if consumer_key is None:
+                return self._respond(401, "missing_api_key")
+
+            validation_started = time.perf_counter()
+            try:
+                decision = client.verify(
+                    consumer_key,
+                    api_id=self.api_id,
+                    credits=self._credit_cost_sync(request),
+                    resource=self._resource_path_sync(request),
+                )
+                validation_time_ms = (time.perf_counter() - validation_started) * 1000
+            except ReqKeyError as exc:
+                validation_time_ms = (time.perf_counter() - validation_started) * 1000
+                if self.failure_mode == "open":
+                    request.reqkey_error = exc  # type: ignore[attr-defined]
+                else:
+                    logger.warning("ReqKey validation failed closed: %s", exc)
+                    return self._respond(503, "reqkey_unavailable")
+
+            denied = self._denied_response(decision)
+            if denied is not None:
+                return denied
+            self._attach_decision(request, decision)
+
+        started = time.perf_counter()
+        try:
+            response = cast(SyncGetResponse, self.get_response)(request)
+        except Exception:
+            if self.mode != "validate":
+                self._ingest_sync(
+                    client,
+                    request=request,
+                    decision=decision,
+                    response=None,
+                    status_code=500,
+                    latency_ms=round((time.perf_counter() - started) * 1000),
+                )
+            raise
+
+        if self.mode != "validate":
+            self._ingest_sync(
+                client,
+                request=request,
+                decision=decision,
+                response=response,
+                status_code=response.status_code,
+                latency_ms=round((time.perf_counter() - started) * 1000),
+            )
+        self._add_decision_headers(response, decision, validation_time_ms)
+        return response
+
+    async def _acall(self, request: HttpRequest) -> HttpResponseBase:
+        if not self.enabled or not await self._applies_to_async(request):
+            return await cast(AsyncGetResponse, self.get_response)(request)
+
+        decision: VerificationResult | None = None
+        validation_time_ms: float | None = None
+        client = cast(AsyncReqKeyLike, self.client)
+
+        if self.mode in {"validate", "both"}:
+            consumer_key = await self._consumer_key_async(request)
+            if consumer_key is None:
+                return self._respond(401, "missing_api_key")
+
+            validation_started = time.perf_counter()
+            try:
+                decision = await client.verify(
+                    consumer_key,
+                    api_id=self.api_id,
+                    credits=await self._credit_cost_async(request),
+                    resource=await self._resource_path_async(request),
+                )
+                validation_time_ms = (time.perf_counter() - validation_started) * 1000
+            except ReqKeyError as exc:
+                validation_time_ms = (time.perf_counter() - validation_started) * 1000
+                if self.failure_mode == "open":
+                    request.reqkey_error = exc  # type: ignore[attr-defined]
+                else:
+                    logger.warning("ReqKey validation failed closed: %s", exc)
+                    return self._respond(503, "reqkey_unavailable")
+
+            denied = self._denied_response(decision)
+            if denied is not None:
+                return denied
+            self._attach_decision(request, decision)
+
+        started = time.perf_counter()
+        try:
+            response = await cast(AsyncGetResponse, self.get_response)(request)
+        except Exception:
+            if self.mode != "validate":
+                await self._ingest_async(
+                    client,
+                    request=request,
+                    decision=decision,
+                    response=None,
+                    status_code=500,
+                    latency_ms=round((time.perf_counter() - started) * 1000),
+                )
+            raise
+
+        if self.mode != "validate":
+            await self._ingest_async(
+                client,
+                request=request,
+                decision=decision,
+                response=response,
+                status_code=response.status_code,
+                latency_ms=round((time.perf_counter() - started) * 1000),
+            )
+        self._add_decision_headers(response, decision, validation_time_ms)
+        return response
+
+    def _applies_to_sync(self, request: HttpRequest) -> bool:
+        if (request.method or "GET").upper() in self.skip_methods:
+            return False
+        if any(path_matches(request.path, pattern) for pattern in self.exclude_paths):
+            return False
+        if self.should_protect is None:
+            return True
+        value = self.should_protect(request)
+        if inspect.isawaitable(value):
+            raise ReqKeyConfigurationError(
+                "A synchronous Django stack requires synchronous middleware resolvers."
+            )
+        return bool(value)
+
+    async def _applies_to_async(self, request: HttpRequest) -> bool:
+        if (request.method or "GET").upper() in self.skip_methods:
+            return False
+        if any(path_matches(request.path, pattern) for pattern in self.exclude_paths):
+            return False
+        if self.should_protect is None:
+            return True
+        value = self.should_protect(request)
+        return bool(await value) if inspect.isawaitable(value) else bool(value)
+
+    def _consumer_key_sync(self, request: HttpRequest) -> str | None:
+        value = self._raw_consumer_key(request)
+        if inspect.isawaitable(value):
+            raise ReqKeyConfigurationError(
+                "A synchronous Django stack requires synchronous middleware resolvers."
+            )
+        return extract_credential(value, self.key_scheme)
+
+    async def _consumer_key_async(self, request: HttpRequest) -> str | None:
+        value = self._raw_consumer_key(request)
+        resolved = await value if inspect.isawaitable(value) else value
+        return extract_credential(resolved, self.key_scheme)
+
+    def _raw_consumer_key(
+        self,
+        request: HttpRequest,
+    ) -> str | None | Awaitable[str | None]:
+        if self.get_consumer_key is not None:
+            return self.get_consumer_key(request)
+        if self.key_location == "header":
+            return request.headers.get(self.key_name)
+        if self.key_location == "query":
+            return request.GET.get(self.key_name)
+        return request.COOKIES.get(self.key_name)
+
+    def _credit_cost_sync(self, request: HttpRequest) -> int:
+        value = self.credits(request) if callable(self.credits) else self.credits
+        if inspect.isawaitable(value):
+            raise ReqKeyConfigurationError(
+                "A synchronous Django stack requires synchronous middleware resolvers."
+            )
+        return validate_credit_cost(value)
+
+    async def _credit_cost_async(self, request: HttpRequest) -> int:
+        value = self.credits(request) if callable(self.credits) else self.credits
+        resolved = await value if inspect.isawaitable(value) else value
+        return validate_credit_cost(resolved)
+
+    def _resource_path_sync(self, request: HttpRequest) -> str:
+        value = request.path if self.path_resolver is None else self.path_resolver(request)
+        if inspect.isawaitable(value):
+            raise ReqKeyConfigurationError(
+                "A synchronous Django stack requires synchronous middleware resolvers."
+            )
+        if not value:
+            raise ReqKeyConfigurationError("The path resolver returned an empty path.")
+        return value
+
+    async def _resource_path_async(self, request: HttpRequest) -> str:
+        value = request.path if self.path_resolver is None else self.path_resolver(request)
+        resolved = await value if inspect.isawaitable(value) else value
+        if not resolved:
+            raise ReqKeyConfigurationError("The path resolver returned an empty path.")
+        return resolved
+
+    def _ingest_sync(
+        self,
+        client: SyncReqKeyLike,
+        *,
+        request: HttpRequest,
+        decision: VerificationResult | None,
+        response: HttpResponseBase | None,
+        status_code: int,
+        latency_ms: int,
+    ) -> None:
+        try:
+            client.ingest(
+                self._request_id_sync(request, decision),
+                **self._ingest_event(
+                    request,
+                    response,
+                    status_code,
+                    latency_ms,
+                    self._resource_path_sync(request),
+                ),
+            )
+        except ReqKeyError as exc:
+            logger.warning("ReqKey analytics ingestion failed: %s", exc)
+
+    async def _ingest_async(
+        self,
+        client: AsyncReqKeyLike,
+        *,
+        request: HttpRequest,
+        decision: VerificationResult | None,
+        response: HttpResponseBase | None,
+        status_code: int,
+        latency_ms: int,
+    ) -> None:
+        try:
+            await client.ingest(
+                await self._request_id_async(request, decision),
+                **self._ingest_event(
+                    request,
+                    response,
+                    status_code,
+                    latency_ms,
+                    await self._resource_path_async(request),
+                ),
+            )
+        except ReqKeyError as exc:
+            logger.warning("ReqKey analytics ingestion failed: %s", exc)
+
+    def _ingest_event(
+        self,
+        request: HttpRequest,
+        response: HttpResponseBase | None,
+        status_code: int,
+        latency_ms: int,
+        resource_path: str,
+    ) -> dict[str, Any]:
+        query_params, query = self._captured_query(request)
+        request_headers = dict(request.headers.items())
+        response_headers = dict(response.items()) if response is not None else {}
+        return {
+            "api_id": self.api_id,
+            "method": request.method,
+            "endpoint": resource_path,
+            "path": resource_path + (f"?{query}" if query else ""),
+            "status_code": status_code,
+            "latency_ms": latency_ms,
+            "client_ip": (
+                str(request.META.get("REMOTE_ADDR"))
+                if self.capture_client_ip and request.META.get("REMOTE_ADDR") is not None
+                else None
+            ),
+            "user_agent": (
+                request.headers.get("user-agent") if self.capture_user_agent else None
+            ),
+            "query_params": query_params,
+            "request_headers": (
+                filtered_headers(request_headers, self.excluded_headers)
+                if self.capture_request_headers
+                else None
+            ),
+            "response_headers": (
+                filtered_headers(response_headers, self.excluded_headers)
+                if self.capture_response_headers
+                else None
+            ),
+            "response_body": self._response_body(response),
+        }
+
+    def _captured_query(self, request: HttpRequest) -> tuple[dict[str, str] | None, str]:
+        if not self.capture_query_params:
+            return None, ""
+        pairs = [
+            (key, value)
+            for key in request.GET
+            for value in request.GET.getlist(key)
+            if not (self.key_location == "query" and key == self.key_name)
+        ]
+        return dict(pairs), urlencode(pairs)
+
+    def _response_body(self, response: HttpResponseBase | None) -> str | None:
+        if (
+            not self.capture_response_body
+            or response is None
+            or response.streaming
+            or not isinstance(response, HttpResponse)
+        ):
+            return None
+        content_type = response.headers.get("content-type", "").lower()
+        if content_type and not any(
+            marker in content_type
+            for marker in ("json", "text/", "xml", "javascript", "x-www-form-urlencoded")
+        ):
+            return None
+        content = response.content
+        if response.headers.get("content-encoding", "").lower() == "gzip":
+            try:
+                decompressor = zlib.decompressobj(16 + zlib.MAX_WBITS)
+                content = decompressor.decompress(content, _MAX_CAPTURE_BYTES)
+            except zlib.error:
+                logger.debug("Could not decompress a gzip response for ReqKey analytics.")
+                return None
+        else:
+            content = content[:_MAX_CAPTURE_BYTES]
+        return content.decode("utf-8", errors="replace")[:MAX_RESPONSE_BODY_CHARACTERS]
+
+    def _request_id_sync(
+        self,
+        request: HttpRequest,
+        decision: VerificationResult | None,
+    ) -> str | None:
+        if decision is not None:
+            return decision.request_id
+        if self.request_id_resolver is not None:
+            value = self.request_id_resolver(request)
+            if inspect.isawaitable(value):
+                raise ReqKeyConfigurationError(
+                    "A synchronous Django stack requires synchronous middleware resolvers."
+                )
+            return value or None
+        value = getattr(request, "reqkey_request_id", None)
+        return value if isinstance(value, str) else None
+
+    async def _request_id_async(
+        self,
+        request: HttpRequest,
+        decision: VerificationResult | None,
+    ) -> str | None:
+        if decision is not None:
+            return decision.request_id
+        if self.request_id_resolver is not None:
+            value = self.request_id_resolver(request)
+            resolved = await value if inspect.isawaitable(value) else value
+            return resolved or None
+        value = getattr(request, "reqkey_request_id", None)
+        return value if isinstance(value, str) else None
+
+    def _denied_response(
+        self,
+        decision: VerificationResult | None,
+    ) -> HttpResponseBase | None:
+        if decision is None or decision.valid:
+            return None
+        status_code, error = denial(decision)
+        response = self._respond(status_code, error)
+        if decision.retry_after is not None:
+            response["Retry-After"] = str(max(0, int(decision.retry_after)))
+        return response
+
+    @staticmethod
+    def _attach_decision(
+        request: HttpRequest,
+        decision: VerificationResult | None,
+    ) -> None:
+        if decision is None:
+            return
+        request.reqkey = decision  # type: ignore[attr-defined]
+        request.reqkey_request_id = decision.request_id  # type: ignore[attr-defined]
+
+    @staticmethod
+    def _add_decision_headers(
+        response: HttpResponseBase,
+        decision: VerificationResult | None,
+        validation_time_ms: float | None,
+    ) -> None:
+        for key, value in decision_headers(decision, validation_time_ms).items():
+            response[key] = value
+
+    def _respond(self, status_code: int, error: str) -> JsonResponse:
+        return JsonResponse(
+            {"error": error, "message": self.error_messages[error]},
+            status=status_code,
+        )
+
+
+def _django_options() -> dict[str, Any]:
+    raw = getattr(settings, "REQKEY", {})
+    if not isinstance(raw, Mapping):
+        raise ReqKeyConfigurationError("The Django REQKEY setting must be a mapping.")
+    return {str(key).lower(): value for key, value in raw.items()}
+
+
+DjangoReqKeyMiddleware = ReqKeyMiddleware
+
+__all__ = ["DjangoReqKeyMiddleware", "ReqKeyMiddleware"]

reqkey/exceptions.py

@@ -0,0 +1,42 @@
+"""Exceptions raised by the ReqKey SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ReqKeyError(Exception):
+    """Base class for all ReqKey SDK errors."""
+
+
+class ReqKeyConfigurationError(ReqKeyError, ValueError):
+    """Raised when the SDK is configured with invalid values."""
+
+
+class ReqKeyTransportError(ReqKeyError):
+    """Raised when ReqKey cannot be reached."""
+
+
+class ReqKeyTimeoutError(ReqKeyTransportError):
+    """Raised when a request to ReqKey exceeds its configured timeout."""
+
+
+class ReqKeyAPIError(ReqKeyError):
+    """Raised when ReqKey returns a response that is not an access decision."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        body: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.body = body or {}
+
+
+class ReqKeyAuthenticationError(ReqKeyAPIError):
+    """Raised when the project credential is missing, invalid, or expired."""
+

reqkey/fastapi.py

@@ -0,0 +1,5 @@
+"""FastAPI and Starlette compatibility imports for ReqKey."""
+
+from .asgi import ReqKeyASGIMiddleware, ReqKeyMiddleware
+
+__all__ = ["ReqKeyASGIMiddleware", "ReqKeyMiddleware"]

reqkey/flask.py

@@ -0,0 +1,5 @@
+"""Flask compatibility imports for ReqKey's WSGI middleware."""
+
+from .wsgi import ReqKeyMiddleware, ReqKeyWSGIMiddleware
+
+__all__ = ["ReqKeyMiddleware", "ReqKeyWSGIMiddleware"]