fastapi-cachex 0.5.2__tar.gz → 0.5.3__tar.gz

{fastapi_cachex-0.5.2 → fastapi_cachex-0.5.3}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.5.2
+Version: 0.5.3
 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
 Author-email: allen0099 <s96016641@gmail.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3

{fastapi_cachex-0.5.2 → fastapi_cachex-0.5.3}/fastapi_cachex/_stored_response.py

@@ -121,7 +121,9 @@ def _get_response_body(response: Response) -> bytes | None:
 
 
 def _etag_for(body: bytes) -> str:
-    return f'W/"{hashlib.md5(body).hexdigest()}"'  # noqa: S324
+    # A validator, not a security control: say so, or a FIPS-mode OpenSSL
+    # refuses MD5 and every render fails (#496).
+    return f'W/"{hashlib.md5(body, usedforsecurity=False).hexdigest()}"'
 
 
 def _weak_etag(etag: str) -> str:

{fastapi_cachex-0.5.2 → fastapi_cachex-0.5.3}/fastapi_cachex/backends/base.py

@@ -7,7 +7,6 @@ from collections.abc import Iterable
 from datetime import timedelta
 from types import TracebackType
 from typing import TYPE_CHECKING
-from typing import Any
 from typing import overload
 
 from fastapi_cachex.exceptions import CacheXError
@@ -102,6 +101,24 @@ def validate_ttl(ttl: int | timedelta | None) -> int | None:
     return ttl
 
 
+def require_ttl(ttl: int | timedelta) -> int:
+    """``validate_ttl`` for a TTL that must be given, such as a lock lease.
+
+    ``expire_if_equals`` renews a lease; "no expiry" there would make a lock
+    permanent, and each backend used to read ``None`` its own way (#499).
+
+    Raises:
+        TTLTypeError: If ``ttl`` is ``None``, or anything ``validate_ttl``
+            refuses with it
+        TTLValueError: As ``validate_ttl``
+    """
+    if ttl is None:
+        # Unreachable for type checkers; guards untyped callers.
+        msg = "ttl must be an int number of seconds or a timedelta, got None"  # type: ignore[unreachable]
+        raise TTLTypeError(msg)
+    return validate_ttl(ttl)
+
+
 def _whole_seconds(value: timedelta, name: str) -> int:
     """The whole number of seconds in ``value``.
 
@@ -305,12 +322,18 @@ class BaseCacheBackend(ABC):
         Args:
             key: Cache key to update expiry for
             expected: The entry the caller stored (compared with ``==``)
-            ttl: Time to live in seconds
+            ttl: Time to live in seconds or as a ``timedelta``; required
 
         Returns:
             Whether the expiry was updated
+
+        Raises:
+            TTLTypeError: If ``ttl`` is ``None`` or not an ``int`` or a
+                ``timedelta``
+            TTLValueError: If ``ttl`` is zero, negative or larger than
+                ``MAX_TTL``
         """
-        ttl = validate_ttl(ttl)
+        ttl = require_ttl(ttl)
         if await self.get(key) != expected:
             return False
         await self.set(key, expected, ttl=ttl)
@@ -442,7 +465,7 @@ class BaseCacheBackend(ABC):
         """
 
     @abstractmethod
-    async def get_cache_data(self) -> dict[str, tuple[Any, float | None]]:
+    async def get_cache_data(self) -> dict[str, tuple[CacheEntry, float | None]]:
         """Get all cache data with expiry information.
 
         This method is primarily used for cache monitoring and statistics.

{fastapi_cachex-0.5.2 → fastapi_cachex-0.5.3}/fastapi_cachex/backends/codec.py

@@ -22,8 +22,10 @@ except ImportError:  # pragma: no cover - import-time, environment dependent
 
 # ``json.loads`` (either implementation) raises ``ValueError`` subclasses for bad
 # JSON; ``KeyError``/``TypeError``/``AttributeError`` cover documents whose shape
-# is not the one ``encode_entry`` writes (missing fields, non-string content).
-_DECODE_ERRORS = (ValueError, KeyError, TypeError, AttributeError)
+# is not the one ``encode_entry`` writes (missing fields, non-string content);
+# fields of another type are checked in ``decode_entry``.
+# The standard library parser raises ``RecursionError`` on deep nesting.
+_DECODE_ERRORS = (ValueError, KeyError, TypeError, AttributeError, RecursionError)
 
 
 def encode_entry(entry: CacheEntry) -> bytes:
@@ -54,6 +56,11 @@ def encode_entry(entry: CacheEntry) -> bytes:
     return serialized if isinstance(serialized, bytes) else serialized.encode("utf-8")
 
 
+# The status codes HTTP defines; anything else cannot be replayed.
+_MIN_STATUS = 100
+_MAX_STATUS = 599
+
+
 def _stored_at(value: object) -> float | None:
     """``stored_at`` from a document; anything but a finite number is unknown."""
     if isinstance(value, bool) or not isinstance(value, (int, float)):
@@ -66,8 +73,8 @@ def decode_entry(raw: str | bytes | None) -> CacheEntry | None:
 
     A bare integer (what the server-side ``INCR`` family leaves behind for
     ``increment``) becomes a counter entry. Anything else that is not a document
-    written by ``encode_entry`` (corrupt JSON, missing fields, non-string
-    content) yields ``None``, so callers can treat every malformed value as a
+    written by ``encode_entry`` (corrupt JSON, missing fields, a field of the
+    wrong type, a status code outside 100-599) yields ``None``, so callers can treat every malformed value as a
     cache miss.
 
     Documents written before entries carried a status code and headers simply
@@ -83,11 +90,22 @@ def decode_entry(raw: str | bytes | None) -> CacheEntry | None:
         return counter_entry(counter)
     try:
         data = json.loads(raw)
+        fingerprint = data["fingerprint"]
+        media_type = data.get("media_type")
+        status_code = data.get("status_code", DEFAULT_STATUS_CODE)
+        if (
+            not isinstance(fingerprint, str)
+            or not isinstance(media_type, (str, type(None)))
+            or isinstance(status_code, bool)
+            or not isinstance(status_code, int)
+            or not _MIN_STATUS <= status_code <= _MAX_STATUS
+        ):
+            return None
         return CacheEntry(
-            fingerprint=data["fingerprint"],
+            fingerprint=fingerprint,
             content=data["content"].encode("latin-1"),
-            media_type=data.get("media_type"),
-            status_code=data.get("status_code", DEFAULT_STATUS_CODE),
+            media_type=media_type,
+            status_code=status_code,
             headers=data.get("headers"),
             stored_at=_stored_at(data.get("stored_at")),
         )

{fastapi_cachex-0.5.2 → fastapi_cachex-0.5.3}/fastapi_cachex/backends/memcached.py

@@ -5,6 +5,7 @@ import hashlib
 import logging
 import time
 import warnings
+from collections.abc import Callable
 from collections.abc import Iterable
 from datetime import timedelta
 
@@ -14,9 +15,11 @@ from fastapi_cachex.backends.codec import encode_entry
 from fastapi_cachex.exceptions import CacheXError
 from fastapi_cachex.exceptions import TTLValueError
 from fastapi_cachex.types import CacheEntry
+from fastapi_cachex.types import log_ref
 
 from ._unavailable import translate_unavailable
 from .base import BaseCacheBackend
+from .base import require_ttl
 from .base import validate_delta
 from .base import validate_ttl
 
@@ -57,6 +60,32 @@ _LEGAL_KEY_BYTES = frozenset(range(0x21, 0x7F))
 _MAX_PREFIX_BYTES = _MAX_KEY_BYTES - 64
 
 
+# What `connect_timeout` and `timeout` are while they are not passed. 0.6.0
+# makes it 1 second, as on the Redis backend (#516).
+_DEFAULT_TIMEOUT = 5.0
+
+_TIMEOUT_DEFAULT_NOTICE = (
+    "MemcachedBackend timeouts will default to 1 second in fastapi-cachex "
+    "0.6.0; they default to 5 seconds now. Pass connect_timeout and timeout "
+    "to choose the values and silence this warning; see "
+    "https://fastapi-cachex.readthedocs.io/en/stable/MIGRATING_0_6/#memcached-timeouts"
+)
+
+
+def _validate_timeout(name: str, value: float) -> None:
+    """Reject a timeout that is not a positive, finite number of seconds.
+
+    Zero would make the sockets non-blocking, and pymemcache reports a
+    negative one only when the first command connects.
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        msg = f"{name} must be a number of seconds, got {type(value).__name__}"
+        raise TypeError(msg)
+    if not 0 < value < float("inf"):
+        msg = f"{name} must be greater than zero and finite, got {value!r}"
+        raise ValueError(msg)
+
+
 def _validate_key_prefix(key_prefix: str) -> None:
     """Reject a ``key_prefix`` that would make keys Memcached refuses (#239).
 
@@ -153,19 +182,48 @@ class MemcachedBackend(BaseCacheBackend):
         self,
         servers: list[str],
         key_prefix: str = DEFAULT_MEMCACHE_PREFIX,
+        *,
+        connect_timeout: float | None = None,
+        timeout: float | None = None,
     ) -> None:
         """Initialize the Memcached backend.
 
         Args:
             servers: List of Memcached servers in format ["host:port", ...]
             key_prefix: Prefix for all cache keys (default: 'fastapi_cachex:')
+            connect_timeout: Seconds to wait for a connection to a server.
+                ``None`` (not passed) is 5 seconds, and 1 second from 0.6.0;
+                it does not disable the timeout.
+            timeout: Seconds to wait for each reply from a server. ``None``
+                (not passed) is 5 seconds, and 1 second from 0.6.0; it does
+                not disable the timeout. Every
+                call runs in a worker thread of the default executor and
+                holds it until it is answered or times out, so while a
+                server is unreachable a lower value frees those threads
+                sooner.
+
+        Warns:
+            FutureWarning: If ``connect_timeout`` or ``timeout`` is not
+                passed, since their default changes in 0.6.0 (#516).
 
         Raises:
             CacheXError: If pymemcache is not installed
+            TypeError: If ``connect_timeout`` or ``timeout`` is not a number
             ValueError: If ``key_prefix`` holds whitespace, control
-                characters or non-ASCII, or is 250 bytes or longer
+                characters or non-ASCII, or is 250 bytes or longer, or if
+                ``connect_timeout`` or ``timeout`` is not greater than zero
         """
         _validate_key_prefix(key_prefix)
+        if connect_timeout is None or timeout is None:
+            warnings.warn(
+                _TIMEOUT_DEFAULT_NOTICE, FutureWarning, stacklevel=caller_stacklevel()
+            )
+        connect_timeout = (
+            _DEFAULT_TIMEOUT if connect_timeout is None else connect_timeout
+        )
+        timeout = _DEFAULT_TIMEOUT if timeout is None else timeout
+        _validate_timeout("connect_timeout", connect_timeout)
+        _validate_timeout("timeout", timeout)
         try:
             from pymemcache import HashClient
         except ImportError as exc:
@@ -185,8 +243,8 @@ class MemcachedBackend(BaseCacheBackend):
         # ``_DEAD_TIMEOUT`` seconds.
         self.client = HashClient(
             servers,
-            connect_timeout=5,
-            timeout=5,
+            connect_timeout=connect_timeout,
+            timeout=timeout,
             use_pooling=True,
             default_noreply=False,
             retry_attempts=0,
@@ -298,7 +356,15 @@ class MemcachedBackend(BaseCacheBackend):
                 return None
             logger.debug("Memcached GET_AND_DELETE RETRY; key=%s", key)
 
-        msg = f"Memcached get_and_delete exceeded {_CAS_MAX_RETRIES} attempts on key {key!r}"
+        # The message reaches error logs and trackers: a digest, not the key.
+        key_ref = log_ref(key)
+        logger.debug(
+            "Memcached GET_AND_DELETE GAVE UP; key_ref=%s key=%s", key_ref, key
+        )
+        msg = (
+            f"Memcached get_and_delete exceeded {_CAS_MAX_RETRIES} attempts "
+            f"(key_ref={key_ref})"
+        )
         raise CacheXError(msg)
 
     @_unavailable
@@ -325,31 +391,45 @@ class MemcachedBackend(BaseCacheBackend):
         )
         return bool(stored)
 
-    @_unavailable
-    async def delete_if_equals(self, key: str, expected: CacheEntry) -> bool:
-        """Atomically remove ``key`` while it holds ``expected`` (see base class).
+    def _cas_if_equals(
+        self,
+        operation: str,
+        key: str,
+        expected: CacheEntry,
+        new: Callable[[bytes], bytes],
+        exptime: int,
+    ) -> bool:
+        """GETS, compare and CAS in one worker thread.
 
-        The classic protocol's DELETE takes no CAS token, so the release is a
-        CAS write with a negative exptime, which Memcached treats as "expired
-        immediately": it succeeds only if nothing wrote the key since ``GETS``
-        read the value that was compared.
+        Writes ``new(raw)``, given the bytes just read, with ``exptime`` only
+        if the key holds ``expected`` and nothing wrote or deleted it since
+        ``GETS`` read the value that was compared. ``new`` is called only once
+        the comparison has passed.
         """
-        return await asyncio.to_thread(self._delete_if_equals, key, expected)
-
-    def _delete_if_equals(self, key: str, expected: CacheEntry) -> bool:
-        """Run ``delete_if_equals``'s GETS, compare and CAS in one worker thread."""
         prefixed_key = self._make_key(key)
         raw, cas_token = self.client.gets(prefixed_key)
         if raw is None or decode_entry(raw) != expected:
-            logger.debug("Memcached DELETE_IF_EQUALS MISMATCH; key=%s", key)
+            logger.debug("Memcached %s MISMATCH; key=%s", operation, key)
             return False
-        deleted = self.client.cas(prefixed_key, b"", cas_token, -1, noreply=False)
+        done = self.client.cas(
+            prefixed_key, new(raw), cas_token, exptime, noreply=False
+        )
         logger.debug(
-            "Memcached DELETE_IF_EQUALS %s; key=%s",
-            "HIT" if deleted else "LOST RACE",
-            key,
+            "Memcached %s %s; key=%s", operation, "HIT" if done else "LOST RACE", key
+        )
+        return bool(done)
+
+    @_unavailable
+    async def delete_if_equals(self, key: str, expected: CacheEntry) -> bool:
+        """Atomically remove ``key`` while it holds ``expected`` (see base class).
+
+        The classic protocol's DELETE takes no CAS token, so the release is a
+        CAS write with a negative exptime, which Memcached treats as "expired
+        immediately".
+        """
+        return await asyncio.to_thread(
+            self._cas_if_equals, "DELETE_IF_EQUALS", key, expected, lambda _: b"", -1
         )
-        return bool(deleted)
 
     @_unavailable
     async def expire_if_equals(
@@ -360,30 +440,16 @@ class MemcachedBackend(BaseCacheBackend):
         TOUCH in the Memcached protocol takes no CAS token, so the renewal is a
         CAS write with the same bytes read by GETS and the new exptime.
         """
-        ttl = validate_ttl(ttl)
         # Converted up front so a ttl Memcached cannot store fails before I/O.
-        exptime = _expiry(ttl)
+        exptime = _expiry(require_ttl(ttl))
         return await asyncio.to_thread(
-            self._expire_if_equals, key, expected, ttl, exptime
-        )
-
-    def _expire_if_equals(
-        self, key: str, expected: CacheEntry, ttl: int, exptime: int
-    ) -> bool:
-        """Run ``expire_if_equals``'s GETS, compare and CAS in one worker thread."""
-        prefixed_key = self._make_key(key)
-        raw, cas_token = self.client.gets(prefixed_key)
-        if raw is None or decode_entry(raw) != expected:
-            logger.debug("Memcached EXPIRE_IF_EQUALS MISMATCH; key=%s", key)
-            return False
-        updated = self.client.cas(prefixed_key, raw, cas_token, exptime, noreply=False)
-        logger.debug(
-            "Memcached EXPIRE_IF_EQUALS %s; key=%s ttl=%s",
-            "HIT" if updated else "LOST RACE",
+            self._cas_if_equals,
+            "EXPIRE_IF_EQUALS",
             key,
-            ttl,
+            expected,
+            lambda raw: raw,
+            exptime,
         )
-        return bool(updated)
 
     @_unavailable
     async def set_if_equals(
@@ -393,42 +459,17 @@ class MemcachedBackend(BaseCacheBackend):
         value: CacheEntry,
         ttl: int | timedelta | None = None,
     ) -> bool:
-        """Atomically store ``value`` while ``key`` holds ``expected`` (see base class).
-
-        GETS reads the value to compare along with its CAS token, and the CAS
-        write succeeds only if nothing wrote or deleted the key since.
-        """
-        ttl = validate_ttl(ttl)
+        """Atomically store ``value`` while ``key`` holds ``expected`` (see base class)."""
         # Converted up front so a ttl Memcached cannot store fails before I/O.
-        exptime = _expiry(ttl)
+        exptime = _expiry(validate_ttl(ttl))
         return await asyncio.to_thread(
-            self._set_if_equals, key, expected, value, ttl, exptime
-        )
-
-    def _set_if_equals(
-        self,
-        key: str,
-        expected: CacheEntry,
-        value: CacheEntry,
-        ttl: int | None,
-        exptime: int,
-    ) -> bool:
-        """Run ``set_if_equals``'s GETS, compare and CAS in one worker thread."""
-        prefixed_key = self._make_key(key)
-        raw, cas_token = self.client.gets(prefixed_key)
-        if raw is None or decode_entry(raw) != expected:
-            logger.debug("Memcached SET_IF_EQUALS MISMATCH; key=%s", key)
-            return False
-        stored = self.client.cas(
-            prefixed_key, encode_entry(value), cas_token, exptime, noreply=False
-        )
-        logger.debug(
-            "Memcached SET_IF_EQUALS %s; key=%s ttl=%s",
-            "HIT" if stored else "LOST RACE",
+            self._cas_if_equals,
+            "SET_IF_EQUALS",
             key,
-            ttl,
+            expected,
+            lambda _: encode_entry(value),
+            exptime,
         )
-        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.
@@ -623,7 +664,6 @@ class MemcachedBackend(BaseCacheBackend):
         )
         return removed
 
-    @_unavailable
     async def clear_pattern(self, pattern: str) -> int:
         """Clear cached responses matching a pattern.
 
@@ -647,7 +687,6 @@ class MemcachedBackend(BaseCacheBackend):
         logger.debug("Memcached CLEAR_PATTERN unsupported; pattern=%s", pattern)
         return 0
 
-    @_unavailable
     async def get_all_keys(self) -> list[str]:
         """Get all cache keys in the backend.
 
@@ -670,7 +709,6 @@ class MemcachedBackend(BaseCacheBackend):
         logger.debug("Memcached GET_ALL_KEYS unsupported; returning empty list")
         return []
 
-    @_unavailable
     async def get_cache_data(self) -> dict[str, tuple[CacheEntry, float | None]]:
         """Get all cache data with expiry information.
 

{fastapi_cachex-0.5.2 → fastapi_cachex-0.5.3}/fastapi_cachex/backends/memory.py

@@ -18,6 +18,7 @@ from fastapi_cachex.types import counter_value
 
 from .base import BaseCacheBackend
 from .base import check_counter_range
+from .base import require_ttl
 from .base import validate_delta
 from .base import validate_ttl
 from .base import warn_if_path_shaped
@@ -235,7 +236,13 @@ class MemoryBackend(BaseCacheBackend):
     async def delete_many(self, keys: Iterable[str]) -> int:
         """Remove every key in ``keys`` under one lock; returns how many existed."""
         doomed = set(keys)
-        removed = await self._evict(doomed.__contains__)
+        # Popped key by key: `_evict` would walk the whole cache (#498).
+        async with self.lock:
+            now = time.time()
+            removed = 0
+            for key in doomed:
+                item = self.cache.pop(key, None)
+                removed += item is not None and _is_live(item, now)
         logger.debug(
             "Memory cache DELETE_MANY; requested=%s removed=%s", len(doomed), removed
         )
@@ -289,7 +296,7 @@ class MemoryBackend(BaseCacheBackend):
         self, key: str, expected: CacheEntry, ttl: int | timedelta
     ) -> bool:
         """Atomically update expiry on ``key`` while it holds ``expected`` (see base class)."""
-        ttl = validate_ttl(ttl)
+        ttl = require_ttl(ttl)
         async with self.lock:
             item = self.cache.get(key)
             if item is None or not _is_live(item, time.time()):