persistence-kit 3.14.1__tar.gz → 3.15.0__tar.gz

{persistence_kit-3.14.1 → persistence_kit-3.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: persistence-kit
-Version: 3.14.1
+Version: 3.15.0
 Summary: Reusable persistence and repository toolkit
 License: MIT
 License-File: LICENSE
@@ -30,6 +30,7 @@ Provides-Extra: security-cognito
 Provides-Extra: storage-routes
 Provides-Extra: storage-s3
 Provides-Extra: testing
+Provides-Extra: tracing
 Requires-Dist: asyncpg (>=0.30.0,<1.0.0)
 Requires-Dist: boto3 (>=1.35.0,<2.0.0) ; extra == "storage-s3" or extra == "security-cognito" or extra == "dynamodb" or extra == "all"
 Requires-Dist: cryptography (>=42.0.0) ; extra == "encrypted" or extra == "testing" or extra == "all"
@@ -37,6 +38,7 @@ Requires-Dist: fastapi (>=0.115.0,<1.0.0) ; extra == "api" or extra == "storage-
 Requires-Dist: httpx (>=0.28.0,<1.0.0) ; extra == "restclient" or extra == "testing" or extra == "all"
 Requires-Dist: jinja2 (>=3.1.4,<4.0.0) ; extra == "mail" or extra == "testing" or extra == "all"
 Requires-Dist: motor (>=3.7.1,<4.0.0)
+Requires-Dist: opentelemetry-api (>=1.20.0,<2.0.0) ; extra == "tracing" or extra == "testing" or extra == "all"
 Requires-Dist: pydantic-settings (>=2.3.0,<3.0.0)
 Requires-Dist: pyjwt[crypto] (>=2.10.1,<3.0.0) ; extra == "security" or extra == "security-cognito" or extra == "testing" or extra == "all"
 Requires-Dist: python-multipart (>=0.0.31,<1.0.0) ; extra == "api" or extra == "storage-routes" or extra == "security" or extra == "security-cognito" or extra == "testing" or extra == "all"
@@ -156,7 +158,8 @@ pip install "persistence-kit[api,security,restclient]"
 | `restclient` | The REST client and its cache | httpx |
 | `encrypted` | Encrypted request and response payloads | fastapi, cryptography |
 | `mail` | Mail templates rendered with Jinja2 (sending itself needs no extra) | jinja2 |
-| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart, cryptography, jinja2 |
+| `tracing` | A span for every REST call, inside the request's trace | opentelemetry-api |
+| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart, cryptography, jinja2, opentelemetry-api |
 | `all` | Every optional capability | all of the above |
 
 Importing `persistence_kit` never loads an optional dependency by itself. Ask for
@@ -329,6 +332,13 @@ real one in tests.
 Base URLs can be overridden per environment with `REST_SERVICE_URLS`, a JSON map
 of service name to URL, without touching the registration.
 
+With `[tracing]` installed and a tracer provider in the app, every call is a client
+span inside the current trace, named `<METHOD> <path>` (`GET /api/invoices`) and
+tagged with the service in `peer.service`, with the host, the status and the retries. The query string is
+never recorded, and a failure keeps only the error type, not its message, so a
+password sent as a query parameter does not reach the traces. `MemoryRestClient`
+registered under a name produces the same spans, so they show up in local runs too.
+
 The cache is a plain key-value store with TTL, chosen by `CACHE_BACKEND` the
 same way repositories are chosen by `REPO_DATABASE`. Set `CACHE_NAMESPACE` when
 several apps share one DynamoDB table or Mongo collection so their keys do not
@@ -449,6 +459,7 @@ The factories read that object: `get_identity_provider`, `get_token_verifier`,
 | `CACHE_BACKEND` | `memory`, `mongo` or `dynamodb`. Defaults to `memory` |
 | `CACHE_NAMESPACE` | Key prefix, so apps sharing a cache store do not collide |
 | `REST_SERVICE_URLS` | JSON map `{"service": "base_url"}` overriding registered REST base URLs |
+| `TRUSTED_PROXY_HOPS` | Proxies in front of the app that append to `X-Forwarded-For`. The auth rate limit counts the address the outermost one saw, so a forged header does not open a new bucket. `1` by default (one load balancer), `2` behind CloudFront and an ALB, `0` with no proxy |
 | `MONGO_DSN`, `MONGO_DB` | Mongo connection |
 | `POSTGRES_DSN` | Full DSN, if you prefer it to the pieces below |
 | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB` | Postgres connection |

{persistence_kit-3.14.1 → persistence_kit-3.15.0}/README.md

@@ -107,7 +107,8 @@ pip install "persistence-kit[api,security,restclient]"
 | `restclient` | The REST client and its cache | httpx |
 | `encrypted` | Encrypted request and response payloads | fastapi, cryptography |
 | `mail` | Mail templates rendered with Jinja2 (sending itself needs no extra) | jinja2 |
-| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart, cryptography, jinja2 |
+| `tracing` | A span for every REST call, inside the request's trace | opentelemetry-api |
+| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart, cryptography, jinja2, opentelemetry-api |
 | `all` | Every optional capability | all of the above |
 
 Importing `persistence_kit` never loads an optional dependency by itself. Ask for
@@ -280,6 +281,13 @@ real one in tests.
 Base URLs can be overridden per environment with `REST_SERVICE_URLS`, a JSON map
 of service name to URL, without touching the registration.
 
+With `[tracing]` installed and a tracer provider in the app, every call is a client
+span inside the current trace, named `<METHOD> <path>` (`GET /api/invoices`) and
+tagged with the service in `peer.service`, with the host, the status and the retries. The query string is
+never recorded, and a failure keeps only the error type, not its message, so a
+password sent as a query parameter does not reach the traces. `MemoryRestClient`
+registered under a name produces the same spans, so they show up in local runs too.
+
 The cache is a plain key-value store with TTL, chosen by `CACHE_BACKEND` the
 same way repositories are chosen by `REPO_DATABASE`. Set `CACHE_NAMESPACE` when
 several apps share one DynamoDB table or Mongo collection so their keys do not
@@ -400,6 +408,7 @@ The factories read that object: `get_identity_provider`, `get_token_verifier`,
 | `CACHE_BACKEND` | `memory`, `mongo` or `dynamodb`. Defaults to `memory` |
 | `CACHE_NAMESPACE` | Key prefix, so apps sharing a cache store do not collide |
 | `REST_SERVICE_URLS` | JSON map `{"service": "base_url"}` overriding registered REST base URLs |
+| `TRUSTED_PROXY_HOPS` | Proxies in front of the app that append to `X-Forwarded-For`. The auth rate limit counts the address the outermost one saw, so a forged header does not open a new bucket. `1` by default (one load balancer), `2` behind CloudFront and an ALB, `0` with no proxy |
 | `MONGO_DSN`, `MONGO_DB` | Mongo connection |
 | `POSTGRES_DSN` | Full DSN, if you prefer it to the pieces below |
 | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB` | Postgres connection |

{persistence_kit-3.14.1 → persistence_kit-3.15.0}/persistence_kit/api/rate_limit.py

@@ -48,16 +48,11 @@ class InMemoryRateLimiter:
             return None
 
 
-def _resolve_client_id(request: Request) -> str:
-    forwarded_for = request.headers.get("x-forwarded-for")
-    if forwarded_for:
-        first_ip = forwarded_for.split(",")[0].strip()
-        if first_ip:
-            return first_ip
-
-    cf_connecting_ip = request.headers.get("cf-connecting-ip")
-    if cf_connecting_ip:
-        return cf_connecting_ip.strip()
+def _resolve_client_id(request: Request, trusted_proxy_hops: int) -> str:
+    forwarded_for = request.headers.get("x-forwarded-for", "")
+    chain = [hop.strip() for hop in forwarded_for.split(",") if hop.strip()]
+    if 0 < trusted_proxy_hops <= len(chain):
+        return chain[-trusted_proxy_hops]
 
     client_host = request.client.host if request.client else None
     return client_host or "unknown"
@@ -87,7 +82,7 @@ def build_auth_rate_limit_dependency(
         limit = getattr(settings, limit_setting_name)
         retry_after = await _get_rate_limiter(request).hit(
             scope=scope,
-            client_id=_resolve_client_id(request),
+            client_id=_resolve_client_id(request, getattr(settings, "trusted_proxy_hops", 1)),
             limit=limit,
             window_seconds=settings.auth_rate_limit_window_seconds,
         )

{persistence_kit-3.14.1 → persistence_kit-3.15.0}/persistence_kit/restclient/client.py

@@ -23,6 +23,7 @@ from persistence_kit.restclient.mapping import ModelMappingMixin
 from persistence_kit.restclient.payload import prepare_request
 from persistence_kit.restclient.resolver import StaticEndpointResolver
 from persistence_kit.restclient.retry import RetryPolicy
+from persistence_kit.restclient.tracing import traced_call
 
 
 class HttpxRestClient(ModelMappingMixin):
@@ -41,7 +42,9 @@ class HttpxRestClient(ModelMappingMixin):
         retry_policy: RetryPolicy | None = None,
         circuit_breaker: CircuitBreaker | None = None,
         client: httpx.AsyncClient | None = None,
+        name: str = "",
     ) -> None:
+        self.name = name
         self._config = config or ServiceConfig()
         self._resolver = resolver or StaticEndpointResolver()
         self._auth = authenticator or NoAuth()
@@ -89,6 +92,14 @@ class HttpxRestClient(ModelMappingMixin):
         )
         request = await self._auth.apply(request)
 
+        with traced_call(self.name, request.method, request.url) as call:
+            response, attempts = await self._exchange(request)
+            call.record(response.status_code, attempts)
+            if self._config.raise_for_status and not response.is_success:
+                raise RestHTTPError(response.status_code, response=response)
+            return response
+
+    async def _exchange(self, request: RestRequest) -> tuple[RestResponse, int]:
         attempt = 0
         refreshed = False
         while True:
@@ -128,10 +139,7 @@ class HttpxRestClient(ModelMappingMixin):
                 attempt += 1
                 continue
             break
-
-        if self._config.raise_for_status and not response.is_success:
-            raise RestHTTPError(response.status_code, response=response)
-        return response
+        return response, attempt
 
     async def _send(self, request: RestRequest) -> RestResponse:
         try:

{persistence_kit-3.14.1 → persistence_kit-3.15.0}/persistence_kit/restclient/factory.py

@@ -24,6 +24,7 @@ def build_rest_client(
     retry_policy: RetryPolicy | None = None,
     circuit_breaker: CircuitBreaker | None = None,
     settings: Any | None = None,
+    name: str = "",
 ) -> RestClient:
     if config is None:
         config = (
@@ -48,4 +49,5 @@ def build_rest_client(
         authenticator=authenticator,
         retry_policy=retry_policy,
         circuit_breaker=circuit_breaker,
+        name=name,
     )

{persistence_kit-3.14.1 → persistence_kit-3.15.0}/persistence_kit/restclient/memory.py

@@ -13,6 +13,7 @@ from persistence_kit.restclient.contracts import (
 from persistence_kit.restclient.errors import RestHTTPError
 from persistence_kit.restclient.mapping import ModelMappingMixin
 from persistence_kit.restclient.payload import prepare_request
+from persistence_kit.restclient.tracing import traced_call
 
 Handler = Callable[[RestRequest], RestResponse]
 
@@ -39,7 +40,9 @@ class MemoryRestClient(ModelMappingMixin):
         resolver: EndpointResolver | None = None,
         default_headers: Mapping[str, str] | None = None,
         raise_for_status: bool = True,
+        name: str = "",
     ) -> None:
+        self.name = name
         self._auth = authenticator or NoAuth()
         self._resolver = resolver
         self._default_headers = dict(default_headers or {})
@@ -100,22 +103,24 @@ class MemoryRestClient(ModelMappingMixin):
         request = await self._auth.apply(request)
         self.calls.append(request)
 
-        stub = self._stubs.get((method.upper(), service))
-        if stub is None:
-            response = RestResponse(
-                status_code=404,
-                headers={},
-                content=b"",
-                url=url,
-            )
-        elif callable(stub):
-            response = stub(request)
-        else:
-            response = stub
-
-        if self._raise and not response.is_success:
-            raise RestHTTPError(response.status_code, response=response)
-        return response
+        with traced_call(self.name, request.method, request.url) as call:
+            stub = self._stubs.get((method.upper(), service))
+            if stub is None:
+                response = RestResponse(
+                    status_code=404,
+                    headers={},
+                    content=b"",
+                    url=url,
+                )
+            elif callable(stub):
+                response = stub(request)
+            else:
+                response = stub
+
+            call.record(response.status_code)
+            if self._raise and not response.is_success:
+                raise RestHTTPError(response.status_code, response=response)
+            return response
 
     async def get(self, service: str, **kwargs: Any) -> RestResponse:
         return await self.request("GET", service, **kwargs)

{persistence_kit-3.14.1 → persistence_kit-3.15.0}/persistence_kit/restclient/registry.py

@@ -83,6 +83,8 @@ class RestClientRegistry:
         Inyecta dobles de prueba o stubs sin pasar por el transporte HTTP: ``get``
         devuelve este cliente tal cual, sin construir un ``HttpxRestClient``.
         """
+        if hasattr(client, "name") and not client.name:
+            client.name = name
         self._clients[name] = client
         return self
 
@@ -108,6 +110,7 @@ class RestClientRegistry:
             authenticator=service.authenticator,
             retry_policy=service.retry_policy,
             circuit_breaker=service.circuit_breaker,
+            name=name,
         )
 
         if service.config.cache_ttl_seconds or service.config.cacheable:

persistence_kit-3.15.0/persistence_kit/restclient/tracing.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Iterator
+from urllib.parse import urlsplit
+
+try:
+    from opentelemetry import trace
+    from opentelemetry.trace import SpanKind, Status, StatusCode
+except ImportError:
+    trace = None
+
+TRACER_NAME = "persistence_kit.restclient"
+
+
+class TracedCall:
+    def __init__(self, span: Any = None) -> None:
+        self._span = span
+
+    def record(self, status_code: int, attempts: int = 0) -> None:
+        if self._span is None:
+            return
+        self._span.set_attribute("http.response.status_code", status_code)
+        if attempts:
+            self._span.set_attribute("http.request.resend_count", attempts)
+        if status_code >= 400:
+            self._span.set_status(Status(StatusCode.ERROR))
+
+
+@contextmanager
+def traced_call(service_name: str, method: str, url: str) -> Iterator[TracedCall]:
+    if trace is None:
+        yield TracedCall()
+        return
+    parts = urlsplit(url)
+    path = parts.path or "/"
+    verb = method.upper()
+    tracer = trace.get_tracer(TRACER_NAME)
+    with tracer.start_as_current_span(
+        f"{verb} {path}",
+        kind=SpanKind.CLIENT,
+        record_exception=False,
+        set_status_on_exception=False,
+    ) as span:
+        span.set_attribute("http.request.method", verb)
+        span.set_attribute("url.path", path)
+        if parts.hostname:
+            span.set_attribute("server.address", parts.hostname)
+        if service_name:
+            span.set_attribute("peer.service", service_name)
+        try:
+            yield TracedCall(span)
+        except Exception as error:
+            status_code = getattr(error, "status_code", None)
+            if isinstance(status_code, int):
+                span.set_attribute("http.response.status_code", status_code)
+            span.set_attribute("error.type", type(error).__name__)
+            span.set_status(Status(StatusCode.ERROR))
+            raise

{persistence_kit-3.14.1 → persistence_kit-3.15.0}/persistence_kit/settings/app_settings.py

@@ -1,6 +1,6 @@
 from enum import Enum
 
-from pydantic import field_validator, model_validator
+from pydantic import Field, field_validator, model_validator
 from pydantic_settings import SettingsConfigDict
 
 from persistence_kit.settings.repo_settings import RepoSettings
@@ -57,6 +57,7 @@ class PersistenceKitSettings(RepoSettings):
     auth_login_rate_limit: int = 10
     auth_refresh_rate_limit: int = 30
     auth_password_rate_limit: int = 5
+    trusted_proxy_hops: int = Field(default=1, ge=0)
 
     # Export Storage
     export_storage_provider: ExportStorageProvider = ExportStorageProvider.LOCAL

{persistence_kit-3.14.1 → persistence_kit-3.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "persistence-kit"
-version = "3.14.1"
+version = "3.15.0"
 description = "Reusable persistence and repository toolkit"
 authors = ["Andres Felipe Serrano Barrios <andresfserrano1@gmail.com>"]
 readme = "README.md"
@@ -37,6 +37,7 @@ python-multipart = {version = ">=0.0.31,<1.0.0", optional = true}
 httpx = {version = ">=0.28.0,<1.0.0", optional = true}
 cryptography = {version = ">=42.0.0", optional = true}
 jinja2 = {version = "^3.1.4", optional = true}
+opentelemetry-api = {version = ">=1.20.0,<2.0.0", optional = true}
 
 [tool.poetry.extras]
 api = ["fastapi", "python-multipart"]
@@ -48,12 +49,14 @@ encrypted = ["fastapi", "cryptography"]
 dynamodb = ["boto3"]
 restclient = ["httpx"]
 mail = ["jinja2"]
-testing = ["fastapi", "pyjwt", "python-multipart", "httpx", "cryptography", "jinja2"]
-all = ["fastapi", "boto3", "pyjwt", "python-multipart", "httpx", "cryptography", "jinja2"]
+tracing = ["opentelemetry-api"]
+testing = ["fastapi", "pyjwt", "python-multipart", "httpx", "cryptography", "jinja2", "opentelemetry-api"]
+all = ["fastapi", "boto3", "pyjwt", "python-multipart", "httpx", "cryptography", "jinja2", "opentelemetry-api"]
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.0"
 pytest-asyncio = ">=0.23.0,<2.0.0"
+opentelemetry-sdk = ">=1.20.0,<2.0.0"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]