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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.2.12
+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
@@ -146,6 +148,44 @@ async def remove_cache(cache: CacheBackend):
     await cache.clear_pattern("/path/to/clear/*")  # Clear cache for a specific pattern
 ```
 
+### Application-Level Caching (Manual Get/Set)
+
+Beyond HTTP response caching via `@cache`, you can cache arbitrary JSON-serializable
+Python values directly in your business logic using `CacheManager`. It's a thin,
+namespaced wrapper around whichever backend is configured via `BackendProxy`.
+
+```python
+from fastapi_cachex import AppCache, CacheManager
+
+@app.get("/expensive")
+async def expensive_operation(cache: AppCache):
+    result = await cache.get("expensive:result")
+    if result is None:
+        result = perform_expensive_calculation()
+        await cache.set("expensive:result", result, ttl=300)
+    return result
+
+
+# Or instantiate directly, e.g. outside of a request:
+manager = CacheManager(key_prefix="myapp:", default_ttl=60)
+await manager.set("user:42", {"name": "Alice"})
+user = await manager.get("user:42")  # {"name": "Alice"}
+await manager.delete("user:42")
+await manager.clear_prefix()  # clear everything under "myapp:"
+```
+
+`CacheManager.get()` returns `None` (or a supplied `default=`) on a cache miss —
+it never raises for missing or corrupted entries. `CacheManager` keys live under
+their own `cache:`-prefixed namespace by default, separate from the HTTP route
+cache and OAuth state, so `clear()`/`clear_prefix()` never touch unrelated cache
+entries.
+
+**Note**: `clear()`/`clear_prefix()` are implemented via the backend's
+`get_all_keys()`. Since Memcached doesn't support key enumeration (see
+[Memcached limitations](#memcached)), these two methods are no-ops on a
+Memcached backend — `get()`/`set()`/`delete()`/`has()` work normally. Use
+Redis or the in-memory backend if you need bulk clearing.
+
 ## Backend Configuration
 
 FastAPI-CacheX supports multiple caching backends. You can easily switch between them using the `BackendProxy`.
@@ -166,6 +206,8 @@ This ensures that:
 
 All backends automatically namespace keys with a prefix (e.g., `fastapi_cachex:`) to avoid conflicts with other applications.
 
+`CacheManager` (see [Application-Level Caching](#application-level-caching-manual-getset)) uses a separate, simpler `cache:`-prefixed key namespace instead of this `|||`-separated format, since its keys aren't tied to HTTP requests.
+
 ### Cache Hit Behavior
 
 When a cached entry is valid (within TTL):

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.1}/README.md

@@ -110,6 +110,44 @@ async def remove_cache(cache: CacheBackend):
     await cache.clear_pattern("/path/to/clear/*")  # Clear cache for a specific pattern
 ```
 
+### Application-Level Caching (Manual Get/Set)
+
+Beyond HTTP response caching via `@cache`, you can cache arbitrary JSON-serializable
+Python values directly in your business logic using `CacheManager`. It's a thin,
+namespaced wrapper around whichever backend is configured via `BackendProxy`.
+
+```python
+from fastapi_cachex import AppCache, CacheManager
+
+@app.get("/expensive")
+async def expensive_operation(cache: AppCache):
+    result = await cache.get("expensive:result")
+    if result is None:
+        result = perform_expensive_calculation()
+        await cache.set("expensive:result", result, ttl=300)
+    return result
+
+
+# Or instantiate directly, e.g. outside of a request:
+manager = CacheManager(key_prefix="myapp:", default_ttl=60)
+await manager.set("user:42", {"name": "Alice"})
+user = await manager.get("user:42")  # {"name": "Alice"}
+await manager.delete("user:42")
+await manager.clear_prefix()  # clear everything under "myapp:"
+```
+
+`CacheManager.get()` returns `None` (or a supplied `default=`) on a cache miss —
+it never raises for missing or corrupted entries. `CacheManager` keys live under
+their own `cache:`-prefixed namespace by default, separate from the HTTP route
+cache and OAuth state, so `clear()`/`clear_prefix()` never touch unrelated cache
+entries.
+
+**Note**: `clear()`/`clear_prefix()` are implemented via the backend's
+`get_all_keys()`. Since Memcached doesn't support key enumeration (see
+[Memcached limitations](#memcached)), these two methods are no-ops on a
+Memcached backend — `get()`/`set()`/`delete()`/`has()` work normally. Use
+Redis or the in-memory backend if you need bulk clearing.
+
 ## Backend Configuration
 
 FastAPI-CacheX supports multiple caching backends. You can easily switch between them using the `BackendProxy`.
@@ -130,6 +168,8 @@ This ensures that:
 
 All backends automatically namespace keys with a prefix (e.g., `fastapi_cachex:`) to avoid conflicts with other applications.
 
+`CacheManager` (see [Application-Level Caching](#application-level-caching-manual-getset)) uses a separate, simpler `cache:`-prefixed key namespace instead of this `|||`-separated format, since its keys aren't tied to HTTP requests.
+
 ### Cache Hit Behavior
 
 When a cached entry is valid (within TTL):

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

@@ -4,10 +4,16 @@ 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
 from .dependencies import get_cache_backend as get_cache_backend
+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
@@ -30,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")
@@ -38,9 +47,13 @@ _package_logger.addHandler(
 )  # Attach a NullHandler to avoid "No handler found" warnings in user applications.
 
 __all__ = [
+    "AppCache",
     "BackendProxy",
     "CacheBackend",
     "CacheKeyBuilder",
+    "CacheManager",
+    "CacheManagerProxy",
+    "FastAPICacheXSessionMiddleware",
     "InvalidStateError",
     "Session",
     "SessionConfig",
@@ -59,12 +72,17 @@ __all__ = [
     "StateError",
     "StateExpiredError",
     "StateManager",
+    "StateManagerDep",
+    "StateManagerProxy",
     "add_routes",
     "cache",
     "default_key_builder",
+    "get_app_cache",
     "get_cache_backend",
     "get_optional_session",
     "get_session",
     "get_session_manager",
+    "get_state_manager",
+    "invalidate",
     "require_session",
 ]

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.1}/fastapi_cachex/backends/base.py

@@ -4,18 +4,18 @@ from abc import ABC
 from abc import abstractmethod
 from typing import Any
 
-from fastapi_cachex.types import ETagContent
+from fastapi_cachex.types import CacheEntry
 
 
 class BaseCacheBackend(ABC):
     """Base class for all cache backends."""
 
     @abstractmethod
-    async def get(self, key: str) -> ETagContent | None:
+    async def get(self, key: str) -> CacheEntry | None:
         """Retrieve a cached response."""
 
     @abstractmethod
-    async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
+    async def set(self, key: str, value: CacheEntry, ttl: int | None = None) -> None:
         """Store a response in the cache."""
 
     @abstractmethod

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

@@ -5,7 +5,7 @@ import logging
 import warnings
 
 from fastapi_cachex.exceptions import CacheXError
-from fastapi_cachex.types import ETagContent
+from fastapi_cachex.types import CacheEntry
 
 from .base import BaseCacheBackend
 
@@ -63,18 +63,17 @@ class MemcachedBackend(BaseCacheBackend):
         """Add prefix to cache key."""
         return f"{self.key_prefix}{key}"
 
-    async def get(self, key: str) -> ETagContent | None:
+    async def get(self, key: str) -> CacheEntry | None:
         """Get value from cache.
 
         Args:
             key: Cache key to retrieve
 
         Returns:
-            Optional[ETagContent]: Cached value with ETag if exists, None otherwise
+            Cached entry if found, None otherwise
         """
         prefixed_key = self._make_key(key)
-        loop = asyncio.get_running_loop()
-        value = await loop.run_in_executor(None, self.client.get, prefixed_key)
+        value = await asyncio.to_thread(self.client.get, prefixed_key)
         if value is None:
             logger.debug("Memcached MISS; key=%s", key)
             return None
@@ -83,8 +82,8 @@ class MemcachedBackend(BaseCacheBackend):
         try:
             data = json.loads(value)
             logger.debug("Memcached HIT; key=%s", key)
-            return ETagContent(
-                etag=data["etag"],
+            return CacheEntry(
+                fingerprint=data["fingerprint"],
                 content=data["content"].encode("latin-1"),
                 media_type=data.get("media_type"),
             )
@@ -92,12 +91,12 @@ class MemcachedBackend(BaseCacheBackend):
             logger.debug("Memcached DESERIALIZE ERROR; key=%s", key)
             return None
 
-    async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
+    async def set(self, key: str, value: CacheEntry, ttl: int | None = None) -> None:
         """Set value in cache.
 
         Args:
             key: Cache key
-            value: ETagContent to store
+            value: CacheEntry instance to store
             ttl: Time to live in seconds
         """
         prefixed_key = self._make_key(key)
@@ -107,7 +106,7 @@ class MemcachedBackend(BaseCacheBackend):
 
         serialized_data: str | bytes = json.dumps(
             {
-                "etag": value.etag,
+                "fingerprint": value.fingerprint,
                 "content": content,
                 "media_type": value.media_type,
             },
@@ -121,11 +120,7 @@ class MemcachedBackend(BaseCacheBackend):
         )
 
         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),
-        )
+        await asyncio.to_thread(self.client.set, prefixed_key, serialized_bytes, expire)
         logger.debug("Memcached SET; key=%s ttl=%s", key, ttl)
 
     async def delete(self, key: str) -> None:
@@ -135,8 +130,7 @@ class MemcachedBackend(BaseCacheBackend):
             key: Cache key to delete
         """
         prefixed = self._make_key(key)
-        loop = asyncio.get_running_loop()
-        await loop.run_in_executor(None, self.client.delete, prefixed)
+        await asyncio.to_thread(self.client.delete, prefixed)
         logger.debug("Memcached DELETE; key=%s", key)
 
     async def clear(self) -> None:
@@ -152,8 +146,7 @@ class MemcachedBackend(BaseCacheBackend):
             RuntimeWarning,
             stacklevel=2,
         )
-        loop = asyncio.get_running_loop()
-        await loop.run_in_executor(None, self.client.flush_all)
+        await asyncio.to_thread(self.client.flush_all)
         logger.debug("Memcached CLEAR; flush_all issued")
 
     async def clear_path(self, path: str, include_params: bool = False) -> int:
@@ -183,11 +176,9 @@ 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 = await loop.run_in_executor(
-                None,
-                lambda: self.client.delete(prefixed_key, noreply=False),
+            result = await asyncio.to_thread(
+                self.client.delete, prefixed_key, noreply=False
             )
         except Exception:  # noqa: BLE001
             return 0
@@ -245,7 +236,7 @@ class MemcachedBackend(BaseCacheBackend):
         logger.debug("Memcached GET_ALL_KEYS unsupported; returning empty list")
         return []
 
-    async def get_cache_data(self) -> dict[str, tuple[ETagContent, float | None]]:
+    async def get_cache_data(self) -> dict[str, tuple[CacheEntry, float | None]]:
         """Get all cache data with expiry information.
 
         Note: Memcached does not support key enumeration or pattern matching.

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

@@ -6,8 +6,8 @@ import logging
 import time
 
 from fastapi_cachex.types import CACHE_KEY_SEPARATOR
+from fastapi_cachex.types import CacheEntry
 from fastapi_cachex.types import CacheItem
-from fastapi_cachex.types import ETagContent
 
 from .base import BaseCacheBackend
 
@@ -68,7 +68,7 @@ class MemoryBackend(BaseCacheBackend):
             self._cleanup_task = None
             logger.debug("Stopped memory backend cleanup task")
 
-    async def get(self, key: str) -> ETagContent | None:
+    async def get(self, key: str) -> CacheEntry | None:
         """Retrieve a cached response.
 
         Expired entries are skipped and return None.
@@ -89,7 +89,7 @@ class MemoryBackend(BaseCacheBackend):
             logger.debug("Memory cache MISS; key=%s", key)
             return None
 
-    async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
+    async def set(self, key: str, value: CacheEntry, ttl: int | None = None) -> None:
         """Store a response in the cache.
 
         Args:
@@ -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]
@@ -201,11 +206,11 @@ class MemoryBackend(BaseCacheBackend):
         async with self.lock:
             return list(self.cache.keys())
 
-    async def get_cache_data(self) -> dict[str, tuple[ETagContent, float | None]]:
+    async def get_cache_data(self) -> dict[str, tuple[CacheEntry, float | None]]:
         """Get all cache data with expiry information.
 
         Returns:
-            Dictionary mapping cache keys to (ETagContent, expiry) tuples
+            Dictionary mapping cache keys to (CacheEntry, expiry) tuples
         """
         async with self.lock:
             return {key: (item.value, item.expiry) for key, item in self.cache.items()}

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

@@ -11,7 +11,7 @@ from fastapi_cachex.backends.config import (
 from fastapi_cachex.backends.config import RedisConfig
 from fastapi_cachex.exceptions import CacheXError
 from fastapi_cachex.types import CACHE_KEY_SEPARATOR
-from fastapi_cachex.types import ETagContent
+from fastapi_cachex.types import CacheEntry
 
 from .base import BaseCacheBackend
 
@@ -125,14 +125,14 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         """Add prefix to cache key."""
         return f"{self.key_prefix}{key}"
 
-    def _serialize(self, value: ETagContent) -> str:
-        """Serialize ETagContent to JSON string."""
+    def _serialize(self, value: CacheEntry) -> str:
+        """Serialize CacheEntry to JSON string."""
         # 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,
+                "fingerprint": value.fingerprint,
                 "content": content,
                 "media_type": value.media_type,
             },
@@ -141,8 +141,8 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         # orjson returns bytes, stdlib json returns str
         return serialized.decode() if isinstance(serialized, bytes) else serialized
 
-    def _deserialize(self, value: str | None) -> ETagContent | None:
-        """Deserialize JSON string to ETagContent.
+    def _deserialize(self, value: str | None) -> CacheEntry | None:
+        """Deserialize JSON string to CacheEntry.
 
         Converts string content back to bytes to maintain consistency with
         other backends and standard Response.body type (bytes).
@@ -152,22 +152,22 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         try:
             data = json.loads(value)
             logger.debug("Content type in JSON: %s", type(data["content"]))
-            return ETagContent(
-                etag=data["etag"],
+            return CacheEntry(
+                fingerprint=data["fingerprint"],
                 content=data["content"].encode("latin-1"),
                 media_type=data.get("media_type"),
             )
         except (json.JSONDecodeError, KeyError, AttributeError):
             return None
 
-    async def get(self, key: str) -> ETagContent | None:
+    async def get(self, key: str) -> CacheEntry | None:
         """Retrieve a cached response."""
         result = await self.client.get(self._make_key(key))
         value = self._deserialize(result)
         logger.debug("Redis %s; key=%s", "HIT" if value else "MISS", key)
         return value
 
-    async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
+    async def set(self, key: str, value: CacheEntry, ttl: int | None = None) -> None:
         """Store a response in the cache."""
         serialized = self._serialize(value)
         prefixed_key = self._make_key(key)
@@ -327,7 +327,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         """Get all cache keys in the backend.
 
         Returns:
-            List of all cache keys currently stored in the backend
+            List of logical cache keys (without the backend key prefix)
         """
         pattern = f"{self.key_prefix}*"
         cursor = 0
@@ -346,34 +346,34 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
             if cursor == 0:
                 break
 
-        logger.debug("Redis GET_ALL_KEYS; count=%s", len(all_keys))
-        return all_keys
+        logical_keys = [k.removeprefix(self.key_prefix) for k in all_keys]
+        logger.debug("Redis GET_ALL_KEYS; count=%s", len(logical_keys))
+        return logical_keys
 
-    async def get_cache_data(self) -> dict[str, tuple[ETagContent, float | None]]:
+    async def get_cache_data(self) -> dict[str, tuple[CacheEntry, float | None]]:
         """Get all cache data with expiry information.
 
         Returns:
-            Dictionary mapping cache keys to (ETagContent, expiry) tuples.
+            Dictionary mapping cache keys to (CacheEntry, expiry) tuples.
             Note: Redis stores TTL but not absolute expiry time, so this
             returns None for expiry (no expiry tracking in Redis backend).
         """
         all_keys = await self.get_all_keys()
-        cache_data: dict[str, tuple[ETagContent, float | None]] = {}
+        cache_data: dict[str, tuple[CacheEntry, 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:
-            pipe.get(prefixed_key)
+        for key in all_keys:
+            pipe.get(self._make_key(key))
         raw_values: list[str | None] = await pipe.execute()
 
-        for prefixed_key, raw in zip(all_keys, raw_values, strict=False):
-            original_key = prefixed_key.removeprefix(self.key_prefix)
+        for key, raw in zip(all_keys, raw_values, strict=False):
             value = self._deserialize(raw)
             if value is not None:
-                cache_data[original_key] = (value, None)
+                cache_data[key] = (value, None)
 
         logger.debug("Redis GET_CACHE_DATA; keys=%s", len(cache_data))
         return cache_data

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

@@ -25,8 +25,8 @@ from .exceptions import CacheXError
 from .exceptions import RequestNotFoundError
 from .proxy import BackendProxy
 from .types import CACHE_KEY_SEPARATOR
+from .types import CacheEntry
 from .types import CacheKeyBuilder
-from .types import ETagContent
 
 if TYPE_CHECKING:
     from fastapi.routing import APIRoute
@@ -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."""
 
@@ -85,6 +123,11 @@ class CacheControl:
         return ", ".join(self.directives)
 
 
+def _get_response_body(response: Response) -> bytes | None:
+    """Return response body bytes, or None for streaming/file responses."""
+    return getattr(response, "body", None)
+
+
 async def get_response(
     __func: HandlerCallable,
     __request: Request,
@@ -151,10 +194,16 @@ def cache(
     """
 
     def decorator(func: HandlerCallable) -> AsyncResponseCallable:
-        # Validate stale parameters eagerly at decoration time
+        # Validate 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)
+        if stale_ttl is not None and stale is None:
+            msg = "stale must be set if stale_ttl is used"
+            raise CacheXError(msg)
+        if public and private:
+            msg = "public and private are mutually exclusive"
+            raise CacheXError(msg)
 
         # Analyze the original function's signature
         sig: Signature = inspect.signature(func)
@@ -266,14 +315,12 @@ def cache(
                 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)
+                    current_body = _get_response_body(current_response)
                     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
-                    )
+                    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
@@ -287,9 +334,7 @@ def cache(
                         )
 
                 # Compare with cached ETag - if match, return 304
-                elif (
-                    cached_data and client_etag == cached_data.etag
-                ):  # pragma: no branch
+                elif cached_data and client_etag == cached_data.fingerprint:
                     # Cache hit with matching ETag: return 304 Not Modified
                     logger.debug(
                         "304 Not Modified (cached ETag match); key=%s", cache_key
@@ -297,7 +342,7 @@ def cache(
                     return Response(
                         status_code=HTTP_304_NOT_MODIFIED,
                         headers={
-                            "ETag": cached_data.etag,
+                            "ETag": cached_data.fingerprint,
                             "Cache-Control": cache_control,
                         },
                     )
@@ -313,7 +358,7 @@ def cache(
                     status_code=200,
                     media_type=cached_data.media_type,
                     headers={
-                        "ETag": cached_data.etag,
+                        "ETag": cached_data.fingerprint,
                         "Cache-Control": cache_control,
                     },
                 )
@@ -321,7 +366,7 @@ 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_body = getattr(current_response, "body", None)
+                current_body = _get_response_body(current_response)
                 if current_body is None:
                     # StreamingResponse/FileResponse — cannot compute ETag; serve as-is
                     current_response.headers["Cache-Control"] = cache_control
@@ -333,17 +378,17 @@ def cache(
             current_response.headers["ETag"] = current_etag
 
             # 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)
+            if not cached_data or cached_data.fingerprint != current_etag:
+                assert (
+                    current_body is not None
+                )  # guaranteed by early-return guards above
                 # Store in cache if data changed
                 await cache_backend.set(
                     cache_key,
-                    ETagContent(
-                        current_etag,
-                        current_body,
-                        current_response.media_type,
+                    CacheEntry(
+                        fingerprint=current_etag,
+                        content=current_body,
+                        media_type=current_response.media_type,
                     ),
                     ttl=ttl,
                 )