hexcore 6.2.0__tar.gz → 7.0.0__tar.gz

{hexcore-6.2.0/hexcore.egg-info → hexcore-7.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 6.2.0
+Version: 7.0.0
 Summary: Núcleo reutilizable para proyectos Python con arquitectura hexagonal y event handling. Provee abstracciones, utilidades y contratos para DDD, eventos y desacoplamiento de infraestructura.
 Author-email: "David Latosefki (Indroic)" <indroic@outlook.com>
 License-Expression: MIT
@@ -10,7 +10,6 @@ License-File: LICENSE
 Requires-Dist: croniter>=2.0.0
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: typer>=0.17.3
-Requires-Dist: ruff>=0.12.11
 Provides-Extra: api
 Requires-Dist: fastapi>=0.116.1; extra == "api"
 Provides-Extra: redis

{hexcore-6.2.0 → hexcore-7.0.0}/hexcore/config.py

@@ -42,9 +42,22 @@ class ServerConfig(BaseModel):
     redis_cache_duration: int = 300  # seconds
 
     # Security
-    allow_origins: list[str] = [
-        "*" if debug else "http://localhost:{port}".format(port=port)
-    ]
+    #
+    # `allow_origins` NO se puede derivar en el cuerpo de la clase. La versión anterior
+    # era ``["*" if debug else "http://localhost:{port}"]``, y ese `debug` es el del
+    # cuerpo de clase (siempre `True`), así que el condicional era código muerto y el
+    # valor era **siempre** `["*"]` — incluso con `ServerConfig(debug=False)`.
+    #
+    # Combinado con `allow_credentials=True`, eso es un agujero real y no teórico:
+    # Starlette no puede mandar `*` junto con credenciales, así que cuando hay cookie
+    # **refleja el Origin del atacante** (`CORSMiddleware`, rama
+    # `if self.allow_all_origins and has_cookie`) y agrega
+    # `Access-Control-Allow-Credentials: true`. Cualquier origen puede entonces leer
+    # respuestas autenticadas con la cookie de sesión de la víctima, sin necesidad de XSS.
+    #
+    # Se deriva en un validador `mode="after"`, que sí ve el `debug` y el `port` de **la
+    # instancia**. Si lo pasás explícito, no se toca.
+    allow_origins: list[str] = Field(default_factory=list)
     allow_credentials: bool = True
     allow_methods: list[str] = ["*"]
     allow_headers: list[str] = ["*"]
@@ -96,6 +109,77 @@ class ServerConfig(BaseModel):
             data["event_bus"] = data.pop("event_dispatcher")
         return data
 
+    # ── CORS ──────────────────────────────────────────────────────────────────
+    @model_validator(mode="after")
+    def _resolve_cors_origins(self) -> "ServerConfig":
+        """
+        Deriva `allow_origins` del `debug`/`port` reales y rechaza la combinación insegura.
+
+        Dos cosas, en este orden:
+
+        1. Si no pasaste `allow_origins`, se completa: en `debug` queda `["*"]` (comodidad
+           de desarrollo, que era la intención original), y fuera de `debug` queda
+           `["http://localhost:<port>"]`. Un valor explícito —incluso `[]`— se respeta.
+        2. **`"*"` con `allow_credentials=True` nunca es válido, y el invariante vale
+           siempre, no sólo fuera de `debug`.** Es que `debug` viene en `True` por
+           defecto, así que condicionarlo al entorno dejaba la combinación peligrosa
+           como configuración *de fábrica*: `create_app()` sin tocar nada reflejaba el
+           Origin del atacante. Según cómo lo pediste:
+
+           - Si **no** declaraste `allow_credentials`, se baja a `False` y se avisa. Sin
+             `Access-Control-Allow-Credentials: true` el navegador no expone la respuesta
+             a una petición con cookies, así que el reflejo queda inofensivo.
+           - Si declaraste las dos cosas, **no arranca**: pediste explícitamente algo que
+             la especificación de CORS no permite, y adivinar cuál de las dos querías
+             sería peor que fallar.
+
+        O sea: si necesitás cookies, declarás tus orígenes. Es la única combinación que
+        sirve para sesiones `HttpOnly`, y ahora el default te empuja hacia ella en vez de
+        dejarte un agujero abierto.
+        """
+        # Se lee ANTES de asignar: en pydantic v2, asignar un campo lo agrega a
+        # `model_fields_set`, así que consultarlo después de derivar el default daría
+        # "lo pidió el usuario" para un valor que puso el framework.
+        lo_pidio_el_usuario = "allow_origins" in self.model_fields_set
+
+        if not lo_pidio_el_usuario and not self.allow_origins:
+            self.allow_origins = (
+                ["*"] if self.debug else [f"http://localhost:{self.port}"]
+            )
+
+        if "*" not in self.allow_origins or not self.allow_credentials:
+            return self
+
+        credenciales_explicitas = "allow_credentials" in self.model_fields_set
+
+        if credenciales_explicitas and lo_pidio_el_usuario:
+            raise ValueError(
+                "allow_origins=['*'] junto con allow_credentials=True permite que "
+                "cualquier origen lea respuestas autenticadas: el navegador no puede "
+                "mandar '*' con credenciales, así que Starlette refleja el Origin de "
+                "quien pregunte y agrega Access-Control-Allow-Credentials.\n\n"
+                "Pediste las dos cosas explícitamente, así que no se adivina. Elegí:\n\n"
+                "    config.allow_origins = ['https://tu-front.com']\n"
+                "    # o, si de verdad querés una API pública sin cookies:\n"
+                "    config.allow_credentials = False\n"
+            )
+
+        # Una de las dos vino por default, así que se baja `allow_credentials` en vez de
+        # negarse a arrancar. Es lo que hace que la configuración de fábrica sea segura.
+        import warnings
+
+        self.allow_credentials = False
+        warnings.warn(
+            "allow_origins incluye '*', así que allow_credentials se baja a False: "
+            "'*' con credenciales haría que Starlette reflejara el Origin de cualquiera "
+            "que mande una cookie, y el navegador no permite esa combinación de todos "
+            "modos. Si necesitás cookies de sesión, declará tus orígenes:\n\n"
+            "    config.allow_origins = ['http://localhost:3000']\n",
+            stacklevel=2,
+        )
+
+        return self
+
 
 class LazyConfig:
     """

{hexcore-6.2.0 → hexcore-7.0.0}/hexcore/infrastructure/api/__init__.py

@@ -10,6 +10,7 @@ from .cqrs import (
 )
 from .exception_handlers import (
     DEFAULT_EXCEPTION_STATUS_MAP,
+    HeadersFactory,
     register_exception_handlers,
 )
 from .health import (
@@ -48,6 +49,7 @@ __all__ = [
     "mount_routers",
     # Handlers de excepción (F5)
     "DEFAULT_EXCEPTION_STATUS_MAP",
+    "HeadersFactory",
     "register_exception_handlers",
     # Providers CQRS (F6)
     "CQRSContainer",

{hexcore-6.2.0 → hexcore-7.0.0}/hexcore/infrastructure/api/app.py

@@ -14,7 +14,7 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from pydantic import BaseModel
 
-from .exception_handlers import register_exception_handlers
+from .exception_handlers import HeadersFactory, register_exception_handlers
 from .health import Probe, ResponseFactory, register_health_routes
 from .middlewares import RequestIDMiddleware, TimingMiddleware
 from .routing import MountableRouter, mount_routers
@@ -78,6 +78,7 @@ def create_app(
     routers: t.Sequence[MountableRouter] | None = None,
     health_probes: t.Sequence[Probe] | None = None,
     exception_mapping: dict[type[Exception], int] | None = None,
+    exception_headers: HeadersFactory | None = None,
     **fastapi_kwargs: t.Any,
 ) -> FastAPI:
     """
@@ -94,6 +95,9 @@ def create_app(
             configuración (F16). Qué rutas se registran y con qué forma se controla con
             `AppFeatures(health=HealthRoutes(...))`.
         exception_mapping: Excepciones extra a mapear, fusionadas con el default (F5).
+        exception_headers: Headers extra por excepción. Necesario para los status que
+            los exigen por especificación: un 401 tiene que llevar `WWW-Authenticate`
+            (RFC 6750 §3).
         **fastapi_kwargs: Se pasan tal cual a `FastAPI` (`title`, `version`,
             `docs_url`, `openapi_tags`…). Lo que pases gana sobre los defaults derivados
             de la configuración.
@@ -123,7 +127,9 @@ def create_app(
         app.add_middleware(RequestIDMiddleware)
 
     if resolved_features.exception_handlers:
-        register_exception_handlers(app, mapping=exception_mapping)
+        register_exception_handlers(
+            app, mapping=exception_mapping, headers_for=exception_headers
+        )
 
     if resolved_features.health:
         health_routes = (

{hexcore-6.2.0 → hexcore-7.0.0}/hexcore/infrastructure/api/exception_handlers.py

@@ -40,6 +40,7 @@ DEFAULT_EXCEPTION_STATUS_MAP: dict[type[Exception], int] = {
 }
 
 DetailFactory = t.Callable[[Exception], str]
+HeadersFactory = t.Callable[[Exception], t.Mapping[str, str]]
 
 
 def register_exception_handlers(
@@ -47,6 +48,7 @@ def register_exception_handlers(
     *,
     mapping: dict[type[Exception], int] | None = None,
     include_detail: bool | DetailFactory = True,
+    headers_for: HeadersFactory | None = None,
 ) -> None:
     """
     Registra handlers que traducen excepciones a respuestas JSON.
@@ -58,13 +60,31 @@ def register_exception_handlers(
         include_detail: Qué poner en el campo ``detail`` de la respuesta.
             ``True`` → ``str(exc)``. ``False`` → un mensaje genérico por status, para no
             filtrar internals en una API pública. Un callable → lo que devuelva.
+        headers_for: Headers extra por excepción. Recibe la excepción y devuelve un mapa
+            de headers; devolvé un mapa vacío para no agregar nada. Hace falta porque hay
+            status codes que **exigen** un header por especificación y no se pueden
+            expresar sólo con un número: un 401 tiene que llevar `WWW-Authenticate`
+            (RFC 6750 §3), y un 429 un `Retry-After`.
 
     El cuerpo es siempre ``{"detail": ..., "error": "<NombreDeLaExcepción>"}``, para que
     el cliente pueda distinguir el caso sin parsear el texto.
 
+    Se eligió un callable aparte antes que cambiar el tipo de valor de
+    `DEFAULT_EXCEPTION_STATUS_MAP` a ``int | tuple[int, Mapping]``: el mapa es público y
+    hay código que lo lee esperando enteros, así que cambiarlo rompería a quien lo
+    inspecciona o lo extiende.
+
     Uso::
 
         register_exception_handlers(app, mapping={MiNotFound: 404})
+
+        # 401 con el header que la especificación exige
+        def cabeceras(exc: Exception) -> dict[str, str]:
+            if isinstance(exc, TokenInvalido):
+                return {"WWW-Authenticate": 'Bearer error="invalid_token"'}
+            return {}
+
+        register_exception_handlers(app, mapping={TokenInvalido: 401}, headers_for=cabeceras)
     """
     resolved = {**DEFAULT_EXCEPTION_STATUS_MAP, **(mapping or {})}
 
@@ -74,7 +94,7 @@ def register_exception_handlers(
     for exc_type in sorted(resolved, key=_specificity, reverse=True):
         app.add_exception_handler(
             exc_type,
-            _build_handler(exc_type, resolved[exc_type], include_detail),
+            _build_handler(exc_type, resolved[exc_type], include_detail, headers_for),
         )
 
 
@@ -87,6 +107,7 @@ def _build_handler(
     exc_type: type[Exception],
     status_code: int,
     include_detail: bool | DetailFactory,
+    headers_for: HeadersFactory | None = None,
 ) -> t.Callable[[Request, Exception], t.Awaitable[JSONResponse]]:
     async def handler(request: Request, exc: Exception) -> JSONResponse:
         if status_code >= 500:
@@ -107,12 +128,27 @@ def _build_handler(
                 exc,
             )
 
+        headers: dict[str, str] | None = None
+        if headers_for is not None:
+            # Un `headers_for` que explota no puede convertir un 401 prolijo en un 500:
+            # el header es accesorio y la respuesta ya está decidida.
+            try:
+                extra = headers_for(exc)
+            except Exception:
+                logger.exception(
+                    "headers_for falló para %s; se responde sin headers extra.",
+                    type(exc).__name__,
+                )
+            else:
+                headers = {str(k): str(v) for k, v in dict(extra).items()} or None
+
         return JSONResponse(
             status_code=status_code,
             content={
                 "detail": _detail_for(exc, status_code, include_detail),
                 "error": type(exc).__name__,
             },
+            headers=headers,
         )
 
     handler.__name__ = f"handle_{exc_type.__name__}"

hexcore-7.0.0/hexcore/infrastructure/api/rate_limit.py

@@ -0,0 +1,310 @@
+"""
+Rate limiting como dependencia de FastAPI.
+
+Se apoya en el puerto `ICache`, no en Redis directamente, para que funcione con
+`MemoryCache` en los tests sin levantar nada.
+
+La ventana lleva su propio vencimiento dentro del valor cacheado (`reset_at`) en vez de
+depender del TTL del backend: `MemoryCache` ignora el parámetro `expire`, y un rate
+limiter que sólo funciona contra Redis no se puede testear.
+"""
+from __future__ import annotations
+
+import ipaddress
+import logging
+import time
+import typing as t
+
+from fastapi import HTTPException, Request
+
+from hexcore.infrastructure.cache import ICache, SupportsAtomicWindow
+
+logger = logging.getLogger("hexcore.api.rate_limit")
+
+__all__ = [
+    "rate_limit",
+    "RateLimitBackendPolicy",
+    "client_ip_key",
+    "forwarded_ip_key",
+]
+
+RateLimitBackendPolicy = t.Literal["allow", "deny"]
+
+KeyFunc = t.Callable[[Request], str]
+
+
+def client_ip_key(request: Request) -> str:
+    """
+    Clave por IP del par TCP. **No** mira `X-Forwarded-For`.
+
+    Antes sí lo miraba, sin condiciones, y eso hacía que el límite no limitara nada:
+    `X-Forwarded-For` lo escribe el cliente, así que mandar un valor distinto en cada
+    petición daba un bucket nuevo en cada petición. Contra un endpoint de login, un
+    límite de 5 intentos se volvía infinito con una línea de código.
+
+    Si estás detrás de un proxy o un balanceador, `request.client.host` es la IP del
+    proxy y esto limita a todo el mundo junto — que es el lado **seguro** del error, pero
+    no el que querés. Para ese caso usá `forwarded_ip_key()`, que exige declarar en quién
+    confiás.
+
+    Uso::
+
+        # sin proxy
+        rate_limit(5, 300, key=client_ip_key)
+
+        # detrás de un balanceador
+        rate_limit(5, 300, key=forwarded_ip_key(trusted_proxies=["10.0.0.0/8"]))
+    """
+    client = request.client
+    return client.host if client else "unknown"
+
+
+def forwarded_ip_key(
+    *,
+    trusted_proxies: t.Collection[str],
+    trust_hops: int = 1,
+) -> KeyFunc:
+    """
+    Clave por IP real del cliente, leyendo `X-Forwarded-For` **sólo de proxies declarados**.
+
+    El header sólo se honra si el par TCP inmediato está en `trusted_proxies`. Si no lo
+    está, se cae a la IP del par y se ignora lo que haya mandado: alguien que llega
+    directo a la app no puede elegir su propio bucket.
+
+    Args:
+        trusted_proxies: IPs o redes CIDR de tus proxies (``["10.0.0.0/8", "172.18.0.5"]``).
+            No puede estar vacío: un allowlist vacío significaría "no confío en nadie", y
+            para eso ya está `client_ip_key`.
+        trust_hops: Cuántos proxies tenés adelante. Cada proxy **agrega** la IP de quien le
+            habló, así que con un balanceador el cliente es el último elemento del header,
+            con dos es el penúltimo, y así. Se cuenta desde la derecha, que es la única
+            parte del header que no controla el cliente: los elementos de la izquierda los
+            puede inventar.
+
+    Raises:
+        ValueError: Si `trusted_proxies` está vacío, si alguna entrada no es una IP/red
+            válida, o si `trust_hops < 1`.
+
+    Uso::
+
+        # un ALB delante
+        key = forwarded_ip_key(trusted_proxies=["10.0.0.0/8"])
+
+        # CDN -> balanceador -> app
+        key = forwarded_ip_key(trusted_proxies=["10.0.0.0/8"], trust_hops=2)
+    """
+    if trust_hops < 1:
+        raise ValueError(
+            "forwarded_ip_key(trust_hops=...) tiene que ser >= 1. Si no tenés ningún "
+            "proxy adelante, usá `client_ip_key` en vez de esta función."
+        )
+    if not trusted_proxies:
+        raise ValueError(
+            "forwarded_ip_key(trusted_proxies=...) no puede estar vacío: sin proxies de "
+            "confianza, `X-Forwarded-For` lo controla el cliente y el límite no limita "
+            "nada. Si no tenés proxy, usá `client_ip_key`."
+        )
+
+    networks: list[ipaddress.IPv4Network | ipaddress.IPv6Network] = []
+    for entry in trusted_proxies:
+        try:
+            networks.append(ipaddress.ip_network(entry, strict=False))
+        except ValueError as exc:
+            raise ValueError(
+                f"forwarded_ip_key(trusted_proxies=...): {entry!r} no es una IP ni una red "
+                f"CIDR válida. Ejemplos válidos: '10.0.0.0/8', '172.18.0.5'."
+            ) from exc
+
+    def key_func(request: Request) -> str:
+        client = request.client
+        peer = client.host if client else None
+        if peer is None or not _ip_in_any(peer, networks):
+            # El par no es un proxy declarado: su header no vale nada.
+            return peer or "unknown"
+
+        forwarded = request.headers.get("X-Forwarded-For")
+        if not forwarded:
+            return peer
+
+        hops = [item.strip() for item in forwarded.split(",") if item.strip()]
+        if len(hops) < trust_hops:
+            # Menos saltos de los declarados: el header está incompleto o alguien lo
+            # recortó. Se cae al par en vez de agarrar la entrada más a la izquierda,
+            # que es justo la que el cliente puede inventar.
+            return peer
+
+        candidate = hops[-trust_hops]
+        try:
+            ipaddress.ip_address(candidate)
+        except ValueError:
+            return peer
+        return candidate
+
+    return key_func
+
+
+def _ip_in_any(
+    address: str,
+    networks: t.Sequence[ipaddress.IPv4Network | ipaddress.IPv6Network],
+) -> bool:
+    try:
+        parsed = ipaddress.ip_address(address)
+    except ValueError:
+        return False
+    return any(parsed in network for network in networks)
+
+
+def rate_limit(
+    limit: int,
+    window_seconds: int = 60,
+    *,
+    key: KeyFunc | None = None,
+    cache: ICache | None = None,
+    on_backend_error: RateLimitBackendPolicy = "allow",
+    namespace: str = "hexcore:ratelimit",
+) -> t.Callable[..., t.Awaitable[None]]:
+    """
+    Construye una dependencia que limita las peticiones por clave.
+
+    Args:
+        limit: Peticiones permitidas por ventana.
+        window_seconds: Duración de la ventana.
+        key: Cómo derivar la clave del request. Por defecto, la IP del cliente. Para
+            limitar por usuario: ``key=lambda r: r.state.user_id``.
+        cache: El backend. Por defecto, `config.cache_backend`.
+        on_backend_error: Qué hacer si el backend falla. ``"allow"`` (default) deja pasar
+            —un Redis caído no debería tumbar la API—; ``"deny"`` devuelve 429. Es una
+            decisión explícita y configurable, no enterrada en un `except`.
+        namespace: Prefijo de las claves en el cache.
+
+    Returns:
+        Una corutina para usar en ``Depends(...)``.
+
+    Devuelve **429 con `Retry-After`**, que es lo que un cliente bien hecho necesita para
+    reintentar sin adivinar.
+
+    Uso::
+
+        @router.get("/reports", dependencies=[Depends(rate_limit(10, 60))])
+        async def reports(): ...
+
+        por_usuario = rate_limit(100, 3600, key=lambda r: r.state.user_id)
+    """
+    if limit < 1:
+        raise ValueError("rate_limit(limit=...) tiene que ser >= 1")
+    if window_seconds < 1:
+        raise ValueError("rate_limit(window_seconds=...) tiene que ser >= 1")
+
+    key_func = key or client_ip_key
+
+    async def dependency(request: Request) -> None:
+        backend = cache or _default_cache()
+        cache_key = f"{namespace}:{key_func(request)}"
+        now = time.time()
+
+        try:
+            if isinstance(backend, SupportsAtomicWindow):
+                # Camino atómico: se incrementa primero y se compara después. Al revés
+                # —leer, comparar, escribir— hay un `await` entre la lectura y la
+                # escritura, así que N peticiones concurrentes leen el mismo contador y
+                # pasan todas.
+                count, reset_at = await backend.incr_window(cache_key, window_seconds)
+                excedido = count > limit
+            else:
+                _warn_backend_sin_atomicidad(backend)
+                state = await backend.get(cache_key)
+                count, reset_at = _read_window(state, now, window_seconds)
+                excedido = count >= limit
+                if not excedido:
+                    result = backend.set(
+                        cache_key,
+                        {"count": count + 1, "reset_at": reset_at},
+                        expire=window_seconds,
+                    )
+                    if _is_awaitable(result):
+                        await result
+
+            if excedido:
+                retry_after = max(1, int(reset_at - now) + 1)
+                raise HTTPException(
+                    status_code=429,
+                    detail=(
+                        f"Límite de {limit} peticiones cada {window_seconds}s alcanzado."
+                    ),
+                    headers={"Retry-After": str(retry_after)},
+                )
+        except HTTPException:
+            raise
+        except Exception as exc:
+            if on_backend_error == "deny":
+                logger.critical(
+                    "El backend de rate limiting falló (%s) y on_backend_error='deny': "
+                    "se rechaza la petición.",
+                    exc,
+                )
+                raise HTTPException(
+                    status_code=429,
+                    detail="Rate limiting no disponible.",
+                    headers={"Retry-After": str(window_seconds)},
+                ) from exc
+            logger.error(
+                "El backend de rate limiting falló (%s) y on_backend_error='allow': "
+                "se deja pasar la petición sin limitar.",
+                exc,
+            )
+
+    return dependency
+
+
+def _read_window(
+    state: t.Any,
+    now: float,
+    window_seconds: int,
+) -> tuple[int, float]:
+    """
+    Lee el contador de la ventana en curso.
+
+    Si no hay estado, o si la ventana ya venció, empieza una nueva. El vencimiento se
+    evalúa aquí y no se delega al TTL del backend, porque no todos los backends de
+    `ICache` lo respetan.
+    """
+    if isinstance(state, dict):
+        reset_at = state.get("reset_at")
+        count = state.get("count")
+        if isinstance(reset_at, (int, float)) and isinstance(count, int):
+            if reset_at > now:
+                return count, float(reset_at)
+
+    return 0, now + window_seconds
+
+
+def _is_awaitable(value: t.Any) -> bool:
+    return hasattr(value, "__await__")
+
+
+_BACKENDS_AVISADOS: set[int] = set()
+
+
+def _warn_backend_sin_atomicidad(backend: ICache) -> None:
+    """
+    Avisa una sola vez por backend que el conteo no es atómico.
+
+    Una vez y no por petición: un log por request en el camino caliente es peor que el
+    problema que denuncia. `id()` alcanza porque el backend es un singleton de proceso.
+    """
+    marca = id(backend)
+    if marca in _BACKENDS_AVISADOS:
+        return
+    _BACKENDS_AVISADOS.add(marca)
+    logger.warning(
+        "%s no implementa `incr_window`, así que el conteo del rate limit hace "
+        "read-modify-write y un pico de peticiones concurrentes puede pasarse del "
+        "límite. Implementá `SupportsAtomicWindow` en tu backend, o usá `RedisCache`.",
+        type(backend).__name__,
+    )
+
+
+def _default_cache() -> ICache:
+    from hexcore.config import LazyConfig
+
+    return LazyConfig.get_config().cache_backend

hexcore-7.0.0/hexcore/infrastructure/cache/__init__.py

@@ -0,0 +1,51 @@
+import typing as t
+import abc
+
+__all__ = ["ICache", "SupportsAtomicWindow"]
+
+
+class ICache(abc.ABC):
+    @abc.abstractmethod
+    async def get(self, key: str) -> t.Optional[t.Any]:
+        pass
+
+    @abc.abstractmethod
+    def set(self, key: str, value: t.Any, expire: int = 3600) -> t.Any:
+        pass
+
+    @abc.abstractmethod
+    def delete(self, key: str) -> t.Union[t.Any, None]:
+        pass
+
+
+@t.runtime_checkable
+class SupportsAtomicWindow(t.Protocol):
+    """
+    Capacidad opcional de un backend de cache: contar una ventana **atómicamente**.
+
+    Existe como Protocol aparte y no como método de `ICache` porque agregar un
+    `@abc.abstractmethod` al puerto rompería a todo el que ya tenga un backend propio.
+    Quien la implementa, la ofrece; quien no, sigue funcionando.
+
+    Por qué hace falta: un contador hecho con `get()` y después `set()` tiene un
+    read-modify-write con un `await` en el medio, así que N peticiones concurrentes leen
+    todas el mismo valor y pasan todas. Contra un endpoint de login eso convierte el
+    límite en un techo blando: con `limit=5` y 50 peticiones simultáneas pasan bastante
+    más de 5. `rate_limit` usa esta capacidad si el backend la tiene y avisa por log
+    cuando no.
+
+    Uso::
+
+        class MiCache(ICache):
+            async def incr_window(self, key: str, window_seconds: int) -> tuple[int, float]:
+                ...  # devolvé (contador_ya_incrementado, timestamp_de_reset)
+    """
+
+    async def incr_window(self, key: str, window_seconds: int) -> tuple[int, float]:
+        """
+        Incrementa el contador de `key` y devuelve `(contador, reset_at)`.
+
+        `reset_at` es un timestamp absoluto (epoch en segundos). La primera llamada de una
+        ventana devuelve `1`, y es la que fija el vencimiento.
+        """
+        ...

hexcore-7.0.0/hexcore/infrastructure/cache/cache_backends/memory.py

@@ -0,0 +1,58 @@
+import time
+import typing as t
+from hexcore.infrastructure.cache import ICache
+
+
+class MemoryCache(ICache):
+    def __init__(self):
+        self.cache: t.Dict[str, t.Dict[str, t.Any]] = {}
+
+    async def incr_window(self, key: str, window_seconds: int) -> tuple[int, float]:
+        """
+        Contador de ventana atómico (`SupportsAtomicWindow`).
+
+        Atómico porque entre la lectura y la escritura **no hay ningún `await`**: dentro
+        de un event loop, esta corutina no cede el control en el medio, así que dos
+        peticiones concurrentes no pueden leer el mismo contador. Es exactamente la
+        garantía que el par `get()`/`set()` no puede dar.
+
+        No sirve entre procesos, y no pretende: para varios workers hace falta un backend
+        compartido (`RedisCache`).
+
+        El vencimiento se guarda **dentro del valor** porque `set()` acá ignora `expire` y
+        nunca desaloja; si el TTL fuera del backend, la ventana no vencería jamás.
+        """
+        now = time.time()
+        state = self.cache.get(key)
+
+        reset_at = None
+        if isinstance(state, dict):
+            candidate = state.get("reset_at")
+            if isinstance(candidate, (int, float)) and candidate > now:
+                reset_at = float(candidate)
+
+        if reset_at is None:
+            count, reset_at = 1, now + window_seconds
+        else:
+            previous = state.get("count") if isinstance(state, dict) else 0
+            count = (previous if isinstance(previous, int) else 0) + 1
+
+        self.cache[key] = {"count": count, "reset_at": reset_at}
+        return count, reset_at
+
+    async def get(self, key: str) -> t.Optional[t.Dict[str, t.Any]]:
+        return self.cache.get(key)
+
+    async def set(
+        self,
+        key: str,
+        value: t.Dict[str, t.Any],
+        expire: int = 0,
+    ) -> None:
+        self.cache[key] = value
+
+    async def delete(self, key: str) -> None:
+        self.cache.pop(key, None)
+
+    async def clear(self) -> None:
+        self.cache.clear()