reqkey 0.1.0__py3-none-any.whl

reqkey/models.py

@@ -0,0 +1,45 @@
+"""Public response models for the ReqKey SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class VerificationReason(str, Enum):
+    """Stable SDK-level categories for a key-validation decision."""
+
+    VALID = "valid"
+    INVALID_KEY = "invalid_key"
+    INSUFFICIENT_CREDITS = "insufficient_credits"
+    FORBIDDEN = "forbidden"
+    RATE_LIMITED = "rate_limited"
+    DENIED = "denied"
+
+
+@dataclass(frozen=True, slots=True)
+class VerificationResult:
+    """The result of a `/key/validate` decision."""
+
+    valid: bool
+    reason: VerificationReason
+    status_code: int
+    request_id: str | None = None
+    message: str | None = None
+    api_id: str | None = None
+    api_name: str | None = None
+    resource: str | None = None
+    credits_remaining: int | None = None
+    credits_limit: int | None = None
+    allowed_apis: tuple[str, ...] = ()
+    retry_after: float | None = None
+    rate_limit: dict[str, Any] | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def allowed(self) -> bool:
+        """Alias that reads naturally inside authorization code."""
+
+        return self.valid
+

reqkey/py.typed

@@ -0,0 +1 @@
+

reqkey/wsgi.py

@@ -0,0 +1,546 @@
+"""Generic WSGI middleware for Flask, Bottle, Pyramid, and other WSGI apps."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+import zlib
+from collections.abc import Callable, Iterable, Iterator, Mapping
+from datetime import datetime
+from http.cookies import SimpleCookie
+from types import TracebackType
+from typing import Any, Protocol
+from urllib.parse import parse_qsl, urlencode
+
+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, 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
+
+WSGIEnvironment = dict[str, Any]
+ResponseHeaders = list[tuple[str, str]]
+ExcInfo = tuple[type[BaseException], BaseException, TracebackType]
+
+
+class StartResponse(Protocol):
+    def __call__(
+        self,
+        status: str,
+        response_headers: ResponseHeaders,
+        exc_info: ExcInfo | None = None,
+    ) -> Callable[[bytes], object]: ...
+
+
+class WSGIApplication(Protocol):
+    def __call__(
+        self,
+        environ: WSGIEnvironment,
+        start_response: StartResponse,
+    ) -> Iterable[bytes]: ...
+
+
+class ReqKeyLike(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: ...
+
+
+CreditsResolver = Callable[[WSGIEnvironment], int]
+ProtectionResolver = Callable[[WSGIEnvironment], bool]
+ConsumerKeyResolver = Callable[[WSGIEnvironment], str | None]
+RequestIdResolver = Callable[[WSGIEnvironment], str | None]
+PathResolver = Callable[[WSGIEnvironment], str]
+
+
+class _ResponseBodyCapture:
+    def __init__(self, *, enabled: bool, headers: Mapping[str, str]) -> None:
+        content_type = headers.get("content-type", "").lower()
+        self.enabled = enabled and (
+            not content_type
+            or any(
+                marker in content_type
+                for marker in (
+                    "json",
+                    "text/",
+                    "xml",
+                    "javascript",
+                    "x-www-form-urlencoded",
+                )
+            )
+        )
+        self._body = bytearray()
+        self._decompressor = (
+            zlib.decompressobj(16 + zlib.MAX_WBITS)
+            if self.enabled and headers.get("content-encoding", "").lower() == "gzip"
+            else None
+        )
+
+    def feed(self, chunk: bytes) -> None:
+        if not self.enabled or not chunk or len(self._body) >= _MAX_CAPTURE_BYTES:
+            return
+        remaining = _MAX_CAPTURE_BYTES - len(self._body)
+        if self._decompressor is None:
+            self._body.extend(chunk[:remaining])
+            return
+        try:
+            self._body.extend(self._decompressor.decompress(chunk, remaining))
+        except zlib.error:
+            self.enabled = False
+            self._body.clear()
+            logger.debug("Could not decompress a gzip response for ReqKey analytics.")
+
+    def text(self) -> str | None:
+        if not self.enabled:
+            return None
+        if self._decompressor is not None and len(self._body) < _MAX_CAPTURE_BYTES:
+            try:
+                remaining = _MAX_CAPTURE_BYTES - len(self._body)
+                self._body.extend(self._decompressor.flush(remaining))
+            except zlib.error:
+                logger.debug("Could not finish gzip response capture for ReqKey analytics.")
+        return self._body.decode("utf-8", errors="replace")[:MAX_RESPONSE_BODY_CHARACTERS]
+
+
+class _ResponseState:
+    def __init__(self) -> None:
+        self.status_code = 500
+        self.headers: dict[str, str] = {}
+        self.body = _ResponseBodyCapture(enabled=False, headers={})
+
+
+class ReqKeyMiddleware:
+    """Pure WSGI middleware for incoming API validation and analytics."""
+
+    def __init__(
+        self,
+        app: WSGIApplication,
+        *,
+        api_id: str,
+        project_key: str | None = None,
+        root_key: str | None = None,
+        client: ReqKeyLike | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        mode: Mode = "both",
+        enabled: bool = True,
+        key_location: KeyLocation = "header",
+        key_name: str = "X-API-Key",
+        key_scheme: KeyScheme = "raw",
+        get_consumer_key: ConsumerKeyResolver | None = None,
+        credits: int | CreditsResolver = 1,
+        exclude_paths: Iterable[str] = (),
+        skip_methods: Iterable[str] = ("OPTIONS",),
+        should_protect: ProtectionResolver | None = None,
+        request_id_resolver: RequestIdResolver | None = None,
+        path_resolver: PathResolver | None = None,
+        error_messages: Mapping[str, str] | None = None,
+        capture_query_params: bool = False,
+        capture_request_headers: bool = False,
+        capture_response_headers: bool = False,
+        capture_response_body: bool = False,
+        capture_client_ip: bool = False,
+        capture_user_agent: bool = True,
+        excluded_headers: Iterable[str] = (),
+        failure_mode: FailureMode = "closed",
+    ) -> None:
+        validate_middleware_options(
+            api_id=api_id,
+            mode=mode,
+            key_location=key_location,
+            key_scheme=key_scheme,
+            failure_mode=failure_mode,
+            credits=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.")
+
+        self.app = app
+        self.api_id = api_id
+        self.client = client or ReqKey(
+            project_key=project_key,
+            root_key=root_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+        self._owns_client = client is None
+        self.mode = mode
+        self.enabled = enabled
+        self.key_location = key_location
+        self.key_name = key_name
+        self.key_scheme = key_scheme
+        self.get_consumer_key = get_consumer_key
+        self.credits = credits
+        self.exclude_paths = tuple(exclude_paths)
+        self.skip_methods = frozenset(method.upper() for method in skip_methods)
+        self.should_protect = should_protect
+        self.request_id_resolver = request_id_resolver
+        self.path_resolver = path_resolver
+        self.error_messages = {**DEFAULT_ERROR_MESSAGES, **dict(error_messages or {})}
+        self.capture_query_params = capture_query_params
+        self.capture_request_headers = capture_request_headers
+        self.capture_response_headers = capture_response_headers
+        self.capture_response_body = capture_response_body
+        self.capture_client_ip = capture_client_ip
+        self.capture_user_agent = capture_user_agent
+        self.excluded_headers = excluded_header_names(key_name, excluded_headers)
+        self.failure_mode = failure_mode
+
+    def __call__(
+        self,
+        environ: WSGIEnvironment,
+        start_response: StartResponse,
+    ) -> Iterable[bytes]:
+        if not self.enabled or not self._applies_to(environ):
+            return self.app(environ, start_response)
+
+        decision: VerificationResult | None = None
+        validation_time_ms: float | None = None
+
+        if self.mode in {"validate", "both"}:
+            consumer_key = self._consumer_key(environ)
+            if consumer_key is None:
+                return self._respond(start_response, 401, "missing_api_key")
+
+            validation_started = time.perf_counter()
+            try:
+                decision = self.client.verify(
+                    consumer_key,
+                    api_id=self.api_id,
+                    credits=self._credit_cost(environ),
+                    resource=self._resource_path(environ),
+                )
+                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":
+                    environ["reqkey.error"] = exc
+                else:
+                    logger.warning("ReqKey validation failed closed: %s", exc)
+                    return self._respond(start_response, 503, "reqkey_unavailable")
+
+            if decision is not None and not decision.valid:
+                status_code, error = denial(decision)
+                headers = {}
+                if decision.retry_after is not None:
+                    headers["Retry-After"] = str(max(0, int(decision.retry_after)))
+                return self._respond(start_response, status_code, error, headers=headers)
+
+            if decision is not None:
+                environ["reqkey.decision"] = decision
+                environ["reqkey.request_id"] = decision.request_id
+
+        headers = decision_headers(decision, validation_time_ms)
+        wrapped_start = self._start_response_with_headers(start_response, headers)
+        if self.mode == "validate":
+            return self.app(environ, wrapped_start)
+
+        return self._run_with_ingest(
+            environ,
+            wrapped_start,
+            decision=decision,
+        )
+
+    def _run_with_ingest(
+        self,
+        environ: WSGIEnvironment,
+        start_response: StartResponse,
+        *,
+        decision: VerificationResult | None,
+    ) -> Iterator[bytes]:
+        response = _ResponseState()
+        started = time.perf_counter()
+
+        def capture_start_response(
+            status: str,
+            response_headers: ResponseHeaders,
+            exc_info: ExcInfo | None = None,
+        ) -> Callable[[bytes], object]:
+            response.status_code = _status_code(status)
+            response.headers = {key.lower(): value for key, value in response_headers}
+            response.body = _ResponseBodyCapture(
+                enabled=self.capture_response_body,
+                headers=response.headers,
+            )
+            write = start_response(status, response_headers, exc_info)
+
+            def capture_write(data: bytes) -> object:
+                response.body.feed(data)
+                return write(data)
+
+            return capture_write
+
+        app_iterable: Iterable[bytes] | None = None
+        failed = False
+        try:
+            app_iterable = self.app(environ, capture_start_response)
+            for chunk in app_iterable:
+                if not isinstance(chunk, bytes):
+                    raise TypeError("WSGI applications must yield bytes.")
+                response.body.feed(chunk)
+                yield chunk
+        except Exception:
+            failed = True
+            raise
+        finally:
+            if app_iterable is not None:
+                close = getattr(app_iterable, "close", None)
+                if callable(close):
+                    close()
+            self._ingest_safely(
+                environ=environ,
+                decision=decision,
+                response_status=500 if failed else response.status_code,
+                latency_ms=round((time.perf_counter() - started) * 1000),
+                response_headers=response.headers,
+                response_body=response.body.text(),
+            )
+
+    def _applies_to(self, environ: WSGIEnvironment) -> bool:
+        method = str(environ.get("REQUEST_METHOD", "GET")).upper()
+        path = str(environ.get("PATH_INFO", "/")) or "/"
+        if method in self.skip_methods:
+            return False
+        if any(path_matches(path, pattern) for pattern in self.exclude_paths):
+            return False
+        return True if self.should_protect is None else bool(self.should_protect(environ))
+
+    def _consumer_key(self, environ: WSGIEnvironment) -> str | None:
+        if self.get_consumer_key is not None:
+            value = self.get_consumer_key(environ)
+        elif self.key_location == "header":
+            value = _request_header(environ, self.key_name)
+        elif self.key_location == "query":
+            values = dict(parse_qsl(str(environ.get("QUERY_STRING", "")), keep_blank_values=True))
+            value = values.get(self.key_name)
+        else:
+            cookie = SimpleCookie()
+            cookie.load(str(environ.get("HTTP_COOKIE", "")))
+            morsel = cookie.get(self.key_name)
+            value = morsel.value if morsel is not None else None
+        return extract_credential(value, self.key_scheme)
+
+    def _credit_cost(self, environ: WSGIEnvironment) -> int:
+        raw = self.credits(environ) if callable(self.credits) else self.credits
+        return validate_credit_cost(raw)
+
+    def _resource_path(self, environ: WSGIEnvironment) -> str:
+        if self.path_resolver is None:
+            return str(environ.get("PATH_INFO", "/")) or "/"
+        value = self.path_resolver(environ)
+        if not value:
+            raise ReqKeyConfigurationError("The path resolver returned an empty path.")
+        return value
+
+    def _resolved_request_id(
+        self,
+        environ: WSGIEnvironment,
+        decision: VerificationResult | None,
+    ) -> str | None:
+        if decision is not None:
+            return decision.request_id
+        if self.request_id_resolver is not None:
+            return self.request_id_resolver(environ) or None
+        value = environ.get("reqkey.request_id")
+        return value if isinstance(value, str) else None
+
+    def _ingest_safely(
+        self,
+        *,
+        environ: WSGIEnvironment,
+        decision: VerificationResult | None,
+        response_status: int,
+        latency_ms: int,
+        response_headers: Mapping[str, str],
+        response_body: str | None,
+    ) -> None:
+        resource_path = self._resource_path(environ)
+        query_params, query = self._captured_query(environ)
+        full_path = resource_path + (f"?{query}" if query else "")
+        request_headers = _request_headers(environ)
+
+        try:
+            self.client.ingest(
+                self._resolved_request_id(environ, decision),
+                api_id=self.api_id,
+                method=str(environ.get("REQUEST_METHOD", "GET")),
+                endpoint=resource_path,
+                path=full_path,
+                status_code=response_status,
+                latency_ms=latency_ms,
+                client_ip=(
+                    str(environ.get("REMOTE_ADDR"))
+                    if self.capture_client_ip and environ.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=response_body,
+            )
+        except ReqKeyError as exc:
+            logger.warning("ReqKey analytics ingestion failed: %s", exc)
+
+    def _captured_query(
+        self,
+        environ: WSGIEnvironment,
+    ) -> tuple[dict[str, str] | None, str]:
+        if not self.capture_query_params:
+            return None, ""
+        pairs = [
+            (key, value)
+            for key, value in parse_qsl(
+                str(environ.get("QUERY_STRING", "")),
+                keep_blank_values=True,
+            )
+            if not (self.key_location == "query" and key == self.key_name)
+        ]
+        return dict(pairs), urlencode(pairs)
+
+    @staticmethod
+    def _start_response_with_headers(
+        start_response: StartResponse,
+        added_headers: Mapping[str, str],
+    ) -> StartResponse:
+        def wrapped(
+            status: str,
+            response_headers: ResponseHeaders,
+            exc_info: ExcInfo | None = None,
+        ) -> Callable[[bytes], object]:
+            headers = _merge_headers(response_headers, added_headers)
+            return start_response(status, headers, exc_info)
+
+        return wrapped
+
+    def _respond(
+        self,
+        start_response: StartResponse,
+        status_code: int,
+        error: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+    ) -> Iterable[bytes]:
+        body = json.dumps(
+            {"error": error, "message": self.error_messages[error]},
+            separators=(",", ":"),
+        ).encode()
+        response_headers: ResponseHeaders = [
+            ("Content-Type", "application/json"),
+            ("Content-Length", str(len(body))),
+        ]
+        response_headers.extend((key, value) for key, value in (headers or {}).items())
+        start_response(f"{status_code} {_reason_phrase(status_code)}", response_headers)
+        return [body]
+
+    def close(self) -> None:
+        if self._owns_client and isinstance(self.client, ReqKey):
+            self.client.close()
+
+
+ReqKeyWSGIMiddleware = ReqKeyMiddleware
+
+
+def _request_header(environ: WSGIEnvironment, name: str) -> str | None:
+    normalized = name.upper().replace("-", "_")
+    key = normalized if normalized in {"CONTENT_TYPE", "CONTENT_LENGTH"} else f"HTTP_{normalized}"
+    value = environ.get(key)
+    return str(value) if value is not None else None
+
+
+def _request_headers(environ: WSGIEnvironment) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    for key, value in environ.items():
+        if key.startswith("HTTP_"):
+            name = key[5:].replace("_", "-").lower()
+        elif key in {"CONTENT_TYPE", "CONTENT_LENGTH"}:
+            name = key.replace("_", "-").lower()
+        else:
+            continue
+        headers[name] = str(value)
+    return headers
+
+
+def _status_code(status: str) -> int:
+    try:
+        return int(status.partition(" ")[0])
+    except ValueError:
+        return 500
+
+
+def _merge_headers(
+    headers: ResponseHeaders,
+    additions: Mapping[str, str],
+) -> ResponseHeaders:
+    lowered = {key.lower() for key in additions}
+    merged = [(key, value) for key, value in headers if key.lower() not in lowered]
+    merged.extend(additions.items())
+    return merged
+
+
+def _reason_phrase(status_code: int) -> str:
+    return {
+        401: "Unauthorized",
+        402: "Payment Required",
+        403: "Forbidden",
+        429: "Too Many Requests",
+        503: "Service Unavailable",
+    }.get(status_code, "Error")
+
+
+__all__ = ["ReqKeyMiddleware", "ReqKeyWSGIMiddleware"]