fastapi-cachex 0.2.1__py3-none-any.whl

fastapi_cachex/backends/redis.py

@@ -0,0 +1,300 @@
+"""Redis cache backend implementation."""
+
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import Literal
+
+from fastapi_cachex.backends.base import BaseCacheBackend
+from fastapi_cachex.exceptions import CacheXError
+from fastapi_cachex.types import ETagContent
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis as AsyncRedis
+
+try:
+    import orjson as json
+
+except ImportError:  # pragma: no cover
+    import json  # type: ignore[no-redef]  # pragma: no cover
+
+# Default Redis key prefix for fastapi-cachex
+DEFAULT_REDIS_PREFIX = "fastapi_cachex:"
+
+
+class AsyncRedisCacheBackend(BaseCacheBackend):
+    """Async Redis cache backend implementation.
+
+    This backend uses Redis with a key prefix to avoid conflicts with other
+    applications. Keys are namespaced with 'fastapi_cachex:' by default.
+    """
+
+    client: "AsyncRedis[str]"
+    key_prefix: str
+
+    def __init__(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 6379,
+        password: str | None = None,
+        db: int = 0,
+        encoding: str = "utf-8",
+        decode_responses: Literal[True] = True,
+        socket_timeout: float = 1.0,
+        socket_connect_timeout: float = 1.0,
+        key_prefix: str = DEFAULT_REDIS_PREFIX,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize async Redis cache backend.
+
+        Args:
+            host: Redis host
+            port: Redis port
+            password: Redis password
+            db: Redis database number
+            encoding: Character encoding to use
+            decode_responses: Whether to decode response automatically
+            socket_timeout: Timeout for socket operations (in seconds)
+            socket_connect_timeout: Timeout for socket connection (in seconds)
+            key_prefix: Prefix for all cache keys (default: 'fastapi_cachex:')
+            **kwargs: Additional arguments to pass to Redis client
+        """
+        try:
+            from redis.asyncio import Redis as AsyncRedis
+        except ImportError:
+            msg = "redis[hiredis] is not installed. Please install it with 'pip install \"redis[hiredis]\"' "
+            raise CacheXError(msg)
+
+        self.client = AsyncRedis(
+            host=host,
+            port=port,
+            password=password,
+            db=db,
+            encoding=encoding,
+            decode_responses=decode_responses,
+            socket_timeout=socket_timeout,
+            socket_connect_timeout=socket_connect_timeout,
+            **kwargs,
+        )
+        self.key_prefix = key_prefix
+
+    def _make_key(self, key: str) -> str:
+        """Add prefix to cache key."""
+        return f"{self.key_prefix}{key}"
+
+    def _serialize(self, value: ETagContent) -> str:
+        """Serialize ETagContent to JSON string."""
+        if isinstance(value.content, bytes):
+            content = value.content.decode()
+        else:
+            content = value.content
+
+        serialized: str | bytes = json.dumps(
+            {
+                "etag": value.etag,
+                "content": content,
+            },
+        )
+
+        # orjson returns bytes, stdlib json returns str
+        return serialized.decode() if isinstance(serialized, bytes) else serialized
+
+    def _deserialize(self, value: str | None) -> ETagContent | None:
+        """Deserialize JSON string to ETagContent."""
+        if value is None:
+            return None
+        try:
+            data = json.loads(value)
+            return ETagContent(
+                etag=data["etag"],
+                content=data["content"].encode()
+                if isinstance(data["content"], str)
+                else data["content"],
+            )
+        except (json.JSONDecodeError, KeyError):
+            return None
+
+    async def get(self, key: str) -> ETagContent | None:
+        """Retrieve a cached response."""
+        result = await self.client.get(self._make_key(key))
+        return self._deserialize(result)
+
+    async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
+        """Store a response in the cache."""
+        serialized = self._serialize(value)
+        prefixed_key = self._make_key(key)
+        if ttl is not None:
+            await self.client.setex(prefixed_key, ttl, serialized)
+        else:
+            await self.client.set(prefixed_key, serialized)
+
+    async def delete(self, key: str) -> None:
+        """Remove a response from the cache."""
+        await self.client.delete(self._make_key(key))
+
+    async def clear(self) -> None:
+        """Clear all cached responses for this namespace.
+
+        Uses SCAN instead of KEYS to avoid blocking in production.
+        Only deletes keys within this backend's prefix.
+        """
+        pattern = f"{self.key_prefix}*"
+        cursor = 0
+        batch_size = 100
+        keys_to_delete: list[str] = []
+
+        # Use SCAN to iterate through keys without blocking
+        while True:
+            cursor, keys = await self.client.scan(
+                cursor,
+                match=pattern,
+                count=batch_size,
+            )
+            if keys:
+                keys_to_delete.extend(keys)
+            if cursor == 0:
+                break
+
+        # Delete all collected keys in batches to avoid huge command size
+        if keys_to_delete:
+            for i in range(0, len(keys_to_delete), batch_size):
+                batch = keys_to_delete[i : i + batch_size]
+                if batch:
+                    await self.client.delete(*batch)
+
+    async def clear_path(self, path: str, include_params: bool = False) -> int:
+        """Clear cached responses for a specific path.
+
+        Uses SCAN instead of KEYS to avoid blocking in production.
+
+        Args:
+            path: The path to clear cache for
+            include_params: Whether to clear all parameter variations
+
+        Returns:
+            Number of cache entries cleared
+        """
+        # Pattern includes the HTTP method, host, and path components
+        if include_params:
+            # Clear all variations: *:path:*
+            pattern = f"{self.key_prefix}*:{path}:*"
+        else:
+            # Clear only exact path (no query params): *:path
+            pattern = f"{self.key_prefix}*:{path}"
+
+        cursor = 0
+        batch_size = 100
+        cleared_count = 0
+        keys_to_delete: list[str] = []
+
+        # Use SCAN to iterate through keys without blocking
+        while True:
+            cursor, keys = await self.client.scan(
+                cursor,
+                match=pattern,
+                count=batch_size,
+            )
+            if keys:
+                keys_to_delete.extend(keys)
+            if cursor == 0:
+                break
+
+        # Delete all collected keys in batches
+        if keys_to_delete:
+            for i in range(0, len(keys_to_delete), batch_size):
+                batch = keys_to_delete[i : i + batch_size]
+                if batch:
+                    deleted = await self.client.delete(*batch)
+                    cleared_count += deleted
+
+        return cleared_count
+
+    async def clear_pattern(self, pattern: str) -> int:
+        """Clear cached responses matching a pattern.
+
+        Uses SCAN instead of KEYS to avoid blocking in production.
+
+        Args:
+            pattern: A glob pattern to match cache keys against
+
+        Returns:
+            Number of cache entries cleared
+        """
+        # Ensure pattern includes the key prefix
+        if not pattern.startswith(self.key_prefix):
+            full_pattern = f"{self.key_prefix}{pattern}"
+        else:
+            full_pattern = pattern
+
+        cursor = 0
+        batch_size = 100
+        cleared_count = 0
+        keys_to_delete: list[str] = []
+
+        # Use SCAN to iterate through keys without blocking
+        while True:
+            cursor, keys = await self.client.scan(
+                cursor,
+                match=full_pattern,
+                count=batch_size,
+            )
+            if keys:
+                keys_to_delete.extend(keys)
+            if cursor == 0:
+                break
+
+        # Delete all collected keys in batches
+        if keys_to_delete:
+            for i in range(0, len(keys_to_delete), batch_size):
+                batch = keys_to_delete[i : i + batch_size]
+                if batch:
+                    deleted = await self.client.delete(*batch)
+                    cleared_count += deleted
+
+        return cleared_count
+
+    async def get_all_keys(self) -> list[str]:
+        """Get all cache keys in the backend.
+
+        Returns:
+            List of all cache keys currently stored in the backend
+        """
+        pattern = f"{self.key_prefix}*"
+        cursor = 0
+        batch_size = 100
+        all_keys: list[str] = []
+
+        # Use SCAN to iterate through keys without blocking
+        while True:
+            cursor, keys = await self.client.scan(
+                cursor,
+                match=pattern,
+                count=batch_size,
+            )
+            if keys:
+                all_keys.extend(keys)
+            if cursor == 0:
+                break
+
+        return all_keys
+
+    async def get_cache_data(self) -> dict[str, tuple[ETagContent, float | None]]:
+        """Get all cache data with expiry information.
+
+        Returns:
+            Dictionary mapping cache keys to (ETagContent, expiry) tuples.
+            Note: Redis stores TTL but not absolute expiry time, so this
+            returns None for expiry (no expiry tracking in Redis backend).
+        """
+        all_keys = await self.get_all_keys()
+        cache_data: dict[str, tuple[ETagContent, float | None]] = {}
+
+        for prefixed_key in all_keys:
+            # Remove prefix to get the original cache key
+            original_key = prefixed_key.removeprefix(self.key_prefix)
+
+            # Get the value using the original key (get() adds prefix internally)
+            value = await self.get(original_key)
+            if value is not None:
+                cache_data[original_key] = (value, None)
+
+        return cache_data

fastapi_cachex/cache.py

@@ -0,0 +1,301 @@
+"""Core caching functionality and decorators."""
+
+import hashlib
+import inspect
+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 TypeVar
+from typing import Union
+
+from fastapi import Request
+from fastapi import Response
+from fastapi.datastructures import DefaultPlaceholder
+from starlette.status import HTTP_304_NOT_MODIFIED
+
+from fastapi_cachex.backends import MemoryBackend
+from fastapi_cachex.directives import DirectiveType
+from fastapi_cachex.exceptions import BackendNotFoundError
+from fastapi_cachex.exceptions import CacheXError
+from fastapi_cachex.exceptions import RequestNotFoundError
+from fastapi_cachex.proxy import BackendProxy
+from fastapi_cachex.types import ETagContent
+
+if TYPE_CHECKING:
+    from fastapi.routing import APIRoute
+
+T = TypeVar("T", bound=Response)
+AsyncCallable = Callable[..., Awaitable[T]]
+SyncCallable = Callable[..., T]
+AnyCallable = Union[AsyncCallable[T], SyncCallable[T]]  # noqa: UP007
+
+
+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)
+
+
+async def get_response(
+    __func: AnyCallable[Response],
+    __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)
+
+    if isinstance(route.response_class, DefaultPlaceholder):
+        response_class: type[Response] = route.response_class.value
+
+    else:
+        response_class = route.response_class
+
+    # Convert non-Response result to Response using appropriate response_class
+    return response_class(content=result)
+
+
+def cache(  # noqa: C901
+    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,
+) -> Callable[[AnyCallable[Response]], AsyncCallable[Response]]:
+    """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
+
+    Returns:
+        Decorator function that wraps route handlers with caching logic
+    """
+
+    def decorator(func: AnyCallable[Response]) -> AsyncCallable[Response]:  # noqa: C901
+        try:
+            cache_backend = BackendProxy.get_backend()
+        except BackendNotFoundError:
+            # Fallback to memory backend if no backend is set
+            cache_backend = MemoryBackend()
+            BackendProxy.set_backend(cache_backend)
+
+        # 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
+
+        async def get_cache_control(cache_control: CacheControl) -> str:  # noqa: C901
+            # Set Cache-Control headers
+            if no_cache:
+                cache_control.add(DirectiveType.NO_CACHE)
+                if must_revalidate:
+                    cache_control.add(DirectiveType.MUST_REVALIDATE)
+            else:
+                # Handle normal cache control cases
+                # 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
+                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 == "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)
+
+        @wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Response:  # noqa: C901
+            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":
+                return await get_response(func, req, *args, **kwargs)
+
+            # Generate cache key: method:host:path:query_params[:vary]
+            # Include host to avoid cross-host cache pollution
+            cache_key = f"{req.method}:{req.headers.get('host', 'unknown')}:{req.url.path}:{req.query_params}"
+            client_etag = req.headers.get("if-none-match")
+            cache_control = await get_cache_control(CacheControl())
+
+            # Handle special case: no-store (highest priority)
+            if no_store:
+                response = await get_response(func, req, *args, **kwargs)
+                cc = CacheControl()
+                cc.add(DirectiveType.NO_STORE)
+                response.headers["Cache-Control"] = str(cc)
+                return response
+
+            # Check cache and handle ETag validation
+            cached_data = await cache_backend.get(cache_key)
+
+            current_response = None
+            current_etag = None
+
+            if client_etag:
+                if no_cache:
+                    # Get fresh response first if using no-cache
+                    current_response = await get_response(func, req, *args, **kwargs)
+                    current_etag = (
+                        f'W/"{hashlib.md5(current_response.body).hexdigest()}"'  # noqa: S324
+                    )
+
+                    if client_etag == current_etag:
+                        # For no-cache, compare fresh data with client's ETag
+                        return Response(
+                            status_code=HTTP_304_NOT_MODIFIED,
+                            headers={
+                                "ETag": current_etag,
+                                "Cache-Control": cache_control,
+                            },
+                        )
+
+                # Compare with cached ETag - if match, return 304
+                elif (
+                    cached_data and client_etag == cached_data.etag
+                ):  # pragma: no branch
+                    # Cache hit with matching ETag: return 304 Not Modified
+                    return Response(
+                        status_code=HTTP_304_NOT_MODIFIED,
+                        headers={
+                            "ETag": cached_data.etag,
+                            "Cache-Control": 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:
+                # We have a cached entry and TTL-based caching is enabled
+                # Return the cached content directly with 200 OK without revalidation
+                return Response(
+                    content=cached_data.content,
+                    status_code=200,
+                    headers={
+                        "ETag": cached_data.etag,
+                        "Cache-Control": cache_control,
+                    },
+                )
+
+            if not current_response or not current_etag:
+                # Retrieve the current response if not already done
+                current_response = await get_response(func, req, *args, **kwargs)
+                current_etag = f'W/"{hashlib.md5(current_response.body).hexdigest()}"'  # noqa: S324
+
+            # Set ETag header
+            current_response.headers["ETag"] = current_etag
+
+            # Update cache if needed
+            if not cached_data or cached_data.etag != current_etag:
+                # Store in cache if data changed
+                await cache_backend.set(
+                    cache_key,
+                    ETagContent(current_etag, current_response.body),
+                    ttl=ttl,
+                )
+
+            current_response.headers["Cache-Control"] = cache_control
+            return current_response
+
+        # Update the wrapper with the new signature
+        update_wrapper(wrapper, func)
+        wrapper.__signature__ = sig  # type: ignore[attr-defined]
+
+        return wrapper
+
+    return decorator

fastapi_cachex/dependencies.py

@@ -0,0 +1,16 @@
+"""FastAPI dependency injection utilities for cache control."""
+
+from typing import Annotated
+
+from fastapi import Depends
+
+from fastapi_cachex.backends.base import BaseCacheBackend
+from fastapi_cachex.proxy import BackendProxy
+
+
+def get_cache_backend() -> BaseCacheBackend:
+    """Dependency to get the current cache backend instance."""
+    return BackendProxy.get_backend()
+
+
+CacheBackend = Annotated[BaseCacheBackend, Depends(get_cache_backend)]

fastapi_cachex/directives.py

@@ -0,0 +1,21 @@
+"""Cache-Control directive types and enumerations."""
+
+from enum import Enum
+
+
+class DirectiveType(Enum):
+    """Enum representing Cache-Control directives."""
+
+    MAX_AGE = "max-age"
+    S_MAXAGE = "s-maxage"
+    NO_CACHE = "no-cache"
+    NO_STORE = "no-store"
+    NO_TRANSFORM = "no-transform"
+    MUST_REVALIDATE = "must-revalidate"
+    PROXY_REVALIDATE = "proxy-revalidate"
+    MUST_UNDERSTAND = "must-understand"
+    PRIVATE = "private"
+    PUBLIC = "public"
+    IMMUTABLE = "immutable"
+    STALE_WHILE_REVALIDATE = "stale-while-revalidate"
+    STALE_IF_ERROR = "stale-if-error"

fastapi_cachex/exceptions.py

@@ -0,0 +1,17 @@
+"""Custom exception classes for FastAPI-CacheX."""
+
+
+class CacheXError(Exception):
+    """Base class for all exceptions in FastAPI-CacheX."""
+
+
+class CacheError(CacheXError):
+    """Exception raised for cache-related errors."""
+
+
+class BackendNotFoundError(CacheXError):
+    """Exception raised when a cache backend is not found."""
+
+
+class RequestNotFoundError(CacheXError):
+    """Exception raised when a request is not found."""

fastapi_cachex/proxy.py

@@ -0,0 +1,36 @@
+"""Backend proxy for managing cache backend instances."""
+
+from fastapi_cachex.backends import BaseCacheBackend
+from fastapi_cachex.exceptions import BackendNotFoundError
+
+_default_backend: BaseCacheBackend | None = None
+
+
+class BackendProxy:
+    """FastAPI CacheX Proxy for backend management."""
+
+    @staticmethod
+    def get_backend() -> BaseCacheBackend:
+        """Get the current cache backend instance.
+
+        Returns:
+            The current cache backend
+
+        Raises:
+            BackendNotFoundError: If no backend has been set
+        """
+        if _default_backend is None:
+            msg = "Backend is not set. Please set the backend first."
+            raise BackendNotFoundError(msg)
+
+        return _default_backend
+
+    @staticmethod
+    def set_backend(backend: BaseCacheBackend | None) -> None:
+        """Set the backend for caching.
+
+        Args:
+            backend: The backend to use for caching, or None to clear the current backend
+        """
+        global _default_backend
+        _default_backend = backend