reqkey 0.1.0__tar.gz → 0.2.1__tar.gz

{reqkey-0.1.0 → reqkey-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reqkey
-Version: 0.1.0
+Version: 0.2.1
 Summary: The official Python SDK for ReqKey API key validation and usage analytics
 Project-URL: Homepage, https://reqkey.com
 Project-URL: Documentation, https://reqkey.com/docs
@@ -76,6 +76,9 @@ Description-Content-Type: text/markdown
 The official Python SDK for API key validation, credit metering, consumer rate
 limits, and correlated API traffic analytics with ReqKey.
 
+**Website:** [reqkey.com](https://reqkey.com) ·
+**Documentation:** [reqkey.com/docs](https://reqkey.com/docs)
+
 One distribution contains the shared sync/async client and optional framework
 adapters. FastAPI, Starlette, Django, Flask, and generic ASGI/WSGI applications
 can all use ready-made middleware without implementing ReqKey request logic.
@@ -313,7 +316,7 @@ With `mode="both"`:
 Consumer request
   → extract consumer key
   → await /key/validate
-  → denied: return 401 / 402 / 403 / 429
+  → denied: await /ingest, then return 401 / 402 / 403 / 429
   → approved: run the FastAPI endpoint
   → collect response metadata
   → await /ingest with the validation requestId
@@ -328,6 +331,11 @@ starting an unreliable background task:
   response.
 - Django's native middleware ingests before returning the response object.
 
+Denied requests are recorded by default in `mode="both"`, including requests
+with a missing key. This makes invalid-key attempts, exhausted consumers, and
+rate-limit hammering visible in analytics. Set `ingest_denied_requests=False`
+if you deliberately do not want those events or their ingestion cost.
+
 Streaming responses are forwarded chunk by chunk. The middleware keeps only
 enough data to reconstruct the first 1,000 response-body characters and holds
 the final ASGI completion message until ingestion finishes. It does not retain
@@ -354,6 +362,10 @@ iterator.
 | `credits` | `1` | Static cost or sync/async cost resolver. |
 | `exclude_paths` | empty | Exact paths or trailing-`*` prefix patterns. |
 | `skip_methods` | `("OPTIONS",)` | Methods that bypass ReqKey. |
+| `consumer_name_resolver` | — | Resolve a display name from a request header, query parameter, or another trusted source. |
+| `client_ip_resolver` | automatic | Override client-IP extraction for a trusted proxy setup. |
+| `on_error` | — | Receive validation or ingestion service failures without exposing request secrets. |
+| `ingest_denied_requests` | `True` | Record denied traffic in `mode="both"`. |
 | `failure_mode` | `"closed"` | Deny or allow when ReqKey itself is unavailable. |
 | `error_messages` | built in | Override customer-facing denial messages. |
 | `timeout` | `2.0` | Timeout for each ReqKey operation. |
@@ -539,6 +551,9 @@ Metadata sent by default:
 - response status
 - endpoint processing latency
 - user agent
+- the consumer API key in the dedicated `apiKey` field, so ReqKey can resolve
+  the internal consumer name
+- `consumerName` when a resolver supplies one
 
 Additional data is opt-in:
 
@@ -561,9 +576,75 @@ app.add_middleware(
 ```
 
 Authorization, cookies, `Set-Cookie`, common API-key headers, and the configured
-consumer-key header are always removed from captured headers. Response-body
-capture is limited to textual content and a hard maximum of 1,000 characters.
-The limit is enforced again by the HTTP client before `/ingest` is called.
+consumer-key header are always removed from captured headers and paths. The
+middleware sends the extracted consumer key only through `/ingest`'s dedicated
+`apiKey` field for consumer resolution. Response-body capture is limited to
+textual content and a hard maximum of 1,000 characters. The limit is enforced
+again by the HTTP client before `/ingest` is called.
+
+### Consumer names
+
+Use `consumer_name_resolver` when an upstream gateway or your application
+provides a useful customer label. The resolver may read any part of the
+framework request and may be synchronous or asynchronous in ASGI/Django:
+
+```python
+def consumer_name(request: Request) -> str | None:
+    return (
+        request.headers.get("X-RapidAPI-User")
+        or request.query_params.get("consumerName")
+    )
+
+
+app.add_middleware(
+    ReqKeyMiddleware,
+    project_key=os.environ["REQKEY_PROJECT_KEY"],
+    api_id="api_payments",
+    consumer_name_resolver=consumer_name,
+)
+```
+
+The resolved value is optional analytics metadata. It is not used as the
+consumer API key and does not change authorization. ReqKey resolves the
+consumer display name in this order:
+
+1. A non-empty `consumerName` supplied by the resolver.
+2. The middleware's extracted consumer key, sent as `apiKey` for an internal
+   consumer lookup.
+3. A `consumerId` supplied to the direct client.
+
+No resolver is required for normal ReqKey-managed consumers. The middleware
+still sends the validation `requestId` for log correlation, but `/ingest` does
+not use it to resolve consumer identity.
+
+For Django, set `CONSUMER_NAME_RESOLVER` in `REQKEY`. For WSGI, the resolver
+receives the WSGI environment, so a header can be read as
+`environ.get("HTTP_X_RAPIDAPI_USER")`.
+
+### Client IPs and trusted proxies
+
+Client-IP capture is opt-in with `capture_client_ip=True`. By default, the SDK
+keeps the framework-provided peer address first: `request.client.host` for
+ASGI, `REMOTE_ADDR` for WSGI, and `request.META["REMOTE_ADDR"]` for Django. It
+only falls back when that value is absent, checking common proxy headers such
+as `X-Forwarded-For`, `X-Real-IP`, Cloudflare, Vercel, Fly, Fastly, Azure,
+App Engine, CloudFront, and standardized `Forwarded` headers.
+
+If a trusted proxy always supplies the real client in a specific header, use a
+resolver to override that default explicitly:
+
+```python
+app.add_middleware(
+    ReqKeyMiddleware,
+    project_key=os.environ["REQKEY_PROJECT_KEY"],
+    api_id="api_payments",
+    capture_client_ip=True,
+    client_ip_resolver=lambda request: request.headers.get("CF-Connecting-IP"),
+)
+```
+
+Only trust forwarding headers when your deployment proxy overwrites them;
+otherwise a caller can spoof their value.
 
 ## Custom denial messages
 
@@ -616,8 +697,9 @@ The response includes these values when available:
 - `X-ReqKey-Credits-Remaining`
 - `X-ReqKey-Validation-Time-Ms`
 
-If browser JavaScript needs these headers, add them to the FastAPI CORS
-middleware's `expose_headers` list.
+No CORS configuration is needed for server-to-server clients or for the server
+itself to set these headers. Only cross-origin browser JavaScript that must read
+them needs the names added to the CORS middleware's `expose_headers` list.
 
 ## Availability behavior
 
@@ -636,6 +718,44 @@ but it will not be correlated to a validated consumer.
 The SDK does not automatically retry `/key/validate`, because validation can
 deduct credits. Safe automatic retries require server-side idempotency.
 
+### Failure alerts
+
+Webhook payload formats differ between Discord, Slack, Teams, and custom alert
+receivers, so the SDK does not post one supposed universal webhook format.
+Instead, `on_error` receives a provider-neutral `MiddlewareErrorEvent` for
+ReqKey validation or ingestion failures:
+
+```python
+from reqkey import MiddlewareErrorEvent
+
+
+async def report_reqkey_failure(event: MiddlewareErrorEvent) -> None:
+    await send_to_your_alert_provider(
+        {
+            "operation": event.operation,
+            "message": event.message,
+            "method": event.method,
+            "path": event.path,
+            "request_id": event.request_id,
+            "status_code": event.status_code,
+        }
+    )
+
+
+app.add_middleware(
+    ReqKeyMiddleware,
+    project_key=os.environ["REQKEY_PROJECT_KEY"],
+    api_id="api_payments",
+    on_error=report_reqkey_failure,
+)
+```
+
+The event intentionally excludes API keys, project credentials, headers,
+query parameters, and bodies. Exceptions raised by the callback are logged and
+do not replace the application response. WSGI callbacks are synchronous;
+ASGI callbacks may be synchronous or asynchronous, and Django follows the
+sync/async mode of its middleware chain.
+
 ## Direct sync and async clients
 
 Async:
@@ -661,6 +781,21 @@ with ReqKey(project_key=os.environ["REQKEY_PROJECT_KEY"]) as reqkey:
     decision = reqkey.verify("consumer_key_...", api_id="api_payments")
 ```
 
+Direct ingestion accepts the same consumer identity inputs as `/ingest`:
+
+```python
+reqkey.ingest(
+    decision.request_id,
+    api_id="api_payments",
+    method="POST",
+    path="/payments",
+    status_code=201,
+    api_key="consumer_key_...",  # resolves the internal consumer name
+    # consumer_name="rapidapi-user",  # optional explicit override
+    # consumer_id="consumer_...",     # fallback when no API key is available
+)
+```
+
 ASGI and FastAPI use the asynchronous client and await both network operations.
 WSGI uses the synchronous client. Django automatically selects the correct
 client based on its middleware chain, avoiding blocking HTTP calls inside an

{reqkey-0.1.0 → reqkey-0.2.1}/README.md

@@ -3,6 +3,9 @@
 The official Python SDK for API key validation, credit metering, consumer rate
 limits, and correlated API traffic analytics with ReqKey.
 
+**Website:** [reqkey.com](https://reqkey.com) ·
+**Documentation:** [reqkey.com/docs](https://reqkey.com/docs)
+
 One distribution contains the shared sync/async client and optional framework
 adapters. FastAPI, Starlette, Django, Flask, and generic ASGI/WSGI applications
 can all use ready-made middleware without implementing ReqKey request logic.
@@ -240,7 +243,7 @@ With `mode="both"`:
 Consumer request
   → extract consumer key
   → await /key/validate
-  → denied: return 401 / 402 / 403 / 429
+  → denied: await /ingest, then return 401 / 402 / 403 / 429
   → approved: run the FastAPI endpoint
   → collect response metadata
   → await /ingest with the validation requestId
@@ -255,6 +258,11 @@ starting an unreliable background task:
   response.
 - Django's native middleware ingests before returning the response object.
 
+Denied requests are recorded by default in `mode="both"`, including requests
+with a missing key. This makes invalid-key attempts, exhausted consumers, and
+rate-limit hammering visible in analytics. Set `ingest_denied_requests=False`
+if you deliberately do not want those events or their ingestion cost.
+
 Streaming responses are forwarded chunk by chunk. The middleware keeps only
 enough data to reconstruct the first 1,000 response-body characters and holds
 the final ASGI completion message until ingestion finishes. It does not retain
@@ -281,6 +289,10 @@ iterator.
 | `credits` | `1` | Static cost or sync/async cost resolver. |
 | `exclude_paths` | empty | Exact paths or trailing-`*` prefix patterns. |
 | `skip_methods` | `("OPTIONS",)` | Methods that bypass ReqKey. |
+| `consumer_name_resolver` | — | Resolve a display name from a request header, query parameter, or another trusted source. |
+| `client_ip_resolver` | automatic | Override client-IP extraction for a trusted proxy setup. |
+| `on_error` | — | Receive validation or ingestion service failures without exposing request secrets. |
+| `ingest_denied_requests` | `True` | Record denied traffic in `mode="both"`. |
 | `failure_mode` | `"closed"` | Deny or allow when ReqKey itself is unavailable. |
 | `error_messages` | built in | Override customer-facing denial messages. |
 | `timeout` | `2.0` | Timeout for each ReqKey operation. |
@@ -466,6 +478,9 @@ Metadata sent by default:
 - response status
 - endpoint processing latency
 - user agent
+- the consumer API key in the dedicated `apiKey` field, so ReqKey can resolve
+  the internal consumer name
+- `consumerName` when a resolver supplies one
 
 Additional data is opt-in:
 
@@ -488,9 +503,75 @@ app.add_middleware(
 ```
 
 Authorization, cookies, `Set-Cookie`, common API-key headers, and the configured
-consumer-key header are always removed from captured headers. Response-body
-capture is limited to textual content and a hard maximum of 1,000 characters.
-The limit is enforced again by the HTTP client before `/ingest` is called.
+consumer-key header are always removed from captured headers and paths. The
+middleware sends the extracted consumer key only through `/ingest`'s dedicated
+`apiKey` field for consumer resolution. Response-body capture is limited to
+textual content and a hard maximum of 1,000 characters. The limit is enforced
+again by the HTTP client before `/ingest` is called.
+
+### Consumer names
+
+Use `consumer_name_resolver` when an upstream gateway or your application
+provides a useful customer label. The resolver may read any part of the
+framework request and may be synchronous or asynchronous in ASGI/Django:
+
+```python
+def consumer_name(request: Request) -> str | None:
+    return (
+        request.headers.get("X-RapidAPI-User")
+        or request.query_params.get("consumerName")
+    )
+
+
+app.add_middleware(
+    ReqKeyMiddleware,
+    project_key=os.environ["REQKEY_PROJECT_KEY"],
+    api_id="api_payments",
+    consumer_name_resolver=consumer_name,
+)
+```
+
+The resolved value is optional analytics metadata. It is not used as the
+consumer API key and does not change authorization. ReqKey resolves the
+consumer display name in this order:
+
+1. A non-empty `consumerName` supplied by the resolver.
+2. The middleware's extracted consumer key, sent as `apiKey` for an internal
+   consumer lookup.
+3. A `consumerId` supplied to the direct client.
+
+No resolver is required for normal ReqKey-managed consumers. The middleware
+still sends the validation `requestId` for log correlation, but `/ingest` does
+not use it to resolve consumer identity.
+
+For Django, set `CONSUMER_NAME_RESOLVER` in `REQKEY`. For WSGI, the resolver
+receives the WSGI environment, so a header can be read as
+`environ.get("HTTP_X_RAPIDAPI_USER")`.
+
+### Client IPs and trusted proxies
+
+Client-IP capture is opt-in with `capture_client_ip=True`. By default, the SDK
+keeps the framework-provided peer address first: `request.client.host` for
+ASGI, `REMOTE_ADDR` for WSGI, and `request.META["REMOTE_ADDR"]` for Django. It
+only falls back when that value is absent, checking common proxy headers such
+as `X-Forwarded-For`, `X-Real-IP`, Cloudflare, Vercel, Fly, Fastly, Azure,
+App Engine, CloudFront, and standardized `Forwarded` headers.
+
+If a trusted proxy always supplies the real client in a specific header, use a
+resolver to override that default explicitly:
+
+```python
+app.add_middleware(
+    ReqKeyMiddleware,
+    project_key=os.environ["REQKEY_PROJECT_KEY"],
+    api_id="api_payments",
+    capture_client_ip=True,
+    client_ip_resolver=lambda request: request.headers.get("CF-Connecting-IP"),
+)
+```
+
+Only trust forwarding headers when your deployment proxy overwrites them;
+otherwise a caller can spoof their value.
 
 ## Custom denial messages
 
@@ -543,8 +624,9 @@ The response includes these values when available:
 - `X-ReqKey-Credits-Remaining`
 - `X-ReqKey-Validation-Time-Ms`
 
-If browser JavaScript needs these headers, add them to the FastAPI CORS
-middleware's `expose_headers` list.
+No CORS configuration is needed for server-to-server clients or for the server
+itself to set these headers. Only cross-origin browser JavaScript that must read
+them needs the names added to the CORS middleware's `expose_headers` list.
 
 ## Availability behavior
 
@@ -563,6 +645,44 @@ but it will not be correlated to a validated consumer.
 The SDK does not automatically retry `/key/validate`, because validation can
 deduct credits. Safe automatic retries require server-side idempotency.
 
+### Failure alerts
+
+Webhook payload formats differ between Discord, Slack, Teams, and custom alert
+receivers, so the SDK does not post one supposed universal webhook format.
+Instead, `on_error` receives a provider-neutral `MiddlewareErrorEvent` for
+ReqKey validation or ingestion failures:
+
+```python
+from reqkey import MiddlewareErrorEvent
+
+
+async def report_reqkey_failure(event: MiddlewareErrorEvent) -> None:
+    await send_to_your_alert_provider(
+        {
+            "operation": event.operation,
+            "message": event.message,
+            "method": event.method,
+            "path": event.path,
+            "request_id": event.request_id,
+            "status_code": event.status_code,
+        }
+    )
+
+
+app.add_middleware(
+    ReqKeyMiddleware,
+    project_key=os.environ["REQKEY_PROJECT_KEY"],
+    api_id="api_payments",
+    on_error=report_reqkey_failure,
+)
+```
+
+The event intentionally excludes API keys, project credentials, headers,
+query parameters, and bodies. Exceptions raised by the callback are logged and
+do not replace the application response. WSGI callbacks are synchronous;
+ASGI callbacks may be synchronous or asynchronous, and Django follows the
+sync/async mode of its middleware chain.
+
 ## Direct sync and async clients
 
 Async:
@@ -588,6 +708,21 @@ with ReqKey(project_key=os.environ["REQKEY_PROJECT_KEY"]) as reqkey:
     decision = reqkey.verify("consumer_key_...", api_id="api_payments")
 ```
 
+Direct ingestion accepts the same consumer identity inputs as `/ingest`:
+
+```python
+reqkey.ingest(
+    decision.request_id,
+    api_id="api_payments",
+    method="POST",
+    path="/payments",
+    status_code=201,
+    api_key="consumer_key_...",  # resolves the internal consumer name
+    # consumer_name="rapidapi-user",  # optional explicit override
+    # consumer_id="consumer_...",     # fallback when no API key is available
+)
+```
+
 ASGI and FastAPI use the asynchronous client and await both network operations.
 WSGI uses the synchronous client. Django automatically selects the correct
 client based on its middleware chain, avoiding blocking HTTP calls inside an

{reqkey-0.1.0 → reqkey-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "reqkey"
-version = "0.1.0"
+version = "0.2.1"
 description = "The official Python SDK for ReqKey API key validation and usage analytics"
 readme = "README.md"
 requires-python = ">=3.10"

{reqkey-0.1.0 → reqkey-0.2.1}/src/reqkey/__init__.py

@@ -9,12 +9,13 @@ from .exceptions import (
     ReqKeyTimeoutError,
     ReqKeyTransportError,
 )
-from .models import VerificationReason, VerificationResult
+from .models import MiddlewareErrorEvent, VerificationReason, VerificationResult
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"
 
 __all__ = [
     "AsyncReqKey",
+    "MiddlewareErrorEvent",
     "ReqKey",
     "ReqKeyAPIError",
     "ReqKeyAuthenticationError",

{reqkey-0.1.0 → reqkey-0.2.1}/src/reqkey/_middleware.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import ipaddress
 from collections.abc import Iterable, Mapping
 from typing import Literal
 
@@ -32,6 +33,20 @@ DEFAULT_EXCLUDED_HEADERS = frozenset(
     }
 )
 
+PROXY_CLIENT_IP_HEADERS = (
+    "x-forwarded-for",
+    "x-real-ip",
+    "cf-connecting-ip",
+    "true-client-ip",
+    "x-vercel-forwarded-for",
+    "fly-client-ip",
+    "fastly-client-ip",
+    "x-azure-clientip",
+    "x-appengine-user-ip",
+    "cloudfront-viewer-address",
+    "forwarded",
+)
+
 
 def validate_middleware_options(
     *,
@@ -130,3 +145,54 @@ def filtered_headers(
         for key, value in headers.items()
         if key.lower() not in excluded
     }
+
+
+def client_ip_from_headers(headers: Mapping[str, str]) -> str | None:
+    """Return the first valid IP from common proxy headers.
+
+    Middleware adapters use this only when the framework did not provide a
+    client address. Applications that intentionally trust a proxy header can
+    override the behavior with ``client_ip_resolver``.
+    """
+
+    normalized = {key.lower(): value for key, value in headers.items()}
+    for name in PROXY_CLIENT_IP_HEADERS:
+        value = normalized.get(name)
+        if not value:
+            continue
+        candidates = _forwarded_candidates(value) if name == "forwarded" else value.split(",")
+        for candidate in candidates:
+            parsed = _parse_ip(candidate)
+            if parsed is not None:
+                return parsed
+    return None
+
+
+def _forwarded_candidates(value: str) -> list[str]:
+    candidates: list[str] = []
+    for element in value.split(","):
+        for parameter in element.split(";"):
+            name, separator, raw = parameter.strip().partition("=")
+            if separator and name.lower() == "for":
+                candidates.append(raw)
+    return candidates
+
+
+def _parse_ip(value: str) -> str | None:
+    candidate = value.strip().strip('"')
+    if not candidate or candidate.lower() == "unknown" or candidate.startswith("_"):
+        return None
+    if candidate.startswith("["):
+        end = candidate.find("]")
+        if end > 0:
+            candidate = candidate[1:end]
+    else:
+        try:
+            return str(ipaddress.ip_address(candidate))
+        except ValueError:
+            if candidate.count(":") == 1:
+                candidate = candidate.partition(":")[0]
+    try:
+        return str(ipaddress.ip_address(candidate))
+    except ValueError:
+        return None