fastapi-cachex 0.4.0__tar.gz → 0.4.1__tar.gz

{fastapi_cachex-0.4.0 → fastapi_cachex-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.4.0
+Version: 0.4.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

fastapi_cachex-0.4.1/fastapi_cachex/_warnings.py

@@ -0,0 +1,25 @@
+"""Point a warning at the application's line rather than the library's (#333)."""
+
+import inspect
+
+
+def caller_stacklevel() -> int:
+    """Return the ``stacklevel`` of the first frame outside fastapi_cachex.
+
+    For a ``warnings.warn`` in the function that calls this. The depth of a
+    library call varies (a backend method called directly, through
+    ``CacheManager`` or through a base-class fallback), so a fixed
+    ``stacklevel`` names a library file on some paths.
+    """
+    frame = inspect.currentframe()
+    if frame is None or frame.f_back is None:  # no frame support
+        return 2
+    # Level 1 is the function that warns; start at its caller.
+    level, frame = 2, frame.f_back.f_back
+    while frame is not None:
+        module = frame.f_globals.get("__name__", "")
+        if module != "fastapi_cachex" and not module.startswith("fastapi_cachex."):
+            break
+        frame = frame.f_back
+        level += 1
+    return level

{fastapi_cachex-0.4.0 → fastapi_cachex-0.4.1}/fastapi_cachex/backends/base.py

@@ -8,6 +8,8 @@ from types import TracebackType
 from typing import TYPE_CHECKING
 from typing import Any
 
+from fastapi_cachex._warnings import caller_stacklevel
+from fastapi_cachex.exceptions import CacheXError
 from fastapi_cachex.types import CACHE_KEY_SEPARATOR
 from fastapi_cachex.types import HTTP_KEY_FORMAT_TAG
 from fastapi_cachex.types import CacheEntry
@@ -97,6 +99,18 @@ def validate_delta(delta: int) -> int:
     return delta
 
 
+def check_counter_range(value: int) -> int:
+    """Return ``value`` if a signed 64-bit counter can hold it.
+
+    Raises:
+        CacheXError: If ``value`` is outside the signed 64-bit range
+    """
+    if not -(2**63) <= value < 2**63:
+        msg = "Counter increment would overflow a signed 64-bit integer"
+        raise CacheXError(msg)
+    return value
+
+
 class BaseCacheBackend(ABC):
     """Base class for all cache backends.
 
@@ -179,7 +193,7 @@ class BaseCacheBackend(ABC):
                 "it as False. See https://fastapi-cachex.readthedocs.io/en/"
                 "stable/MIGRATING_0_4/#backend-delete",
                 FutureWarning,
-                stacklevel=3,
+                stacklevel=caller_stacklevel(),
             )
             return True
         return bool(result)
@@ -340,7 +354,10 @@ class BaseCacheBackend(ABC):
             The counter value after the increment
 
         Raises:
-            CacheXError: If ``key`` holds a cached response instead of a counter
+            CacheXError: If ``key`` holds a cached response instead of a
+                counter, or the result would leave the counter's range: signed
+                64-bit, except on Memcached, whose counters are unsigned 64-bit.
+                The counter is left unchanged.
             TypeError: If ``delta`` or ``ttl`` is not an ``int``
             ValueError: If ``ttl`` is out of range, or ``delta`` does not fit
                 in a signed 64-bit integer
@@ -349,6 +366,7 @@ class BaseCacheBackend(ABC):
         validate_ttl(ttl)
         current = await self.get(key)
         value = delta if current is None else counter_value(current) + delta
+        check_counter_range(value)
         await self.set(key, counter_entry(value), ttl=ttl)
         return value
 

{fastapi_cachex-0.4.0 → fastapi_cachex-0.4.1}/fastapi_cachex/backends/memcached.py

@@ -2,12 +2,12 @@
 
 import asyncio
 import hashlib
-import inspect
 import logging
 import time
 import warnings
 from collections.abc import Iterable
 
+from fastapi_cachex._warnings import caller_stacklevel
 from fastapi_cachex.backends.codec import decode_entry
 from fastapi_cachex.backends.codec import encode_entry
 from fastapi_cachex.exceptions import CacheXError
@@ -27,6 +27,41 @@ DEFAULT_MEMCACHE_PREFIX = "fastapi_cachex:"
 # the printable ASCII range with the space removed.
 _MAX_KEY_BYTES = 250
 _LEGAL_KEY_BYTES = frozenset(range(0x21, 0x7F))
+# A key Memcached refuses becomes the prefix plus a 64-character digest, so a
+# longer prefix leaves even the hashed key too long.
+_MAX_PREFIX_BYTES = _MAX_KEY_BYTES - 64
+
+
+def _validate_key_prefix(key_prefix: str) -> None:
+    """Reject a ``key_prefix`` that would make keys Memcached refuses (#239).
+
+    The prefix stays in front of the digest of a hashed key, so a prefix with
+    whitespace, control characters or non-ASCII, or one that leaves no room
+    for a key, makes every call raise ``MemcacheIllegalInputError``. A prefix
+    that leaves room for short keys but not for a digest works until the
+    first key that needs hashing, so it warns instead of raising.
+
+    Raises:
+        ValueError: If no key with this prefix is legal
+    """
+    encoded = key_prefix.encode("utf-8")
+    if not _LEGAL_KEY_BYTES.issuperset(encoded):
+        msg = (
+            "MemcachedBackend key_prefix must be printable ASCII without "
+            f"whitespace, got {key_prefix!r}"
+        )
+        raise ValueError(msg)
+    if len(encoded) >= _MAX_KEY_BYTES:
+        msg = f"MemcachedBackend key_prefix must be shorter than {_MAX_KEY_BYTES} bytes"
+        raise ValueError(msg)
+    if len(encoded) > _MAX_PREFIX_BYTES:
+        warnings.warn(
+            f"MemcachedBackend key_prefix is {len(encoded)} bytes; keys that "
+            f"need hashing fail above {_MAX_PREFIX_BYTES} bytes",
+            UserWarning,
+            stacklevel=caller_stacklevel(),
+        )
+
 
 # An exptime above 30 days is read by Memcached as an absolute Unix timestamp,
 # not as a duration, so a longer TTL has to be converted before it is sent.
@@ -69,26 +104,6 @@ def _expiry(ttl: int | None) -> int:
     return ttl
 
 
-def _caller_stacklevel() -> int:
-    """Return the ``stacklevel`` of the first frame outside fastapi_cachex.
-
-    For a ``warnings.warn`` in the method that calls this, so a warning raised
-    through ``CacheManager`` names the application's line, not manager.py.
-    """
-    frame = inspect.currentframe()
-    if frame is None or frame.f_back is None:  # no frame support
-        return 2
-    # Level 1 is the method that warns; start at its caller.
-    level, frame = 2, frame.f_back.f_back
-    while frame is not None:
-        module = frame.f_globals.get("__name__", "")
-        if module != "fastapi_cachex" and not module.startswith("fastapi_cachex."):
-            break
-        frame = frame.f_back
-        level += 1
-    return level
-
-
 class MemcachedBackend(BaseCacheBackend):
     """Memcached backend implementation.
 
@@ -121,7 +136,10 @@ class MemcachedBackend(BaseCacheBackend):
 
         Raises:
             CacheXError: If pymemcache is not installed
+            ValueError: If ``key_prefix`` holds whitespace, control
+                characters or non-ASCII, or is 250 bytes or longer
         """
+        _validate_key_prefix(key_prefix)
         try:
             from pymemcache import HashClient
         except ImportError as exc:
@@ -376,12 +394,32 @@ class MemcachedBackend(BaseCacheBackend):
         return bool(stored)
 
     def _add_delta(self, prefixed_key: str, delta: int) -> int | None:
-        """Apply ``delta`` with INCR/DECR; ``None`` when the key does not exist."""
+        """Apply ``delta`` with INCR/DECR; ``None`` when the key does not exist.
+
+        Memcached's INCR wraps around past 2**64 - 1. A wrapped result is
+        smaller than ``delta``, which no other result can be, so the wrap is
+        undone with an INCR of ``2**64 - delta`` (addition modulo 2**64 also
+        keeps any increment that landed in between) and reported. The two
+        INCRs are not atomic: a concurrent INCR between them can return the
+        wrapped value, and a DECR that clamps at 0 between them makes the undo
+        land on a different value. Making it exact would take a CAS loop on
+        every increment.
+
+        Raises:
+            CacheXError: If the INCR wrapped the counter around.
+        """
         if delta < 0:
             result = self.client.decr(prefixed_key, -delta, noreply=False)
         else:
             result = self.client.incr(prefixed_key, delta, noreply=False)
-        return None if result is None else int(result)
+        if result is None:
+            return None
+        value = int(result)
+        if delta > 0 and value < delta:
+            self.client.incr(prefixed_key, 2**64 - delta, noreply=False)
+            msg = "Counter increment would overflow an unsigned 64-bit integer"
+            raise CacheXError(msg)
+        return value
 
     def _increment(self, prefixed_key: str, delta: int, exptime: int) -> int | None:
         """Run ``increment``'s INCR, ADD and retried INCR in one worker thread.
@@ -418,7 +456,8 @@ class MemcachedBackend(BaseCacheBackend):
         pair is retried, starting a new window at ``delta``.
 
         Raises:
-            CacheXError: If the key holds a value that is not a counter, or
+            CacheXError: If the key holds a value that is not a counter, the
+                result would pass 2**64 - 1 (the counter is restored), or
                 the counter vanished after every ADD + INCR attempt.
         """
         validate_delta(delta)
@@ -497,7 +536,7 @@ class MemcachedBackend(BaseCacheBackend):
             "this namespace cannot be cleared on its own; delete known keys "
             "with delete() or delete_many() instead.",
             RuntimeWarning,
-            stacklevel=_caller_stacklevel(),
+            stacklevel=caller_stacklevel(),
         )
         await asyncio.to_thread(self.client.flush_all)
         logger.debug("Memcached CLEAR; flush_all issued")
@@ -527,7 +566,7 @@ class MemcachedBackend(BaseCacheBackend):
             "exactly as the path, and include_params has no effect. Use "
             "invalidate(request) to drop a cached route's entry.",
             RuntimeWarning,
-            stacklevel=_caller_stacklevel(),
+            stacklevel=caller_stacklevel(),
         )
 
         # Try to delete the prefixed key (exact match only)
@@ -558,7 +597,7 @@ class MemcachedBackend(BaseCacheBackend):
             "Consider using Redis backend for pattern support, "
             "or track keys manually in your application logic.",
             RuntimeWarning,
-            stacklevel=_caller_stacklevel(),
+            stacklevel=caller_stacklevel(),
         )
         logger.debug("Memcached CLEAR_PATTERN unsupported; pattern=%s", pattern)
         return 0
@@ -580,7 +619,7 @@ class MemcachedBackend(BaseCacheBackend):
             "Consider using Redis backend if you need cache monitoring, "
             "or track keys manually in your application.",
             RuntimeWarning,
-            stacklevel=_caller_stacklevel(),
+            stacklevel=caller_stacklevel(),
         )
         logger.debug("Memcached GET_ALL_KEYS unsupported; returning empty list")
         return []

{fastapi_cachex-0.4.0 → fastapi_cachex-0.4.1}/fastapi_cachex/backends/memory.py

@@ -1,6 +1,7 @@
 """In-memory cache backend implementation."""
 
 import asyncio
+import copy
 import fnmatch
 import logging
 import time
@@ -14,6 +15,7 @@ from fastapi_cachex.types import counter_entry
 from fastapi_cachex.types import counter_value
 
 from .base import BaseCacheBackend
+from .base import check_counter_range
 from .base import validate_delta
 from .base import validate_ttl
 from .base import warn_if_path_shaped
@@ -143,7 +145,7 @@ class MemoryBackend(BaseCacheBackend):
                 logger.debug("Memory cache EXPIRED; key=%s removed", key)
                 return None
             logger.debug("Memory cache HIT; key=%s", key)
-            return cached_item.value
+            return copy.copy(cached_item.value)
 
     async def set(self, key: str, value: CacheEntry, ttl: int | None = None) -> None:
         """Store a response in the cache.
@@ -163,7 +165,7 @@ class MemoryBackend(BaseCacheBackend):
 
         async with self.lock:
             expiry = time.time() + ttl if ttl is not None else None
-            self.cache[key] = CacheItem(value=value, expiry=expiry)
+            self.cache[key] = CacheItem(value=copy.copy(value), expiry=expiry)
             logger.debug("Memory cache SET; key=%s ttl=%s", key, ttl)
 
     async def delete(self, key: str) -> bool:
@@ -209,7 +211,7 @@ class MemoryBackend(BaseCacheBackend):
                 logger.debug("Memory cache SET_IF_ABSENT EXISTS; key=%s", key)
                 return False
             expiry = now + ttl if ttl is not None else None
-            self.cache[key] = CacheItem(value=value, expiry=expiry)
+            self.cache[key] = CacheItem(value=copy.copy(value), expiry=expiry)
             logger.debug("Memory cache SET_IF_ABSENT STORED; key=%s ttl=%s", key, ttl)
             return True
 
@@ -261,7 +263,7 @@ class MemoryBackend(BaseCacheBackend):
                 logger.debug("Memory cache SET_IF_EQUALS MISMATCH; key=%s", key)
                 return False
             expiry = now + ttl if ttl is not None else None
-            self.cache[key] = CacheItem(value=value, expiry=expiry)
+            self.cache[key] = CacheItem(value=copy.copy(value), expiry=expiry)
             logger.debug("Memory cache SET_IF_EQUALS HIT; key=%s ttl=%s", key, ttl)
             return True
 
@@ -269,7 +271,13 @@ class MemoryBackend(BaseCacheBackend):
         """Atomically add ``delta`` to the counter at ``key`` (see base class).
 
         The read-modify-write happens under the backend lock, so concurrent
-        callers on the same event loop never lose an increment.
+        callers on the same event loop never lose an increment. Counters are
+        signed 64-bit, as on Redis.
+
+        Raises:
+            CacheXError: If the key holds a value that is not a counter, or
+                the result would leave the signed 64-bit range (the counter
+                is left unchanged).
         """
         validate_delta(delta)
         validate_ttl(ttl)
@@ -279,7 +287,7 @@ class MemoryBackend(BaseCacheBackend):
             now = time.time()
             item = self.cache.get(key)
             if item is not None and _is_live(item, now):
-                value = counter_value(item.value) + delta
+                value = check_counter_range(counter_value(item.value) + delta)
                 item.value = counter_entry(value)
             else:
                 value = delta
@@ -378,7 +386,7 @@ class MemoryBackend(BaseCacheBackend):
         async with self.lock:
             now = time.time()
             return {
-                key: (item.value, item.expiry)
+                key: (copy.copy(item.value), item.expiry)
                 for key, item in self.cache.items()
                 if _is_live(item, now)
             }

{fastapi_cachex-0.4.0 → fastapi_cachex-0.4.1}/fastapi_cachex/backends/redis.py

@@ -35,13 +35,15 @@ _BATCH_SIZE = 100
 
 # 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).
+# The value is returned as the stored string: Lua turns an integer reply into
+# a double, which rounds anything past 2**53 (#364).
 _INCREMENT_SCRIPT = """
 local created = redis.call('EXISTS', KEYS[1]) == 0
-local value = redis.call('INCRBY', KEYS[1], ARGV[1])
+redis.call('INCRBY', KEYS[1], ARGV[1])
 if created and tonumber(ARGV[2]) > 0 then
     redis.call('EXPIRE', KEYS[1], ARGV[2])
 end
-return value
+return redis.call('GET', KEYS[1])
 """
 
 # DEL that only fires while the key still holds the exact bytes the caller read,
@@ -436,6 +438,9 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
                 keys=[self._make_key(key)], args=[delta, ttl or 0]
             )
         except ResponseError as e:
+            if "would overflow" in str(e):
+                msg = "Counter increment would overflow a signed 64-bit integer"
+                raise CacheXError(msg) from e
             if "not an integer" not in str(e):
                 raise
             msg = "Cache key holds a value that is not a counter"

{fastapi_cachex-0.4.0 → fastapi_cachex-0.4.1}/fastapi_cachex/cache.py

@@ -6,6 +6,7 @@ import logging
 import threading
 import time
 import warnings
+from collections import Counter
 from collections.abc import Awaitable
 from collections.abc import Callable
 from collections.abc import Iterable
@@ -28,6 +29,7 @@ from typing import get_type_hints
 from fastapi import Request
 from fastapi import Response
 from fastapi.encoders import jsonable_encoder
+from fastapi.params import Depends as DependsParam
 from fastapi.utils import is_body_allowed_for_status_code
 from pydantic import TypeAdapter
 from starlette.concurrency import run_in_threadpool
@@ -259,6 +261,14 @@ _COOKIE_VARY_WARNING = (
 )
 
 
+def _no_store_ignored_warning(ignored: list[str]) -> str:
+    return (
+        f"cache no_store ignores {', '.join(ignored)}: @cache(no_store=True) "
+        "stores nothing and sends only Cache-Control: no-store, so the other "
+        "arguments have no effect. Remove them, or drop no_store."
+    )
+
+
 # How the one-time bypass warning names each `_request_credential` result.
 _CREDENTIAL_DESCRIPTIONS = {
     "Authorization header": "an Authorization header",
@@ -653,15 +663,52 @@ def _is_request_annotation(annotation: Any) -> bool:
     return isinstance(annotation, type) and issubclass(annotation, Request)
 
 
+def _is_response_annotation(annotation: Any) -> bool:
+    """Whether an annotation asks for the sub-``Response`` FastAPI injects.
+
+    ``Annotated[Response, Depends(...)]`` is a dependency that returns a
+    ``Response``, not the sub-response.
+    """
+    if get_origin(annotation) is Annotated:
+        annotation, *metadata = get_args(annotation)
+        if any(isinstance(item, DependsParam) for item in metadata):
+            return False
+    return isinstance(annotation, type) and issubclass(annotation, Response)
+
+
 def _find_request_param(
     func: HandlerCallable, params: list[Parameter]
 ) -> Parameter | None:
-    """The handler's own ``Request`` parameter, if it declares one.
+    """The handler's own ``Request`` parameter, if it declares one (see ``_find_param``)."""
+    return _find_param(func, params, _is_request_annotation)
+
+
+def _find_response_param(
+    func: HandlerCallable, params: list[Parameter]
+) -> Parameter | None:
+    """The handler's own ``Response`` parameter, if it declares one (see ``_find_param``).
+
+    A parameter defaulting to ``Depends(...)`` is a dependency's result, not
+    the sub-response, whatever its annotation.
+    """
+    return _find_param(
+        func,
+        [param for param in params if not isinstance(param.default, DependsParam)],
+        _is_response_annotation,
+    )
+
+
+def _find_param(
+    func: HandlerCallable,
+    params: list[Parameter],
+    matches: Callable[[Any], bool],
+) -> Parameter | None:
+    """The handler's first parameter whose annotation ``matches``.
 
     Annotations are resolved first, so a handler under ``from __future__ import
     annotations`` (where the annotation is the string ``"Request"``),
     ``Annotated[Request, ...]``, or a ``Request`` subclass is recognised
-    instead of being given a second, unused request parameter. Resolution can
+    instead of being given a second, unused parameter. Resolution can
     fail on a forward reference that does not resolve in the handler's module,
     which must not break decoration: the raw annotations are used instead.
     """
@@ -671,15 +718,107 @@ def _find_request_param(
         hints = {}
 
     return next(
-        (
-            param
-            for param in params
-            if _is_request_annotation(hints.get(param.name, param.annotation))
-        ),
+        (param for param in params if matches(hints.get(param.name, param.annotation))),
         None,
     )
 
 
+def _split_header_lines(
+    lines: Iterable[tuple[bytes, bytes]], before: Iterable[tuple[bytes, bytes]]
+) -> tuple[list[tuple[bytes, bytes]], list[tuple[bytes, bytes]]]:
+    """Split a sub-response's header lines into those of ``before`` and the rest.
+
+    FastAPI resolves the dependencies before it calls the handler, so the
+    sub-response's lines when the wrapper starts (``before``) are the
+    dependencies' and the lines added since are the handler's. Lines are
+    matched as a multiset, so a repeated line is counted once per copy.
+    """
+    remaining = Counter(before)
+    kept: list[tuple[bytes, bytes]] = []
+    added: list[tuple[bytes, bytes]] = []
+    for line in lines:
+        if remaining[line] > 0:
+            remaining[line] -= 1
+            kept.append(line)
+        else:
+            added.append(line)
+    return kept, added
+
+
+def _sets_cookie(lines: Iterable[tuple[bytes, bytes]]) -> bool:
+    return any(name.lower() == b"set-cookie" for name, _ in lines)
+
+
+def _cache_control_values(lines: Iterable[tuple[bytes, bytes]]) -> list[str]:
+    return [
+        value.decode("latin-1")
+        for name, value in lines
+        if name.lower() == b"cache-control"
+    ]
+
+
+def _dependency_unshareable_reason(
+    dependency_lines: Iterable[tuple[bytes, bytes]],
+) -> str | None:
+    """Why the dependencies' lines keep a response out of the backend, if they do."""
+    lines = list(dependency_lines)
+    if _has_unshareable_directive(_cache_control_values(lines)):
+        return "a dependency's Cache-Control is private or no-store"
+    if _sets_cookie(lines):
+        return "a dependency sets a cookie"
+    return None
+
+
+def _with_dependency_headers(
+    response: Response,
+    sub_response: Response | None,
+    dependency_lines: Sequence[tuple[bytes, bytes]],
+    private_cache_control: str,
+    *,
+    cacheable_get: bool,
+) -> Response:
+    """Add the header lines the dependencies set on this request (#233).
+
+    FastAPI merges the sub-response into the response only when the handler
+    returns plain data, and the wrapper always returns a ``Response``, so it
+    merges them itself: on a miss, a hit and a 304 alike, with the values of
+    this request rather than those stored with the entry.
+
+    On a cacheable GET response, ``Cache-Control`` is decided as for the
+    handler's own lines: a handler's ``private`` or ``no-store`` header (or
+    ``no_store=True``) is kept; otherwise a dependency's ``private`` or
+    ``no-store`` header replaces the decorator's, and a ``Set-Cookie`` makes it
+    ``private``. Any header the response already carries (other than
+    ``Set-Cookie``) is not added, the decorator's ``Cache-Control`` included:
+    the handler set it over the dependency's, which on a hit is the stored
+    value.
+    Any other response gets every line, as FastAPI would send them.
+    """
+    if sub_response is None or not dependency_lines:
+        return response
+    current, _ = _split_header_lines(sub_response.headers.raw, dependency_lines)
+    if not cacheable_get or not (
+        response.status_code == HTTP_304_NOT_MODIFIED
+        or _is_cacheable_status(response.status_code)
+    ):
+        response.headers.raw.extend(current)
+        return response
+    own = {name.lower() for name, _ in response.headers.raw}
+    response.headers.raw.extend(
+        (name, value)
+        for name, value in current
+        if name.lower() == b"set-cookie" or name.lower() not in own
+    )
+    if _marked_unshareable(response):
+        return response
+    dependency_cache_control = _cache_control_values(current)
+    if _has_unshareable_directive(dependency_cache_control):
+        response.headers["Cache-Control"] = ", ".join(dependency_cache_control)
+    elif _sets_cookie(current):
+        response.headers["Cache-Control"] = private_cache_control
+    return response
+
+
 def _get_response_body(response: Response) -> bytes | None:
     """Return response body bytes, or None for streaming/file responses."""
     return getattr(response, "body", None)
@@ -739,11 +878,34 @@ def _not_modified(
     response = Response(status_code=HTTP_304_NOT_MODIFIED)
     _append_headers(response, _revalidation_headers(headers))
     response.headers["ETag"] = etag
-    response.headers["Cache-Control"] = cache_control
+    if cache_control:
+        response.headers["Cache-Control"] = cache_control
     response.headers.update(age or {})
     return response
 
 
+def _fresh_not_modified(
+    response: Response, etag: str, client_etag: str | None, cache_control: str
+) -> Response | None:
+    """The 304 for a response the handler just rendered, or None to send it.
+
+    None unless ``client_etag`` matches. The handler ran, so what it did
+    beyond the body still reaches the client: its ``Set-Cookie`` lines are
+    repeated on the 304 (such a response is never stored, and
+    ``_cache_control_for`` marks it ``private``), and its ``background`` task
+    moves onto the 304 (#233).
+    """
+    if not _etag_matches(client_etag, etag):
+        return None
+    not_modified = _not_modified(etag, cache_control, response.headers.items())
+    _append_headers(
+        not_modified,
+        [(k, v) for k, v in response.headers.items() if k.lower() == "set-cookie"],
+    )
+    not_modified.background = response.background
+    return not_modified
+
+
 # Response directives by which the handler says its response belongs to one
 # caller (``private``) or must not be kept at all (``no-store``).
 _UNSHAREABLE_DIRECTIVES = frozenset(
@@ -757,9 +919,14 @@ def _marked_unshareable(response: Response) -> bool:
     Directive names are matched as whole tokens, case-insensitively, across
     every ``Cache-Control`` field the response carries.
     """
+    return _has_unshareable_directive(response.headers.getlist("cache-control"))
+
+
+def _has_unshareable_directive(cache_control: Iterable[str]) -> bool:
+    """Whether any of these ``Cache-Control`` values has ``private`` or ``no-store``."""
     return any(
         directive.split("=", 1)[0].strip().lower() in _UNSHAREABLE_DIRECTIVES
-        for value in response.headers.getlist("cache-control")
+        for value in cache_control
         for directive in value.split(",")
     )
 
@@ -781,12 +948,16 @@ def _cache_control_for(
     A handler that marked its response ``private`` or ``no-store`` keeps its own
     header; the decorator's would widen what the handler allowed. A response
     that sets a cookie gets ``private_cache_control``, so a shared cache in
-    front of the app does not store it either.
+    front of the app does not store it either. When the decorator has no
+    directive to send (a bare ``@cache()``), the handler's own header is kept,
+    or none is sent (#363); a cookie still gets ``private_cache_control``.
     """
     if _marked_unshareable(response):
         return ", ".join(response.headers.getlist("cache-control"))
     if "set-cookie" in response.headers:
         return private_cache_control
+    if not cache_control:
+        return ", ".join(response.headers.getlist("cache-control"))
     return cache_control
 
 
@@ -794,17 +965,30 @@ def _with_cache_control(
     response: Response, cache_control: str, private_cache_control: str
 ) -> Response:
     if not _marked_unshareable(response):
-        response.headers["Cache-Control"] = _cache_control_for(
-            response, cache_control, private_cache_control
-        )
+        value = _cache_control_for(response, cache_control, private_cache_control)
+        if value:
+            response.headers["Cache-Control"] = value
     return response
 
 
 async def _render(
-    func: HandlerCallable, request: Request, /, *args: Any, **kwargs: Any
+    func: HandlerCallable,
+    request: Request,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    *,
+    sub_response: Response | None,
+    dependency_lines: Sequence[tuple[bytes, bytes]],
 ) -> tuple[Response, bytes | None, str | None]:
     """Run the handler; the body and ETag are None for streaming/file responses."""
-    response = await get_response(func, request, *args, **kwargs)
+    response = await _respond(
+        func,
+        request,
+        args,
+        kwargs,
+        sub_response=sub_response,
+        dependency_lines=dependency_lines,
+    )
     body = _get_response_body(response)
     return response, body, None if body is None else _etag_for(body)
 
@@ -865,12 +1049,37 @@ async def get_response(
 
     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.
+    in a ``def`` handler does not stall the event loop. Every header line of a
+    ``Response`` among ``kwargs`` is carried over onto a plain-data result.
+    """
+    sub_response = next(
+        (value for value in kwargs.values() if isinstance(value, Response)), None
+    )
+    return await _respond(
+        __func, __request, args, kwargs, sub_response=sub_response, dependency_lines=()
+    )
+
+
+async def _respond(
+    func: HandlerCallable,
+    request: Request,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    *,
+    sub_response: Response | None,
+    dependency_lines: Sequence[tuple[bytes, bytes]],
+) -> Response:
+    """Run the handler and build its response, as ``get_response`` describes.
+
+    Only the lines added to ``sub_response`` beyond ``dependency_lines`` are
+    carried over here: the dependencies' own lines are added to every
+    response the wrapper sends (``_with_dependency_headers``), and must not be
+    stored with the entry.
     """
-    if _is_coroutine_callable(__func):
-        result = await cast("Callable[..., Awaitable[object]]", __func)(*args, **kwargs)
+    if _is_coroutine_callable(func):
+        result = await cast("Callable[..., Awaitable[object]]", func)(*args, **kwargs)
     else:
-        result = await run_in_threadpool(__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):
@@ -881,7 +1090,7 @@ async def get_response(
         return result
 
     # Get response_class from route if available
-    route: APIRoute | None = __request.scope.get("route")
+    route: APIRoute | None = request.scope.get("route")
     if route is None:
         msg = "Route not found in request scope"
         raise CacheXError(msg)
@@ -889,7 +1098,7 @@ async def get_response(
     # A placeholder means this route uses the application default. Unwrap the
     # application value instead of calling the route's DefaultPlaceholder.
     route_response_class = route.response_class
-    application_default_response_class = __request.app.router.default_response_class
+    application_default_response_class = request.app.router.default_response_class
     response_class: type[Response] = cast(
         "type[Response]",
         (
@@ -905,10 +1114,7 @@ async def get_response(
 
     # 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
-    )
+    # carry over what the handler set on the injected `response: Response`.
     status_code = route.status_code
     if sub_response is not None and sub_response.status_code:
         status_code = sub_response.status_code
@@ -920,7 +1126,8 @@ async def get_response(
     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)
+        _, added = _split_header_lines(sub_response.headers.raw, dependency_lines)
+        response.headers.raw.extend(added)
     return response
 
 
@@ -1062,6 +1269,17 @@ def cache(
             ``key_builder``, or if ``key_builder`` is an ``async`` callable.
             At request time, if
             ``key_builder`` returns anything but a ``str``.
+
+    Without ``ttl`` or any directive (a bare ``@cache()``), nothing is stored
+    and the decorator has no ``Cache-Control`` of its own: it adds an ETag,
+    answers a matching ``If-None-Match`` with 304 and keeps the handler's own
+    ``Cache-Control``, except that a response setting a cookie or answering a
+    request with credentials is still sent with ``private``.
+
+    Warns:
+        UserWarning: When the decorator is applied, if ``vary`` lists
+            ``Cookie``, or if ``no_store`` is combined with another caching
+            argument it overrides.
     """
 
     def decorator(func: HandlerCallable) -> AsyncResponseCallable:
@@ -1092,6 +1310,27 @@ def cache(
             # stacklevel=2: the caller applying the decorator, i.e. the line
             # of the user's @cache(...).
             warnings.warn(_COOKIE_VARY_WARNING, UserWarning, stacklevel=2)
+        # Arguments no_store overrides are accepted but warned about (#328);
+        # rejecting them would break routes that work today.
+        if no_store:
+            ignored = [
+                name
+                for name, value in (
+                    ("ttl", ttl),
+                    ("stale", stale),
+                    ("stale_ttl", stale_ttl),
+                    ("no_cache", no_cache),
+                    ("public", public),
+                    ("private", private),
+                    ("immutable", immutable),
+                    ("must_revalidate", must_revalidate),
+                )
+                if value is not None and value is not False
+            ]
+            if ignored:
+                warnings.warn(
+                    _no_store_ignored_warning(ignored), UserWarning, stacklevel=2
+                )
 
         # Analyze the original function's signature
         sig: Signature = inspect.signature(func)
@@ -1100,16 +1339,32 @@ def cache(
         # Check if Request is already in the parameters
         found_request: Parameter | None = _find_request_param(func, params)
 
-        # Add Request parameter if it's not present
+        # FastAPI's sub-response: the wrapper needs it even when the handler
+        # does not ask for it, to send what the dependencies set on it (#233).
+        found_response: Parameter | None = _find_response_param(func, params)
+
+        # Add the Request and Response parameters the handler does not declare
+        injected: list[Parameter] = []
         if not found_request:
             request_name: str = "__cachex_request"
-
-            request_param = inspect.Parameter(
-                request_name,
-                inspect.Parameter.KEYWORD_ONLY,
-                annotation=Request,
+            injected.append(
+                inspect.Parameter(
+                    request_name, inspect.Parameter.KEYWORD_ONLY, annotation=Request
+                )
+            )
+        else:
+            request_name = found_request.name
+        if not found_response:
+            response_name: str = "__cachex_response"
+            injected.append(
+                inspect.Parameter(
+                    response_name, inspect.Parameter.KEYWORD_ONLY, annotation=Response
+                )
             )
+        else:
+            response_name = found_response.name
 
+        if injected:
             # A keyword-only parameter must precede **kwargs; appending it
             # after one makes `Signature.replace` raise at decoration time,
             # so a handler taking **kwargs could not be cached at all.
@@ -1122,16 +1377,9 @@ def cache(
                 len(params),
             )
             sig = sig.replace(
-                parameters=[
-                    *params[:insert_at],
-                    request_param,
-                    *params[insert_at:],
-                ]
+                parameters=[*params[:insert_at], *injected, *params[insert_at:]]
             )
 
-        else:
-            request_name = found_request.name
-
         # The header only depends on the decorator arguments, so build it once.
         cache_control = _build_cache_control(
             ttl=ttl,
@@ -1171,8 +1419,14 @@ def cache(
             f"{getattr(func, '__module__', '?')}.{getattr(func, '__qualname__', '?')}"
         )
 
-        @wraps(func)
-        async def serve(*args: Any, **kwargs: Any) -> Response:
+        async def respond(
+            sub_response: Response | None,
+            dependency_lines: Sequence[tuple[bytes, bytes]],
+            dependency_status: int | None,
+            /,
+            *args: Any,
+            **kwargs: Any,
+        ) -> Response:
             # Resolve backend on every request to support lifespan-configured backends
             cache_backend = get_backend_or_fallback()
 
@@ -1191,11 +1445,25 @@ def cache(
                 logger.debug(
                     "Non-GET request; bypassing cache for method=%s", req.method
                 )
-                return await get_response(func, req, *args, **kwargs)
+                return await _respond(
+                    func,
+                    req,
+                    args,
+                    kwargs,
+                    sub_response=sub_response,
+                    dependency_lines=dependency_lines,
+                )
 
             # Handle special case: no-store (highest priority)
             if no_store:
-                response = await get_response(func, req, *args, **kwargs)
+                response = await _respond(
+                    func,
+                    req,
+                    args,
+                    kwargs,
+                    sub_response=sub_response,
+                    dependency_lines=dependency_lines,
+                )
                 logger.debug(
                     "no-store active; bypassed cache for path=%s", req.url.path
                 )
@@ -1245,7 +1513,14 @@ def cache(
                 # cache reuse the answer to an `Authorization` request under
                 # `must-revalidate`, and nothing at all stops one reusing the
                 # answer to a cookie.
-                response, _, etag = await _render(func, req, *args, **kwargs)
+                response, _, etag = await _render(
+                    func,
+                    req,
+                    args,
+                    kwargs,
+                    sub_response=sub_response,
+                    dependency_lines=dependency_lines,
+                )
                 if not _is_cacheable_status(response.status_code):
                     return response
                 if etag is None:
@@ -1253,15 +1528,17 @@ def cache(
                     return _with_cache_control(
                         response, response_cache_control, private_cache_control
                     )
-                if _etag_matches(client_etag, etag):
+                not_modified = _fresh_not_modified(
+                    response,
+                    etag,
+                    client_etag,
+                    _cache_control_for(
+                        response, response_cache_control, private_cache_control
+                    ),
+                )
+                if not_modified is not None:
                     logger.debug("304 Not Modified (uncached); path=%s", req.url.path)
-                    return _not_modified(
-                        etag,
-                        _cache_control_for(
-                            response, response_cache_control, private_cache_control
-                        ),
-                        response.headers.items(),
-                    )
+                    return not_modified
                 response.headers["ETag"] = etag
                 logger.debug("Bypassed the backend; path=%s", req.url.path)
                 return _with_cache_control(
@@ -1290,7 +1567,12 @@ def cache(
                 if no_cache:
                     # Get fresh response first if using no-cache
                     current_response, current_body, current_etag = await _render(
-                        func, req, *args, **kwargs
+                        func,
+                        req,
+                        args,
+                        kwargs,
+                        sub_response=sub_response,
+                        dependency_lines=dependency_lines,
                     )
                     if not _is_cacheable_status(current_response.status_code):
                         # Error responses carry no validator: never answer 304.
@@ -1309,18 +1591,20 @@ def cache(
                             private_cache_control,
                         )
 
-                    if _etag_matches(client_etag, current_etag):
-                        # For no-cache, compare fresh data with client's ETag
+                    # For no-cache, compare fresh data with client's ETag
+                    not_modified = _fresh_not_modified(
+                        current_response,
+                        current_etag,
+                        client_etag,
+                        _cache_control_for(
+                            current_response,
+                            response_cache_control,
+                            private_cache_control,
+                        ),
+                    )
+                    if not_modified is not None:
                         logger.debug("304 Not Modified via no-cache; key=%s", cache_key)
-                        return _not_modified(
-                            current_etag,
-                            _cache_control_for(
-                                current_response,
-                                response_cache_control,
-                                private_cache_control,
-                            ),
-                            current_response.headers.items(),
-                        )
+                        return not_modified
 
                 # Compare with cached ETag - if match, return 304
                 elif cached_data and _etag_matches(
@@ -1366,7 +1650,12 @@ def cache(
             if current_response is None or current_etag is None:
                 # Retrieve the current response if not already done
                 current_response, current_body, current_etag = await _render(
-                    func, req, *args, **kwargs
+                    func,
+                    req,
+                    args,
+                    kwargs,
+                    sub_response=sub_response,
+                    dependency_lines=dependency_lines,
                 )
                 if not _is_cacheable_status(current_response.status_code):
                     # Leave any existing entry alone: a transient error must not
@@ -1391,6 +1680,11 @@ def cache(
             # stored. An entry already under this key is left alone, as for an
             # error status: it came from a response that was shareable.
             skip_reason = _unshareable_reason(current_response)
+            if skip_reason is None:
+                skip_reason = _dependency_unshareable_reason(dependency_lines)
+            if skip_reason is None and dependency_status is not None:
+                # It may hold for this request only, and a hit would replay it.
+                skip_reason = "a dependency set the status code"
             if skip_reason is not None:
                 logger.debug("Not storing key=%s: %s", cache_key, skip_reason)
 
@@ -1421,10 +1715,52 @@ def cache(
                 else:
                     logger.debug("Updated cache entry; key=%s ttl=%s", cache_key, ttl)
 
+            # A client revalidating a copy that the fresh render reproduces gets
+            # a 304, as on the bypass and no_cache paths: the entry may have
+            # expired, been cleared or evicted, or never been stored in this
+            # worker, while the client's ETag still matches (#237).
+            not_modified = _fresh_not_modified(
+                current_response,
+                current_etag,
+                client_etag,
+                _cache_control_for(
+                    current_response, response_cache_control, private_cache_control
+                ),
+            )
+            if not_modified is not None:
+                logger.debug("304 Not Modified (fresh render); key=%s", cache_key)
+                return not_modified
+
             return _with_cache_control(
                 current_response, response_cache_control, private_cache_control
             )
 
+        @wraps(func)
+        async def serve(*args: Any, **kwargs: Any) -> Response:
+            if found_response:
+                sub_response: Response | None = kwargs.get(response_name)
+            else:
+                sub_response = kwargs.pop(response_name, None)
+            # The dependencies have run; the handler has not (see
+            # `_split_header_lines`).
+            dependency_lines = (
+                [] if sub_response is None else list(sub_response.headers.raw)
+            )
+            dependency_status = (
+                None if sub_response is None else sub_response.status_code
+            )
+            req: Request | None = kwargs.get(request_name)
+            response = await respond(
+                sub_response, dependency_lines, dependency_status, *args, **kwargs
+            )
+            return _with_dependency_headers(
+                response,
+                sub_response,
+                dependency_lines,
+                private_cache_control,
+                cacheable_get=req is not None and req.method == "GET",
+            )
+
         wrapper: AsyncResponseCallable = serve
         if vary_names:
 

{fastapi_cachex-0.4.0 → fastapi_cachex-0.4.1}/fastapi_cachex/lock.py

@@ -1,6 +1,7 @@
 """Distributed lock helper for FastAPI-CacheX."""
 
 import asyncio
+import contextlib
 import logging
 import secrets
 import time
@@ -16,6 +17,10 @@ logger = logging.getLogger(__name__)
 # Fingerprint every backend reports for a key that holds a lock entry
 _LOCK_FINGERPRINT = "lock"
 
+# Withdrawals still running after a second cancellation; the event loop keeps
+# only a weak reference to a task.
+_pending_withdrawals: set["asyncio.Task[bool]"] = set()
+
 
 def _lock_entry(token: str) -> CacheEntry:
     """Wrap a lock token string in the entry model shared by every backend."""
@@ -107,6 +112,10 @@ class CacheLock:
             raise RuntimeError(msg)
 
         self._is_held = True
+        # True while a claim is on its way to the backend: if acquire() is
+        # interrupted then, the claim may be stored with nobody to release it.
+        claim_in_flight = False
+        backend: BaseCacheBackend | None = None
         try:
             is_blocking = self.blocking if blocking is None else blocking
             effective_timeout = self.timeout if timeout is None else timeout
@@ -116,19 +125,23 @@ class CacheLock:
             backend = self._get_backend()
 
             if not is_blocking:
+                claim_in_flight = True
                 acquired = await backend.set_if_absent(
                     self.key, self._entry, ttl=effective_ttl
                 )
+                claim_in_flight = False
                 if not acquired:
                     self._is_held = False
                 return acquired
 
             start = time.monotonic()
             while True:
+                claim_in_flight = True
                 if await backend.set_if_absent(
                     self.key, self._entry, ttl=effective_ttl
                 ):
                     return True
+                claim_in_flight = False
                 if effective_timeout is not None:
                     elapsed = time.monotonic() - start
                     if elapsed >= effective_timeout:
@@ -141,8 +154,43 @@ class CacheLock:
                 await asyncio.sleep(sleep_time)
         except BaseException:
             self._is_held = False
+            if claim_in_flight and backend is not None:
+                await self._withdraw_claim(backend)
             raise
 
+    async def _withdraw_claim(self, backend: BaseCacheBackend) -> None:
+        """Remove a claim that may have reached the backend before an error (#234).
+
+        A cancellation (a request timeout, a client disconnect) or a transport
+        error can interrupt ``set_if_absent`` after the backend stored the
+        claim, which would leave the key held by nobody until its TTL ran
+        out. The token is unique to this instance, so deleting it only if it
+        is still there cannot release anyone else's lock. Shielded, so a
+        second cancellation does not stop the delete; best effort, so a
+        failure is logged and the original exception still propagates. The
+        failure is logged from the task itself, so it is logged even when a
+        second cancellation stopped this method from waiting for the delete.
+        """
+        withdrawal = asyncio.ensure_future(
+            backend.delete_if_equals(self.key, self._entry)
+        )
+        _pending_withdrawals.add(withdrawal)
+        withdrawal.add_done_callback(self._log_failed_withdrawal)
+        # A failure is logged by _log_failed_withdrawal.
+        with contextlib.suppress(Exception):
+            await asyncio.shield(withdrawal)
+
+    def _log_failed_withdrawal(self, withdrawal: "asyncio.Task[bool]") -> None:
+        """Log a withdrawal that raised; reading the exception also retrieves it."""
+        _pending_withdrawals.discard(withdrawal)
+        if withdrawal.cancelled() or withdrawal.exception() is None:
+            return
+        logger.warning(
+            "CacheLock could not withdraw an interrupted claim; key=%s",
+            self.key,
+            exc_info=withdrawal.exception(),
+        )
+
     async def release(self) -> bool:
         """Release the lock if still held by this instance.
 

{fastapi_cachex-0.4.0 → fastapi_cachex-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-cachex"
-version = "0.4.0"
+version = "0.4.1"
 description = "A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends."
 readme = "README.md"
 requires-python = ">=3.10"

{fastapi_cachex-0.4.0 → fastapi_cachex-0.4.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-cachex"
-version = "0.4.0"
+version = "0.4.1"
 description = "A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends."
 readme = "README.md"
 requires-python = ">=3.10"