Buckets:

download
raw
15.4 kB
"""Core caching functionality and decorators."""
import hashlib
import inspect
import logging
from collections.abc import Awaitable
from collections.abc import Callable
from functools import update_wrapper
from functools import wraps
from inspect import Parameter
from inspect import Signature
from typing import TYPE_CHECKING
from typing import Any
from typing import Literal
from typing import cast
from fastapi import Request
from fastapi import Response
from starlette.status import HTTP_304_NOT_MODIFIED
from .backends import MemoryBackend
from .directives import DirectiveType
from .exceptions import BackendNotFoundError
from .exceptions import CacheXError
from .exceptions import RequestNotFoundError
from .proxy import BackendProxy
from .types import CACHE_KEY_SEPARATOR
from .types import CacheEntry
from .types import CacheKeyBuilder
if TYPE_CHECKING:
from fastapi.routing import APIRoute
# Handler callable accepted by @cache: can return any type (sync or async).
HandlerCallable = Callable[..., Awaitable[object]] | Callable[..., object]
# Wrapper callable produced by @cache: always async and returns Response.
AsyncResponseCallable = Callable[..., Awaitable[Response]]
logger = logging.getLogger(__name__)
_NO_STORE = DirectiveType.NO_STORE.value
def default_key_builder(request: Request) -> str:
"""Default cache key builder function.
Generates cache key in format: method|||host|||path|||query_params
Args:
request: The FastAPI Request object
Returns:
Generated cache key string
"""
key = (
f"{request.method}{CACHE_KEY_SEPARATOR}"
f"{request.headers.get('host', 'unknown')}{CACHE_KEY_SEPARATOR}"
f"{request.url.path}{CACHE_KEY_SEPARATOR}"
f"{request.query_params}"
)
logger.debug("Built cache key: %s", key)
return key
async def invalidate(
request: Request,
key_builder: CacheKeyBuilder | None = None,
) -> bool:
"""Invalidate the cache entry a ``@cache``-decorated route would use.
Builds the same cache key the ``@cache`` decorator would build for
``request`` (via ``key_builder`` or ``default_key_builder``) and deletes
it from the configured backend. Use this after a mutation to bust the
cache for a specific cached route response.
Args:
request: The request whose cache key should be invalidated. Typically
a request to the same route/method as the cached one (e.g. build
it via ``request.app.url_path_for(...)`` for a GET route).
key_builder: Custom key builder used by the target route's ``@cache``
decorator, if any. If None, uses ``default_key_builder``.
Returns:
True if a cache entry existed and was deleted, False otherwise.
"""
builder = key_builder or default_key_builder
cache_key = builder(request)
try:
cache_backend = BackendProxy.get()
except BackendNotFoundError:
return False
if await cache_backend.get_and_delete(cache_key) is None:
return False
logger.debug("Cache INVALIDATE; key=%s", cache_key)
return True
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 _get_response_body(response: Response) -> bytes | None:
"""Return response body bytes, or None for streaming/file responses."""
return getattr(response, "body", None)
def _etag_for(body: bytes) -> str:
return f'W/"{hashlib.md5(body).hexdigest()}"' # noqa: S324
def _not_modified(etag: str, cache_control: str) -> Response:
return Response(
status_code=HTTP_304_NOT_MODIFIED,
headers={"ETag": etag, "Cache-Control": cache_control},
)
def _with_cache_control(response: Response, cache_control: str) -> Response:
response.headers["Cache-Control"] = cache_control
return response
async def _render(
func: HandlerCallable, request: Request, /, *args: Any, **kwargs: Any
) -> tuple[Response, bytes | None, str | None]:
"""Run the handler; the body and ETag are None for streaming/file responses."""
response = await get_response(func, request, *args, **kwargs)
body = _get_response_body(response)
return response, body, None if body is None else _etag_for(body)
async def get_response(
__func: HandlerCallable,
__request: Request,
/,
*args: Any,
**kwargs: Any,
) -> Response:
"""Get the response from the function."""
if inspect.iscoroutinefunction(__func):
result = await __func(*args, **kwargs)
else:
result = __func(*args, **kwargs)
# If already a Response object, return it directly
if isinstance(result, Response):
return result
# Get response_class from route if available
route: APIRoute | None = __request.scope.get("route")
if route is None: # pragma: no cover
msg = "Route not found in request scope"
raise CacheXError(msg)
# A placeholder means this route uses the application default. Unwrap the
# application value instead of calling the route's DefaultPlaceholder.
route_response_class = route.response_class
application_default_response_class = __request.app.router.default_response_class
response_class: type[Response] = cast(
"type[Response]",
(
getattr(
application_default_response_class,
"value",
application_default_response_class,
)
if hasattr(route_response_class, "value")
else route_response_class
),
)
# Convert non-Response result to Response using appropriate response_class
return response_class(content=result)
def cache(
ttl: int | None = None,
stale_ttl: int | None = None,
*,
stale: Literal["error", "revalidate"] | None = None,
no_cache: bool = False,
no_store: bool = False,
public: bool = False,
private: bool = False,
immutable: bool = False,
must_revalidate: bool = False,
key_builder: CacheKeyBuilder | None = None,
) -> Callable[[HandlerCallable], AsyncResponseCallable]:
"""Cache decorator for FastAPI route handlers.
Args:
ttl: Time-to-live in seconds for cache entries
stale_ttl: Additional time-to-live for stale cache entries
stale: Stale response handling strategy ('error' or 'revalidate')
no_cache: Whether to disable caching
no_store: Whether to prevent storing responses
public: Whether responses can be cached by shared caches
private: Whether responses are for single user only
immutable: Whether cached responses never change
must_revalidate: Whether to force revalidation when stale
key_builder: Custom function to build cache keys. If None, uses default_key_builder
Returns:
Decorator function that wraps route handlers with caching logic
"""
def decorator(func: HandlerCallable) -> AsyncResponseCallable:
# Validate parameters eagerly at decoration time
if stale is not None and stale_ttl is None:
msg = "stale_ttl must be set if stale is used"
raise CacheXError(msg)
if stale_ttl is not None and stale is None:
msg = "stale must be set if stale_ttl is used"
raise CacheXError(msg)
if public and private:
msg = "public and private are mutually exclusive"
raise CacheXError(msg)
# Analyze the original function's signature
sig: Signature = inspect.signature(func)
params: list[Parameter] = list(sig.parameters.values())
# Check if Request is already in the parameters
found_request: Parameter | None = next(
(param for param in params if param.annotation == Request),
None,
)
# Add Request parameter if it's not present
if not found_request:
request_name: str = "__cachex_request"
request_param = inspect.Parameter(
request_name,
inspect.Parameter.KEYWORD_ONLY,
annotation=Request,
)
sig = sig.replace(parameters=[*params, request_param])
else:
request_name = found_request.name
def build_cache_control() -> str:
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)
# The header only depends on the decorator arguments, so build it once.
cache_control = build_cache_control()
builder = key_builder or default_key_builder
@wraps(func)
async def wrapper(*args: Any, **kwargs: Any) -> Response:
# Resolve backend on every request to support lifespan-configured backends
try:
cache_backend = BackendProxy.get()
except BackendNotFoundError:
cache_backend = MemoryBackend()
BackendProxy.set(cache_backend)
logger.debug("No backend configured; using MemoryBackend fallback")
if found_request:
req: Request | None = kwargs.get(request_name)
else:
req = kwargs.pop(request_name, None)
if not req: # pragma: no cover
# Skip coverage for this case, as it should not happen
raise RequestNotFoundError
# Only cache GET requests
if req.method != "GET":
logger.debug(
"Non-GET request; bypassing cache for method=%s", req.method
)
return await get_response(func, req, *args, **kwargs)
cache_key = builder(req)
# Handle special case: no-store (highest priority)
if no_store:
response = await get_response(func, req, *args, **kwargs)
logger.debug("no-store active; bypassed cache for key=%s", cache_key)
return _with_cache_control(response, _NO_STORE)
client_etag = req.headers.get("if-none-match")
cached_data = await cache_backend.get(cache_key)
current_response: Response | None = None
current_body: bytes | None = None
current_etag: str | None = None
if client_etag:
if no_cache:
# Get fresh response first if using no-cache
current_response, current_body, current_etag = await _render(
func, req, *args, **kwargs
)
if current_etag is None:
# StreamingResponse/FileResponse — cannot compute ETag; serve as-is
return _with_cache_control(current_response, cache_control)
if client_etag == current_etag:
# For no-cache, compare fresh data with client's ETag
logger.debug("304 Not Modified via no-cache; key=%s", cache_key)
return _not_modified(current_etag, cache_control)
# Compare with cached ETag - if match, return 304
elif cached_data and client_etag == cached_data.fingerprint:
logger.debug(
"304 Not Modified (cached ETag match); key=%s", cache_key
)
return _not_modified(cached_data.fingerprint, cache_control)
# If we don't have If-None-Match header, check if we have a valid cached copy
# and can serve it directly (cache hit without ETag comparison)
if cached_data and not no_cache and ttl is not None:
logger.debug("Cache HIT (TTL valid); key=%s", cache_key)
return Response(
content=cached_data.content,
status_code=200,
media_type=cached_data.media_type,
headers={
"ETag": cached_data.fingerprint,
"Cache-Control": cache_control,
},
)
if current_response is None or current_etag is None:
# Retrieve the current response if not already done
current_response, current_body, current_etag = await _render(
func, req, *args, **kwargs
)
if current_etag is None:
# StreamingResponse/FileResponse — cannot compute ETag; serve as-is
return _with_cache_control(current_response, cache_control)
logger.debug("Cache MISS; computed fresh ETag for key=%s", cache_key)
current_response.headers["ETag"] = current_etag
# Update cache if needed
if not cached_data or cached_data.fingerprint != current_etag:
assert (
current_body is not None
) # guaranteed by early-return guards above
await cache_backend.set(
cache_key,
CacheEntry(
fingerprint=current_etag,
content=current_body,
media_type=current_response.media_type,
),
ttl=ttl,
)
logger.debug("Updated cache entry; key=%s ttl=%s", cache_key, ttl)
return _with_cache_control(current_response, cache_control)
# Update the wrapper with the new signature
update_wrapper(wrapper, func)
wrapper.__signature__ = sig # type: ignore[attr-defined]
return wrapper
return decorator

Xet Storage Details

Size:
15.4 kB
·
Xet hash:
d734634d1358291367debb7af8f92256e423a52037c7f3dac84e043859886e69

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.