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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.4.1
+Version: 0.5.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
@@ -16,16 +16,14 @@ 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.15
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Framework :: FastAPI
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Classifier: Typing :: Typed
-Requires-Dist: fastapi>=0.133.0
-Requires-Dist: itsdangerous>=1.1.0
+Requires-Dist: fastapi>=0.128.2
 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 == 'memcached'
 Requires-Dist: redis[hiredis]>=5.3.0 ; extra == 'redis'
 Requires-Dist: orjson>=3.4.7 ; extra == 'redis'
@@ -34,7 +32,6 @@ 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: memcached
 Provides-Extra: redis
 Description-Content-Type: text/markdown
@@ -64,12 +61,10 @@ A high-performance caching extension for FastAPI: a server-side response cache w
 - **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()` and atomic store-if-absent `add()`.
+  your own code, with compute-on-miss `get_or_set()` and atomic store-if-absent `add()`,
+  and `@cached` for a plain function, keyed on its arguments.
 - **Backends** — in-memory, Redis and Memcached, with atomic counters,
   one-shot values and locks.
-- **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
 
@@ -78,15 +73,14 @@ 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:
+backends 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` |
-| `jwt` | `uv add "fastapi-cachex[jwt]"` | `PyJWT` | `SessionConfig(token_format="jwt")` |
 
-Extras combine: `uv add "fastapi-cachex[redis,jwt]"`.
+Extras combine: `uv add "fastapi-cachex[redis,memcached]"`.
 
 ## Quick Start
 
@@ -136,17 +130,25 @@ async def report(cache: AppCache):
 > [!WARNING]
 > The default cache key carries no user identity. Cache authenticated endpoints
 > with `private=True` or a per-user key builder plus `cache_authorized=True`
-> (requests with `Authorization` or a session otherwise bypass the backend) — see
+> (requests with `Authorization` or non-empty `request.session` data otherwise
+> bypass the backend) — see
 > [Authenticated endpoints](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#authenticated-endpoints).
 
 ## Documentation
 
+The guides are built from `docs/` into the site linked below. Read them there:
+a code block that includes one of the runnable examples renders on the site,
+while GitHub shows only its `--8<--` include line (the sentence before each
+block links the example file).
+
+- [Migrating to 0.5.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_5/) — what 0.5.0 removes and how to upgrade from 0.4.x
 - [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
+- [Migrating from fastapi-cache2](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_FROM_FASTAPI_CACHE2/) — its API mapped onto this one, and the behaviour that differs
+- [When to use it](https://fastapi-cachex.readthedocs.io/en/latest/COMPARISON/) — how it compares with fastapi-cache2, cashews, aiocache and a CDN, and when another one fits better
 - [HTTP caching](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes
 - [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
 - [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/)

{fastapi_cachex-0.4.1 → fastapi_cachex-0.5.1}/README.md

@@ -23,12 +23,10 @@ A high-performance caching extension for FastAPI: a server-side response cache w
 - **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()` and atomic store-if-absent `add()`.
+  your own code, with compute-on-miss `get_or_set()` and atomic store-if-absent `add()`,
+  and `@cached` for a plain function, keyed on its arguments.
 - **Backends** — in-memory, Redis and Memcached, with atomic counters,
   one-shot values and locks.
-- **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
 
@@ -37,15 +35,14 @@ 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:
+backends 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` |
-| `jwt` | `uv add "fastapi-cachex[jwt]"` | `PyJWT` | `SessionConfig(token_format="jwt")` |
 
-Extras combine: `uv add "fastapi-cachex[redis,jwt]"`.
+Extras combine: `uv add "fastapi-cachex[redis,memcached]"`.
 
 ## Quick Start
 
@@ -95,17 +92,25 @@ async def report(cache: AppCache):
 > [!WARNING]
 > The default cache key carries no user identity. Cache authenticated endpoints
 > with `private=True` or a per-user key builder plus `cache_authorized=True`
-> (requests with `Authorization` or a session otherwise bypass the backend) — see
+> (requests with `Authorization` or non-empty `request.session` data otherwise
+> bypass the backend) — see
 > [Authenticated endpoints](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#authenticated-endpoints).
 
 ## Documentation
 
+The guides are built from `docs/` into the site linked below. Read them there:
+a code block that includes one of the runnable examples renders on the site,
+while GitHub shows only its `--8<--` include line (the sentence before each
+block links the example file).
+
+- [Migrating to 0.5.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_5/) — what 0.5.0 removes and how to upgrade from 0.4.x
 - [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
+- [Migrating from fastapi-cache2](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_FROM_FASTAPI_CACHE2/) — its API mapped onto this one, and the behaviour that differs
+- [When to use it](https://fastapi-cachex.readthedocs.io/en/latest/COMPARISON/) — how it compares with fastapi-cache2, cashews, aiocache and a CDN, and when another one fits better
 - [HTTP caching](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes
 - [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
 - [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/)

fastapi_cachex-0.5.1/fastapi_cachex/__init__.py

@@ -0,0 +1,83 @@
+"""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 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 .cached import CachedFunction as CachedFunction
+from .cached import cached as cached
+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 BackendUnavailableError as BackendUnavailableError
+from .exceptions import CacheXError as CacheXError
+from .exceptions import InvalidTTLError as InvalidTTLError
+from .exceptions import LockTimeoutError as LockTimeoutError
+from .exceptions import ProxyNotSetError as ProxyNotSetError
+from .exceptions import RequestNotFoundError as RequestNotFoundError
+from .exceptions import TTLTypeError as TTLTypeError
+from .exceptions import TTLValueError as TTLValueError
+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
+
+
+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.
+
+__all__ = [
+    "AppCache",
+    "BackendNotFoundError",
+    "BackendProxy",
+    "BackendUnavailableError",
+    "CacheBackend",
+    "CacheKey",
+    "CacheKeyBuilder",
+    "CacheLock",
+    "CacheManager",
+    "CacheManagerProxy",
+    "CacheXError",
+    "CachedFunction",
+    "InvalidTTLError",
+    "LockTimeoutError",
+    "ProxyNotSetError",
+    "RequestNotFoundError",
+    "TTLTypeError",
+    "TTLValueError",
+    "__version__",
+    "add_routes",
+    "build_cache_key",
+    "cache",
+    "cached",
+    "default_key_builder",
+    "get_app_cache",
+    "get_cache_backend",
+    "invalidate",
+]

fastapi_cachex-0.5.1/fastapi_cachex/_cache_control.py

@@ -0,0 +1,150 @@
+"""The `Cache-Control` header `@cache` sends, and which responses stay private."""
+
+from collections.abc import Iterable
+from typing import Literal
+
+from fastapi import Response
+
+from .directives import DirectiveType
+
+_NO_STORE = DirectiveType.NO_STORE.value
+
+
+class CacheControl:
+    """Manages Cache-Control header directives."""
+
+    def __init__(self) -> None:
+        """Initialize an empty CacheControl instance."""
+        self.directives: list[str] = []
+
+    def add(self, directive: DirectiveType, value: int | None = None) -> None:
+        """Add a Cache-Control directive.
+
+        Args:
+            directive: The directive type to add
+            value: Optional value for the directive
+        """
+        if value is not None:
+            self.directives.append(f"{directive.value}={value}")
+        else:
+            self.directives.append(directive.value)
+
+    def __str__(self) -> str:
+        """Return the Cache-Control header value as a string."""
+        return ", ".join(self.directives)
+
+
+def _build_cache_control(
+    *,
+    ttl: int | None,
+    stale: Literal["error", "revalidate"] | None,
+    stale_ttl: int | None,
+    no_cache: bool,
+    public: bool,
+    private: bool,
+    immutable: bool,
+    must_revalidate: bool,
+) -> str:
+    """The ``Cache-Control`` value for a ``@cache`` route's arguments.
+
+    ``no_cache`` sends only ``no-cache`` (plus ``must-revalidate``); otherwise
+    the directives follow in a fixed order: scope, ``max-age``,
+    ``must-revalidate``, the stale directive, ``immutable``.
+    """
+    cache_control = CacheControl()
+    if no_cache:
+        cache_control.add(DirectiveType.NO_CACHE)
+        if must_revalidate:
+            cache_control.add(DirectiveType.MUST_REVALIDATE)
+        return str(cache_control)
+
+    # 1. Access scope (public/private)
+    if public:
+        cache_control.add(DirectiveType.PUBLIC)
+    elif private:
+        cache_control.add(DirectiveType.PRIVATE)
+
+    # 2. Cache time settings
+    if ttl is not None:
+        cache_control.add(DirectiveType.MAX_AGE, ttl)
+
+    # 3. Validation related
+    if must_revalidate:
+        cache_control.add(DirectiveType.MUST_REVALIDATE)
+
+    # 4. Stale response handling (stale_ttl is validated at decoration time)
+    if stale == "revalidate":
+        cache_control.add(DirectiveType.STALE_WHILE_REVALIDATE, stale_ttl)
+    elif stale == "error":
+        cache_control.add(DirectiveType.STALE_IF_ERROR, stale_ttl)
+
+    # 5. Special flags
+    if immutable:
+        cache_control.add(DirectiveType.IMMUTABLE)
+
+    return str(cache_control)
+
+
+# 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(
+    {DirectiveType.PRIVATE.value, DirectiveType.NO_STORE.value}
+)
+
+
+def _marked_unshareable(response: Response) -> bool:
+    """Whether the handler's own ``Cache-Control`` has ``private`` or ``no-store``.
+
+    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 cache_control
+        for directive in value.split(",")
+    )
+
+
+def _unshareable_reason(response: Response) -> str | None:
+    """Why a rendered response must not be stored, or None when it may be."""
+    if _marked_unshareable(response):
+        return "response Cache-Control is private or no-store"
+    if "set-cookie" in response.headers:
+        return "response sets a cookie"
+    return None
+
+
+def _cache_control_for(
+    response: Response, cache_control: str, private_cache_control: str
+) -> str:
+    """The ``Cache-Control`` to send for a response the handler just rendered.
+
+    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. 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
+
+
+def _with_cache_control(
+    response: Response, cache_control: str, private_cache_control: str
+) -> Response:
+    if not _marked_unshareable(response):
+        value = _cache_control_for(response, cache_control, private_cache_control)
+        if value:
+            response.headers["Cache-Control"] = value
+    return response

fastapi_cachex-0.5.1/fastapi_cachex/_callables.py

@@ -0,0 +1,17 @@
+"""Telling whether a callable returns a coroutine, for handlers and key builders."""
+
+import inspect
+from collections.abc import Callable
+
+
+def _is_coroutine_callable(func: Callable[..., object]) -> bool:
+    """Report whether calling `func` returns a coroutine.
+
+    `inspect.iscoroutinefunction` already sees through `functools.partial`;
+    an instance with an ``async def __call__`` needs its method checked. The
+    method is looked up on the type, as the call itself does, so a class
+    (whose type is ``type``) counts as sync.
+    """
+    return inspect.iscoroutinefunction(func) or inspect.iscoroutinefunction(
+        type(func).__call__
+    )

fastapi_cachex-0.5.1/fastapi_cachex/_coalesce.py

@@ -0,0 +1,70 @@
+"""In-process coalescing of concurrent misses for `@cache(coalesce=True)` (#252).
+
+The first request to miss a key leads: it runs the handler as usual. Requests
+that miss the same key while it runs follow: they wait until the leader has
+answered, then read the backend again. A follower that still finds no entry
+(the leader's response was not stored, or the handler failed) renders its own
+response without waiting again, so followers never queue behind each other.
+
+Only requests in this process are coalesced. The registry is keyed by event
+loop and backend as well as the cache key, so two apps or loops never wait on
+each other.
+"""
+
+import asyncio
+
+# One future per key being rendered by a leader; done once it has answered.
+_IN_FLIGHT: dict[tuple[int, int, str], asyncio.Future[None]] = {}
+
+
+class _Flight:
+    """One request's part in coalescing: leader, follower or neither.
+
+    The wrapper creates one per request and calls ``finish()`` once the
+    request has been answered, however it ended, so a leader always releases
+    its followers and leaves nothing behind in the registry.
+    """
+
+    def __init__(self) -> None:
+        self._key: tuple[int, int, str] | None = None
+        self._future: asyncio.Future[None] | None = None
+
+    def join(
+        self, backend: object, cache_key: str, *, may_lead: bool
+    ) -> asyncio.Future[None] | None:
+        """Return the leader's future to wait on, or ``None`` to render.
+
+        With ``may_lead`` and no leader for the key, this request becomes the
+        leader. Without it (HEAD, whose response is never stored), it renders
+        without blocking anyone.
+        """
+        loop = asyncio.get_running_loop()
+        key = (id(loop), id(backend), cache_key)
+        running = _IN_FLIGHT.get(key)
+        if running is not None or not may_lead:
+            return running
+        self._key = key
+        self._future = loop.create_future()
+        _IN_FLIGHT[key] = self._future
+        return None
+
+    def finish(self) -> None:
+        """Release the followers, if this request led."""
+        if self._key is None or self._future is None:
+            return
+        # Only the leader registers or removes its key, and followers wait
+        # through a shield, so the future is still pending. `pop` because a
+        # test teardown may have cleared the registry already.
+        _IN_FLIGHT.pop(self._key, None)
+        self._future.set_result(None)
+        self._key = None
+        self._future = None
+
+
+async def _wait_for(leader: asyncio.Future[None]) -> None:
+    """Wait until the leader has answered.
+
+    Shielded: a follower that is cancelled stops waiting without cancelling
+    the leader's future for the other followers.
+    """
+    await asyncio.shield(leader)

fastapi_cachex-0.5.1/fastapi_cachex/_key_builders.py

@@ -0,0 +1,175 @@
+"""Cache keys for `@cache`: the default key builder and custom ones."""
+
+import inspect
+import logging
+from collections.abc import Callable
+from collections.abc import Sequence
+from functools import partial
+
+from fastapi import Request
+
+from ._callables import _is_coroutine_callable
+from .cache_key import CacheKey
+from .exceptions import CacheXError
+from .types import CACHE_KEY_SEPARATOR
+from .types import CacheKeyBuilder
+from .types import escape_key_component
+
+# The documented logger: every part of `@cache` logs under this name.
+logger = logging.getLogger("fastapi_cachex.cache")
+
+
+def build_cache_key(
+    request: Request, *components: str | int, sort_query: bool = True
+) -> str:
+    """Build the default cache key for ``request``, plus extra components.
+
+    With no ``components`` the key is ``http:v2|method|host|path|query``,
+    exactly what ``@cache`` uses by default. Each extra component is appended
+    after another separator, so a custom ``key_builder`` can add a dimension
+    (user ID, tenant, locale) without rebuilding the default key by hand::
+
+        def per_user_key(request: Request) -> str:
+            return build_cache_key(request, request.state.user_id)
+
+    The host is the ``Host`` header lower-cased, without an empty or default
+    port (``:80`` on http, ``:443`` on https), or ``unknown`` when there is
+    none. ``|`` and ``%`` in the host, the path and every extra component are
+    percent-encoded (see ``escape_key_component``), so none of them can
+    contain the separator and make one request's key equal another's. The
+    query string is already URL-encoded and never contains ``|``.
+
+    Keys built this way keep the tag, method, host and path in front, so
+    ``clear_path()`` still finds them and the monitoring routes still show
+    their method, host, path and query. This is
+    ``CacheKey.from_request(...).to_str()``; ``CacheKey.parse()`` decodes the
+    key again.
+
+    Args:
+        request: The FastAPI Request object
+        *components: Extra key components, appended in order. A ``str`` is
+            used as is and an ``int`` is written in decimal, so ``1`` and
+            ``"1"`` give the same key. An empty string is a component of its
+            own: ``build_cache_key(request, "")`` differs from
+            ``build_cache_key(request)``.
+        sort_query: Order the query parameters by name (a stable sort, so
+            ``?tag=b&tag=a`` stays distinct from ``?tag=a&tag=b``), so that
+            ``?a=1&b=2`` and ``?b=2&a=1`` give the same key. On by default,
+            as in ``@cache``; ``False`` keeps the order the client sent, as
+            ``@cache(sort_query=False)`` does.
+
+    Returns:
+        Generated cache key string
+
+    Raises:
+        TypeError: If a component is not a ``str`` or ``int`` (``bool`` is
+            rejected too), e.g. ``None`` from a missing user ID, which would
+            otherwise put every such caller under one ``"None"`` key.
+    """
+    key = CacheKey.from_request(request, *components, sort_query=sort_query).to_str()
+    logger.debug("Built cache key: %s", key)
+    return key
+
+
+def _append_key_components(key: str, components: Sequence[str]) -> str:
+    """Append each component to ``key``, escaped, after another separator."""
+    return CACHE_KEY_SEPARATOR.join(
+        [key, *(escape_key_component(component) for component in components)]
+    )
+
+
+def default_key_builder(request: Request) -> str:
+    """Default cache key builder function: ``build_cache_key(request)``.
+
+    Generates cache key in format: http:v2|method|host|path|query, with the
+    query parameters sorted by name.
+
+    Kept as the name ``@cache`` and ``invalidate()`` fall back to. To add
+    components to the default key, call ``build_cache_key`` instead.
+
+    Args:
+        request: The FastAPI Request object
+
+    Returns:
+        Generated cache key string
+    """
+    return build_cache_key(request)
+
+
+def _unsorted_query_key_builder(request: Request) -> str:
+    """The key builder of ``@cache(sort_query=False)``."""
+    return build_cache_key(request, sort_query=False)
+
+
+_SORT_QUERY_WITH_KEY_BUILDER_MSG = (
+    "sort_query only applies to the default key builder; a custom key_builder "
+    "builds its own key, so pass sort_query to build_cache_key() in it instead "
+    "(it sorts unless told otherwise)"
+)
+
+
+def _resolve_key_builder(
+    key_builder: CacheKeyBuilder | None, sort_query: object
+) -> CacheKeyBuilder:
+    """Pick the key builder for ``key_builder`` and ``sort_query``.
+
+    ``sort_query=None`` means it was not passed: the default key builder
+    sorts, and a custom one is used as is.
+
+    Raises:
+        CacheXError: If ``sort_query`` is not a ``bool`` or ``None``, if it
+            is passed with a custom ``key_builder`` (the flag would silently
+            do nothing), or if ``key_builder`` is an ``async`` callable.
+    """
+    if sort_query is not None and not isinstance(sort_query, bool):
+        msg = f"sort_query must be a bool, got {type(sort_query).__name__}"
+        raise CacheXError(msg)
+    if key_builder is not None:
+        if sort_query is not None:
+            raise CacheXError(_SORT_QUERY_WITH_KEY_BUILDER_MSG)
+        _validate_key_builder(key_builder)
+        return key_builder
+    return _unsorted_query_key_builder if sort_query is False else default_key_builder
+
+
+_ASYNC_KEY_BUILDER_MSG = (
+    "key_builder must be a sync function returning str; async key builders "
+    "are not supported (the key is built without awaiting)"
+)
+
+
+def _validate_key_builder(builder: Callable[..., object]) -> None:
+    """Reject a key builder whose call returns a coroutine.
+
+    ``functools.partial`` layers are unwrapped first, so a partial of an async
+    callable object is caught as well. A builder this cannot see through
+    (say a sync wrapper returning a coroutine) is caught by ``_build_key``.
+
+    Raises:
+        CacheXError: If calling ``builder`` would return a coroutine.
+    """
+    target = builder
+    while isinstance(target, partial):
+        target = target.func
+    if _is_coroutine_callable(target):
+        raise CacheXError(_ASYNC_KEY_BUILDER_MSG)
+
+
+def _build_key(builder: CacheKeyBuilder, request: Request) -> str:
+    """Call ``builder`` and check that it returned a ``str``.
+
+    A returned coroutine is closed, so it does not also trigger a "never
+    awaited" ``RuntimeWarning``. ``fail_open`` does not cover this: it is a
+    programming error in the route, not a backend failure.
+
+    Raises:
+        CacheXError: If ``builder`` returns anything but a ``str``.
+    """
+    key: object = builder(request)
+    if isinstance(key, str):
+        return key
+    if inspect.iscoroutine(key):
+        key.close()
+        raise CacheXError(_ASYNC_KEY_BUILDER_MSG)
+    msg = f"key_builder must return a str, got {type(key).__name__}"
+    raise CacheXError(msg)