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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.3.8
+Version: 0.4.0
 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
@@ -26,7 +26,6 @@ Requires-Dist: itsdangerous>=1.1.0
 Requires-Dist: pydantic>=2.7.0
 Requires-Dist: starlette>=1.0.0
 Requires-Dist: pyjwt>=2.9.0 ; extra == 'jwt'
-Requires-Dist: pymemcache>=4.0.0 ; extra == 'memcache'
 Requires-Dist: pymemcache>=4.0.0 ; extra == 'memcached'
 Requires-Dist: redis[hiredis]>=5.3.0 ; extra == 'redis'
 Requires-Dist: orjson>=3.4.7 ; extra == 'redis'
@@ -36,7 +35,6 @@ 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: memcached
 Provides-Extra: redis
 Description-Content-Type: text/markdown
@@ -57,7 +55,7 @@ Description-Content-Type: text/markdown
 
 [English](https://fastapi-cachex.readthedocs.io/en/latest/) | [繁體中文](https://fastapi-cachex.readthedocs.io/zh-tw/latest/)
 
-A high-performance caching extension for FastAPI: a server-side response cache with `Cache-Control` and `ETag` support, application-level caching, and optional session management.
+A high-performance caching extension for FastAPI: a server-side response cache with `Cache-Control` and `ETag` support, and application-level caching.
 
 **Documentation:** <https://fastapi-cachex.readthedocs.io/en/latest/> — guides and the full API reference.
 
@@ -69,9 +67,9 @@ A high-performance caching extension for FastAPI: a server-side response cache w
   your own code, with compute-on-miss `get_or_set()` and atomic store-if-absent `add()`.
 - **Backends** — in-memory, Redis and Memcached, with atomic counters,
   one-shot values and locks.
-- **Sessions (optional)** — HMAC-signed or JWT session tokens over headers,
-  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.
+- **Sessions and OAuth state (deprecated)**: signed session tokens and one-time
+  OAuth state tokens. Both are deprecated in 0.4.0 and removed in 0.5.0; see
+  [where to move](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/#session-state-deprecated).
 
 ## Installation
 
@@ -85,7 +83,7 @@ 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` |
-| `memcached` | `uv add "fastapi-cachex[memcached]"` | `pymemcache` | `MemcachedBackend` (the older `memcache` name still works until 0.4.0) |
+| `memcached` | `uv add "fastapi-cachex[memcached]"` | `pymemcache` | `MemcachedBackend` |
 | `jwt` | `uv add "fastapi-cachex[jwt]"` | `PyJWT` | `SessionConfig(token_format="jwt")` |
 
 Extras combine: `uv add "fastapi-cachex[redis,jwt]"`.
@@ -114,27 +112,45 @@ def build_report() -> dict:
 
 @app.get("/report")
 async def report(cache: AppCache):
-    # Cache any JSON value in your own code.
+    # Cache any JSON value in your own code. Concurrent misses run
+    # build_report once: get_or_set() locks by default.
     return await cache.get_or_set("report", build_report, ttl=300)
 ```
 
+> [!IMPORTANT]
+> Put `@cache` **below** the route decorator. FastAPI registers whatever function
+> reaches `@app.get(...)`; with `@cache` on top, FastAPI registers the
+> undecorated handler, so the route works but nothing is cached and nothing warns
+> (see [Decorator order](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#decorator-order)).
+>
+> ```python
+> @app.get("/items")  # ✅ route decorator first,
+> @cache(ttl=60)      #    @cache directly above the function
+> async def items(): ...
+>
+> @cache(ttl=60)      # ❌ never called: nothing is cached
+> @app.get("/items")
+> async def items(): ...
+> ```
+
 > [!WARNING]
 > The default cache key carries no user identity. Cache authenticated endpoints
-> with `private=True` or a per-user key builder — see
+> with `private=True` or a per-user key builder plus `cache_authorized=True`
+> (requests with `Authorization` or a session otherwise bypass the backend) — see
 > [Authenticated endpoints](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#authenticated-endpoints).
 
 ## Documentation
 
+- [Migrating to 0.4.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/) — what 0.4.0 changes and how to upgrade from 0.3.x
 - [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
 - [Distributed lock](https://fastapi-cachex.readthedocs.io/en/latest/LOCK/) — `CacheLock` for multi-process mutual exclusion
+- Deprecated, removed in 0.5.0: [Session management](https://fastapi-cachex.readthedocs.io/en/latest/SESSION/), [OAuth state](https://fastapi-cachex.readthedocs.io/en/latest/STATE/) (one-shot OAuth/CSRF state tokens) and [JWT claims](https://fastapi-cachex.readthedocs.io/en/latest/JWT_CLAIMS/)
+- [Cache flow](https://fastapi-cachex.readthedocs.io/en/latest/CACHE_FLOW/) — what happens inside a cached request
 - [Runnable examples](https://github.com/allen0099/FastAPI-CacheX/tree/master/examples) — one complete app per feature, each covered by the test suite
 - [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/)
+- [Development guide](https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/) and [contributing](https://fastapi-cachex.readthedocs.io/en/latest/CONTRIBUTING/) · [Security policy](https://github.com/allen0099/FastAPI-CacheX/blob/master/SECURITY.md) — report vulnerabilities privately, not in public issues
 - [Changelog](https://github.com/allen0099/FastAPI-CacheX/blob/master/CHANGELOG.md) · [Known limitations and planned work](https://github.com/allen0099/FastAPI-CacheX/issues)
 
 ## License

{fastapi_cachex-0.3.8 → fastapi_cachex-0.4.0}/README.md

@@ -14,7 +14,7 @@
 
 [English](https://fastapi-cachex.readthedocs.io/en/latest/) | [繁體中文](https://fastapi-cachex.readthedocs.io/zh-tw/latest/)
 
-A high-performance caching extension for FastAPI: a server-side response cache with `Cache-Control` and `ETag` support, application-level caching, and optional session management.
+A high-performance caching extension for FastAPI: a server-side response cache with `Cache-Control` and `ETag` support, and application-level caching.
 
 **Documentation:** <https://fastapi-cachex.readthedocs.io/en/latest/> — guides and the full API reference.
 
@@ -26,9 +26,9 @@ A high-performance caching extension for FastAPI: a server-side response cache w
   your own code, with compute-on-miss `get_or_set()` and atomic store-if-absent `add()`.
 - **Backends** — in-memory, Redis and Memcached, with atomic counters,
   one-shot values and locks.
-- **Sessions (optional)** — HMAC-signed or JWT session tokens over headers,
-  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.
+- **Sessions and OAuth state (deprecated)**: signed session tokens and one-time
+  OAuth state tokens. Both are deprecated in 0.4.0 and removed in 0.5.0; see
+  [where to move](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/#session-state-deprecated).
 
 ## Installation
 
@@ -42,7 +42,7 @@ 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` |
-| `memcached` | `uv add "fastapi-cachex[memcached]"` | `pymemcache` | `MemcachedBackend` (the older `memcache` name still works until 0.4.0) |
+| `memcached` | `uv add "fastapi-cachex[memcached]"` | `pymemcache` | `MemcachedBackend` |
 | `jwt` | `uv add "fastapi-cachex[jwt]"` | `PyJWT` | `SessionConfig(token_format="jwt")` |
 
 Extras combine: `uv add "fastapi-cachex[redis,jwt]"`.
@@ -71,27 +71,45 @@ def build_report() -> dict:
 
 @app.get("/report")
 async def report(cache: AppCache):
-    # Cache any JSON value in your own code.
+    # Cache any JSON value in your own code. Concurrent misses run
+    # build_report once: get_or_set() locks by default.
     return await cache.get_or_set("report", build_report, ttl=300)
 ```
 
+> [!IMPORTANT]
+> Put `@cache` **below** the route decorator. FastAPI registers whatever function
+> reaches `@app.get(...)`; with `@cache` on top, FastAPI registers the
+> undecorated handler, so the route works but nothing is cached and nothing warns
+> (see [Decorator order](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#decorator-order)).
+>
+> ```python
+> @app.get("/items")  # ✅ route decorator first,
+> @cache(ttl=60)      #    @cache directly above the function
+> async def items(): ...
+>
+> @cache(ttl=60)      # ❌ never called: nothing is cached
+> @app.get("/items")
+> async def items(): ...
+> ```
+
 > [!WARNING]
 > The default cache key carries no user identity. Cache authenticated endpoints
-> with `private=True` or a per-user key builder — see
+> with `private=True` or a per-user key builder plus `cache_authorized=True`
+> (requests with `Authorization` or a session otherwise bypass the backend) — see
 > [Authenticated endpoints](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#authenticated-endpoints).
 
 ## Documentation
 
+- [Migrating to 0.4.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/) — what 0.4.0 changes and how to upgrade from 0.3.x
 - [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
 - [Distributed lock](https://fastapi-cachex.readthedocs.io/en/latest/LOCK/) — `CacheLock` for multi-process mutual exclusion
+- Deprecated, removed in 0.5.0: [Session management](https://fastapi-cachex.readthedocs.io/en/latest/SESSION/), [OAuth state](https://fastapi-cachex.readthedocs.io/en/latest/STATE/) (one-shot OAuth/CSRF state tokens) and [JWT claims](https://fastapi-cachex.readthedocs.io/en/latest/JWT_CLAIMS/)
+- [Cache flow](https://fastapi-cachex.readthedocs.io/en/latest/CACHE_FLOW/) — what happens inside a cached request
 - [Runnable examples](https://github.com/allen0099/FastAPI-CacheX/tree/master/examples) — one complete app per feature, each covered by the test suite
 - [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/)
+- [Development guide](https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/) and [contributing](https://fastapi-cachex.readthedocs.io/en/latest/CONTRIBUTING/) · [Security policy](https://github.com/allen0099/FastAPI-CacheX/blob/master/SECURITY.md) — report vulnerabilities privately, not in public issues
 - [Changelog](https://github.com/allen0099/FastAPI-CacheX/blob/master/CHANGELOG.md) · [Known limitations and planned work](https://github.com/allen0099/FastAPI-CacheX/issues)
 
 ## License

fastapi_cachex-0.4.0/fastapi_cachex/__init__.py

@@ -0,0 +1,149 @@
+"""FastAPI-CacheX: A powerful and flexible caching extension for FastAPI."""
+
+import logging
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version
+from typing import TYPE_CHECKING
+
+from .cache import build_cache_key as build_cache_key
+from .cache import cache as cache
+from .cache import default_key_builder as default_key_builder
+from .cache import invalidate as invalidate
+from .cache_key import CacheKey as CacheKey
+from .dependencies import AppCache as AppCache
+from .dependencies import CacheBackend as CacheBackend
+from .dependencies import get_app_cache as get_app_cache
+from .dependencies import get_cache_backend as get_cache_backend
+from .exceptions import BackendNotFoundError as BackendNotFoundError
+from .exceptions import CacheXError as CacheXError
+from .exceptions import LockTimeoutError as LockTimeoutError
+from .exceptions import ProxyNotSetError as ProxyNotSetError
+from .exceptions import RequestNotFoundError as RequestNotFoundError
+from .lock import CacheLock as CacheLock
+from .manager import CacheManager as CacheManager
+from .manager_proxy import CacheManagerProxy as CacheManagerProxy
+from .proxy import BackendProxy as BackendProxy
+from .routes import add_routes as add_routes
+from .types import CacheKeyBuilder as CacheKeyBuilder
+
+if TYPE_CHECKING:
+    # Type checkers see the real types; at runtime `__getattr__` loads them.
+    from .session import (
+        FastAPICacheXSessionMiddleware as FastAPICacheXSessionMiddleware,
+    )
+    from .session import Session as Session
+    from .session import SessionConfig as SessionConfig
+    from .session import SessionManager as SessionManager
+    from .session import SessionManagerProxy as SessionManagerProxy
+    from .session import SessionUser as SessionUser
+    from .session import get_optional_session as get_optional_session
+    from .session import get_session as get_session
+    from .session import get_session_manager as get_session_manager
+    from .session import require_session as require_session
+    from .session import require_user_session as require_user_session
+    from .session.exceptions import SessionError as SessionError
+    from .session.exceptions import SessionExpiredError as SessionExpiredError
+    from .session.exceptions import SessionInvalidError as SessionInvalidError
+    from .session.exceptions import SessionNotFoundError as SessionNotFoundError
+    from .session.exceptions import SessionSecurityError as SessionSecurityError
+    from .session.exceptions import SessionTokenError as SessionTokenError
+    from .state import InvalidStateError as InvalidStateError
+    from .state import StateData as StateData
+    from .state import StateDataError as StateDataError
+    from .state import StateError as StateError
+    from .state import StateExpiredError as StateExpiredError
+    from .state import StateManager as StateManager
+    from .state import StateManagerDep as StateManagerDep
+    from .state import StateManagerProxy as StateManagerProxy
+    from .state import get_state_manager as get_state_manager
+
+
+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()
+)  # Attach a NullHandler to avoid "No handler found" warnings in user applications.
+
+# Session and OAuth state names, deprecated in 0.4.0 and removed in 0.5.0
+# (#420). They load on first use, so `import fastapi_cachex` does not import
+# either package; importing one emits its FutureWarning. They are left out of
+# `__all__`, so `from fastapi_cachex import *` does not load them either.
+_DEPRECATED_NAMES = {
+    "FastAPICacheXSessionMiddleware": "fastapi_cachex.session",
+    "InvalidStateError": "fastapi_cachex.state",
+    "Session": "fastapi_cachex.session",
+    "SessionConfig": "fastapi_cachex.session",
+    "SessionError": "fastapi_cachex.session.exceptions",
+    "SessionExpiredError": "fastapi_cachex.session.exceptions",
+    "SessionInvalidError": "fastapi_cachex.session.exceptions",
+    "SessionManager": "fastapi_cachex.session",
+    "SessionManagerProxy": "fastapi_cachex.session",
+    "SessionNotFoundError": "fastapi_cachex.session.exceptions",
+    "SessionSecurityError": "fastapi_cachex.session.exceptions",
+    "SessionTokenError": "fastapi_cachex.session.exceptions",
+    "SessionUser": "fastapi_cachex.session",
+    "StateData": "fastapi_cachex.state",
+    "StateDataError": "fastapi_cachex.state",
+    "StateError": "fastapi_cachex.state",
+    "StateExpiredError": "fastapi_cachex.state",
+    "StateManager": "fastapi_cachex.state",
+    "StateManagerDep": "fastapi_cachex.state",
+    "StateManagerProxy": "fastapi_cachex.state",
+    "get_optional_session": "fastapi_cachex.session",
+    "get_session": "fastapi_cachex.session",
+    "get_session_manager": "fastapi_cachex.session",
+    "get_state_manager": "fastapi_cachex.state",
+    "require_session": "fastapi_cachex.session",
+    "require_user_session": "fastapi_cachex.session",
+}
+
+
+def __getattr__(name: str) -> object:
+    """Resolve a deprecated session or state name on first use."""
+    module_name = _DEPRECATED_NAMES.get(name)
+    if module_name is None:
+        msg = f"module {__name__!r} has no attribute {name!r}"
+        raise AttributeError(msg)
+    value = getattr(import_module(module_name), name)
+    globals()[name] = value
+    return value
+
+
+__all__ = [
+    "AppCache",
+    "BackendNotFoundError",
+    "BackendProxy",
+    "CacheBackend",
+    "CacheKey",
+    "CacheKeyBuilder",
+    "CacheLock",
+    "CacheManager",
+    "CacheManagerProxy",
+    "CacheXError",
+    "LockTimeoutError",
+    "ProxyNotSetError",
+    "RequestNotFoundError",
+    "__version__",
+    "add_routes",
+    "build_cache_key",
+    "cache",
+    "default_key_builder",
+    "get_app_cache",
+    "get_cache_backend",
+    "invalidate",
+]

fastapi_cachex-0.4.0/fastapi_cachex/_deprecation.py

@@ -0,0 +1,68 @@
+"""Deprecation of the session and OAuth state subsystems (#420).
+
+Both packages warn once, when they are first imported, and are removed in
+0.5.0 (#421).
+"""
+
+import inspect
+import warnings
+from types import FrameType
+
+_MIGRATION_URL = (
+    "https://fastapi-cachex.readthedocs.io/en/latest/"
+    "MIGRATING_0_4/#session-state-deprecated"
+)
+
+SESSION_DEPRECATION = (
+    "fastapi_cachex.session is deprecated and will be removed in "
+    "fastapi-cachex 0.5.0. Use Starlette's SessionMiddleware for signed-cookie "
+    f"sessions, or a dedicated session library for server-side sessions; see {_MIGRATION_URL}"
+)
+
+STATE_DEPRECATION = (
+    "fastapi_cachex.state is deprecated and will be removed in "
+    "fastapi-cachex 0.5.0. Use the state handling of your OAuth client library "
+    f"(Authlib, for example); see {_MIGRATION_URL}"
+)
+
+
+def _is_import_machinery(frame: FrameType) -> bool:
+    """Whether ``warnings.warn()`` skips ``frame`` when it counts stacklevel."""
+    filename = frame.f_code.co_filename
+    return "importlib" in filename and "_bootstrap" in filename
+
+
+def _importer_stacklevel() -> int:
+    """Return the ``stacklevel`` of the first frame outside this package.
+
+    Frames of fastapi_cachex and of the import machinery are skipped, so the
+    warning names the application's ``import`` line, or the line that read a
+    deprecated name from the ``fastapi_cachex`` package.
+    """
+    frame = inspect.currentframe()
+    if frame is None or frame.f_back is None:  # no frame support
+        return 2
+    # Level 1 is warn_deprecated(); start at its caller.
+    level, frame = 2, frame.f_back.f_back
+    while frame is not None:
+        module = frame.f_globals.get("__name__", "")
+        if not module.startswith(("fastapi_cachex.", "importlib.")) and module not in {
+            "fastapi_cachex",
+            "importlib",
+        }:
+            break
+        # warnings.warn() does not count the frozen import machinery's frames
+        # towards stacklevel, so neither may this.
+        if not _is_import_machinery(frame):
+            level += 1
+        frame = frame.f_back
+    return level
+
+
+def warn_deprecated(message: str) -> None:
+    """Emit the ``FutureWarning`` for a deprecated subsystem.
+
+    ``FutureWarning`` rather than ``DeprecationWarning``: it is shown by
+    default, and the removal affects the application, not only its tests.
+    """
+    warnings.warn(message, FutureWarning, stacklevel=_importer_stacklevel())

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

@@ -4,13 +4,21 @@ import warnings
 from abc import ABC
 from abc import abstractmethod
 from collections.abc import Iterable
+from types import TracebackType
+from typing import TYPE_CHECKING
 from typing import Any
 
 from fastapi_cachex.types import CACHE_KEY_SEPARATOR
+from fastapi_cachex.types import HTTP_KEY_FORMAT_TAG
 from fastapi_cachex.types import CacheEntry
 from fastapi_cachex.types import counter_entry
 from fastapi_cachex.types import counter_value
 
+if TYPE_CHECKING:
+    # Type-only: typing.Self is 3.11+, and typing_extensions is not a runtime
+    # dependency.
+    from typing_extensions import Self
+
 
 def warn_if_path_shaped(pattern: str, cleared: int) -> None:
     """Warn when a ``clear_pattern`` that cleared nothing was written as a path.
@@ -23,13 +31,14 @@ def warn_if_path_shaped(pattern: str, cleared: int) -> None:
     paths (stored directly through ``set``) stay silent when they work.
     """
     if cleared == 0 and pattern.startswith("/") and CACHE_KEY_SEPARATOR not in pattern:
+        sep = CACHE_KEY_SEPARATOR
         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}'.",
+            f"cache keys, which look like '{HTTP_KEY_FORMAT_TAG}{sep}method{sep}"
+            f"host{sep}path{sep}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 as "
+            f"'{HTTP_KEY_FORMAT_TAG}{sep}GET{sep}*{sep}{pattern}{sep}*'.",
             RuntimeWarning,
             stacklevel=3,
         )
@@ -89,7 +98,33 @@ def validate_delta(delta: int) -> int:
 
 
 class BaseCacheBackend(ABC):
-    """Base class for all cache backends."""
+    """Base class for all cache backends.
+
+    Every backend is an async context manager: ``async with`` returns the
+    backend itself and calls ``aclose()`` on the way out.
+    """
+
+    async def aclose(self) -> None:  # noqa: B027 - a no-op default, not abstract
+        """Release what the backend holds open: connections, background tasks.
+
+        Call it once on shutdown, typically at the end of a FastAPI lifespan.
+        It is safe to call more than once. The base implementation does
+        nothing, for backends with nothing to release; the built-in backends
+        override it.
+        """
+
+    async def __aenter__(self) -> "Self":
+        """Return the backend itself."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the backend with ``aclose()``."""
+        await self.aclose()
 
     @abstractmethod
     async def get(self, key: str) -> CacheEntry | None:
@@ -105,23 +140,50 @@ class BaseCacheBackend(ABC):
         """
 
     @abstractmethod
-    async def delete(self, key: str) -> None:
-        """Remove a response from the cache."""
+    async def delete(self, key: str) -> bool:
+        """Remove a response from the cache.
+
+        Returns:
+            Whether ``key`` held an entry that had not expired yet
+        """
 
     async def delete_many(self, keys: Iterable[str]) -> int:
         """Remove every key in ``keys``; returns how many were removed.
 
-        The base implementation deletes one key at a time and reports how
-        many were attempted, since ``delete`` does not say whether the key
-        existed. The built-in backends override it and count what was
-        actually removed.
+        The base implementation deletes one key at a time and counts the
+        deletes that found an entry. The built-in backends override it with
+        batched deletes.
         """
         count = 0
         for key in keys:
-            await self.delete(key)
-            count += 1
+            if await self._delete_reporting(key):
+                count += 1
         return count
 
+    async def _delete_reporting(self, key: str) -> bool:
+        """Call ``delete`` for the fallbacks, accepting a 0.3.x ``None`` result.
+
+        ``delete`` returned ``None`` before 0.4.0, and a third-party backend
+        written then may still do so. ``None`` counts as removed, as every
+        fallback assumed in 0.3.x, and warns: 0.5.0 will treat it as ``False``.
+        ``FutureWarning`` rather than ``DeprecationWarning``: the warning is
+        raised inside the package, where a ``DeprecationWarning`` is hidden by
+        default, and the change affects the application at runtime.
+        """
+        result: object = await self.delete(key)
+        if result is None:
+            warnings.warn(
+                f"{type(self).__name__}.delete() returned None. Since "
+                "fastapi-cachex 0.4.0 it must return whether the key was "
+                "removed; None is counted as removed until 0.5.0, which treats "
+                "it as False. See https://fastapi-cachex.readthedocs.io/en/"
+                "stable/MIGRATING_0_4/#backend-delete",
+                FutureWarning,
+                stacklevel=3,
+            )
+            return True
+        return bool(result)
+
     async def get_and_delete(self, key: str) -> CacheEntry | None:
         """Atomically retrieve and remove a cached entry.
 
@@ -137,8 +199,10 @@ class BaseCacheBackend(ABC):
             The entry that was stored under ``key``, or ``None`` if there was none
         """
         value = await self.get(key)
-        if value is not None:
-            await self.delete(key)
+        if value is None or not await self._delete_reporting(key):
+            # Absent, or another caller removed it between the get and the
+            # delete: that caller got the entry.
+            return None
         return value
 
     async def set_if_absent(
@@ -191,8 +255,7 @@ class BaseCacheBackend(ABC):
         """
         if await self.get(key) != expected:
             return False
-        await self.delete(key)
-        return True
+        return await self._delete_reporting(key)
 
     async def expire_if_equals(self, key: str, expected: CacheEntry, ttl: int) -> bool:
         """Update expiry on ``key`` to ``ttl`` seconds only while it still holds ``expected``.
@@ -220,6 +283,39 @@ class BaseCacheBackend(ABC):
         await self.set(key, expected, ttl=ttl)
         return True
 
+    async def set_if_equals(
+        self,
+        key: str,
+        expected: CacheEntry,
+        value: CacheEntry,
+        ttl: int | None = None,
+    ) -> bool:
+        """Store ``value`` only while ``key`` still holds ``expected``.
+
+        A compare-and-set: a caller that read ``expected`` earlier overwrites
+        it only if nothing changed, deleted or expired the key since. Sessions
+        save through it, so a request that loaded a session cannot bring it
+        back after another request deleted or invalidated it.
+
+        The base implementation is a best-effort, NON-atomic get-compare-set
+        fallback for third-party backends; the built-in backends override it
+        with an atomic implementation.
+
+        Args:
+            key: Cache key to overwrite
+            expected: The entry the caller last read or wrote (compared with ``==``)
+            value: Entry to store in its place
+            ttl: Time to live in seconds (``None`` = never expires)
+
+        Returns:
+            Whether ``value`` was stored
+        """
+        validate_ttl(ttl)
+        if await self.get(key) != expected:
+            return False
+        await self.set(key, value, ttl=ttl)
+        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``.
 
@@ -246,7 +342,8 @@ class BaseCacheBackend(ABC):
         Raises:
             CacheXError: If ``key`` holds a cached response instead of a counter
             TypeError: If ``delta`` or ``ttl`` is not an ``int``
-            ValueError: If ``ttl`` is out of range
+            ValueError: If ``ttl`` is out of range, or ``delta`` does not fit
+                in a signed 64-bit integer
         """
         validate_delta(delta)
         validate_ttl(ttl)
@@ -277,10 +374,11 @@ class BaseCacheBackend(ABC):
 
         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::
+        HTTP cache keys are ``http:v2|method|host|path|query`` (see
+        ``CacheKey``), so matching a path means writing the other components
+        out::
 
-            await backend.clear_pattern("GET|||*|||/users/*")
+            await backend.clear_pattern("http:v2|GET|*|/users/*")
             await backend.clear_pattern("cache:user:*")  # a CacheManager key
 
         To clear by path, prefer ``clear_path(path, include_params=...)``: it