fast-cache-middleware 0.0.4__py3-none-any.whl → 0.0.5__py3-none-any.whl

fast_cache_middleware/_helpers.py

@@ -0,0 +1,28 @@
+from fastapi import FastAPI, routing
+
+from .depends import CacheConfig
+
+
+def set_cache_age_in_openapi_schema(app: FastAPI) -> None:
+    openapi_schema = app.openapi()
+
+    for route in app.routes:
+        if isinstance(route, routing.APIRoute):
+            path = route.path
+            methods = route.methods
+
+            for dependency in route.dependencies:
+                dep = dependency.dependency
+                if isinstance(dep, CacheConfig):
+                    max_age = dep.max_age
+
+                    for method in methods:
+                        method = method.lower()
+                        try:
+                            operation = openapi_schema["paths"][path][method]
+                            operation.setdefault("x-cache-age", max_age)
+                        except KeyError:
+                            continue
+
+    app.openapi_schema = openapi_schema
+    return None

fast_cache_middleware/controller.py

@@ -1,12 +1,13 @@
 import http
 import logging
-import typing as tp
+import re
 from hashlib import blake2b
+from typing import Optional
 
 from starlette.requests import Request
 from starlette.responses import Response
 
-from .depends import CacheConfig, CacheDropConfig
+from .schemas import CacheConfiguration
 from .storages import BaseStorage
 
 logger = logging.getLogger(__name__)
@@ -136,7 +137,7 @@ class Controller:
         return True
 
     async def generate_cache_key(
-        self, request: Request, cache_config: CacheConfig
+        self, request: Request, cache_configuration: CacheConfiguration
     ) -> str:
         """Generates cache key for request.
 
@@ -148,8 +149,8 @@ class Controller:
             str: Cache key
         """
         # Use custom key generation function if available
-        if cache_config.key_func:
-            return cache_config.key_func(request)
+        if cache_configuration.key_func:
+            return cache_configuration.key_func(request)
 
         # Use standard function
         return generate_key(request)
@@ -160,7 +161,7 @@ class Controller:
         request: Request,
         response: Response,
         storage: BaseStorage,
-        ttl: tp.Optional[int] = None,
+        ttl: Optional[int] = None,
     ) -> None:
         """Saves response to cache.
 
@@ -180,7 +181,7 @@ class Controller:
 
     async def get_cached_response(
         self, cache_key: str, storage: BaseStorage
-    ) -> tp.Optional[Response]:
+    ) -> Optional[Response]:
         """Gets cached response if it exists and is valid.
 
         Args:
@@ -198,13 +199,13 @@ class Controller:
 
     async def invalidate_cache(
         self,
-        cache_drop_config: CacheDropConfig,
+        invalidate_paths: list[re.Pattern],
         storage: BaseStorage,
     ) -> None:
         """Invalidates cache by configuration.
 
         Args:
-            cache_drop_config: Cache invalidation configuration
+            invalidate_paths: List of regex patterns for cache invalidation
             storage: Cache storage
 
         TODO: Comments on improvements:
@@ -226,6 +227,6 @@ class Controller:
         5. Add tag support for grouping related caches
            and their joint invalidation
         """
-        for path in cache_drop_config.paths:
+        for path in invalidate_paths:
             await storage.remove(path)
             logger.info("Invalidated cache for pattern: %s", path.pattern)

fast_cache_middleware/depends.py

@@ -1,5 +1,5 @@
 import re
-import typing as tp
+from typing import Callable, Optional
 
 from fastapi import params
 from starlette.requests import Request
@@ -15,23 +15,7 @@ class BaseCacheConfigDepends(params.Depends):
     use_cache: bool = True
 
     def __call__(self, request: Request) -> None:
-        """Saves configuration in ASGI scope extensions.
-
-        Args:
-            request: HTTP request
-        """
-        # Use standard ASGI extensions mechanism
-        if "extensions" not in request.scope:
-            request.scope["extensions"] = {}
-
-        if "fast_cache" not in request.scope["extensions"]:
-            request.scope["extensions"]["fast_cache"] = {}
-
-        request.scope["extensions"]["fast_cache"]["config"] = self
-
-    @property
-    def dependency(self) -> params.Depends:
-        return self
+        pass
 
 
 class CacheConfig(BaseCacheConfigDepends):
@@ -45,11 +29,13 @@ class CacheConfig(BaseCacheConfigDepends):
     def __init__(
         self,
         max_age: int = 5 * 60,
-        key_func: tp.Optional[tp.Callable[[Request], str]] = None,
+        key_func: Optional[Callable[[Request], str]] = None,
     ) -> None:
         self.max_age = max_age
         self.key_func = key_func
 
+        self.dependency = self
+
 
 class CacheDropConfig(BaseCacheConfigDepends):
     """Cache invalidation configuration for route.
@@ -64,3 +50,5 @@ class CacheDropConfig(BaseCacheConfigDepends):
         self.paths: list[re.Pattern] = [
             p if isinstance(p, re.Pattern) else re.compile(f"^{p}") for p in paths
         ]
+
+        self.dependency = self

fast_cache_middleware/middleware.py

@@ -5,17 +5,138 @@ import typing as tp
 from fastapi import FastAPI, routing
 from starlette.requests import Request
 from starlette.responses import Response
-from starlette.routing import Mount
+from starlette.routing import Match, Mount
 from starlette.types import ASGIApp, Receive, Scope, Send
 
+from ._helpers import set_cache_age_in_openapi_schema
 from .controller import Controller
 from .depends import BaseCacheConfigDepends, CacheConfig, CacheDropConfig
-from .schemas import RouteInfo
+from .schemas import CacheConfiguration, RouteInfo
 from .storages import BaseStorage, InMemoryStorage
 
 logger = logging.getLogger(__name__)
 
 
+class BaseMiddleware:
+    def __init__(
+        self,
+        app: ASGIApp,
+    ) -> None:
+        self.app = app
+
+        self.executors_map = {
+            "lifespan": self.on_lifespan,
+            "http": self.on_http,
+        }
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        scope_type = scope["type"]
+        try:
+            is_request_processed = await self.executors_map[scope_type](
+                scope, receive, send
+            )
+        except KeyError:
+            logger.debug("Not supported scope type: %s", scope_type)
+            is_request_processed = False
+
+        if not is_request_processed:
+            await self.app(scope, receive, send)
+
+    async def on_lifespan(
+        self, scope: Scope, receive: Receive, send: Send
+    ) -> bool | None:
+        pass
+
+    async def on_http(self, scope: Scope, receive: Receive, send: Send) -> bool | None:
+        pass
+
+
+class BaseSendWrapper:
+    def __init__(self, app: ASGIApp, scope: Scope, receive: Receive, send: Send):
+        self.app = app
+        self.scope = scope
+        self.receive = receive
+        self.send = send
+
+        self._response_status: int = 200
+        self._response_headers: dict[str, str] = dict()
+        self._response_body: bytes = b""
+
+        self.executors_map = {
+            "http.response.start": self.on_response_start,
+            "http.response.body": self.on_response_body,
+        }
+
+    async def __call__(self) -> None:
+        return await self.app(self.scope, self.receive, self._message_processor)
+
+    async def _message_processor(self, message: tp.MutableMapping[str, tp.Any]) -> None:
+        try:
+            executor = self.executors_map[message["type"]]
+        except KeyError:
+            logger.error("Not found executor for %s message type", message["type"])
+        else:
+            await executor(message)
+
+        await self.send(message)
+
+    async def on_response_start(self, message: tp.MutableMapping[str, tp.Any]) -> None:
+        self._response_status = message["status"]
+        self._response_headers = {
+            k.decode(): v.decode() for k, v in message.get("headers", [])
+        }
+
+    async def on_response_body(self, message: tp.MutableMapping[str, tp.Any]) -> None:
+        self._response_body += message.get("body", b"")
+
+        # this is the last chunk
+        if not message.get("more_body", False):
+            response = Response(
+                content=self._response_body,
+                status_code=self._response_status,
+                headers=self._response_headers,
+            )
+            await self.on_response_ready(response)
+
+    async def on_response_ready(self, response: Response) -> None:
+        pass
+
+
+class CacheSendWrapper(BaseSendWrapper):
+    def __init__(
+        self,
+        controller: Controller,
+        storage: BaseStorage,
+        request: Request,
+        cache_key: str,
+        ttl: int,
+        app: ASGIApp,
+        scope: Scope,
+        receive: Receive,
+        send: Send,
+    ) -> None:
+        super().__init__(app, scope, receive, send)
+
+        self.controller = controller
+        self.storage = storage
+        self.request = request
+        self.cache_key = cache_key
+        self.ttl = ttl
+
+    async def on_response_start(self, message: tp.MutableMapping[str, tp.Any]) -> None:
+        message.get("headers", []).append(("X-Cache-Status".encode(), "MISS".encode()))
+        return await super().on_response_start(message)
+
+    async def on_response_ready(self, response: Response) -> None:
+        await self.controller.cache_response(
+            cache_key=self.cache_key,
+            request=self.request,
+            response=response,
+            storage=self.storage,
+            ttl=self.ttl,
+        )
+
+
 def get_app_routes(app: FastAPI) -> tp.List[routing.APIRoute]:
     """Gets all routes from FastAPI application.
 
@@ -66,51 +187,7 @@ def get_routes(router: routing.APIRouter) -> list[routing.APIRoute]:
     return routes
 
 
-async def send_with_callbacks(
-    app: ASGIApp,
-    scope: Scope,
-    receive: Receive,
-    send: Send,
-    on_response_ready: tp.Callable[[Response], tp.Awaitable[None]] | None = None,
-) -> None:
-    response_holder: tp.Dict[str, tp.Any] = {}
-
-    async def response_builder(message: tp.Dict[str, tp.Any]) -> None:
-        """Wrapper for intercepting and saving response."""
-        if message["type"] == "http.response.start":
-            response_holder["status"] = message["status"]
-
-            message.get("headers", []).append(
-                ("X-Cache-Status".encode(), "MISS".encode())
-            )
-            response_holder["headers"] = [
-                (k.decode(), v.decode()) for k, v in message.get("headers", [])
-            ]
-
-            response_holder["body"] = b""
-        elif message["type"] == "http.response.body":
-            body = message.get("body", b"")
-            response_holder["body"] += body
-
-            # If this is the last chunk, cache the response
-            if not message.get("more_body", False):
-                response = Response(
-                    content=response_holder["body"],
-                    status_code=response_holder["status"],
-                    headers=dict(response_holder["headers"]),
-                )
-
-                # Call callback with ready response
-                if on_response_ready:
-                    await on_response_ready(response)
-
-        # Pass event further
-        await send(message)
-
-    await app(scope, receive, response_builder)
-
-
-class FastCacheMiddleware:
+class FastCacheMiddleware(BaseMiddleware):
     """Middleware for caching responses in ASGI applications.
 
     Route resolution approach:
@@ -137,12 +214,79 @@ class FastCacheMiddleware:
         storage: tp.Optional[BaseStorage] = None,
         controller: tp.Optional[Controller] = None,
     ) -> None:
-        self.app = app
+        super().__init__(app)
+
         self.storage = storage or InMemoryStorage()
         self.controller = controller or Controller()
+        self._openapi_initialized = False
 
         self._routes_info: list[RouteInfo] = []
 
+        current_app: tp.Any = app
+        while current_app := getattr(current_app, "app", None):
+            if isinstance(current_app, routing.APIRouter):
+                _routes = get_routes(current_app)
+                self._routes_info = self._extract_routes_info(_routes)
+                break
+
+    async def on_lifespan(self, scope: Scope, _: Receive, __: Send) -> bool | None:
+        app_routes = get_app_routes(scope["app"])
+        set_cache_age_in_openapi_schema(scope["app"])
+        self._routes_info = self._extract_routes_info(app_routes)
+        return None
+
+    async def on_http(self, scope: Scope, receive: Receive, send: Send) -> bool | None:
+        request = Request(scope, receive)
+
+        if not self._openapi_initialized:
+            set_cache_age_in_openapi_schema(scope["app"])
+            self._openapi_initialized = True
+
+        # Find matching route
+        route_info = self._find_matching_route(request, self._routes_info)
+        if not route_info:
+            return None
+
+        cache_configuration = route_info.cache_config
+
+        # Handle invalidation if specified
+        if cache_configuration.invalidate_paths:
+            await self.controller.invalidate_cache(
+                cache_configuration.invalidate_paths, storage=self.storage
+            )
+
+        if not cache_configuration.max_age:
+            return None
+
+        if not await self.controller.is_cachable_request(request):
+            return None
+
+        cache_key = await self.controller.generate_cache_key(
+            request, cache_configuration=cache_configuration
+        )
+
+        cached_response = await self.controller.get_cached_response(
+            cache_key, self.storage
+        )
+        if cached_response is not None:
+            logger.debug("Returning cached response for key: %s", cache_key)
+            await cached_response(scope, receive, send)
+            return True
+
+        # Cache not found - execute request and cache result
+        await CacheSendWrapper(
+            app=self.app,
+            scope=scope,
+            receive=receive,
+            send=send,
+            controller=self.controller,
+            storage=self.storage,
+            request=request,
+            cache_key=cache_key,
+            ttl=cache_configuration.max_age,
+        )()
+        return True
+
     def _extract_routes_info(self, routes: list[routing.APIRoute]) -> list[RouteInfo]:
         """Recursively extracts route information and their dependencies.
 
@@ -157,10 +301,17 @@ class FastCacheMiddleware:
             ) = self._extract_cache_configs_from_route(route)
 
             if cache_config or cache_drop_config:
+                cache_configuration = CacheConfiguration(
+                    max_age=cache_config.max_age if cache_config else None,
+                    key_func=cache_config.key_func if cache_config else None,
+                    invalidate_paths=(
+                        cache_drop_config.paths if cache_drop_config else None
+                    ),
+                )
+
                 route_info = RouteInfo(
                     route=route,
-                    cache_config=cache_config,
-                    cache_drop_config=cache_drop_config,
+                    cache_config=cache_configuration,
                 )
                 routes_info.append(route_info)
 
@@ -212,83 +363,7 @@ class FastCacheMiddleware:
             if request.method not in route_info.methods:
                 continue
             match_mode, _ = route_info.route.matches(request.scope)
-            if match_mode == routing.Match.FULL:
+            if match_mode == Match.FULL:
                 return route_info
 
-        return
-
-    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
-        if scope["type"] != "http":
-            await self.app(scope, receive, send)
-            return
-
-        if not self._routes_info:
-            app_routes = get_app_routes(scope["app"])
-            self._routes_info = self._extract_routes_info(app_routes)
-
-        request = Request(scope, receive)
-
-        # Find matching route
-        route_info = self._find_matching_route(request, self._routes_info)
-        if not route_info:
-            await self.app(scope, receive, send)
-            return
-
-        # Handle invalidation if specified
-        if cc := route_info.cache_drop_config:
-            await self.controller.invalidate_cache(cc, storage=self.storage)
-
-        # Handle caching if config exists
-        if route_info.cache_config:
-            await self._handle_cache_request(route_info, request, scope, receive, send)
-            return
-
-        # Execute original request
-        await self.app(scope, receive, send)
-
-    async def _handle_cache_request(
-        self,
-        route_info: RouteInfo,
-        request: Request,
-        scope: Scope,
-        receive: Receive,
-        send: Send,
-    ) -> None:
-        """Handles request with caching.
-
-        Args:
-            route_info: Route information
-            request: HTTP request
-            scope: ASGI scope
-            receive: ASGI receive callable
-            send: ASGI send callable
-        """
-        cache_config = route_info.cache_config
-        if not cache_config:
-            await self.app(scope, receive, send)
-            return
-
-        if not await self.controller.is_cachable_request(request):
-            await self.app(scope, receive, send)
-            return
-
-        cache_key = await self.controller.generate_cache_key(request, cache_config)
-
-        cached_response = await self.controller.get_cached_response(
-            cache_key, self.storage
-        )
-        if cached_response is not None:
-            logger.debug("Returning cached response for key: %s", cache_key)
-            await cached_response(scope, receive, send)
-            return
-
-        # Cache not found - execute request and cache result
-        await send_with_callbacks(
-            self.app,
-            scope,
-            receive,
-            send,
-            lambda response: self.controller.cache_response(
-                cache_key, request, response, self.storage, cache_config.max_age
-            ),
-        )
+        return None

fast_cache_middleware/schemas.py

@@ -1,21 +1,78 @@
-import typing as tp
+import re
+from typing import Any, Callable
 
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    computed_field,
+    field_validator,
+    model_validator,
+)
+from starlette.requests import Request
 from starlette.routing import Route
 
-from .depends import BaseCacheConfigDepends
+from .depends import CacheConfig, CacheDropConfig
 
 
-class RouteInfo:
+class CacheConfiguration(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
+
+    max_age: int | None = Field(
+        default=None,
+        description="Cache lifetime in seconds. If None, caching is disabled.",
+    )
+    key_func: Callable[[Request], str] | None = Field(
+        default=None,
+        description="Custom cache key generation function. If None, default key generation is used.",
+    )
+    invalidate_paths: list[re.Pattern] | None = Field(
+        default=None,
+        description="Paths for cache invalidation (strings or regex patterns). No invalidation if None.",
+    )
+
+    @model_validator(mode="after")
+    def one_of_field_is_set(self) -> "CacheConfiguration":
+        if (
+            self.max_age is None
+            and self.key_func is None
+            and self.invalidate_paths is None
+        ):
+            raise ValueError(
+                "At least one of max_age, key_func, or invalidate_paths must be set."
+            )
+        return self
+
+    @field_validator("invalidate_paths")
+    @classmethod
+    def compile_paths(cls, item: Any) -> Any:
+        if item is None:
+            return None
+        if isinstance(item, str):
+            return re.compile(f"^{item}")
+        if isinstance(item, re.Pattern):
+            return item
+        if isinstance(item, list):
+            return [cls.compile_paths(i) for i in item]
+        raise ValueError(
+            "invalidate_paths must be a string, regex pattern, or list of them."
+        )
+
+
+class RouteInfo(BaseModel):
     """Route information with cache configuration."""
 
-    def __init__(
-        self,
-        route: Route,
-        cache_config: tp.Optional[BaseCacheConfigDepends] = None,
-        cache_drop_config: tp.Optional[BaseCacheConfigDepends] = None,
-    ):
-        self.route = route
-        self.cache_config = cache_config
-        self.cache_drop_config = cache_drop_config
-        self.path: str = getattr(route, "path")
-        self.methods: tp.Set[str] = getattr(route, "methods", set())
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
+
+    route: Route
+    cache_config: CacheConfiguration
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def path(self) -> str:
+        return getattr(self.route, "path", "")
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def methods(self) -> set[str]:
+        return getattr(self.route, "methods", set())

fast_cache_middleware/serializers.py

@@ -1,23 +1,21 @@
 import json
-import typing as tp
+from typing import Any, Callable, Dict, Optional, Tuple, TypeAlias, Union
 
 from starlette.requests import Request
 from starlette.responses import Response
 
 # Define types for metadata and stored response
-Metadata: tp.TypeAlias = tp.Dict[str, tp.Any]  # todo: make it models
-StoredResponse: tp.TypeAlias = tp.Tuple[Response, Request, Metadata]
+Metadata: TypeAlias = Dict[str, Any]  # todo: make it models
+StoredResponse: TypeAlias = Tuple[Response, Request, Metadata]
 
 
 class BaseSerializer:
     def dumps(
         self, response: Response, request: Request, metadata: Metadata
-    ) -> tp.Union[str, bytes]:
+    ) -> Union[str, bytes]:
         raise NotImplementedError()
 
-    def loads(
-        self, data: tp.Union[str, bytes]
-    ) -> tp.Tuple[Response, Request, Metadata]:
+    def loads(self, data: Union[str, bytes]) -> Tuple[Response, Request, Metadata]:
         raise NotImplementedError()
 
     @property
@@ -27,26 +25,9 @@ class BaseSerializer:
 
 class JSONSerializer(BaseSerializer):
     def dumps(self, response: Response, request: Request, metadata: Metadata) -> str:
-        serialized = {
-            "response": {
-                "status_code": response.status_code,
-                "headers": [[k.decode(), v.decode()] for k, v in response.headers.raw],
-                "content": (
-                    response.body.decode("utf-8", errors="ignore")
-                    if response.body
-                    else None
-                ),
-            },
-            "request": {
-                "method": request.method,
-                "url": str(request.url),
-                "headers": [[k.decode(), v.decode()] for k, v in request.headers.raw],
-            },
-            "metadata": metadata,
-        }
-        return json.dumps(serialized)
+        raise NotImplementedError()  # fixme: bad implementation now, maybe async?
 
-    def loads(self, data: tp.Union[str, bytes]) -> StoredResponse:
+    def loads(self, data: Union[str, bytes]) -> StoredResponse:
         if isinstance(data, bytes):
             data = data.decode()
 
@@ -80,7 +61,7 @@ class JSONSerializer(BaseSerializer):
         }
 
         # Create empty receive function
-        async def receive():
+        async def receive() -> Dict[str, Any]:
             return {"type": "http.request", "body": b""}
 
         request = Request(scope, receive)