reqkey 0.1.0__py3-none-any.whl

reqkey/__init__.py

@@ -0,0 +1,27 @@
+"""The official Python SDK for ReqKey."""
+
+from .client import AsyncReqKey, ReqKey
+from .exceptions import (
+    ReqKeyAPIError,
+    ReqKeyAuthenticationError,
+    ReqKeyConfigurationError,
+    ReqKeyError,
+    ReqKeyTimeoutError,
+    ReqKeyTransportError,
+)
+from .models import VerificationReason, VerificationResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncReqKey",
+    "ReqKey",
+    "ReqKeyAPIError",
+    "ReqKeyAuthenticationError",
+    "ReqKeyConfigurationError",
+    "ReqKeyError",
+    "ReqKeyTimeoutError",
+    "ReqKeyTransportError",
+    "VerificationReason",
+    "VerificationResult",
+]

reqkey/_middleware.py

@@ -0,0 +1,132 @@
+"""Framework-independent helpers shared by ReqKey middleware adapters."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Literal
+
+from .exceptions import ReqKeyConfigurationError
+from .models import VerificationReason, VerificationResult
+
+Mode = Literal["validate", "ingest", "both"]
+FailureMode = Literal["closed", "open"]
+KeyLocation = Literal["header", "query", "cookie"]
+KeyScheme = Literal["raw", "bearer"]
+
+DEFAULT_ERROR_MESSAGES: dict[str, str] = {
+    "missing_api_key": "An API key is required.",
+    "invalid_api_key": "The API key is invalid or inactive.",
+    "insufficient_credits": "The API key has insufficient credits.",
+    "access_denied": "The API key is not allowed to access this API.",
+    "rate_limited": "The API key has exceeded its rate limit.",
+    "reqkey_unavailable": "API key verification is temporarily unavailable.",
+}
+
+DEFAULT_EXCLUDED_HEADERS = frozenset(
+    {
+        "authorization",
+        "cookie",
+        "proxy-authorization",
+        "set-cookie",
+        "x-api-key",
+    }
+)
+
+
+def validate_middleware_options(
+    *,
+    api_id: str,
+    mode: str,
+    key_location: str,
+    key_scheme: str,
+    failure_mode: str,
+    credits: object,
+) -> None:
+    if not api_id.strip():
+        raise ReqKeyConfigurationError("api_id cannot be empty.")
+    if mode not in {"validate", "ingest", "both"}:
+        raise ReqKeyConfigurationError("mode must be 'validate', 'ingest', or 'both'.")
+    if key_location not in {"header", "query", "cookie"}:
+        raise ReqKeyConfigurationError("key_location must be 'header', 'query', or 'cookie'.")
+    if key_scheme not in {"raw", "bearer"}:
+        raise ReqKeyConfigurationError("key_scheme must be 'raw' or 'bearer'.")
+    if key_location != "header" and key_scheme != "raw":
+        raise ReqKeyConfigurationError(
+            "Query-parameter and cookie keys must use the raw scheme."
+        )
+    if failure_mode not in {"closed", "open"}:
+        raise ReqKeyConfigurationError("failure_mode must be 'closed' or 'open'.")
+    if not callable(credits) and (
+        isinstance(credits, bool) or not isinstance(credits, int) or credits < 0
+    ):
+        raise ReqKeyConfigurationError(
+            "credits must be a non-negative integer or a callable."
+        )
+
+
+def extract_credential(value: str | None, key_scheme: KeyScheme) -> str | None:
+    if value is None or not value.strip():
+        return None
+    value = value.strip()
+    if key_scheme == "bearer":
+        scheme, separator, credential = value.partition(" ")
+        if not separator or scheme.lower() != "bearer" or not credential.strip():
+            return None
+        return credential.strip()
+    return value
+
+
+def validate_credit_cost(value: object) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise ReqKeyConfigurationError(
+            "The credits resolver must return a non-negative integer."
+        )
+    return value
+
+
+def path_matches(path: str, pattern: str) -> bool:
+    return path.startswith(pattern[:-1]) if pattern.endswith("*") else path == pattern
+
+
+def denial(decision: VerificationResult) -> tuple[int, str]:
+    if decision.reason is VerificationReason.INSUFFICIENT_CREDITS:
+        return 402, "insufficient_credits"
+    if decision.reason is VerificationReason.RATE_LIMITED:
+        return 429, "rate_limited"
+    if decision.reason is VerificationReason.FORBIDDEN:
+        return 403, "access_denied"
+    return 401, "invalid_api_key"
+
+
+def decision_headers(
+    decision: VerificationResult | None,
+    validation_time_ms: float | None,
+) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    if decision is not None:
+        if decision.request_id:
+            headers["X-ReqKey-Request-ID"] = decision.request_id
+        if decision.credits_limit is not None:
+            headers["X-ReqKey-Credits-Limit"] = str(decision.credits_limit)
+        if decision.credits_remaining is not None:
+            headers["X-ReqKey-Credits-Remaining"] = str(decision.credits_remaining)
+    if validation_time_ms is not None:
+        headers["X-ReqKey-Validation-Time-Ms"] = f"{validation_time_ms:.3f}"
+    return headers
+
+
+def excluded_header_names(key_name: str, extra: Iterable[str]) -> frozenset[str]:
+    return DEFAULT_EXCLUDED_HEADERS | {header.lower() for header in extra} | {
+        key_name.lower()
+    }
+
+
+def filtered_headers(
+    headers: Mapping[str, str],
+    excluded: frozenset[str],
+) -> dict[str, str]:
+    return {
+        key: value
+        for key, value in headers.items()
+        if key.lower() not in excluded
+    }