reqkey 0.1.0__py3-none-any.whl

reqkey/client.py

@@ -0,0 +1,469 @@
+"""Synchronous and asynchronous clients for the ReqKey HTTP API."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+from .exceptions import (
+    ReqKeyAPIError,
+    ReqKeyAuthenticationError,
+    ReqKeyConfigurationError,
+    ReqKeyTimeoutError,
+    ReqKeyTransportError,
+)
+from .models import VerificationReason, VerificationResult
+
+DEFAULT_BASE_URL = "https://api.reqkey.com"
+DEFAULT_TIMEOUT_SECONDS = 2.0
+USER_AGENT = "reqkey-python/0.1.0"
+MAX_BODY_CHARACTERS = 1000
+_DECISION_STATUS_CODES = {200, 402, 403, 429}
+
+
+def _require_project_key(project_key: str | None, root_key: str | None) -> str:
+    if project_key is not None and root_key is not None:
+        raise ReqKeyConfigurationError("Pass project_key or root_key, not both.")
+    value = (project_key or root_key or "").strip()
+    if not value:
+        raise ReqKeyConfigurationError(
+            "A ReqKey project key is required. Pass project_key/root_key or set "
+            "REQKEY_PROJECT_KEY/REQKEY_ROOT_KEY."
+        )
+    return value
+
+
+def _validate_verify_input(key: str, credits: int) -> None:
+    if not key.strip():
+        raise ReqKeyConfigurationError("The consumer API key cannot be empty.")
+    if isinstance(credits, bool) or not isinstance(credits, int) or credits < 0:
+        raise ReqKeyConfigurationError("credits must be a non-negative integer.")
+
+
+def _json_object(response: httpx.Response) -> dict[str, Any]:
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise ReqKeyAPIError(
+            "ReqKey returned a non-JSON response.",
+            status_code=response.status_code,
+        ) from exc
+    if not isinstance(payload, dict):
+        raise ReqKeyAPIError(
+            "ReqKey returned an unexpected response body.",
+            status_code=response.status_code,
+        )
+    return payload
+
+
+def _error_message(payload: Mapping[str, Any], fallback: str) -> str:
+    for key in ("error", "message"):
+        value = payload.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return fallback
+
+
+def _number(value: Any) -> int | None:
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _float_number(value: Any) -> float | None:
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    return None
+
+
+def _reason_for(response: httpx.Response, payload: Mapping[str, Any]) -> VerificationReason:
+    if response.status_code == 402:
+        return VerificationReason.INSUFFICIENT_CREDITS
+    if response.status_code == 403:
+        return VerificationReason.FORBIDDEN
+    if response.status_code == 429 or payload.get("rateLimited") is True:
+        return VerificationReason.RATE_LIMITED
+    if payload.get("valid") is True:
+        return VerificationReason.VALID
+    if response.status_code == 200:
+        return VerificationReason.INVALID_KEY
+    return VerificationReason.DENIED
+
+
+def _verification_result(response: httpx.Response) -> VerificationResult:
+    payload = _json_object(response)
+
+    if response.status_code == 401:
+        raise ReqKeyAuthenticationError(
+            _error_message(payload, "ReqKey rejected the project credential."),
+            status_code=response.status_code,
+            body=payload,
+        )
+    if response.status_code not in _DECISION_STATUS_CODES:
+        raise ReqKeyAPIError(
+            _error_message(payload, f"ReqKey returned HTTP {response.status_code}."),
+            status_code=response.status_code,
+            body=payload,
+        )
+
+    retry_after = _float_number(payload.get("retryAfter"))
+    if retry_after is None:
+        retry_after = _float_number(response.headers.get("Retry-After"))
+
+    raw_allowed_apis = payload.get("allowedApis")
+    allowed_apis = (
+        tuple(str(item) for item in raw_allowed_apis)
+        if isinstance(raw_allowed_apis, list)
+        else ()
+    )
+    raw_rate_limit = payload.get("rateLimit")
+    rate_limit = dict(raw_rate_limit) if isinstance(raw_rate_limit, dict) else None
+
+    return VerificationResult(
+        valid=payload.get("valid") is True,
+        reason=_reason_for(response, payload),
+        status_code=response.status_code,
+        request_id=payload.get("requestId") if isinstance(payload.get("requestId"), str) else None,
+        message=payload.get("message") if isinstance(payload.get("message"), str) else None,
+        api_id=payload.get("apiId") if isinstance(payload.get("apiId"), str) else None,
+        api_name=payload.get("apiName") if isinstance(payload.get("apiName"), str) else None,
+        resource=payload.get("resource") if isinstance(payload.get("resource"), str) else None,
+        credits_remaining=_number(payload.get("creditsRemaining")),
+        credits_limit=_number(payload.get("creditsLimit")),
+        allowed_apis=allowed_apis,
+        retry_after=retry_after,
+        rate_limit=rate_limit,
+        raw=payload,
+    )
+
+
+def _verify_payload(
+    *,
+    key: str,
+    api_id: str | None,
+    credits: int,
+    resource: str | None,
+) -> dict[str, Any]:
+    _validate_verify_input(key, credits)
+    payload: dict[str, Any] = {"key": key, "credits": credits}
+    if api_id is not None:
+        payload["apiId"] = api_id
+    if resource is not None:
+        payload["resource"] = resource
+    return payload
+
+
+def _ingest_payload(
+    *,
+    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,
+) -> dict[str, Any]:
+    if request_id is not None and not request_id.strip():
+        raise ReqKeyConfigurationError("request_id cannot be empty when provided.")
+    if api_id is not None and not api_id.strip():
+        raise ReqKeyConfigurationError("api_id cannot be empty when provided.")
+    if request_id is None and api_id is None:
+        raise ReqKeyConfigurationError("Ingestion requires request_id, api_id, or both.")
+    payload: dict[str, Any] = {}
+    if request_id is not None:
+        payload["requestId"] = request_id
+    if api_id is not None:
+        payload["apiId"] = api_id
+    optional_values: dict[str, Any] = {
+        "method": method,
+        "endpoint": endpoint,
+        "path": path,
+        "statusCode": status_code,
+        "latencyMs": latency_ms,
+        "clientIp": client_ip,
+        "userAgent": user_agent,
+        "userId": user_id,
+        "queryParams": dict(query_params) if query_params is not None else None,
+        "requestHeaders": dict(request_headers) if request_headers is not None else None,
+        "responseHeaders": dict(response_headers) if response_headers is not None else None,
+        "requestBody": (
+            request_body[:MAX_BODY_CHARACTERS] if request_body is not None else None
+        ),
+        "responseBody": (
+            response_body[:MAX_BODY_CHARACTERS] if response_body is not None else None
+        ),
+        "timestamp": timestamp.isoformat() if isinstance(timestamp, datetime) else timestamp,
+    }
+    payload.update({key: value for key, value in optional_values.items() if value is not None})
+    return payload
+
+
+class _ClientConfig:
+    def __init__(
+        self,
+        project_key: str | None,
+        root_key: str | None,
+        base_url: str,
+        timeout: float,
+    ) -> None:
+        self.project_key = _require_project_key(project_key, root_key)
+        self.base_url = base_url.rstrip("/")
+        if not self.base_url:
+            raise ReqKeyConfigurationError("base_url cannot be empty.")
+        if timeout <= 0:
+            raise ReqKeyConfigurationError("timeout must be greater than zero.")
+        self.timeout = timeout
+
+    @property
+    def headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.project_key}",
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+
+
+class ReqKey:
+    """Synchronous ReqKey client."""
+
+    def __init__(
+        self,
+        *,
+        project_key: str | None = None,
+        root_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._config = _ClientConfig(project_key, root_key, base_url, timeout)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout, headers=self._config.headers)
+
+    @classmethod
+    def from_env(cls, **kwargs: Any) -> ReqKey:
+        """Create a client using `REQKEY_PROJECT_KEY` or `REQKEY_ROOT_KEY`."""
+
+        return cls(
+            project_key=os.getenv("REQKEY_PROJECT_KEY") or os.getenv("REQKEY_ROOT_KEY"),
+            **kwargs,
+        )
+
+    def verify(
+        self,
+        key: str,
+        *,
+        api_id: str | None = None,
+        credits: int = 1,
+        resource: str | None = None,
+    ) -> VerificationResult:
+        """Validate a consumer key and atomically deduct credits."""
+
+        try:
+            response = self._client.post(
+                f"{self._config.base_url}/key/validate",
+                json=_verify_payload(key=key, api_id=api_id, credits=credits, resource=resource),
+                headers=self._config.headers,
+            )
+        except httpx.TimeoutException as exc:
+            raise ReqKeyTimeoutError("The ReqKey validation request timed out.") from exc
+        except httpx.RequestError as exc:
+            raise ReqKeyTransportError(f"Could not reach ReqKey: {exc}") from exc
+        return _verification_result(response)
+
+    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:
+        """Send request/response metadata to ReqKey analytics."""
+
+        payload = _ingest_payload(
+            request_id=request_id,
+            api_id=api_id,
+            method=method,
+            endpoint=endpoint,
+            path=path,
+            status_code=status_code,
+            latency_ms=latency_ms,
+            client_ip=client_ip,
+            user_agent=user_agent,
+            user_id=user_id,
+            query_params=query_params,
+            request_headers=request_headers,
+            response_headers=response_headers,
+            request_body=request_body,
+            response_body=response_body,
+            timestamp=timestamp,
+        )
+        try:
+            response = self._client.post(
+                f"{self._config.base_url}/ingest",
+                json=payload,
+                headers=self._config.headers,
+            )
+        except httpx.TimeoutException as exc:
+            raise ReqKeyTimeoutError("The ReqKey ingestion request timed out.") from exc
+        except httpx.RequestError as exc:
+            raise ReqKeyTransportError(f"Could not reach ReqKey: {exc}") from exc
+        if response.status_code not in {200, 202}:
+            body = _json_object(response)
+            raise ReqKeyAPIError(
+                _error_message(body, f"ReqKey returned HTTP {response.status_code}."),
+                status_code=response.status_code,
+                body=body,
+            )
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> ReqKey:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncReqKey:
+    """Asynchronous ReqKey client for FastAPI and other async applications."""
+
+    def __init__(
+        self,
+        *,
+        project_key: str | None = None,
+        root_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._config = _ClientConfig(project_key, root_key, base_url, timeout)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(
+            timeout=timeout,
+            headers=self._config.headers,
+        )
+
+    @classmethod
+    def from_env(cls, **kwargs: Any) -> AsyncReqKey:
+        """Create a client using `REQKEY_PROJECT_KEY` or `REQKEY_ROOT_KEY`."""
+
+        return cls(
+            project_key=os.getenv("REQKEY_PROJECT_KEY") or os.getenv("REQKEY_ROOT_KEY"),
+            **kwargs,
+        )
+
+    async def verify(
+        self,
+        key: str,
+        *,
+        api_id: str | None = None,
+        credits: int = 1,
+        resource: str | None = None,
+    ) -> VerificationResult:
+        """Validate a consumer key and atomically deduct credits."""
+
+        try:
+            response = await self._client.post(
+                f"{self._config.base_url}/key/validate",
+                json=_verify_payload(key=key, api_id=api_id, credits=credits, resource=resource),
+                headers=self._config.headers,
+            )
+        except httpx.TimeoutException as exc:
+            raise ReqKeyTimeoutError("The ReqKey validation request timed out.") from exc
+        except httpx.RequestError as exc:
+            raise ReqKeyTransportError(f"Could not reach ReqKey: {exc}") from exc
+        return _verification_result(response)
+
+    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:
+        """Send request/response metadata to ReqKey analytics."""
+
+        payload = _ingest_payload(
+            request_id=request_id,
+            api_id=api_id,
+            method=method,
+            endpoint=endpoint,
+            path=path,
+            status_code=status_code,
+            latency_ms=latency_ms,
+            client_ip=client_ip,
+            user_agent=user_agent,
+            user_id=user_id,
+            query_params=query_params,
+            request_headers=request_headers,
+            response_headers=response_headers,
+            request_body=request_body,
+            response_body=response_body,
+            timestamp=timestamp,
+        )
+        try:
+            response = await self._client.post(
+                f"{self._config.base_url}/ingest",
+                json=payload,
+                headers=self._config.headers,
+            )
+        except httpx.TimeoutException as exc:
+            raise ReqKeyTimeoutError("The ReqKey ingestion request timed out.") from exc
+        except httpx.RequestError as exc:
+            raise ReqKeyTransportError(f"Could not reach ReqKey: {exc}") from exc
+        if response.status_code not in {200, 202}:
+            body = _json_object(response)
+            raise ReqKeyAPIError(
+                _error_message(body, f"ReqKey returned HTTP {response.status_code}."),
+                status_code=response.status_code,
+                body=body,
+            )
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncReqKey:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()