fastapi-cachex 0.3.6__tar.gz → 0.3.7__tar.gz

{fastapi_cachex-0.3.6 → fastapi_cachex-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.3.6
+Version: 0.3.7
 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
@@ -50,9 +50,9 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://img.shields.io/pypi/v/fastapi-cachex.svg?logo=pypi&logoColor=gold&label=PyPI)](https://pypi.org/project/fastapi-cachex)
 [![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-cachex.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/fastapi-cachex/)
 
-[English](https://github.com/allen0099/FastAPI-CacheX/blob/master/README.md) | [繁體中文](https://github.com/allen0099/FastAPI-CacheX/blob/master/docs/README.zh-TW.md)
+[English](https://github.com/allen0099/FastAPI-CacheX/blob/master/README.md) | [繁體中文](https://github.com/allen0099/FastAPI-CacheX/blob/master/i18n/zh-TW/docs/index.md)
 
-A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support and optional session management.
+A high-performance caching extension for FastAPI: a server-side response cache with `Cache-Control` and `ETag` support, application-level caching, and optional session management.
 
 **Documentation:** <https://fastapi-cachex.readthedocs.io/en/latest/> — guides and the full API reference.
 
@@ -61,7 +61,7 @@ A high-performance caching extension for FastAPI, providing comprehensive HTTP c
 - **HTTP caching** — a `@cache` decorator for GET routes with `Cache-Control`,
   `ETag` / `If-None-Match` (304) and per-route invalidation.
 - **Application cache** — `CacheManager` for caching arbitrary JSON values in
-  your own code, with compute-on-miss `get_or_set()`.
+  your own code, with compute-on-miss `get_or_set()` and atomic store-if-absent `add()`.
 - **Backends** — in-memory, Redis and Memcached, with atomic counters,
   one-shot values and locks.
 - **Sessions (optional)** — HMAC-signed or JWT session tokens over headers,

{fastapi_cachex-0.3.6 → fastapi_cachex-0.3.7}/README.md

@@ -12,9 +12,9 @@
 [![PyPI version](https://img.shields.io/pypi/v/fastapi-cachex.svg?logo=pypi&logoColor=gold&label=PyPI)](https://pypi.org/project/fastapi-cachex)
 [![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-cachex.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/fastapi-cachex/)
 
-[English](https://github.com/allen0099/FastAPI-CacheX/blob/master/README.md) | [繁體中文](https://github.com/allen0099/FastAPI-CacheX/blob/master/docs/README.zh-TW.md)
+[English](https://github.com/allen0099/FastAPI-CacheX/blob/master/README.md) | [繁體中文](https://github.com/allen0099/FastAPI-CacheX/blob/master/i18n/zh-TW/docs/index.md)
 
-A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support and optional session management.
+A high-performance caching extension for FastAPI: a server-side response cache with `Cache-Control` and `ETag` support, application-level caching, and optional session management.
 
 **Documentation:** <https://fastapi-cachex.readthedocs.io/en/latest/> — guides and the full API reference.
 
@@ -23,7 +23,7 @@ A high-performance caching extension for FastAPI, providing comprehensive HTTP c
 - **HTTP caching** — a `@cache` decorator for GET routes with `Cache-Control`,
   `ETag` / `If-None-Match` (304) and per-route invalidation.
 - **Application cache** — `CacheManager` for caching arbitrary JSON values in
-  your own code, with compute-on-miss `get_or_set()`.
+  your own code, with compute-on-miss `get_or_set()` and atomic store-if-absent `add()`.
 - **Backends** — in-memory, Redis and Memcached, with atomic counters,
   one-shot values and locks.
 - **Sessions (optional)** — HMAC-signed or JWT session tokens over headers,

{fastapi_cachex-0.3.6 → fastapi_cachex-0.3.7}/fastapi_cachex/backends/base.py

@@ -35,6 +35,23 @@ def warn_if_path_shaped(pattern: str, cleared: int) -> None:
         )
 
 
+def validate_ttl(ttl: int | None) -> int | None:
+    """Return ``ttl`` if it is ``None`` or a positive number of seconds.
+
+    Every backend reads ``0`` or a negative TTL differently (Memcached treats
+    ``0`` as "never expires", Redis rejects it, the memory backend expires the
+    entry at once), so the library refuses them instead of letting the
+    meaning depend on the backend. ``None`` is the way to say "no expiry".
+
+    Raises:
+        ValueError: If ``ttl`` is zero or negative
+    """
+    if ttl is not None and ttl <= 0:
+        msg = f"ttl must be a positive number of seconds or None, got {ttl!r}"
+        raise ValueError(msg)
+    return ttl
+
+
 class BaseCacheBackend(ABC):
     """Base class for all cache backends."""
 
@@ -44,7 +61,12 @@ class BaseCacheBackend(ABC):
 
     @abstractmethod
     async def set(self, key: str, value: CacheEntry, ttl: int | None = None) -> None:
-        """Store a response in the cache."""
+        """Store a response in the cache.
+
+        ``ttl`` is ``None`` (never expires) or a positive number of seconds;
+        implementations should pass it through ``validate_ttl`` so zero and
+        negative values are rejected the same way on every backend.
+        """
 
     @abstractmethod
     async def delete(self, key: str) -> None:
@@ -55,8 +77,9 @@ class BaseCacheBackend(ABC):
 
         The base implementation deletes one key at a time and reports how
         many were attempted, since ``delete`` does not say whether the key
-        existed. The built-in backends override it with a single batched
-        operation that counts what was actually removed.
+        existed. The memory and Redis backends override it with a single
+        batched operation that counts what was actually removed; Memcached
+        keeps this per-key loop.
         """
         count = 0
         for key in keys:
@@ -106,6 +129,7 @@ class BaseCacheBackend(ABC):
         Returns:
             Whether ``value`` was stored
         """
+        validate_ttl(ttl)
         if await self.get(key) is not None:
             return False
         await self.set(key, value, ttl=ttl)
@@ -161,6 +185,7 @@ class BaseCacheBackend(ABC):
         Raises:
             CacheXError: If ``key`` holds a cached response instead of a counter
         """
+        validate_ttl(ttl)
         current = await self.get(key)
         value = delta if current is None else counter_value(current) + delta
         await self.set(key, counter_entry(value), ttl=ttl)

{fastapi_cachex-0.3.6 → fastapi_cachex-0.3.7}/fastapi_cachex/backends/memcached.py

@@ -12,6 +12,7 @@ from fastapi_cachex.exceptions import CacheXError
 from fastapi_cachex.types import CacheEntry
 
 from .base import BaseCacheBackend
+from .base import validate_ttl
 
 logger = logging.getLogger(__name__)
 
@@ -141,6 +142,7 @@ class MemcachedBackend(BaseCacheBackend):
             value: CacheEntry instance to store
             ttl: Time to live in seconds
         """
+        validate_ttl(ttl)
         await asyncio.to_thread(
             self.client.set, self._make_key(key), encode_entry(value), _expiry(ttl)
         )
@@ -174,6 +176,7 @@ class MemcachedBackend(BaseCacheBackend):
 
         Memcached's ``ADD`` is exactly this operation.
         """
+        validate_ttl(ttl)
         stored = await asyncio.to_thread(
             self.client.add,
             self._make_key(key),
@@ -226,6 +229,7 @@ class MemcachedBackend(BaseCacheBackend):
         Memcached counters are unsigned, so a negative ``delta`` uses DECR,
         which stops at 0 instead of going negative.
         """
+        validate_ttl(ttl)
         from pymemcache.exceptions import MemcacheClientError
 
         prefixed_key = self._make_key(key)
@@ -260,13 +264,16 @@ class MemcachedBackend(BaseCacheBackend):
     async def clear(self) -> None:
         """Clear all values from cache.
 
-        Note: Memcached's flush_all affects the entire server.
-        Consider using clear_path() with your specific keys instead.
+        Note: Memcached's flush_all affects the entire server, including
+        other applications' keys. Memcached cannot enumerate keys, so there
+        is no way to clear only this namespace; delete keys you know by name
+        with ``delete()``/``delete_many()`` instead.
         """
         warnings.warn(
             "Memcached.clear() flushes ALL cached data from the server, "
-            "affecting other applications. Consider using clear_path() instead "
-            "to selectively remove only this namespace's keys.",
+            "affecting other applications. Memcached cannot enumerate keys, so "
+            "this namespace cannot be cleared on its own; delete known keys "
+            "with delete() or delete_many() instead.",
             RuntimeWarning,
             stacklevel=2,
         )
@@ -276,14 +283,15 @@ class MemcachedBackend(BaseCacheBackend):
     async def clear_path(self, path: str, include_params: bool = False) -> int:
         """Clear cached responses for a specific path.
 
-        Note: Memcached does not support pattern-based queries.
-        This method can only delete keys if the exact key is provided,
-        or will try to match keys in memory if include_params=True.
-        For better pattern support, consider using Redis backend.
+        Note: Memcached does not support pattern-based queries, so this
+        only deletes the key that is exactly ``path``. HTTP route keys
+        (``method|||host|||path|||query``) are not matched. For path-based
+        clearing, use the Redis or memory backend.
 
         Args:
-            path: The path to clear cache for
-            include_params: Currently unsupported (Memcached limitation)
+            path: The exact key to delete
+            include_params: Unsupported; emits a ``RuntimeWarning`` and is
+                otherwise ignored
 
         Returns:
             Number of cache entries cleared (0 or 1 for exact match only)

{fastapi_cachex-0.3.6 → fastapi_cachex-0.3.7}/fastapi_cachex/backends/memory.py

@@ -14,6 +14,7 @@ from fastapi_cachex.types import counter_entry
 from fastapi_cachex.types import counter_value
 
 from .base import BaseCacheBackend
+from .base import validate_ttl
 from .base import warn_if_path_shaped
 
 logger = logging.getLogger(__name__)
@@ -123,6 +124,7 @@ class MemoryBackend(BaseCacheBackend):
             value: Content to cache
             ttl: Time to live in seconds (None = never expires)
         """
+        validate_ttl(ttl)
         self._ensure_cleanup_started()
 
         async with self.lock:
@@ -161,6 +163,7 @@ class MemoryBackend(BaseCacheBackend):
         self, key: str, value: CacheEntry, ttl: int | None = None
     ) -> bool:
         """Atomically store ``value`` unless ``key`` exists (see base class)."""
+        validate_ttl(ttl)
         self._ensure_cleanup_started()
 
         async with self.lock:
@@ -194,6 +197,7 @@ class MemoryBackend(BaseCacheBackend):
         The read-modify-write happens under the backend lock, so concurrent
         callers on the same event loop never lose an increment.
         """
+        validate_ttl(ttl)
         self._ensure_cleanup_started()
 
         async with self.lock:

{fastapi_cachex-0.3.6 → fastapi_cachex-0.3.7}/fastapi_cachex/backends/redis.py

@@ -1,6 +1,7 @@
 """Redis cache backend implementation."""
 
 import logging
+import time
 from collections.abc import Iterable
 from typing import TYPE_CHECKING
 from typing import Any
@@ -15,6 +16,7 @@ from fastapi_cachex.types import CACHE_KEY_SEPARATOR
 from fastapi_cachex.types import CacheEntry
 
 from .base import BaseCacheBackend
+from .base import validate_ttl
 from .base import warn_if_path_shaped
 
 if TYPE_CHECKING:
@@ -22,9 +24,22 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+# PTTL replies that are not a remaining lifetime.
+_PTTL_NO_EXPIRY = -1
+_PTTL_MISSING = -2
+
 # SCAN page size and DEL batch size; keeps individual commands small.
 _BATCH_SIZE = 100
 
+# Characters that are live in a Redis glob pattern.
+_GLOB_SPECIAL = frozenset("*?[]\\")
+
+
+def _escape_glob(text: str) -> str:
+    """Backslash-escape ``text`` so a Redis glob pattern matches it literally."""
+    return "".join(f"\\{ch}" if ch in _GLOB_SPECIAL else ch for ch in text)
+
+
 # INCRBY that attaches a TTL only when it creates the key, so a counter lives in
 # a fixed window. KEYS[1] = key, ARGV[1] = delta, ARGV[2] = ttl (0 = none).
 _INCREMENT_SCRIPT = """
@@ -148,6 +163,11 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         """Add prefix to cache key."""
         return f"{self.key_prefix}{key}"
 
+    @property
+    def _prefix_pattern(self) -> str:
+        """The key prefix as a literal glob, so ``*``/``?``/``[`` in it stay inert."""
+        return _escape_glob(self.key_prefix)
+
     async def _scan_keys(self, pattern: str) -> list[str]:
         """Collect every key matching ``pattern`` (a full, prefixed glob).
 
@@ -178,6 +198,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
 
     async def set(self, key: str, value: CacheEntry, ttl: int | None = None) -> None:
         """Store a response in the cache."""
+        validate_ttl(ttl)
         await self.client.set(self._make_key(key), encode_entry(value), ex=ttl)
         logger.debug("Redis SET; key=%s ttl=%s", key, ttl)
 
@@ -208,6 +229,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
 
         A single ``SET ... NX EX``.
         """
+        validate_ttl(ttl)
         stored = await self.client.set(
             self._make_key(key), encode_entry(value), ex=ttl, nx=True
         )
@@ -243,6 +265,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         A short Lua script makes the increment and the expiry one server-side
         operation; the key is stored as a plain Redis integer.
         """
+        validate_ttl(ttl)
         from redis.exceptions import ResponseError
 
         try:
@@ -262,7 +285,9 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
 
         Only deletes keys within this backend's prefix.
         """
-        removed = await self._delete_keys(await self._scan_keys(f"{self.key_prefix}*"))
+        removed = await self._delete_keys(
+            await self._scan_keys(f"{self._prefix_pattern}*")
+        )
         logger.debug("Redis CLEAR; removed=%s", removed)
 
     async def clear_path(self, path: str, include_params: bool = False) -> int:
@@ -277,9 +302,13 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         """
         # Keys are method|||host|||path|||query. Without include_params only the
         # exact path is matched: default_key_builder always appends a separator
-        # after the path, so keys with no query params end with "|||".
+        # after the path, so keys with no query params end with "|||". The
+        # path is a literal, not a glob: "/files/[draft]" means those brackets.
         suffix = "*" if include_params else ""
-        pattern = f"{self.key_prefix}*{CACHE_KEY_SEPARATOR}{path}{CACHE_KEY_SEPARATOR}{suffix}"
+        pattern = (
+            f"{self._prefix_pattern}*{CACHE_KEY_SEPARATOR}"
+            f"{_escape_glob(path)}{CACHE_KEY_SEPARATOR}{suffix}"
+        )
         keys = await self._scan_keys(pattern)
 
         # Also match direct keys (custom key formats without separators)
@@ -300,15 +329,16 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
     async def clear_pattern(self, pattern: str) -> int:
         """Clear cached responses matching a pattern.
 
+        Only ``pattern`` is a live glob; the backend's key prefix is matched
+        literally, whether or not ``pattern`` repeats it.
+
         Args:
             pattern: A glob pattern to match cache keys against
 
         Returns:
             Number of cache entries cleared
         """
-        full_pattern = (
-            pattern if pattern.startswith(self.key_prefix) else self._make_key(pattern)
-        )
+        full_pattern = self._prefix_pattern + pattern.removeprefix(self.key_prefix)
         cleared_count = await self._delete_keys(await self._scan_keys(full_pattern))
         warn_if_path_shaped(pattern, cleared_count)
         logger.debug(
@@ -322,7 +352,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         Returns:
             List of logical cache keys (without the backend key prefix)
         """
-        keys = await self._scan_keys(f"{self.key_prefix}*")
+        keys = await self._scan_keys(f"{self._prefix_pattern}*")
         logical_keys = [k.removeprefix(self.key_prefix) for k in keys]
         logger.debug("Redis GET_ALL_KEYS; count=%s", len(logical_keys))
         return logical_keys
@@ -331,9 +361,10 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         """Get all cache data with expiry information.
 
         Returns:
-            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).
+            Dictionary mapping cache keys to (CacheEntry, expiry) tuples, where
+            expiry is an absolute ``time.time()`` timestamp like the memory
+            backend reports, or None for a key without a TTL. It is derived
+            from each key's ``PTTL``, so it is accurate to the round-trip.
         """
         all_keys = await self.get_all_keys()
         cache_data: dict[str, tuple[CacheEntry, float | None]] = {}
@@ -341,16 +372,25 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         if not all_keys:
             return cache_data
 
-        # Fetch all values in a single pipeline round-trip instead of N+1 GETs
+        # Fetch every value and its remaining lifetime in a single pipeline
+        # round-trip instead of 2N commands.
         pipe = self.client.pipeline()
         for key in all_keys:
-            pipe.get(self._make_key(key))
-        raw_values: list[str | None] = await pipe.execute()
-
-        for key, raw in zip(all_keys, raw_values, strict=False):
+            redis_key = self._make_key(key)
+            pipe.get(redis_key)
+            pipe.pttl(redis_key)
+        replies: list[Any] = await pipe.execute()
+        now = time.time()
+
+        for key, raw, pttl in zip(all_keys, replies[::2], replies[1::2], strict=True):
+            # -2: the key expired or was deleted between SCAN and this fetch.
+            if pttl == _PTTL_MISSING:
+                continue
             value = decode_entry(raw)
-            if value is not None:
-                cache_data[key] = (value, None)
+            if value is None:
+                continue
+            expiry = None if pttl == _PTTL_NO_EXPIRY else now + pttl / 1000
+            cache_data[key] = (value, expiry)
 
         logger.debug("Redis GET_CACHE_DATA; keys=%s", len(cache_data))
         return cache_data

{fastapi_cachex-0.3.6 → fastapi_cachex-0.3.7}/fastapi_cachex/cache.py

@@ -21,6 +21,10 @@ from typing import get_type_hints
 
 from fastapi import Request
 from fastapi import Response
+from fastapi.encoders import jsonable_encoder
+from fastapi.utils import is_body_allowed_for_status_code
+from pydantic import TypeAdapter
+from starlette.concurrency import run_in_threadpool
 from starlette.status import HTTP_200_OK
 from starlette.status import HTTP_206_PARTIAL_CONTENT
 from starlette.status import HTTP_300_MULTIPLE_CHOICES
@@ -303,6 +307,51 @@ async def _render(
     return response, body, None if body is None else _etag_for(body)
 
 
+# Attribute a route's response-model TypeAdapter is kept under, so it is built
+# once per route rather than on every cache miss.
+_ADAPTER_ATTR = "_cachex_response_adapter"
+
+
+def _serialize_result(route: "APIRoute", result: object) -> object:
+    """JSON-compatible content for a handler's non-Response return value.
+
+    With a response model (declared, or inferred from the return annotation)
+    the result is validated against it and dumped with the route's
+    ``response_model_*`` options, so fields the model leaves out are dropped.
+    Otherwise it goes through ``jsonable_encoder``, as FastAPI does.
+    """
+    if route.response_model is None:
+        return jsonable_encoder(result)
+    adapter: TypeAdapter[Any] | None = getattr(route, _ADAPTER_ATTR, None)
+    if adapter is None:
+        adapter = TypeAdapter(route.response_model)
+        setattr(route, _ADAPTER_ATTR, adapter)
+    validated = adapter.validate_python(result, from_attributes=True)
+    return adapter.dump_python(
+        validated,
+        mode="json",
+        include=route.response_model_include,
+        exclude=route.response_model_exclude,
+        by_alias=route.response_model_by_alias,
+        exclude_unset=route.response_model_exclude_unset,
+        exclude_defaults=route.response_model_exclude_defaults,
+        exclude_none=route.response_model_exclude_none,
+    )
+
+
+def _is_coroutine_callable(func: HandlerCallable) -> bool:
+    """Report whether calling `func` returns a coroutine.
+
+    `inspect.iscoroutinefunction` already sees through `functools.partial`;
+    an instance with an ``async def __call__`` needs its method checked. The
+    method is looked up on the type, as the call itself does, so a class
+    (whose type is ``type``) counts as sync.
+    """
+    return inspect.iscoroutinefunction(func) or inspect.iscoroutinefunction(
+        type(func).__call__
+    )
+
+
 async def get_response(
     __func: HandlerCallable,
     __request: Request,
@@ -310,11 +359,20 @@ async def get_response(
     *args: Any,
     **kwargs: Any,
 ) -> Response:
-    """Get the response from the function."""
-    if inspect.iscoroutinefunction(__func):
-        result = await __func(*args, **kwargs)
+    """Get the response from the function.
+
+    Coroutine handlers are awaited. Sync handlers run in the threadpool, as
+    FastAPI would run them without the (async) cache wrapper, so blocking I/O
+    in a ``def`` handler does not stall the event loop.
+    """
+    if _is_coroutine_callable(__func):
+        result = await cast("Callable[..., Awaitable[object]]", __func)(*args, **kwargs)
     else:
-        result = __func(*args, **kwargs)
+        result = await run_in_threadpool(__func, *args, **kwargs)
+    # A sync callable can still hand back an awaitable (a lambda wrapping a
+    # coroutine function, say); await it rather than try to encode it.
+    if inspect.isawaitable(result):
+        result = await result
 
     # If already a Response object, return it directly
     if isinstance(result, Response):
@@ -343,8 +401,25 @@ async def get_response(
         ),
     )
 
-    # Convert non-Response result to Response using appropriate response_class
-    return response_class(content=result)
+    # Build the response the way FastAPI would have without the cache wrapper:
+    # serialize through the response model, apply the route's status code and
+    # carry over what the handler set on an injected `response: Response`.
+    sub_response = next(
+        (value for value in kwargs.values() if isinstance(value, Response)), None
+    )
+    status_code = route.status_code
+    if sub_response is not None and sub_response.status_code:
+        status_code = sub_response.status_code
+    response_args: dict[str, Any] = {}
+    if status_code is not None:
+        response_args["status_code"] = status_code
+
+    response = response_class(_serialize_result(route, result), **response_args)
+    if not is_body_allowed_for_status_code(response.status_code):
+        response.body = b""
+    if sub_response is not None:
+        response.headers.raw.extend(sub_response.headers.raw)
+    return response
 
 
 def cache(
@@ -362,20 +437,45 @@ def cache(
 ) -> Callable[[HandlerCallable], AsyncResponseCallable]:
     """Cache decorator for FastAPI route handlers.
 
+    Only GET requests go through the cache; other methods run the handler
+    unchanged.
+
     Args:
-        ttl: Time-to-live in seconds for cache entries
-        stale_ttl: Additional time-to-live for stale cache entries
-        stale: Stale response handling strategy ('error' or 'revalidate')
-        no_cache: Whether to disable caching
-        no_store: Whether to prevent storing responses
-        public: Whether responses can be cached by shared caches
-        private: Whether responses are for single user only
-        immutable: Whether cached responses never change
-        must_revalidate: Whether to force revalidation when stale
-        key_builder: Custom function to build cache keys. If None, uses default_key_builder
+        ttl: How long, in seconds, a stored response may be served without
+            running the handler. The same value is sent as ``max-age``.
+            ``ttl=0`` sends ``max-age=0`` and, like ``None``, keeps the entry
+            only for ETag revalidation: the body is never served from the
+            cache, but a matching ``If-None-Match`` still gets a 304. Negative
+            values are rejected.
+        stale_ttl: Seconds sent with the directive chosen by ``stale``. It only
+            shapes the ``Cache-Control`` header; the backend entry still
+            expires after ``ttl``. Must be given together with ``stale``.
+        stale: ``"revalidate"`` sends ``stale-while-revalidate=<stale_ttl>``,
+            ``"error"`` sends ``stale-if-error=<stale_ttl>``.
+        no_cache: Run the handler on every request and send ``no-cache``. The
+            response is still stored and ``If-None-Match`` still gets a 304
+            when it matches the fresh ETag. The header then carries only
+            ``no-cache`` (plus ``must-revalidate`` when set); ``ttl``,
+            ``stale``, ``public``/``private`` and ``immutable`` are left out.
+        no_store: Run the handler, store nothing, and send ``no-store``. Takes
+            precedence over every other option.
+        public: Send ``public``. Mutually exclusive with ``private``.
+        private: Send ``private`` and bypass the shared backend entirely: the
+            handler runs on every request and nothing is read or stored. ETag
+            revalidation still works against the freshly rendered response.
+            Mutually exclusive with ``public``.
+        immutable: Send ``immutable``.
+        must_revalidate: Send ``must-revalidate``.
+        key_builder: Custom function to build cache keys. If None, uses
+            ``default_key_builder``.
 
     Returns:
         Decorator function that wraps route handlers with caching logic
+
+    Raises:
+        CacheXError: When the decorator is applied, if ``stale`` and
+            ``stale_ttl`` are not given together, if ``public`` and
+            ``private`` are both set, or if ``ttl`` is negative.
     """
 
     def decorator(func: HandlerCallable) -> AsyncResponseCallable:
@@ -389,6 +489,9 @@ def cache(
         if public and private:
             msg = "public and private are mutually exclusive"
             raise CacheXError(msg)
+        if ttl is not None and ttl < 0:
+            msg = "ttl must not be negative"
+            raise CacheXError(msg)
 
         # Analyze the original function's signature
         sig: Signature = inspect.signature(func)
@@ -466,6 +569,10 @@ def cache(
         # The header only depends on the decorator arguments, so build it once.
         cache_control = build_cache_control()
         builder = key_builder or default_key_builder
+        # `max-age=0` is a legal header, but backends disagree on what a zero
+        # TTL means, so such an entry is stored like `ttl=None`: kept only to
+        # answer ETag revalidation, never served directly.
+        store_ttl = ttl or None
 
         @wraps(func)
         async def wrapper(*args: Any, **kwargs: Any) -> Response:
@@ -563,7 +670,7 @@ def cache(
 
             # If we don't have If-None-Match header, check if we have a valid cached copy
             # and can serve it directly (cache hit without ETag comparison)
-            if cached_data and not no_cache and ttl is not None:
+            if cached_data and not no_cache and store_ttl is not None:
                 logger.debug("Cache HIT (TTL valid); key=%s", cache_key)
                 return Response(
                     content=cached_data.content,
@@ -612,7 +719,7 @@ def cache(
                         status_code=current_response.status_code,
                         headers=_cacheable_headers(current_response),
                     ),
-                    ttl=ttl,
+                    ttl=store_ttl,
                 )
                 logger.debug("Updated cache entry; key=%s ttl=%s", cache_key, ttl)