fastapi-cachex 0.3.0__tar.gz → 0.3.1__tar.gz

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.3.0
+Version: 0.3.1
 Summary: A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends.
 Keywords: fastapi,cache,etag,cache-control,redis,memcached,in-memory
 Author: allen0099
@@ -25,6 +25,7 @@ Requires-Dist: pyjwt>=2.9.0 ; extra == 'jwt'
 Requires-Dist: pymemcache ; extra == 'memcache'
 Requires-Dist: redis[hiredis]>=5.3.0 ; extra == 'redis'
 Requires-Dist: orjson ; extra == 'redis'
+Requires-Dist: itsdangerous ; extra == 'starlette'
 Requires-Python: >=3.10
 Project-URL: Homepage, https://github.com/allen0099/FastAPI-CacheX
 Project-URL: Repository, https://github.com/allen0099/FastAPI-CacheX.git
@@ -32,6 +33,7 @@ Project-URL: Issues, https://github.com/allen0099/FastAPI-CacheX/issues
 Provides-Extra: jwt
 Provides-Extra: memcache
 Provides-Extra: redis
+Provides-Extra: starlette
 Description-Content-Type: text/markdown
 
 # FastAPI-Cache X

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/fastapi_cachex/__init__.py

@@ -4,6 +4,7 @@ import logging
 
 from .cache import cache as cache
 from .cache import default_key_builder as default_key_builder
+from .cache import invalidate as invalidate
 from .dependencies import AppCache as AppCache
 from .dependencies import CacheBackend as CacheBackend
 from .dependencies import get_app_cache as get_app_cache
@@ -12,6 +13,7 @@ from .manager import CacheManager as CacheManager
 from .manager_proxy import CacheManagerProxy as CacheManagerProxy
 from .proxy import BackendProxy as BackendProxy
 from .routes import add_routes as add_routes
+from .session import FastAPICacheXSessionMiddleware as FastAPICacheXSessionMiddleware
 from .session import Session as Session
 from .session import SessionConfig as SessionConfig
 from .session import SessionManager as SessionManager
@@ -34,6 +36,9 @@ from .state import StateDataError as StateDataError
 from .state import StateError as StateError
 from .state import StateExpiredError as StateExpiredError
 from .state import StateManager as StateManager
+from .state import StateManagerDep as StateManagerDep
+from .state import StateManagerProxy as StateManagerProxy
+from .state import get_state_manager as get_state_manager
 from .types import CacheKeyBuilder as CacheKeyBuilder
 
 _package_logger = logging.getLogger("fastapi_cachex")
@@ -48,6 +53,7 @@ __all__ = [
     "CacheKeyBuilder",
     "CacheManager",
     "CacheManagerProxy",
+    "FastAPICacheXSessionMiddleware",
     "InvalidStateError",
     "Session",
     "SessionConfig",
@@ -66,6 +72,8 @@ __all__ = [
     "StateError",
     "StateExpiredError",
     "StateManager",
+    "StateManagerDep",
+    "StateManagerProxy",
     "add_routes",
     "cache",
     "default_key_builder",
@@ -74,5 +82,7 @@ __all__ = [
     "get_optional_session",
     "get_session",
     "get_session_manager",
+    "get_state_manager",
+    "invalidate",
     "require_session",
 ]

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/fastapi_cachex/backends/memcached.py

@@ -177,7 +177,9 @@ class MemcachedBackend(BaseCacheBackend):
         # Try to delete the prefixed key (exact match only)
         prefixed_key = self._make_key(path)
         try:
-            result = await asyncio.to_thread(self.client.delete, prefixed_key, False)
+            result = await asyncio.to_thread(
+                self.client.delete, prefixed_key, noreply=False
+            )
         except Exception:  # noqa: BLE001
             return 0
         else:

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/fastapi_cachex/backends/memory.py

@@ -183,6 +183,11 @@ class MemoryBackend(BaseCacheBackend):
                     if fnmatch.fnmatch(cache_path, pattern):
                         keys_to_delete.append(key)
                         cleared_count += 1
+                elif fnmatch.fnmatch(key, pattern):
+                    # Non-HTTP-cache key (no separators, e.g. CacheManager/
+                    # StateManager keys) - match against the raw key.
+                    keys_to_delete.append(key)
+                    cleared_count += 1
 
             for key in keys_to_delete:
                 del self.cache[key]

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/fastapi_cachex/cache.py

@@ -61,6 +61,44 @@ def default_key_builder(request: Request) -> str:
     return key
 
 
+async def invalidate(
+    request: Request,
+    key_builder: CacheKeyBuilder | None = None,
+) -> bool:
+    """Invalidate the cache entry a ``@cache``-decorated route would use.
+
+    Builds the same cache key the ``@cache`` decorator would build for
+    ``request`` (via ``key_builder`` or ``default_key_builder``) and deletes
+    it from the configured backend. Use this after a mutation to bust the
+    cache for a specific cached route response.
+
+    Args:
+        request: The request whose cache key should be invalidated. Typically
+            a request to the same route/method as the cached one (e.g. build
+            it via ``request.app.url_path_for(...)`` for a GET route).
+        key_builder: Custom key builder used by the target route's ``@cache``
+            decorator, if any. If None, uses ``default_key_builder``.
+
+    Returns:
+        True if a cache entry existed and was deleted, False otherwise.
+    """
+    builder = key_builder or default_key_builder
+    cache_key = builder(request)
+
+    try:
+        cache_backend = BackendProxy.get()
+    except BackendNotFoundError:
+        return False
+
+    existing = await cache_backend.get(cache_key)
+    if existing is None:
+        return False
+
+    await cache_backend.delete(cache_key)
+    logger.debug("Cache INVALIDATE; key=%s", cache_key)
+    return True
+
+
 class CacheControl:
     """Manages Cache-Control header directives."""
 
@@ -282,9 +320,7 @@ def cache(
                         # StreamingResponse/FileResponse — cannot compute ETag; serve as-is
                         current_response.headers["Cache-Control"] = cache_control
                         return current_response
-                    current_etag = (
-                        f'W/"{hashlib.md5(current_body).hexdigest()}"'  # noqa: S324
-                    )
+                    current_etag = f'W/"{hashlib.md5(current_body).hexdigest()}"'  # noqa: S324
 
                     if client_etag == current_etag:
                         # For no-cache, compare fresh data with client's ETag
@@ -343,7 +379,9 @@ def cache(
 
             # Update cache if needed
             if not cached_data or cached_data.fingerprint != current_etag:
-                assert current_body is not None  # guaranteed by early-return guards above
+                assert (
+                    current_body is not None
+                )  # guaranteed by early-return guards above
                 # Store in cache if data changed
                 await cache_backend.set(
                     cache_key,

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/fastapi_cachex/manager.py

@@ -1,8 +1,11 @@
 """Generic application-level cache manager for FastAPI-CacheX."""
 
 import hashlib
+import inspect
 import json
 import logging
+from collections.abc import Awaitable
+from collections.abc import Callable
 from typing import Any
 
 from .backends.base import BaseCacheBackend
@@ -117,6 +120,67 @@ class CacheManager:
         """
         return await self.backend.get(self._cache_key(key)) is not None
 
+    async def get_or_set(
+        self,
+        key: str,
+        factory: Callable[[], Any] | Callable[[], Awaitable[Any]],
+        ttl: int | None = None,
+    ) -> Any:
+        """Get a cached value, computing and storing it via ``factory`` on a miss.
+
+        ``factory`` is only invoked when ``key`` is missing, expired, or its
+        stored content cannot be decoded; on a hit the cached value is
+        returned directly. This method does not provide stampede protection:
+        concurrent misses for the same key may each invoke ``factory``.
+
+        Args:
+            key: Logical cache key (without the manager's prefix).
+            factory: Zero-argument callable (sync or async) that produces the
+                JSON-serializable value to cache on a miss.
+            ttl: Time-to-live in seconds for a newly created value. If None,
+                uses ``self.default_ttl``.
+
+        Returns:
+            The cached value (existing or newly created).
+
+        Raises:
+            TypeError: If the value produced by ``factory`` is not JSON-serializable.
+        """
+        sentinel = object()
+        cached = await self.get(key, default=sentinel)
+        if cached is not sentinel:
+            return cached
+
+        if inspect.iscoroutinefunction(factory):
+            value = await factory()
+        else:
+            value = factory()
+
+        await self.set(key, value, ttl=ttl)
+        return value
+
+    async def clear_pattern(self, pattern: str) -> int:
+        """Clear all keys under this manager's namespace matching a glob pattern.
+
+        Delegates to the backend's native ``clear_pattern`` (e.g. Redis ``SCAN``),
+        which can be more efficient than ``clear_prefix``'s full key-space scan.
+        Note that backends without key-enumeration support (e.g. Memcached)
+        cannot honor this and will return 0 with a ``RuntimeWarning``.
+
+        Args:
+            pattern: Glob pattern (relative to ``self.key_prefix``) to match
+                against, e.g. ``"user:*"``.
+
+        Returns:
+            Number of cache entries cleared.
+        """
+        match_pattern = self._cache_key(pattern)
+        cleared = await self.backend.clear_pattern(match_pattern)
+        logger.debug(
+            "Cache CLEAR_PATTERN; pattern=%s removed=%s", match_pattern, cleared
+        )
+        return cleared
+
     async def clear_prefix(self, prefix: str | None = None) -> int:
         """Clear all keys under this manager's namespace matching a sub-prefix.
 

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/fastapi_cachex/routes.py

@@ -129,7 +129,9 @@ async def _get_cached_hits_handler(backend: BaseCacheBackend) -> CacheHitsRespon
         if method:  # Valid cache key
             # Check if cache entry is expired
             is_expired = expiry is not None and expiry <= now
-            ttl_remaining = max(0.0, round(expiry - now, 2)) if expiry is not None else None
+            ttl_remaining = (
+                max(0.0, round(expiry - now, 2)) if expiry is not None else None
+            )
 
             cached_hits.append(
                 CacheHitRecord(
@@ -188,7 +190,9 @@ async def _get_cached_records_handler(
             content = entry.content
             content_size = len(content) if isinstance(content, (bytes, str)) else 0
 
-            ttl_remaining = max(0.0, round(expiry - now, 2)) if expiry is not None else None
+            ttl_remaining = (
+                max(0.0, round(expiry - now, 2)) if expiry is not None else None
+            )
 
             content_preview = (
                 content[:100].decode("utf-8", errors="ignore")

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/fastapi_cachex/session/__init__.py

@@ -6,12 +6,14 @@ from .dependencies import get_session
 from .dependencies import get_session_manager
 from .dependencies import require_session
 from .manager import SessionManager
+from .middleware import FastAPICacheXSessionMiddleware
 from .middleware import SessionMiddleware
 from .models import Session
 from .models import SessionUser
 from .proxy import SessionManagerProxy
 
 __all__ = [
+    "FastAPICacheXSessionMiddleware",
     "Session",
     "SessionConfig",
     "SessionManager",

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/fastapi_cachex/session/config.py

@@ -3,13 +3,18 @@
 from typing import Literal
 
 from pydantic import BaseModel
+from pydantic import ConfigDict
 from pydantic import Field
 from pydantic import SecretStr
 
+SameSitePolicy = Literal["lax", "strict", "none"]
+
 
 class SessionConfig(BaseModel):
     """Session configuration settings."""
 
+    model_config = ConfigDict(extra="forbid")
+
     # Session lifetime
     session_ttl: int = Field(
         default=3600,
@@ -87,3 +92,33 @@ class SessionConfig(BaseModel):
         default="session:",
         description="Prefix for session keys in backend storage",
     )
+
+    # Cookie settings (FastAPICacheXSessionMiddleware only)
+    cookie_name: str = Field(
+        default="session",
+        description="Name of the cookie used to store the session token "
+        "(FastAPICacheXSessionMiddleware only)",
+    )
+    cookie_max_age: int | None = Field(
+        default=14 * 24 * 60 * 60,
+        description="Max-Age (seconds) for the session cookie; None disables "
+        "Max-Age/Expires (session cookie deleted when browser closes)",
+    )
+    cookie_path: str = Field(
+        default="/",
+        description="Path attribute for the session cookie",
+    )
+    cookie_same_site: SameSitePolicy = Field(
+        default="lax",
+        description="SameSite attribute for the session cookie",
+    )
+    cookie_https_only: bool = Field(
+        default=False,
+        description="Whether to set the Secure flag on the session cookie "
+        "(cookie only sent over HTTPS)",
+    )
+    cookie_domain: str | None = Field(
+        default=None,
+        description="Domain attribute for the session cookie; None omits the "
+        "Domain attribute",
+    )

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/fastapi_cachex/session/manager.py

@@ -76,7 +76,7 @@ class SessionManager:
         user: SessionUser,
         ip_address: str | None = None,
         user_agent: str | None = None,
-        **extra_data: dict[str, object],
+        **extra_data: object,
     ) -> tuple[Session, str]:
         """Create a new session for an authenticated user.
 
@@ -100,7 +100,7 @@ class SessionManager:
         self,
         ip_address: str | None = None,
         user_agent: str | None = None,
-        **extra_data: dict[str, object],
+        **extra_data: object,
     ) -> tuple[Session, str]:
         """Create a new session without user information."""
         return await self._create_session(
@@ -115,7 +115,7 @@ class SessionManager:
         user: SessionUser | None,
         ip_address: str | None = None,
         user_agent: str | None = None,
-        **extra_data: dict[str, object],
+        **extra_data: object,
     ) -> tuple[Session, str]:
         """Internal helper to create and persist a session."""
         session = Session(
@@ -449,7 +449,9 @@ class SessionManager:
             ttl = max(ttl, 1)  # Ensure at least 1 second
 
         fingerprint = self.security.hash_data(value.decode("utf-8"))
-        await self.backend.set(key, CacheEntry(fingerprint=fingerprint, content=value), ttl=ttl)
+        await self.backend.set(
+            key, CacheEntry(fingerprint=fingerprint, content=value), ttl=ttl
+        )
         logger.debug("Session saved; id=%s ttl=%s", session.session_id, ttl)
 
     async def _load_session(self, session_id: str) -> Session | None:

fastapi_cachex-0.3.1/fastapi_cachex/session/middleware.py

@@ -0,0 +1,485 @@
+"""Session middleware for FastAPI."""
+
+import logging
+import warnings
+from typing import TYPE_CHECKING
+from typing import Any
+
+from fastapi import Request
+from fastapi import Response
+from starlette.datastructures import MutableHeaders
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.middleware.base import RequestResponseEndpoint
+from starlette.requests import HTTPConnection
+from starlette.types import ASGIApp
+from starlette.types import Message
+from starlette.types import Receive
+from starlette.types import Scope
+from starlette.types import Send
+
+from .config import SessionConfig
+from .exceptions import SessionError
+from .manager import SessionManager
+from .proxy import SessionManagerProxy
+
+if TYPE_CHECKING:
+    # starlette.middleware.sessions unconditionally imports itsdangerous, an
+    # optional dependency (fastapi-cachex[starlette]) only needed at runtime by
+    # FastAPICacheXSessionMiddleware; import it lazily there instead (see its
+    # __init__) so the rest of this module doesn't require it.
+    from starlette.middleware.sessions import Session as StarletteSession
+
+    from .models import Session
+
+logger = logging.getLogger(__name__)
+
+
+def _get_client_ip(connection: HTTPConnection) -> str | None:
+    """Get client IP address from an HTTP connection.
+
+    Args:
+        connection: Incoming HTTP connection (or a `Request`, which IS-A
+            `HTTPConnection`)
+
+    Returns:
+        Client IP address or None
+    """
+    # Check X-Forwarded-For header (for proxied requests)
+    forwarded_for = connection.headers.get("x-forwarded-for")
+    if forwarded_for:
+        # Get first IP from comma-separated list
+        ip = forwarded_for.split(",")[0].strip()
+        logger.debug("Client IP from X-Forwarded-For: %s", ip)
+        return ip
+
+    # Check X-Real-IP header
+    real_ip = connection.headers.get("x-real-ip")
+    if real_ip:
+        logger.debug("Client IP from X-Real-IP: %s", real_ip)
+        return real_ip
+
+    # Fallback to direct client IP
+    if connection.client:
+        logger.debug("Client IP from connection: %s", connection.client.host)
+        return connection.client.host
+
+    return None
+
+
+def _extract_header_token(
+    connection: HTTPConnection, config: SessionConfig
+) -> str | None:
+    """Extract a session token from request headers.
+
+    Honours ``SessionConfig.token_source_priority``: checks the configured
+    custom header (``config.header_name``) and/or an ``Authorization: Bearer``
+    token. This is the header/bearer transport shared with ``SessionMiddleware``.
+
+    Args:
+        connection: Incoming HTTP connection (or a `Request`, which IS-A
+            `HTTPConnection`)
+        config: Session configuration
+
+    Returns:
+        Session token or None
+    """
+    for source in config.token_source_priority:
+        if source == "header":
+            token = connection.headers.get(config.header_name)
+            if token:
+                logger.debug("Token extracted from header")
+                return token
+
+        elif source == "bearer":
+            if config.use_bearer_token:
+                auth_header = connection.headers.get("authorization")
+                if auth_header and auth_header.startswith("Bearer "):
+                    bearer_prefix_len = 7
+                    token_value = auth_header[bearer_prefix_len:]
+                    logger.debug("Token extracted from bearer auth")
+                    return token_value
+
+    return None
+
+
+def _stash_session_manager(app: Any, manager: SessionManager) -> None:
+    """Register the session manager on ``app.state`` for dependency injection.
+
+    Stored under a private key on the first request only; ``get_session_manager``
+    reads it back.
+
+    Args:
+        app: The Starlette application (``scope["app"]`` / ``request.app``)
+        manager: Session manager to register
+    """
+    if not hasattr(app.state, "__fastapi_cachex_session_manager"):
+        setattr(app.state, "__fastapi_cachex_session_manager", manager)
+
+
+class SessionMiddleware(BaseHTTPMiddleware):
+    """Middleware to handle session loading and token extraction.
+
+    Extracts the session token from the request (via a custom header and/or
+    an ``Authorization: Bearer`` header, per ``SessionConfig.token_source_priority``)
+    and loads the corresponding session into ``request.state``. Cookie-based
+    token transport is not currently supported.
+
+    .. deprecated:: 0.3.1
+        Use :class:`FastAPICacheXSessionMiddleware` instead. Will be removed in
+        version 0.3.5.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        session_manager: SessionManager | None = None,
+        config: SessionConfig | None = None,
+    ) -> None:
+        """Initialize session middleware.
+
+        Args:
+            app: ASGI application
+            session_manager: Session manager instance
+            config: Session configuration
+        """
+        warnings.warn(
+            "SessionMiddleware is deprecated, use FastAPICacheXSessionMiddleware. "
+            "Will be removed in version 0.3.5.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(app)
+        self.session_manager = session_manager or SessionManagerProxy.get()
+
+        if config is None:
+            config = self.session_manager.config
+
+        self.config = config
+
+        logger.debug(
+            "SessionMiddleware initialized; header=%s bearer=%s",
+            config.header_name,
+            config.use_bearer_token,
+        )
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: RequestResponseEndpoint,
+    ) -> Response:
+        """Process request and handle session.
+
+        Args:
+            request: Incoming request
+            call_next: Next handler in chain
+
+        Returns:
+            Response
+        """
+        # Store session manager in app state for dependency injection (first request only)
+        # This allows developers to use get_session_manager() dependency
+        if not hasattr(request.app.state, "__fastapi_cachex_session_manager"):
+            setattr(
+                request.app.state,
+                "__fastapi_cachex_session_manager",
+                self.session_manager,
+            )
+
+        # Extract session token from request
+        token = self._extract_token(request)
+
+        # Try to load session
+        session: Session | None = None
+        renewed_token: str | None = None
+        if token:
+            try:
+                ip_address = self._get_client_ip(request)
+                user_agent = request.headers.get("user-agent")
+                session, renewed_token = await self.session_manager.get_session(
+                    token,
+                    ip_address=ip_address,
+                    user_agent=user_agent,
+                )
+                logger.debug("Session loaded in middleware; id=%s", session.session_id)
+            except SessionError:
+                # Session invalid/expired, continue without session
+                session = None
+                logger.debug("Session failed to load; token invalid/expired")
+
+        # Store session in request state
+        setattr(request.state, "__fastapi_cachex_session", session)
+
+        # Process request
+        response: Response = await call_next(request)
+
+        # Propagate renewed token to client so its JWT exp stays in sync
+        if renewed_token is not None:
+            response.headers[self.config.header_name] = renewed_token
+
+        return response
+
+    def _extract_token(self, request: Request) -> str | None:
+        """Extract session token from request.
+
+        Args:
+            request: Incoming request
+
+        Returns:
+            Session token or None
+        """
+        return _extract_header_token(request, self.config)
+
+    def _get_client_ip(self, request: Request) -> str | None:
+        """Get client IP address from request.
+
+        Args:
+            request: Incoming request
+
+        Returns:
+            Client IP address or None
+        """
+        return _get_client_ip(request)
+
+
+class FastAPICacheXSessionMiddleware:
+    """Drop-in-compatible replacement for Starlette's ``SessionMiddleware``.
+
+    Provides the same ``request.session`` / ``scope["session"]`` dict-like
+    interface as ``starlette.middleware.sessions.SessionMiddleware``, but the
+    session payload is persisted via the configured ``SessionManager``/cache
+    backend instead of being encoded into the cookie itself. Only a signed
+    session token is stored client-side, in the cookie named by
+    ``SessionConfig.cookie_name``.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        session_manager: SessionManager | None = None,
+        config: SessionConfig | None = None,
+    ) -> None:
+        """Initialize the Starlette-aligned session middleware.
+
+        Args:
+            app: ASGI application
+            session_manager: Session manager instance
+            config: Session configuration
+        """
+        try:
+            from starlette.middleware.sessions import Session as _StarletteSession
+        except ImportError as e:  # pragma: no cover
+            msg = (
+                "FastAPICacheXSessionMiddleware requires itsdangerous; "
+                "install fastapi-cachex[starlette]"
+            )
+            raise ImportError(msg) from e
+        self._session_cls: type[StarletteSession] = _StarletteSession
+
+        self.app = app
+        self.session_manager = session_manager or SessionManagerProxy.get()
+        self.config = config or self.session_manager.config
+
+        security_flags = f"httponly; samesite={self.config.cookie_same_site}"
+        if self.config.cookie_https_only:
+            security_flags += "; secure"
+        if self.config.cookie_domain is not None:
+            security_flags += f"; domain={self.config.cookie_domain}"
+        self._security_flags = security_flags
+
+        logger.debug(
+            "FastAPICacheXSessionMiddleware initialized; cookie=%s path=%s",
+            self.config.cookie_name,
+            self.config.cookie_path,
+        )
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Load the session for the connection and persist it on response.
+
+        Args:
+            scope: ASGI connection scope
+            receive: ASGI receive callable
+            send: ASGI send callable
+        """
+        if scope["type"] not in ("http", "websocket"):
+            await self.app(scope, receive, send)
+            return
+
+        # Store session manager in app state for dependency injection (first request only)
+        _stash_session_manager(scope["app"], self.session_manager)
+
+        connection = HTTPConnection(scope)
+        initial_session_was_empty = True
+        loaded_token: str | None = None
+        renewed_token: str | None = None
+        backend_session: Session | None = None
+
+        # Resolve the incoming session token: prefer the header/bearer transport
+        # (e.g. X-Session-Token, as used by SessionMiddleware) and fall back to
+        # the session cookie, so header-based clients authenticate here too.
+        # `header_token` is captured so the response is routed by transport: a
+        # header-sourced token is echoed back via the response header, otherwise
+        # via Set-Cookie (see send_wrapper).
+        header_token = _extract_header_token(connection, self.config)
+        token_value = header_token or connection.cookies.get(self.config.cookie_name)
+        if token_value:
+            try:
+                ip_address = _get_client_ip(connection)
+                user_agent = connection.headers.get("user-agent")
+                backend_session, renewed_token = await self.session_manager.get_session(
+                    token_value,
+                    ip_address=ip_address,
+                    user_agent=user_agent,
+                )
+                loaded_token = renewed_token or token_value
+                scope["session"] = self._session_cls(backend_session.data)
+                initial_session_was_empty = not backend_session.data
+            except SessionError:
+                logger.debug(
+                    "FastAPICacheXSessionMiddleware: token invalid/expired; "
+                    "starting empty session",
+                )
+                scope["session"] = self._session_cls()
+        else:
+            scope["session"] = self._session_cls()
+
+        scope.setdefault("state", {})["__fastapi_cachex_session"] = backend_session
+
+        # Route the response by how the token arrived: header-sourced tokens are
+        # echoed back via the response header (no cookies); cookie-sourced (or
+        # brand-new) sessions use Set-Cookie.
+        from_header = header_token is not None
+
+        async def send_wrapper(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                session: StarletteSession = scope["session"]
+                headers = MutableHeaders(scope=message)
+
+                if session.accessed:
+                    headers.add_vary_header("Cookie")
+
+                if session.modified and session:
+                    cookie_token, new_token = await self._write_session(
+                        session,
+                        connection,
+                        backend_session,
+                        loaded_token,
+                        renewed_token,
+                    )
+                    # Header clients only need a genuinely new/renewed token (an
+                    # unchanged one is already held); cookie clients always get a
+                    # refreshed cookie.
+                    token_to_emit = new_token if from_header else cookie_token
+                    if token_to_emit is not None:
+                        self._emit_token(
+                            headers, token_to_emit, from_header=from_header
+                        )
+                elif session.modified and not initial_session_was_empty:
+                    # Cleared -> delete backend session. backend_session is always
+                    # set when initial_session_was_empty is False (both are only set
+                    # together, after a successful get_session() call above).
+                    assert backend_session is not None  # noqa: S101
+                    await self.session_manager.delete_session(
+                        backend_session.session_id
+                    )
+                    if not from_header:
+                        # Cookie transport: expire the cookie. A header-based client
+                        # simply drops its now-dangling token (record is deleted).
+                        headers.append("Set-Cookie", self._build_clear_cookie_header())
+                elif renewed_token is not None:
+                    # Sliding expiration renewed the token even though the dict
+                    # itself was untouched; propagate it via the same transport.
+                    self._emit_token(headers, renewed_token, from_header=from_header)
+
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)
+
+    def _emit_token(
+        self, headers: MutableHeaders, token: str, *, from_header: bool
+    ) -> None:
+        """Send a session token to the client via its transport.
+
+        Args:
+            headers: Mutable response headers to write to
+            token: Session token string to deliver
+            from_header: If True, echo via the configured response header;
+                otherwise (re)set it as a Set-Cookie header.
+        """
+        if from_header:
+            headers.append(self.config.header_name, token)
+        else:
+            headers.append("Set-Cookie", self._build_set_cookie_header(token))
+
+    async def _write_session(
+        self,
+        session: "StarletteSession",
+        connection: HTTPConnection,
+        backend_session: "Session | None",
+        loaded_token: str | None,
+        renewed_token: str | None,
+    ) -> tuple[str, str | None]:
+        """Create-or-update the backend session for a modified, non-empty dict.
+
+        Args:
+            session: The Starlette session dict for this request
+            connection: Incoming HTTP connection (for IP / User-Agent binding)
+            backend_session: Loaded backend session, or None for a new session
+            loaded_token: Token for the loaded session (None when creating anew)
+            renewed_token: Sliding-expiration renewed token, if any
+
+        Returns:
+            ``(cookie_token, new_token)`` where ``cookie_token`` is the token to
+            (re)set as a cookie, and ``new_token`` is a genuinely new/renewed token
+            to hand a header-based client (``None`` when the token is unchanged).
+        """
+        if backend_session is None:
+            (
+                backend_session,
+                loaded_token,
+            ) = await self.session_manager.create_anonymous_session(
+                ip_address=_get_client_ip(connection),
+                user_agent=connection.headers.get("user-agent"),
+            )
+            new_token: str | None = loaded_token
+        else:
+            # backend_session and loaded_token are always set together (after a
+            # successful get_session() call).
+            assert loaded_token is not None  # noqa: S101
+            new_token = renewed_token
+        backend_session.data = dict(session)
+        await self.session_manager.update_session(backend_session)
+        return loaded_token, new_token
+
+    def _build_set_cookie_header(self, token: str) -> str:
+        """Build a `Set-Cookie` header value carrying the session token.
+
+        Args:
+            token: Signed session token string
+
+        Returns:
+            Set-Cookie header value
+        """
+        max_age = (
+            f"Max-Age={self.config.cookie_max_age}; "
+            if self.config.cookie_max_age
+            else ""
+        )
+        return (
+            f"{self.config.cookie_name}={token}; "
+            f"path={self.config.cookie_path}; "
+            f"{max_age}"
+            f"{self._security_flags}"
+        )
+
+    def _build_clear_cookie_header(self) -> str:
+        """Build a `Set-Cookie` header value that expires the session cookie.
+
+        Returns:
+            Set-Cookie header value
+        """
+        return (
+            f"{self.config.cookie_name}=; "
+            f"path={self.config.cookie_path}; "
+            f"expires=Thu, 01 Jan 1970 00:00:00 GMT; "
+            f"{self._security_flags}"
+        )

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/fastapi_cachex/state/__init__.py

@@ -1,8 +1,11 @@
 """State management extension for FastAPI-CacheX."""
 
+from .dependencies import StateManagerDep as StateManagerDep
+from .dependencies import get_state_manager as get_state_manager
 from .exceptions import InvalidStateError as InvalidStateError
 from .exceptions import StateDataError as StateDataError
 from .exceptions import StateError as StateError
 from .exceptions import StateExpiredError as StateExpiredError
 from .manager import StateManager as StateManager
 from .models import StateData as StateData
+from .proxy import StateManagerProxy as StateManagerProxy

fastapi_cachex-0.3.1/fastapi_cachex/state/dependencies.py

@@ -0,0 +1,28 @@
+"""FastAPI dependency injection utilities for state management."""
+
+from typing import Annotated
+
+from fastapi import Depends
+
+from fastapi_cachex.exceptions import BackendNotFoundError
+
+from .manager import StateManager
+from .proxy import StateManagerProxy
+
+
+def get_state_manager() -> StateManager:
+    """Dependency to get the application StateManager instance.
+
+    Lazily creates and registers a default StateManager (backed by
+    BackendProxy) the first time it's requested, unless one was already
+    set via StateManagerProxy.set(...).
+    """
+    try:
+        return StateManagerProxy.get()
+    except BackendNotFoundError:
+        manager = StateManager()
+        StateManagerProxy.set(manager)
+        return manager
+
+
+StateManagerDep = Annotated[StateManager, Depends(get_state_manager)]

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/fastapi_cachex/state/manager.py

@@ -125,7 +125,9 @@ class StateManager:
         fingerprint = hashlib.sha256(json_content.encode()).hexdigest()
 
         cache_key = f"{self.key_prefix}{state}"
-        entry = CacheEntry(fingerprint=fingerprint, content=json_content.encode("utf-8"))
+        entry = CacheEntry(
+            fingerprint=fingerprint, content=json_content.encode("utf-8")
+        )
         await self.backend.set(cache_key, entry, ttl=effective_ttl)
 
         logger.debug("OAuth state created; state=%s ttl=%s", state, effective_ttl)

fastapi_cachex-0.3.1/fastapi_cachex/state/proxy.py

@@ -0,0 +1,9 @@
+"""FastAPI CacheX Proxy for state manager management."""
+
+from fastapi_cachex.proxy import ProxyBase
+
+from .manager import StateManager
+
+
+class StateManagerProxy(ProxyBase[StateManager]):
+    """FastAPI CacheX Proxy for StateManager instance management."""

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-cachex"
-version = "0.3.0"
+version = "0.3.1"
 description = "A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -58,6 +58,7 @@ dev = [
 memcache = ["pymemcache"]
 redis = ["redis[hiredis]>=5.3.0", "orjson"]
 jwt = ["PyJWT>=2.9.0"]
+starlette = ["itsdangerous"]
 
 [build-system]
 requires = ["uv_build>=0.11.26,<0.12"]
@@ -111,10 +112,13 @@ keep-runtime-typing = true
 ]
 "fastapi_cachex/cache.py" = [
     "PLR0913", "PLR0915", "PLR0911", "PLR0912", # Many arguments/statements/returns/branches needed for flexible caching logic
+    "S101", # Internal invariant guard, not a validation shortcut
 ]
 "fastapi_cachex/backends/memcached.py" = ["PLC0415"]  # Optional dependency
 "fastapi_cachex/backends/redis.py" = ["PLR0913", "PLC0415"]  # Optional dependency, Redis config
 "fastapi_cachex/proxy.py" = ["PLW0603"]  # Global backend management by design
+"fastapi_cachex/session/manager.py" = ["PLR0915"]  # Session/security validation branches needed
+"fastapi_cachex/session/middleware.py" = ["PLC0415"]  # Optional dependency (itsdangerous)
 
 [tool.ruff.format]
 docstring-code-format = true

fastapi_cachex-0.3.0/fastapi_cachex/session/middleware.py

@@ -1,164 +0,0 @@
-"""Session middleware for FastAPI."""
-
-import logging
-from typing import TYPE_CHECKING
-
-from fastapi import Request
-from fastapi import Response
-from starlette.middleware.base import BaseHTTPMiddleware
-from starlette.middleware.base import RequestResponseEndpoint
-from starlette.types import ASGIApp
-
-from .config import SessionConfig
-from .exceptions import SessionError
-from .manager import SessionManager
-from .proxy import SessionManagerProxy
-
-if TYPE_CHECKING:
-    from .models import Session
-
-logger = logging.getLogger(__name__)
-
-
-class SessionMiddleware(BaseHTTPMiddleware):
-    """Middleware to handle session loading and cookie management."""
-
-    def __init__(
-        self,
-        app: ASGIApp,
-        session_manager: SessionManager | None = None,
-        config: SessionConfig | None = None,
-    ) -> None:
-        """Initialize session middleware.
-
-        Args:
-            app: ASGI application
-            session_manager: Session manager instance
-            config: Session configuration
-        """
-        super().__init__(app)
-        self.session_manager = session_manager or SessionManagerProxy.get()
-
-        if config is None:
-            config = self.session_manager.config
-
-        self.config = config
-
-        logger.debug(
-            "SessionMiddleware initialized; header=%s bearer=%s",
-            config.header_name,
-            config.use_bearer_token,
-        )
-
-    async def dispatch(
-        self,
-        request: Request,
-        call_next: RequestResponseEndpoint,
-    ) -> Response:
-        """Process request and handle session.
-
-        Args:
-            request: Incoming request
-            call_next: Next handler in chain
-
-        Returns:
-            Response
-        """
-        # Store session manager in app state for dependency injection (first request only)
-        # This allows developers to use get_session_manager() dependency
-        if not hasattr(request.app.state, "__fastapi_cachex_session_manager"):
-            setattr(
-                request.app.state,
-                "__fastapi_cachex_session_manager",
-                self.session_manager,
-            )
-
-        # Extract session token from request
-        token = self._extract_token(request)
-
-        # Try to load session
-        session: Session | None = None
-        renewed_token: str | None = None
-        if token:
-            try:
-                ip_address = self._get_client_ip(request)
-                user_agent = request.headers.get("user-agent")
-                session, renewed_token = await self.session_manager.get_session(
-                    token,
-                    ip_address=ip_address,
-                    user_agent=user_agent,
-                )
-                logger.debug("Session loaded in middleware; id=%s", session.session_id)
-            except SessionError:
-                # Session invalid/expired, continue without session
-                session = None
-                logger.debug("Session failed to load; token invalid/expired")
-
-        # Store session in request state
-        setattr(request.state, "__fastapi_cachex_session", session)
-
-        # Process request
-        response: Response = await call_next(request)
-
-        # Propagate renewed token to client so its JWT exp stays in sync
-        if renewed_token is not None:
-            response.headers[self.config.header_name] = renewed_token
-
-        return response
-
-    def _extract_token(self, request: Request) -> str | None:
-        """Extract session token from request.
-
-        Args:
-            request: Incoming request
-
-        Returns:
-            Session token or None
-        """
-        for source in self.config.token_source_priority:
-            if source == "header":
-                token = request.headers.get(self.config.header_name)
-                if token:
-                    logger.debug("Token extracted from header")
-                    return token
-
-            elif source == "bearer":
-                if self.config.use_bearer_token:
-                    auth_header = request.headers.get("authorization")
-                    if auth_header and auth_header.startswith("Bearer "):
-                        bearer_prefix_len = 7
-                        token_value = auth_header[bearer_prefix_len:]
-                        logger.debug("Token extracted from bearer auth")
-                        return token_value
-
-        return None
-
-    def _get_client_ip(self, request: Request) -> str | None:
-        """Get client IP address from request.
-
-        Args:
-            request: Incoming request
-
-        Returns:
-            Client IP address or None
-        """
-        # Check X-Forwarded-For header (for proxied requests)
-        forwarded_for = request.headers.get("x-forwarded-for")
-        if forwarded_for:
-            # Get first IP from comma-separated list
-            ip = forwarded_for.split(",")[0].strip()
-            logger.debug("Client IP from X-Forwarded-For: %s", ip)
-            return ip
-
-        # Check X-Real-IP header
-        real_ip = request.headers.get("x-real-ip")
-        if real_ip:
-            logger.debug("Client IP from X-Real-IP: %s", real_ip)
-            return real_ip
-
-        # Fallback to direct client IP
-        if request.client:
-            logger.debug("Client IP from connection: %s", request.client.host)
-            return request.client.host
-
-        return None