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

fastapi_cachex-0.3.6/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: fastapi-cachex
+Version: 0.3.6
+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
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Dist: fastapi
+Requires-Dist: itsdangerous
+Requires-Dist: pydantic
+Requires-Dist: pyjwt>=2.9.0 ; extra == 'jwt'
+Requires-Dist: pymemcache ; extra == 'memcache'
+Requires-Dist: redis[hiredis]>=5.3.0 ; extra == 'redis'
+Requires-Dist: orjson ; extra == 'redis'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/allen0099/FastAPI-CacheX
+Project-URL: Repository, https://github.com/allen0099/FastAPI-CacheX.git
+Project-URL: Issues, https://github.com/allen0099/FastAPI-CacheX/issues
+Project-URL: Documentation, https://fastapi-cachex.readthedocs.io/
+Provides-Extra: jwt
+Provides-Extra: memcache
+Provides-Extra: redis
+Description-Content-Type: text/markdown
+
+# FastAPI-Cache X
+
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Tests](https://github.com/allen0099/FastAPI-CacheX/actions/workflows/test.yml/badge.svg)](https://github.com/allen0099/FastAPI-CacheX/actions/workflows/test.yml)
+[![Coverage Status](https://raw.githubusercontent.com/allen0099/FastAPI-CacheX/coverage-badge/coverage.svg)](https://github.com/allen0099/FastAPI-CacheX/actions/workflows/coverage.yml)
+
+[![Downloads](https://static.pepy.tech/badge/fastapi-cachex)](https://pepy.tech/project/fastapi-cachex)
+[![Weekly downloads](https://static.pepy.tech/badge/fastapi-cachex/week)](https://pepy.tech/project/fastapi-cachex)
+[![Monthly downloads](https://static.pepy.tech/badge/fastapi-cachex/month)](https://pepy.tech/project/fastapi-cachex)
+
+[![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)
+
+A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support and optional session management.
+
+**Documentation:** <https://fastapi-cachex.readthedocs.io/en/latest/> — guides and the full API reference.
+
+## Features
+
+- **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()`.
+- **Backends** — in-memory, Redis and Memcached, with atomic counters,
+  one-shot values and locks.
+- **Sessions (optional)** — HMAC-signed or JWT session tokens over headers,
+  bearer tokens or cookies, with sliding expiration and IP/User-Agent binding.
+- **OAuth state** — one-time state tokens for CSRF protection in OAuth/OIDC flows.
+
+## Installation
+
+```bash
+uv add fastapi-cachex
+```
+
+Everything in the core package works with the in-memory backend. The other
+backends and the optional session transports ship as extras:
+
+| Extra | Install | Pulls in | Needed for |
+|-------|---------|----------|------------|
+| `redis` | `uv add "fastapi-cachex[redis]"` | `redis[hiredis]`, `orjson` | `AsyncRedisCacheBackend` |
+| `memcache` | `uv add "fastapi-cachex[memcache]"` | `pymemcache` | `MemcachedBackend` (note: `memcache`, not `memcached`) |
+| `jwt` | `uv add "fastapi-cachex[jwt]"` | `PyJWT` | `SessionConfig(token_format="jwt")` |
+
+Extras combine: `uv add "fastapi-cachex[redis,jwt]"`.
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+
+from fastapi_cachex import AppCache, BackendProxy, cache
+from fastapi_cachex.backends import MemoryBackend
+
+app = FastAPI()
+BackendProxy.set(MemoryBackend())  # or AsyncRedisCacheBackend / MemcachedBackend
+
+
+@app.get("/items/{item_id}")
+@cache(ttl=60)  # served from the cache for 60 seconds, with ETag revalidation
+async def read_item(item_id: int):
+    return {"item_id": item_id}
+
+
+def build_report() -> dict:
+    return {"total": 42}  # stands in for something slow
+
+
+@app.get("/report")
+async def report(cache: AppCache):
+    # Cache any JSON value in your own code.
+    return await cache.get_or_set("report", build_report, ttl=300)
+```
+
+> [!WARNING]
+> The default cache key carries no user identity. Cache authenticated endpoints
+> with `private=True` or a per-user key builder — see
+> [Authenticated endpoints](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#authenticated-endpoints).
+
+## Documentation
+
+- [HTTP caching](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes
+- [Cache flow](https://fastapi-cachex.readthedocs.io/en/latest/CACHE_FLOW/) — what happens inside a cached request
+- [Application cache](https://fastapi-cachex.readthedocs.io/en/latest/APP_CACHE/) — `CacheManager`
+- [Backends](https://fastapi-cachex.readthedocs.io/en/latest/BACKENDS/) — choosing and configuring a backend, atomic primitives
+- [Session management](https://fastapi-cachex.readthedocs.io/en/latest/SESSION/) and [JWT claims](https://fastapi-cachex.readthedocs.io/en/latest/JWT_CLAIMS/)
+- [OAuth state](https://fastapi-cachex.readthedocs.io/en/latest/STATE/) — one-shot OAuth/CSRF state tokens
+- [API reference](https://fastapi-cachex.readthedocs.io/en/latest/api/http-caching/)
+- [Development guide](https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/) and [contributing](https://fastapi-cachex.readthedocs.io/en/latest/CONTRIBUTING/)
+- [Changelog](https://github.com/allen0099/FastAPI-CacheX/blob/master/CHANGELOG.md) · [Known limitations and planned work](https://github.com/allen0099/FastAPI-CacheX/issues)
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](https://github.com/allen0099/FastAPI-CacheX/blob/master/LICENSE) file for details.

fastapi_cachex-0.3.6/README.md

@@ -0,0 +1,97 @@
+# FastAPI-Cache X
+
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Tests](https://github.com/allen0099/FastAPI-CacheX/actions/workflows/test.yml/badge.svg)](https://github.com/allen0099/FastAPI-CacheX/actions/workflows/test.yml)
+[![Coverage Status](https://raw.githubusercontent.com/allen0099/FastAPI-CacheX/coverage-badge/coverage.svg)](https://github.com/allen0099/FastAPI-CacheX/actions/workflows/coverage.yml)
+
+[![Downloads](https://static.pepy.tech/badge/fastapi-cachex)](https://pepy.tech/project/fastapi-cachex)
+[![Weekly downloads](https://static.pepy.tech/badge/fastapi-cachex/week)](https://pepy.tech/project/fastapi-cachex)
+[![Monthly downloads](https://static.pepy.tech/badge/fastapi-cachex/month)](https://pepy.tech/project/fastapi-cachex)
+
+[![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)
+
+A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support and optional session management.
+
+**Documentation:** <https://fastapi-cachex.readthedocs.io/en/latest/> — guides and the full API reference.
+
+## Features
+
+- **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()`.
+- **Backends** — in-memory, Redis and Memcached, with atomic counters,
+  one-shot values and locks.
+- **Sessions (optional)** — HMAC-signed or JWT session tokens over headers,
+  bearer tokens or cookies, with sliding expiration and IP/User-Agent binding.
+- **OAuth state** — one-time state tokens for CSRF protection in OAuth/OIDC flows.
+
+## Installation
+
+```bash
+uv add fastapi-cachex
+```
+
+Everything in the core package works with the in-memory backend. The other
+backends and the optional session transports ship as extras:
+
+| Extra | Install | Pulls in | Needed for |
+|-------|---------|----------|------------|
+| `redis` | `uv add "fastapi-cachex[redis]"` | `redis[hiredis]`, `orjson` | `AsyncRedisCacheBackend` |
+| `memcache` | `uv add "fastapi-cachex[memcache]"` | `pymemcache` | `MemcachedBackend` (note: `memcache`, not `memcached`) |
+| `jwt` | `uv add "fastapi-cachex[jwt]"` | `PyJWT` | `SessionConfig(token_format="jwt")` |
+
+Extras combine: `uv add "fastapi-cachex[redis,jwt]"`.
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+
+from fastapi_cachex import AppCache, BackendProxy, cache
+from fastapi_cachex.backends import MemoryBackend
+
+app = FastAPI()
+BackendProxy.set(MemoryBackend())  # or AsyncRedisCacheBackend / MemcachedBackend
+
+
+@app.get("/items/{item_id}")
+@cache(ttl=60)  # served from the cache for 60 seconds, with ETag revalidation
+async def read_item(item_id: int):
+    return {"item_id": item_id}
+
+
+def build_report() -> dict:
+    return {"total": 42}  # stands in for something slow
+
+
+@app.get("/report")
+async def report(cache: AppCache):
+    # Cache any JSON value in your own code.
+    return await cache.get_or_set("report", build_report, ttl=300)
+```
+
+> [!WARNING]
+> The default cache key carries no user identity. Cache authenticated endpoints
+> with `private=True` or a per-user key builder — see
+> [Authenticated endpoints](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#authenticated-endpoints).
+
+## Documentation
+
+- [HTTP caching](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes
+- [Cache flow](https://fastapi-cachex.readthedocs.io/en/latest/CACHE_FLOW/) — what happens inside a cached request
+- [Application cache](https://fastapi-cachex.readthedocs.io/en/latest/APP_CACHE/) — `CacheManager`
+- [Backends](https://fastapi-cachex.readthedocs.io/en/latest/BACKENDS/) — choosing and configuring a backend, atomic primitives
+- [Session management](https://fastapi-cachex.readthedocs.io/en/latest/SESSION/) and [JWT claims](https://fastapi-cachex.readthedocs.io/en/latest/JWT_CLAIMS/)
+- [OAuth state](https://fastapi-cachex.readthedocs.io/en/latest/STATE/) — one-shot OAuth/CSRF state tokens
+- [API reference](https://fastapi-cachex.readthedocs.io/en/latest/api/http-caching/)
+- [Development guide](https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/) and [contributing](https://fastapi-cachex.readthedocs.io/en/latest/CONTRIBUTING/)
+- [Changelog](https://github.com/allen0099/FastAPI-CacheX/blob/master/CHANGELOG.md) · [Known limitations and planned work](https://github.com/allen0099/FastAPI-CacheX/issues)
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](https://github.com/allen0099/FastAPI-CacheX/blob/master/LICENSE) file for details.

{fastapi_cachex-0.3.4 → fastapi_cachex-0.3.6}/fastapi_cachex/__init__.py

@@ -1,6 +1,8 @@
 """FastAPI-CacheX: A powerful and flexible caching extension for FastAPI."""
 
 import logging
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version
 
 from .cache import cache as cache
 from .cache import default_key_builder as default_key_builder
@@ -41,6 +43,22 @@ from .state import StateManagerProxy as StateManagerProxy
 from .state import get_state_manager as get_state_manager
 from .types import CacheKeyBuilder as CacheKeyBuilder
 
+
+def _read_version() -> str:
+    """Return the installed distribution's version.
+
+    Importing from a source tree that was never installed leaves no metadata to
+    read; reporting a development version there is part of the contract, so this
+    lives in a function the tests can drive rather than behind a coverage pragma.
+    """
+    try:
+        return version("fastapi-cachex")
+    except PackageNotFoundError:
+        return "0.0.0.dev0"
+
+
+__version__ = _read_version()
+
 _package_logger = logging.getLogger("fastapi_cachex")
 _package_logger.addHandler(
     logging.NullHandler()
@@ -74,6 +92,7 @@ __all__ = [
     "StateManager",
     "StateManagerDep",
     "StateManagerProxy",
+    "__version__",
     "add_routes",
     "cache",
     "default_key_builder",

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

@@ -1,15 +1,40 @@
 """Base cache backend interface and abstract implementation."""
 
+import warnings
 from abc import ABC
 from abc import abstractmethod
 from collections.abc import Iterable
 from typing import Any
 
+from fastapi_cachex.types import CACHE_KEY_SEPARATOR
 from fastapi_cachex.types import CacheEntry
 from fastapi_cachex.types import counter_entry
 from fastapi_cachex.types import counter_value
 
 
+def warn_if_path_shaped(pattern: str, cleared: int) -> None:
+    """Warn when a ``clear_pattern`` that cleared nothing was written as a path.
+
+    Matching happens against the whole key, so a pattern like ``/users/*``
+    cannot match an HTTP cache entry and the call quietly reports zero cleared
+    — indistinguishable from a cache that was already empty, which is exactly
+    the outcome the caller was trying to avoid. Only the combination of "looks
+    like a bare path" and "matched nothing" warns, so keys that really are
+    paths (stored directly through ``set``) stay silent when they work.
+    """
+    if cleared == 0 and pattern.startswith("/") and CACHE_KEY_SEPARATOR not in pattern:
+        warnings.warn(
+            f"clear_pattern({pattern!r}) cleared nothing. Patterns match whole "
+            f"cache keys, which look like 'method{CACHE_KEY_SEPARATOR}host"
+            f"{CACHE_KEY_SEPARATOR}path{CACHE_KEY_SEPARATOR}query', so a bare "
+            "path matches no HTTP cache entry. Use clear_path(path, "
+            "include_params=True) to clear by path, or write the whole key out "
+            f"as 'GET{CACHE_KEY_SEPARATOR}*{CACHE_KEY_SEPARATOR}{pattern}'.",
+            RuntimeWarning,
+            stacklevel=3,
+        )
+
+
 class BaseCacheBackend(ABC):
     """Base class for all cache backends."""
 
@@ -58,6 +83,58 @@ class BaseCacheBackend(ABC):
             await self.delete(key)
         return value
 
+    async def set_if_absent(
+        self, key: str, value: CacheEntry, ttl: int | None = None
+    ) -> bool:
+        """Store ``value`` only when ``key`` does not exist yet.
+
+        The building block for locks and slots: of several concurrent callers
+        exactly one stores its value and gets ``True``, every other caller
+        gets ``False`` and the stored value is left untouched. An expired key
+        counts as absent. Pair it with ``delete_if_equals`` to release only
+        what you still hold.
+
+        The base implementation is a best-effort, NON-atomic get-then-set
+        fallback for third-party backends; the built-in backends override it
+        with an atomic implementation.
+
+        Args:
+            key: Cache key to claim
+            value: Entry to store, typically carrying a unique owner token
+            ttl: Time to live in seconds (``None`` = never expires)
+
+        Returns:
+            Whether ``value`` was stored
+        """
+        if await self.get(key) is not None:
+            return False
+        await self.set(key, value, ttl=ttl)
+        return True
+
+    async def delete_if_equals(self, key: str, expected: CacheEntry) -> bool:
+        """Remove ``key`` only while it still holds ``expected``.
+
+        Releasing a lock with a plain ``delete`` is unsafe: if the holder's
+        entry expired and someone else claimed the key in the meantime, the
+        delete removes the new holder's entry. Comparing against the value the
+        caller stored makes the release a no-op in that case.
+
+        The base implementation is a best-effort, NON-atomic get-compare-delete
+        fallback for third-party backends; the built-in backends override it
+        with an atomic implementation.
+
+        Args:
+            key: Cache key to release
+            expected: The entry the caller stored (compared with ``==``)
+
+        Returns:
+            Whether the entry was removed
+        """
+        if await self.get(key) != expected:
+            return False
+        await self.delete(key)
+        return True
+
     async def increment(self, key: str, delta: int = 1, ttl: int | None = None) -> int:
         """Atomically add ``delta`` to the integer counter stored at ``key``.
 
@@ -107,10 +184,23 @@ class BaseCacheBackend(ABC):
 
     @abstractmethod
     async def clear_pattern(self, pattern: str) -> int:
-        """Clear cached responses matching a pattern.
+        """Clear cached entries whose key matches a glob pattern.
+
+        The pattern is matched against the whole logical key — the key as the
+        caller sees it, without whatever prefix the backend adds internally.
+        HTTP cache keys are ``method|||host|||path|||query``, so matching a
+        path means writing the other components out::
+
+            await backend.clear_pattern("GET|||*|||/users/*")
+            await backend.clear_pattern("cache:user:*")  # a CacheManager key
+
+        To clear by path, prefer ``clear_path(path, include_params=...)``: it
+        is built for exactly that and needs no knowledge of the key layout.
+        Implementations report a path written here through
+        ``warn_if_path_shaped`` rather than silently clearing nothing.
 
         Args:
-            pattern: A glob pattern to match cache keys against (e.g., "/users/*")
+            pattern: A glob pattern to match whole cache keys against
 
         Returns:
             Number of cache entries cleared

{fastapi_cachex-0.3.4 → fastapi_cachex-0.3.6}/fastapi_cachex/backends/codec.py

@@ -4,14 +4,17 @@ Both backends store a ``CacheEntry`` as a JSON document; ``orjson`` is used when
 it is installed and the standard library ``json`` module otherwise.
 """
 
+from fastapi_cachex.types import DEFAULT_STATUS_CODE
 from fastapi_cachex.types import CacheEntry
 from fastapi_cachex.types import counter_entry
 
 try:
     import orjson as json
 
-except ImportError:  # pragma: no cover
-    import json  # type: ignore[no-redef]  # pragma: no cover
+# Resolved once at import time; whichever branch this interpreter takes, the
+# other one cannot be reached again in the same process.
+except ImportError:  # pragma: no cover - import-time, environment dependent
+    import json  # type: ignore[no-redef]
 
 # ``json.loads`` (either implementation) raises ``ValueError`` subclasses for bad
 # JSON; ``KeyError``/``TypeError``/``AttributeError`` cover documents whose shape
@@ -30,6 +33,8 @@ def encode_entry(entry: CacheEntry) -> bytes:
             "fingerprint": entry.fingerprint,
             "content": entry.content.decode("latin-1"),
             "media_type": entry.media_type,
+            "status_code": entry.status_code,
+            "headers": entry.headers,
         },
     )
     # orjson returns bytes, stdlib json returns str
@@ -52,6 +57,9 @@ def decode_entry(raw: str | bytes | None) -> CacheEntry | None:
     written by ``encode_entry`` (corrupt JSON, missing fields, non-string
     content) yields ``None``, so callers can treat every malformed value as a
     cache miss.
+
+    Documents written before entries carried a status code and headers simply
+    lack those keys and decode to a plain ``200`` with no extra headers.
     """
     if raw is None:
         return None
@@ -64,6 +72,8 @@ def decode_entry(raw: str | bytes | None) -> CacheEntry | None:
             fingerprint=data["fingerprint"],
             content=data["content"].encode("latin-1"),
             media_type=data.get("media_type"),
+            status_code=data.get("status_code", DEFAULT_STATUS_CODE),
+            headers=data.get("headers"),
         )
     except _DECODE_ERRORS:
         return None

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

@@ -1,7 +1,9 @@
 """Memcached cache backend implementation."""
 
 import asyncio
+import hashlib
 import logging
+import time
 import warnings
 
 from fastapi_cachex.backends.codec import decode_entry
@@ -16,6 +18,30 @@ logger = logging.getLogger(__name__)
 # Default Memcached key prefix for fastapi-cachex
 DEFAULT_MEMCACHE_PREFIX = "fastapi_cachex:"
 
+# Memcached accepts keys of at most 250 bytes, and pymemcache rejects any key
+# containing whitespace, control characters or non-ASCII bytes. What is left is
+# the printable ASCII range with the space removed.
+_MAX_KEY_BYTES = 250
+_LEGAL_KEY_BYTES = frozenset(range(0x21, 0x7F))
+
+# 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.
+_MAX_RELATIVE_TTL = 30 * 24 * 60 * 60
+
+
+def _expiry(ttl: int | None) -> int:
+    """Convert a TTL in seconds to the exptime Memcached expects.
+
+    Anything past the 30-day boundary is sent as an absolute timestamp;
+    passing it through as a duration would have Memcached read it as a moment
+    in 1970 and expire the entry immediately. ``None`` means no expiry.
+    """
+    if ttl is None:
+        return 0
+    if ttl > _MAX_RELATIVE_TTL:
+        return int(time.time()) + ttl
+    return ttl
+
 
 class MemcachedBackend(BaseCacheBackend):
     """Memcached backend implementation.
@@ -67,8 +93,26 @@ class MemcachedBackend(BaseCacheBackend):
         self.key_prefix = key_prefix
 
     def _make_key(self, key: str) -> str:
-        """Add prefix to cache key."""
-        return f"{self.key_prefix}{key}"
+        """Namespace a cache key, hashing it when Memcached would refuse it.
+
+        pymemcache raises ``MemcacheIllegalInputError`` for a key over 250
+        bytes or carrying whitespace, control characters or non-ASCII bytes,
+        and nothing catches it on the way out — so ordinary traffic could turn
+        into a 500. ASGI percent-decodes the path, so `/foo%20bar` alone builds
+        a key with a literal space in it, and a long query string easily runs
+        past 250 bytes.
+
+        A key Memcached would accept is returned byte-for-byte, which keeps
+        entries written by earlier versions readable; only the rest collapse to
+        a SHA-256 digest of the whole namespaced key.
+        """
+        prefixed = f"{self.key_prefix}{key}"
+        encoded = prefixed.encode("utf-8")
+        if len(encoded) <= _MAX_KEY_BYTES and _LEGAL_KEY_BYTES.issuperset(encoded):
+            return prefixed
+        digest = hashlib.sha256(encoded).hexdigest()
+        logger.debug("Memcached key hashed; key=%s digest=%s", key, digest)
+        return f"{self.key_prefix}{digest}"
 
     async def get(self, key: str) -> CacheEntry | None:
         """Get value from cache.
@@ -97,9 +141,8 @@ class MemcachedBackend(BaseCacheBackend):
             value: CacheEntry instance to store
             ttl: Time to live in seconds
         """
-        expire = ttl if ttl is not None else 0
         await asyncio.to_thread(
-            self.client.set, self._make_key(key), encode_entry(value), expire
+            self.client.set, self._make_key(key), encode_entry(value), _expiry(ttl)
         )
         logger.debug("Memcached SET; key=%s ttl=%s", key, ttl)
 
@@ -124,6 +167,51 @@ class MemcachedBackend(BaseCacheBackend):
         logger.debug("Memcached GET_AND_DELETE HIT; key=%s", key)
         return decode_entry(raw)
 
+    async def set_if_absent(
+        self, key: str, value: CacheEntry, ttl: int | None = None
+    ) -> bool:
+        """Atomically store ``value`` unless ``key`` exists (see base class).
+
+        Memcached's ``ADD`` is exactly this operation.
+        """
+        stored = await asyncio.to_thread(
+            self.client.add,
+            self._make_key(key),
+            encode_entry(value),
+            _expiry(ttl),
+            noreply=False,
+        )
+        logger.debug(
+            "Memcached SET_IF_ABSENT %s; key=%s ttl=%s",
+            "STORED" if stored else "EXISTS",
+            key,
+            ttl,
+        )
+        return bool(stored)
+
+    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": it succeeds only if nothing wrote the key since ``GETS``
+        read the value that was compared.
+        """
+        prefixed_key = self._make_key(key)
+        raw, cas_token = await asyncio.to_thread(self.client.gets, prefixed_key)
+        if raw is None or decode_entry(raw) != expected:
+            logger.debug("Memcached DELETE_IF_EQUALS MISMATCH; key=%s", key)
+            return False
+        deleted = await asyncio.to_thread(
+            self.client.cas, prefixed_key, b"", cas_token, -1, noreply=False
+        )
+        logger.debug(
+            "Memcached DELETE_IF_EQUALS %s; key=%s",
+            "HIT" if deleted else "LOST RACE",
+            key,
+        )
+        return bool(deleted)
+
     def _add_delta(self, prefixed_key: str, delta: int) -> int | None:
         """Apply ``delta`` with INCR/DECR; ``None`` when the key does not exist."""
         if delta < 0:
@@ -147,13 +235,13 @@ class MemcachedBackend(BaseCacheBackend):
                 # No counter yet: ADD is atomic and a no-op when a concurrent
                 # call created it first, so the retry always finds a counter.
                 await asyncio.to_thread(
-                    self.client.add, prefixed_key, b"0", ttl or 0, noreply=False
+                    self.client.add, prefixed_key, b"0", _expiry(ttl), noreply=False
                 )
                 value = await asyncio.to_thread(self._add_delta, prefixed_key, delta)
         except MemcacheClientError as e:
             msg = "Cache key holds a value that is not a counter"
             raise CacheXError(msg) from e
-        if value is None:  # pragma: no cover - the counter expired mid-call
+        if value is None:
             msg = "Counter vanished between ADD and INCR"
             raise CacheXError(msg)
         logger.debug("Memcached INCREMENT; key=%s value=%s ttl=%s", key, value, ttl)