fastapi-cachex 0.2.11__tar.gz → 0.2.12__tar.gz

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.2.11
+Version: 0.2.12
 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
@@ -23,7 +23,7 @@ Requires-Dist: fastapi
 Requires-Dist: pydantic
 Requires-Dist: pyjwt>=2.9.0 ; extra == 'jwt'
 Requires-Dist: pymemcache ; extra == 'memcache'
-Requires-Dist: redis[hiredis] ; extra == 'redis'
+Requires-Dist: redis[hiredis]>=5.3.0 ; extra == 'redis'
 Requires-Dist: orjson ; extra == 'redis'
 Requires-Python: >=3.10
 Project-URL: Homepage, https://github.com/allen0099/FastAPI-CacheX

fastapi_cachex-0.2.12/fastapi_cachex/__init__.py

@@ -0,0 +1,70 @@
+"""FastAPI-CacheX: A powerful and flexible caching extension for FastAPI."""
+
+import logging
+
+from .cache import cache as cache
+from .cache import default_key_builder as default_key_builder
+from .dependencies import CacheBackend as CacheBackend
+from .dependencies import get_cache_backend as get_cache_backend
+from .proxy import BackendProxy as BackendProxy
+from .routes import add_routes as add_routes
+from .session import Session as Session
+from .session import SessionConfig as SessionConfig
+from .session import SessionManager as SessionManager
+from .session import SessionManagerProxy as SessionManagerProxy
+from .session import SessionMiddleware as SessionMiddleware
+from .session import SessionUser as SessionUser
+from .session import get_optional_session as get_optional_session
+from .session import get_session as get_session
+from .session import get_session_manager as get_session_manager
+from .session import require_session as require_session
+from .session.exceptions import SessionError as SessionError
+from .session.exceptions import SessionExpiredError as SessionExpiredError
+from .session.exceptions import SessionInvalidError as SessionInvalidError
+from .session.exceptions import SessionNotFoundError as SessionNotFoundError
+from .session.exceptions import SessionSecurityError as SessionSecurityError
+from .session.exceptions import SessionTokenError as SessionTokenError
+from .state import InvalidStateError as InvalidStateError
+from .state import StateData as StateData
+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 .types import CacheKeyBuilder as CacheKeyBuilder
+
+_package_logger = logging.getLogger("fastapi_cachex")
+_package_logger.addHandler(
+    logging.NullHandler()
+)  # Attach a NullHandler to avoid "No handler found" warnings in user applications.
+
+__all__ = [
+    "BackendProxy",
+    "CacheBackend",
+    "CacheKeyBuilder",
+    "InvalidStateError",
+    "Session",
+    "SessionConfig",
+    "SessionError",
+    "SessionExpiredError",
+    "SessionInvalidError",
+    "SessionManager",
+    "SessionManagerProxy",
+    "SessionMiddleware",
+    "SessionNotFoundError",
+    "SessionSecurityError",
+    "SessionTokenError",
+    "SessionUser",
+    "StateData",
+    "StateDataError",
+    "StateError",
+    "StateExpiredError",
+    "StateManager",
+    "add_routes",
+    "cache",
+    "default_key_builder",
+    "get_cache_backend",
+    "get_optional_session",
+    "get_session",
+    "get_session_manager",
+    "require_session",
+]

fastapi_cachex-0.2.12/fastapi_cachex/backends/config.py

@@ -0,0 +1,40 @@
+"""Configuration models for cache backends."""
+
+from pydantic import BaseModel
+from pydantic import Field
+from pydantic import SecretStr
+
+DEFAULT_REDIS_PREFIX = "fastapi_cachex:"
+
+
+class RedisConfig(BaseModel):
+    """Configuration for Redis backend."""
+
+    host: str = Field(default="localhost", description="Redis server address")
+    port: int = Field(default=6379, ge=1, le=65535, description="Redis server port")
+    password: SecretStr | None = Field(
+        default=None, description="Redis server password"
+    )
+    db: int = Field(default=0, ge=0, description="Redis database number")
+    encoding: str = Field(default="utf-8", description="Character encoding to use")
+    socket_timeout: float = Field(
+        default=1.0, description="Timeout for socket operations in seconds"
+    )
+    socket_connect_timeout: float = Field(
+        default=1.0, description="Timeout for socket connection in seconds"
+    )
+    key_prefix: str = Field(
+        default=DEFAULT_REDIS_PREFIX,
+        description="Prefix applied to all cache keys",
+    )
+    protocol: int = Field(
+        default=2,
+        ge=2,
+        le=3,
+        description=(
+            "RESP protocol version (2 or 3). "
+            "Keep at 2 (default) unless you need RESP3 features and your hiredis "
+            "version supports it (hiredis >= 3.0 is required for RESP3). "
+            "Redis 8.0 supports RESP3 but older hiredis builds do not."
+        ),
+    )

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/backends/memcached.py

@@ -1,5 +1,6 @@
 """Memcached cache backend implementation."""
 
+import asyncio
 import logging
 import warnings
 
@@ -72,20 +73,20 @@ class MemcachedBackend(BaseCacheBackend):
             Optional[ETagContent]: Cached value with ETag if exists, None otherwise
         """
         prefixed_key = self._make_key(key)
-        value = self.client.get(prefixed_key)
+        loop = asyncio.get_running_loop()
+        value = await loop.run_in_executor(None, self.client.get, prefixed_key)
         if value is None:
             logger.debug("Memcached MISS; key=%s", key)
             return None
 
         # Memcached stores data as bytes; deserialize from JSON
         try:
-            data = json.loads(value.decode("utf-8"))
+            data = json.loads(value)
             logger.debug("Memcached HIT; key=%s", key)
             return ETagContent(
                 etag=data["etag"],
-                content=data["content"].encode()
-                if isinstance(data["content"], str)
-                else data["content"],
+                content=data["content"].encode("latin-1"),
+                media_type=data.get("media_type"),
             )
         except (json.JSONDecodeError, KeyError, ValueError):
             logger.debug("Memcached DESERIALIZE ERROR; key=%s", key)
@@ -101,16 +102,14 @@ class MemcachedBackend(BaseCacheBackend):
         """
         prefixed_key = self._make_key(key)
 
-        # Prepare content for JSON serialization
-        if isinstance(value.content, bytes):
-            content = value.content.decode()
-        else:
-            content = value.content
+        # Use latin-1 to round-trip arbitrary bytes through JSON storage
+        content = value.content.decode("latin-1")
 
         serialized_data: str | bytes = json.dumps(
             {
                 "etag": value.etag,
                 "content": content,
+                "media_type": value.media_type,
             },
         )
 
@@ -121,10 +120,11 @@ class MemcachedBackend(BaseCacheBackend):
             else serialized_data.encode("utf-8")
         )
 
-        self.client.set(
-            prefixed_key,
-            serialized_bytes,
-            expire=ttl if ttl is not None else 0,
+        expire = ttl if ttl is not None else 0
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(
+            None,
+            lambda: self.client.set(prefixed_key, serialized_bytes, expire=expire),
         )
         logger.debug("Memcached SET; key=%s ttl=%s", key, ttl)
 
@@ -134,7 +134,9 @@ class MemcachedBackend(BaseCacheBackend):
         Args:
             key: Cache key to delete
         """
-        self.client.delete(self._make_key(key))
+        prefixed = self._make_key(key)
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, self.client.delete, prefixed)
         logger.debug("Memcached DELETE; key=%s", key)
 
     async def clear(self) -> None:
@@ -150,7 +152,8 @@ class MemcachedBackend(BaseCacheBackend):
             RuntimeWarning,
             stacklevel=2,
         )
-        self.client.flush_all()
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, self.client.flush_all)
         logger.debug("Memcached CLEAR; flush_all issued")
 
     async def clear_path(self, path: str, include_params: bool = False) -> int:
@@ -180,8 +183,12 @@ class MemcachedBackend(BaseCacheBackend):
 
         # Try to delete the prefixed key (exact match only)
         prefixed_key = self._make_key(path)
+        loop = asyncio.get_running_loop()
         try:
-            result = self.client.delete(prefixed_key, noreply=False)
+            result = await loop.run_in_executor(
+                None,
+                lambda: self.client.delete(prefixed_key, noreply=False),
+            )
         except Exception:  # noqa: BLE001
             return 0
         else:

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/backends/memory.py

@@ -1,7 +1,6 @@
 """In-memory cache backend implementation."""
 
 import asyncio
-import contextlib
 import fnmatch
 import logging
 import time
@@ -44,13 +43,16 @@ class MemoryBackend(BaseCacheBackend):
     def _ensure_cleanup_started(self) -> None:
         """Ensure cleanup task is started in proper async context."""
         if self._cleanup_task is None or self._cleanup_task.done():
-            with contextlib.suppress(RuntimeError):
-                # No event loop yet; will be created on first async operation
-                self._cleanup_task = asyncio.create_task(self._cleanup_task_impl())
-                logger.debug(
-                    "Started memory backend cleanup task (interval=%s)",
-                    self.cleanup_interval,
-                )
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                # No running event loop yet; defer until first real async call.
+                return
+            self._cleanup_task = loop.create_task(self._cleanup_task_impl())
+            logger.debug(
+                "Started memory backend cleanup task (interval=%s)",
+                self.cleanup_interval,
+            )
 
     def start_cleanup(self) -> None:
         """Start the cleanup task if it's not already running.

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/backends/redis.py

@@ -5,6 +5,9 @@ from typing import TYPE_CHECKING
 from typing import Any
 from typing import Literal
 
+from fastapi_cachex.backends.config import (
+    DEFAULT_REDIS_PREFIX as DEFAULT_REDIS_PREFIX,  # noqa: PLC0414
+)
 from fastapi_cachex.backends.config import RedisConfig
 from fastapi_cachex.exceptions import CacheXError
 from fastapi_cachex.types import CACHE_KEY_SEPARATOR
@@ -23,8 +26,7 @@ except ImportError:  # pragma: no cover
 
 logger = logging.getLogger(__name__)
 
-# Default Redis key prefix for fastapi-cachex
-DEFAULT_REDIS_PREFIX = "fastapi_cachex:"
+# Default Redis key prefix for fastapi-cachex — re-exported from config for convenience
 
 
 class AsyncRedisCacheBackend(BaseCacheBackend):
@@ -48,6 +50,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         socket_timeout: float = 1.0,
         socket_connect_timeout: float = 1.0,
         key_prefix: str = DEFAULT_REDIS_PREFIX,
+        protocol: int = 2,
         **kwargs: Any,
     ) -> None:
         """Initialize async Redis cache backend.
@@ -62,6 +65,9 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
             socket_timeout: Timeout for socket operations (in seconds)
             socket_connect_timeout: Timeout for socket connection (in seconds)
             key_prefix: Prefix for all cache keys (default: 'fastapi_cachex:')
+            protocol: RESP protocol version (2 or 3). Defaults to 2 (RESP2) for
+                broadest compatibility. Use 3 only when hiredis >= 3.0 is installed
+                and Redis 8.0+ RESP3 features are required.
             **kwargs: Additional arguments to pass to Redis client
         """
         try:
@@ -76,6 +82,9 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
             )
             raise CacheXError(msg)
 
+        # `protocol` is not in the types-redis stubs (added in redis-py 5.x).
+        # Pass it via **kwargs so mypy doesn't complain about an unknown keyword.
+        kwargs.setdefault("protocol", protocol)
         self.client = AsyncRedis(
             host=host,
             port=port,
@@ -104,6 +113,12 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
             password=config.password.get_secret_value()
             if config.password is not None
             else None,
+            db=config.db,
+            encoding=config.encoding,
+            socket_timeout=config.socket_timeout,
+            socket_connect_timeout=config.socket_connect_timeout,
+            key_prefix=config.key_prefix,
+            protocol=config.protocol,
         )
 
     def _make_key(self, key: str) -> str:
@@ -112,15 +127,14 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
 
     def _serialize(self, value: ETagContent) -> str:
         """Serialize ETagContent to JSON string."""
-        if isinstance(value.content, bytes):
-            content = value.content.decode()
-        else:
-            content = value.content
+        # Use latin-1 to round-trip arbitrary bytes through JSON/UTF-8 Redis storage
+        content = value.content.decode("latin-1")
 
         serialized: str | bytes = json.dumps(
             {
                 "etag": value.etag,
                 "content": content,
+                "media_type": value.media_type,
             },
         )
 
@@ -140,11 +154,10 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
             logger.debug("Content type in JSON: %s", type(data["content"]))
             return ETagContent(
                 etag=data["etag"],
-                content=data["content"].encode()
-                if isinstance(data["content"], str)
-                else data["content"],
+                content=data["content"].encode("latin-1"),
+                media_type=data.get("media_type"),
             )
-        except (json.JSONDecodeError, KeyError):
+        except (json.JSONDecodeError, KeyError, AttributeError):
             return None
 
     async def get(self, key: str) -> ETagContent | None:
@@ -158,10 +171,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         """Store a response in the cache."""
         serialized = self._serialize(value)
         prefixed_key = self._make_key(key)
-        if ttl is not None:
-            await self.client.setex(prefixed_key, ttl, serialized)
-        else:
-            await self.client.set(prefixed_key, serialized)
+        await self.client.set(prefixed_key, serialized, ex=ttl)
         logger.debug("Redis SET; key=%s ttl=%s", key, ttl)
 
     async def delete(self, key: str) -> None:
@@ -350,12 +360,18 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         all_keys = await self.get_all_keys()
         cache_data: dict[str, tuple[ETagContent, float | None]] = {}
 
+        if not all_keys:
+            return cache_data
+
+        # Fetch all values in a single pipeline round-trip instead of N+1 GETs
+        pipe = self.client.pipeline()
         for prefixed_key in all_keys:
-            # Remove prefix to get the original cache key
-            original_key = prefixed_key.removeprefix(self.key_prefix)
+            pipe.get(prefixed_key)
+        raw_values: list[str | None] = await pipe.execute()
 
-            # Get the value using the original key (get() adds prefix internally)
-            value = await self.get(original_key)
+        for prefixed_key, raw in zip(all_keys, raw_values, strict=False):
+            original_key = prefixed_key.removeprefix(self.key_prefix)
+            value = self._deserialize(raw)
             if value is not None:
                 cache_data[original_key] = (value, None)
 

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/cache.py

@@ -12,10 +12,10 @@ from inspect import Signature
 from typing import TYPE_CHECKING
 from typing import Any
 from typing import Literal
+from typing import cast
 
 from fastapi import Request
 from fastapi import Response
-from fastapi.datastructures import DefaultPlaceholder
 from starlette.status import HTTP_304_NOT_MODIFIED
 
 from .backends import MemoryBackend
@@ -108,11 +108,12 @@ async def get_response(
         msg = "Route not found in request scope"
         raise CacheXError(msg)
 
-    if isinstance(route.response_class, DefaultPlaceholder):
-        response_class: type[Response] = route.response_class.value
-
-    else:
-        response_class = route.response_class
+    # FastAPI <= 0.136.x stores a DefaultPlaceholder; >= 0.137.0 stores the class directly.
+    # getattr with a fallback handles both without importing the internal class.
+    response_class: type[Response] = cast(
+        "type[Response]",
+        getattr(route.response_class, "value", route.response_class),
+    )
 
     # Convert non-Response result to Response using appropriate response_class
     return response_class(content=result)
@@ -150,13 +151,10 @@ def cache(
     """
 
     def decorator(func: HandlerCallable) -> AsyncResponseCallable:
-        try:
-            cache_backend = BackendProxy.get()
-        except BackendNotFoundError:
-            # Fallback to memory backend if no backend is set
-            cache_backend = MemoryBackend()
-            BackendProxy.set(cache_backend)
-            logger.debug("No backend configured; using MemoryBackend fallback")
+        # Validate stale parameters eagerly at decoration time
+        if stale is not None and stale_ttl is None:
+            msg = "stale_ttl must be set if stale is used"
+            raise CacheXError(msg)
 
         # Analyze the original function's signature
         sig: Signature = inspect.signature(func)
@@ -183,14 +181,13 @@ def cache(
         else:
             request_name = found_request.name
 
-        async def get_cache_control(cache_control: CacheControl) -> str:
+        def get_cache_control(cache_control: CacheControl) -> str:
             # Set Cache-Control headers
             if no_cache:
                 cache_control.add(DirectiveType.NO_CACHE)
                 if must_revalidate:
                     cache_control.add(DirectiveType.MUST_REVALIDATE)
             else:
-                # Handle normal cache control cases
                 # 1. Access scope (public/private)
                 if public:
                     cache_control.add(DirectiveType.PUBLIC)
@@ -205,11 +202,7 @@ def cache(
                 if must_revalidate:
                     cache_control.add(DirectiveType.MUST_REVALIDATE)
 
-                # 4. Stale response handling
-                if stale is not None and stale_ttl is None:
-                    msg = "stale_ttl must be set if stale is used"
-                    raise CacheXError(msg)
-
+                # 4. Stale response handling (stale_ttl is validated at decoration time)
                 if stale == "revalidate":
                     cache_control.add(DirectiveType.STALE_WHILE_REVALIDATE, stale_ttl)
                 elif stale == "error":
@@ -223,6 +216,14 @@ def cache(
 
         @wraps(func)
         async def wrapper(*args: Any, **kwargs: Any) -> Response:
+            # Resolve backend on every request to support lifespan-configured backends
+            try:
+                cache_backend = BackendProxy.get()
+            except BackendNotFoundError:
+                cache_backend = MemoryBackend()
+                BackendProxy.set(cache_backend)
+                logger.debug("No backend configured; using MemoryBackend fallback")
+
             if found_request:
                 req: Request | None = kwargs.get(request_name)
             else:
@@ -243,7 +244,7 @@ def cache(
             builder = key_builder or default_key_builder
             cache_key = builder(req)
             client_etag = req.headers.get("if-none-match")
-            cache_control = await get_cache_control(CacheControl())
+            cache_control = get_cache_control(CacheControl())
 
             # Handle special case: no-store (highest priority)
             if no_store:
@@ -257,15 +258,21 @@ def cache(
             # Check cache and handle ETag validation
             cached_data = await cache_backend.get(cache_key)
 
-            current_response = None
-            current_etag = None
+            current_response: Response | None = None
+            current_etag: str | None = None
+            current_body: bytes | None = None
 
             if client_etag:
                 if no_cache:
                     # Get fresh response first if using no-cache
                     current_response = await get_response(func, req, *args, **kwargs)
+                    current_body = getattr(current_response, "body", None)
+                    if current_body is None:
+                        # 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_response.body).hexdigest()}"'  # noqa: S324
+                        f'W/"{hashlib.md5(current_body).hexdigest()}"'  # noqa: S324
                     )
 
                     if client_etag == current_etag:
@@ -304,6 +311,7 @@ def cache(
                 return Response(
                     content=cached_data.content,
                     status_code=200,
+                    media_type=cached_data.media_type,
                     headers={
                         "ETag": cached_data.etag,
                         "Cache-Control": cache_control,
@@ -313,7 +321,12 @@ def cache(
             if not current_response or not current_etag:
                 # Retrieve the current response if not already done
                 current_response = await get_response(func, req, *args, **kwargs)
-                current_etag = f'W/"{hashlib.md5(current_response.body).hexdigest()}"'  # noqa: S324
+                current_body = getattr(current_response, "body", None)
+                if current_body is None:
+                    # 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
                 logger.debug("Cache MISS; computed fresh ETag for key=%s", cache_key)
 
             # Set ETag header
@@ -321,10 +334,17 @@ def cache(
 
             # Update cache if needed
             if not cached_data or cached_data.etag != current_etag:
+                if current_body is None:  # pragma: no cover - guaranteed by earlier guards
+                    msg = "Unexpected state: response body unavailable after ETag computation"
+                    raise CacheXError(msg)
                 # Store in cache if data changed
                 await cache_backend.set(
                     cache_key,
-                    ETagContent(current_etag, current_response.body),
+                    ETagContent(
+                        current_etag,
+                        current_body,
+                        current_response.media_type,
+                    ),
                     ttl=ttl,
                 )
                 logger.debug("Updated cache entry; key=%s ttl=%s", cache_key, ttl)

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/proxy.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import warnings
 from logging import getLogger
 from typing import Generic
+from typing import NoReturn
 from typing import TypeVar
 
 from .backends import BaseCacheBackend
@@ -18,7 +19,7 @@ logger = getLogger(__name__)
 class ProxyMeta(type):
     """Metaclass for BackendProxy to prevent instantiation."""
 
-    def __call__(cls) -> None:
+    def __call__(cls) -> NoReturn:
         """Prevent instantiation of BackendProxy."""
         msg = "Proxy class cannot be instantiated. Use static methods instead."
         raise TypeError(msg)

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/routes.py

@@ -1,8 +1,10 @@
 """Optional routes for cache monitoring and management."""
 
 import time
+from collections.abc import Sequence
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
+from typing import Any
 
 from .backends import BaseCacheBackend
 from .exceptions import BackendNotFoundError
@@ -37,7 +39,7 @@ class CacheHitSummary:
 
     total_cached_entries: int
     active_entries: int
-    frequently_cached_routes: list[str]
+    cached_paths: list[str]
 
 
 @dataclass
@@ -127,7 +129,7 @@ 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 = 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(
@@ -155,7 +157,7 @@ async def _get_cached_hits_handler(backend: BaseCacheBackend) -> CacheHitsRespon
         summary=CacheHitSummary(
             total_cached_entries=len(cached_hits),
             active_entries=len(valid_hits),
-            frequently_cached_routes=sorted(routes_hit),
+            cached_paths=sorted(routes_hit),
         ),
     )
 
@@ -186,7 +188,7 @@ async def _get_cached_records_handler(
             content = etag_content.content
             content_size = len(content) if isinstance(content, (bytes, str)) else 0
 
-            ttl_remaining = 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")
@@ -229,7 +231,10 @@ async def _get_cached_records_handler(
 
 
 def add_routes(
-    app: "FastAPI", prefix: str = "", include_in_schema: bool = False
+    app: "FastAPI",
+    prefix: str = "",
+    include_in_schema: bool = False,
+    dependencies: Sequence[Any] | None = None,
 ) -> None:
     """Add cache monitoring routes to the FastAPI application.
 
@@ -243,6 +248,10 @@ def add_routes(
                 Defaults to "" (no prefix).
         include_in_schema: Whether to include routes in OpenAPI schema.
                           Defaults to False.
+        dependencies: Optional list of FastAPI ``Depends`` objects applied to
+                      all monitoring routes.  Useful for adding authentication
+                      or authorization guards (e.g.
+                      ``[Depends(verify_api_key)]``).
 
     Example:
         from fastapi import FastAPI
@@ -255,7 +264,11 @@ def add_routes(
         add_routes(app, prefix="/api/cache")  # Routes at /api/cache/cached-hits and /api/cache/cached-records
     """
 
-    @app.get(f"{prefix}/cached-hits", include_in_schema=include_in_schema)
+    @app.get(
+        f"{prefix}/cached-hits",
+        include_in_schema=include_in_schema,
+        dependencies=dependencies,
+    )
     async def get_cached_hits() -> CacheHitsResponse:
         """Return cached hit records.
 
@@ -277,13 +290,17 @@ def add_routes(
                 summary=CacheHitSummary(
                     total_cached_entries=0,
                     active_entries=0,
-                    frequently_cached_routes=[],
+                    cached_paths=[],
                 ),
             )
 
         return await _get_cached_hits_handler(backend)
 
-    @app.get(f"{prefix}/cached-records", include_in_schema=include_in_schema)
+    @app.get(
+        f"{prefix}/cached-records",
+        include_in_schema=include_in_schema,
+        dependencies=dependencies,
+    )
     async def get_cached_records() -> CachedRecordsResponse:
         """Display currently cached records.
 

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/session/config.py

@@ -81,10 +81,6 @@ class SessionConfig(BaseModel):
         default=False,
         description="Whether to bind session to User-Agent",
     )
-    regenerate_on_login: bool = Field(
-        default=True,
-        description="Whether to regenerate session ID on login",
-    )
 
     # Backend settings
     backend_key_prefix: str = Field(

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/session/manager.py

@@ -138,8 +138,8 @@ class SessionManager:
         # Store in backend
         await self._save_session(session)
 
-        # Generate signed token
-        token = self._create_token(session.session_id)
+        # Generate signed token (pass expires_at so JWT exp reflects sliding expiration)
+        token = self._create_token(session.session_id, expires_at=session.expires_at)
         logger.debug(
             "Session created; id=%s ttl=%s ip=%s ua=%s",
             session.session_id,
@@ -214,6 +214,22 @@ class SessionManager:
             logger.debug("Session expired; id=%s", session.session_id)
             raise SessionExpiredError(msg)
 
+        # Check absolute timeout (hard cap regardless of sliding expiration)
+        if self.config.absolute_timeout is not None:
+            absolute_expires_at = session.created_at + timedelta(
+                seconds=self.config.absolute_timeout,
+            )
+            if datetime.now(timezone.utc) >= absolute_expires_at:
+                session.status = SessionStatus.EXPIRED
+                await self._save_session(session)
+                msg = "Session has exceeded absolute timeout"
+                logger.debug(
+                    "Session absolute timeout exceeded; id=%s created_at=%s",
+                    session.session_id,
+                    session.created_at,
+                )
+                raise SessionExpiredError(msg)
+
         # Security checks
         if self.config.ip_binding and not self.security.check_ip_match(
             session,
@@ -314,8 +330,8 @@ class SessionManager:
         # Save with new ID
         await self._save_session(session)
 
-        # Create new token
-        token = self._create_token(session.session_id)
+        # Create new token (pass expires_at so JWT exp reflects current expiry)
+        token = self._create_token(session.session_id, expires_at=session.expires_at)
         logger.debug(
             "Session ID regenerated; old_id=%s new_id=%s", old_id, session.session_id
         )
@@ -372,11 +388,16 @@ class SessionManager:
         logger.debug("Expired sessions cleared; count=%s", count)
         return count
 
-    def _create_token(self, session_id: str) -> SessionToken:
+    def _create_token(
+        self,
+        session_id: str,
+        expires_at: datetime | None = None,
+    ) -> SessionToken:
         """Create a signed session token.
 
         Args:
             session_id: Session ID to sign
+            expires_at: Session expiry time, forwarded to JWT serializers
 
         Returns:
             SessionToken object
@@ -389,7 +410,9 @@ class SessionManager:
             if self.config.token_format == "simple"
             else ""
         )
-        return SessionToken(session_id=session_id, signature=signature)
+        return SessionToken(
+            session_id=session_id, signature=signature, expires_at=expires_at
+        )
 
     async def _save_session(self, session: Session) -> None:
         """Save session to backend.

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/session/models.py

@@ -142,3 +142,4 @@ class SessionToken(BaseModel):
     session_id: str
     signature: str
     issued_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    expires_at: datetime | None = None

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/session/security.py

@@ -21,7 +21,8 @@ class SecurityManager:
         if len(secret_key) < 32:  # noqa: PLR2004
             msg = "Secret key must be at least 32 characters"
             raise ValueError(msg)
-        self.secret_key = secret_key.encode("utf-8")
+        # Use name mangling so the key bytes are not trivially accessible via repr
+        self.__secret_key_bytes = secret_key.encode("utf-8")
 
         logger.debug(
             "SecurityManager initialized with secret length=%s", len(secret_key)
@@ -37,7 +38,7 @@ class SecurityManager:
             The signature as a hex string
         """
         return hmac.new(
-            self.secret_key,
+            self.__secret_key_bytes,
             session_id.encode("utf-8"),
             hashlib.sha256,
         ).hexdigest()

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/session/token_serializers.py

@@ -133,7 +133,11 @@ class JWTTokenSerializer:
         Uses claims `sid`, `iat`, `exp`, and optional `iss`/`aud`.
         """
         iat = int(token.issued_at.timestamp())
-        exp = iat + int(self._session_ttl)
+        # Use session's expires_at when available (supports sliding expiration)
+        if token.expires_at is not None:
+            exp = int(token.expires_at.timestamp())
+        else:
+            exp = iat + int(self._session_ttl)
 
         payload: dict[str, object] = {
             "sid": token.session_id,

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/state/manager.py

@@ -9,6 +9,7 @@ from datetime import timedelta
 from datetime import timezone
 from typing import Any
 
+from fastapi_cachex.backends.base import BaseCacheBackend
 from fastapi_cachex.proxy import BackendProxy
 from fastapi_cachex.types import ETagContent
 
@@ -27,18 +28,67 @@ class StateManager:
     """Manages OAuth state and session state lifecycle and storage."""
 
     def __init__(
-        self, key_prefix: str = "oauth_state:", default_ttl: int = DEFAULT_STATE_TTL
+        self,
+        backend: BaseCacheBackend | None = None,
+        key_prefix: str = "oauth_state:",
+        default_ttl: int = DEFAULT_STATE_TTL,
     ) -> None:
         """Initialize StateManager.
 
         Args:
+            backend: Cache backend instance. If None, uses BackendProxy.get().
             key_prefix: Prefix for state keys in cache backend
             default_ttl: Default time-to-live in seconds for state
         """
-        self.backend = BackendProxy.get()
+        self.backend = backend if backend is not None else BackendProxy.get()
         self.key_prefix = key_prefix
         self.default_ttl = default_ttl
 
+    def _extract_json_content(self, cached: ETagContent) -> str:
+        """Extract JSON string from a cached ETagContent value.
+
+        Args:
+            cached: The ETagContent retrieved from backend
+
+        Returns:
+            JSON string
+
+        Raises:
+            StateDataError: If the content cannot be decoded as UTF-8 text
+        """
+        try:
+            return cached.content.decode("utf-8")
+        except (AttributeError, UnicodeDecodeError) as e:
+            msg = "Unexpected state data format"
+            raise StateDataError(msg) from e
+
+    def _parse_state_data(self, json_content: str, state: str) -> StateData:
+        """Parse JSON content into a StateData model.
+
+        Args:
+            json_content: JSON string to parse
+            state: State string (used for logging)
+
+        Returns:
+            StateData instance
+
+        Raises:
+            StateDataError: If parsing or validation fails
+        """
+        try:
+            state_dict: dict[str, Any] = json.loads(json_content)
+        except json.JSONDecodeError as e:
+            msg = f"Failed to parse state data: {e}"
+            logger.exception("Failed to parse state data; state=%s", state)
+            raise StateDataError(msg) from e
+
+        try:
+            return StateData(**state_dict)
+        except ValueError as e:
+            msg = f"Invalid state data structure: {e}"
+            logger.exception("Failed to create StateData model; state=%s", state)
+            raise StateDataError(msg) from e
+
     async def create_state(
         self,
         ttl: int | None = None,
@@ -77,7 +127,7 @@ class StateManager:
 
         # Store in backend with TTL using ETagContent
         cache_key = f"{self.key_prefix}{state}"
-        etag_content = ETagContent(etag=etag, content=json_content)
+        etag_content = ETagContent(etag=etag, content=json_content.encode("utf-8"))
         await self.backend.set(cache_key, etag_content, ttl=effective_ttl)
 
         logger.debug("OAuth state created; state=%s ttl=%s", state, effective_ttl)
@@ -106,34 +156,8 @@ class StateManager:
             msg = "Invalid or expired state"
             raise InvalidStateError(msg)
 
-        # Extract content from ETagContent
-        json_content = cached_etag_content.content
-        if isinstance(json_content, bytes):
-            json_content = json_content.decode("utf-8")
-        elif not isinstance(json_content, str):
-            msg = "Unexpected state data format"
-            logger.error(
-                "Unexpected content type in state; state=%s type=%s",
-                state,
-                type(json_content),
-            )
-            raise StateDataError(msg)
-
-        # Parse the stored state data
-        try:
-            state_dict: dict[str, Any] = json.loads(json_content)
-        except json.JSONDecodeError as e:
-            msg = f"Failed to parse state data: {e}"
-            logger.exception("Failed to parse state data; state=%s", state)
-            raise StateDataError(msg) from e
-
-        # Validate and create StateData model
-        try:
-            state_data = StateData(**state_dict)
-        except ValueError as e:
-            msg = f"Invalid state data structure: {e}"
-            logger.exception("Failed to create StateData model; state=%s", state)
-            raise StateDataError(msg) from e
+        json_content = self._extract_json_content(cached_etag_content)
+        state_data = self._parse_state_data(json_content, state)
 
         # Verify expiry
         if datetime.now(timezone.utc) > state_data.expires_at:
@@ -158,43 +182,21 @@ class StateManager:
         """
         cache_key = f"{self.key_prefix}{state}"
 
-        # Try to retrieve state data from backend
         cached_etag_content = await self.backend.get(cache_key)
         if cached_etag_content is None:
             logger.debug("State validation failed - not found; state=%s", state)
             return False
 
-        # Extract content from ETagContent
-        json_content = cached_etag_content.content
-        if isinstance(json_content, bytes):
-            try:
-                json_content = json_content.decode("utf-8")
-            except UnicodeDecodeError:
-                logger.exception(
-                    "Failed to decode bytes content in state; state=%s",
-                    state,
-                )
-                return False
-        elif not isinstance(json_content, str):
-            logger.error(
-                "Unexpected content type in state; state=%s type=%s",
-                state,
-                type(json_content),
-            )
-            return False
-
         try:
-            state_dict: dict[str, Any] = json.loads(json_content)
-            # Validate and create StateData model
-            state_data = StateData(**state_dict)
-        except (json.JSONDecodeError, ValueError):
+            json_content = self._extract_json_content(cached_etag_content)
+            state_data = self._parse_state_data(json_content, state)
+        except (StateDataError, UnicodeDecodeError):
             logger.exception(
                 "Failed to parse or validate state data; state=%s",
                 state,
             )
             return False
 
-        # Check expiry
         if datetime.now(timezone.utc) > state_data.expires_at:
             logger.debug("State validation failed - expired; state=%s", state)
             return False
@@ -217,34 +219,13 @@ class StateManager:
         if cached_etag_content is None:
             return None
 
-        # Extract content from ETagContent
-        json_content = cached_etag_content.content
-        if isinstance(json_content, bytes):
-            try:
-                json_content = json_content.decode("utf-8")
-            except UnicodeDecodeError:
-                logger.exception(
-                    "Failed to decode bytes content in state; state=%s",
-                    state,
-                )
-                return None
-        elif not isinstance(json_content, str):
-            logger.error(
-                "Unexpected content type in state; state=%s type=%s",
-                state,
-                type(json_content),
-            )
-            return None
-
         try:
-            state_dict: dict[str, Any] = json.loads(json_content)
-            # Validate and create StateData model
-            state_data = StateData(**state_dict)
-        except (json.JSONDecodeError, ValueError):
+            json_content = self._extract_json_content(cached_etag_content)
+            state_data = self._parse_state_data(json_content, state)
+        except (StateDataError, UnicodeDecodeError):
             logger.exception("Failed to parse or validate state data; state=%s", state)
             return None
 
-        # Check expiry
         if datetime.now(timezone.utc) > state_data.expires_at:
             return None
 
@@ -260,6 +241,11 @@ class StateManager:
             True if state was deleted, False if it didn't exist
         """
         cache_key = f"{self.key_prefix}{state}"
+        # Check existence before deleting to return accurate result
+        existing = await self.backend.get(cache_key)
+        if existing is None:
+            logger.debug("OAuth state not found for deletion; state=%s", state)
+            return False
         await self.backend.delete(cache_key)
         logger.debug("OAuth state deleted; state=%s", state)
         return True

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/fastapi_cachex/types.py

@@ -2,7 +2,6 @@
 
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Any
 
 from fastapi import Request
 
@@ -18,7 +17,8 @@ class ETagContent:
     """ETag and content for cache items."""
 
     etag: str
-    content: Any
+    content: bytes
+    media_type: str | None = None
 
 
 @dataclass

{fastapi_cachex-0.2.11 → fastapi_cachex-0.2.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-cachex"
-version = "0.2.11"
+version = "0.2.12"
 description = "A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -45,7 +45,7 @@ dev = [
     "pytest>=8.3.5",
     "pytest-asyncio>=0.26.0",
     "pytest-cov>=6.1.0",
-    "redis[hiredis]>=5.2.1",
+    "redis[hiredis]>=5.3.0",
     "ruff>=0.11.2",
     "tox>=4.25.0",
     "tox-uv>=1.29.0",
@@ -56,11 +56,11 @@ dev = [
 
 [project.optional-dependencies]
 memcache = ["pymemcache"]
-redis = ["redis[hiredis]", "orjson"]
+redis = ["redis[hiredis]>=5.3.0", "orjson"]
 jwt = ["PyJWT>=2.9.0"]
 
 [build-system]
-requires = ["uv_build>=0.9.17,<0.10.0"]
+requires = ["uv_build>=0.9.17,<0.11.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
@@ -110,7 +110,7 @@ keep-runtime-typing = true
     "PT031"  # Single statement in pytest.warns is acceptable
 ]
 "fastapi_cachex/cache.py" = [
-    "PLR0913", "PLR0915", # Many arguments/statements needed for flexible caching logic
+    "PLR0913", "PLR0915", "PLR0911", "PLR0912", # Many arguments/statements/returns/branches needed for flexible caching logic
 ]
 "fastapi_cachex/backends/memcached.py" = ["PLC0415"]  # Optional dependency
 "fastapi_cachex/backends/redis.py" = ["PLR0913", "PLC0415"]  # Optional dependency, Redis config

fastapi_cachex-0.2.11/fastapi_cachex/__init__.py

@@ -1,27 +0,0 @@
-"""FastAPI-CacheX: A powerful and flexible caching extension for FastAPI."""
-
-import logging
-
-from .cache import cache as cache
-from .cache import default_key_builder as default_key_builder
-from .dependencies import CacheBackend as CacheBackend
-from .dependencies import get_cache_backend as get_cache_backend
-from .proxy import BackendProxy as BackendProxy
-from .routes import add_routes as add_routes
-from .types import CacheKeyBuilder as CacheKeyBuilder
-
-_package_logger = logging.getLogger("fastapi_cachex")
-_package_logger.addHandler(
-    logging.NullHandler()
-)  # Attach a NullHandler to avoid "No handler found" warnings in user applications.
-
-# Session management (optional feature)
-__all__ = [
-    "BackendProxy",
-    "CacheBackend",
-    "CacheKeyBuilder",
-    "add_routes",
-    "cache",
-    "default_key_builder",
-    "get_cache_backend",
-]

fastapi_cachex-0.2.11/fastapi_cachex/backends/config.py

@@ -1,15 +0,0 @@
-"""Configuration models for cache backends."""
-
-from pydantic import BaseModel
-from pydantic import Field
-from pydantic import SecretStr
-
-
-class RedisConfig(BaseModel):
-    """Configuration for Redis backend."""
-
-    host: str = Field(default="localhost", description="Redis server address")
-    port: int = Field(default=6379, description="Redis server port")
-    password: SecretStr | None = Field(
-        default=None, description="Redis server password"
-    )