AnonymousSpottedToad/securityPatternsRecovery / codebase /repos /python /allen0099_FastAPI-CacheX /fastapi_cachex /cache.py
| """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 | |
| 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.