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

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)

fast_cache_middleware/storages.py

@@ -1,8 +1,8 @@
 import logging
 import re
 import time
-import typing as tp
 from collections import OrderedDict
+from typing import Any, Dict, Optional, Tuple, Union
 
 from starlette.requests import Request
 from starlette.responses import Response
@@ -14,7 +14,7 @@ from .serializers import BaseSerializer, JSONSerializer, Metadata
 logger = logging.getLogger(__name__)
 
 # Define type for stored response
-StoredResponse: TypeAlias = tp.Tuple[Response, Request, Metadata]
+StoredResponse: TypeAlias = Tuple[Response, Request, Metadata]
 
 
 # Define base class for cache storage
@@ -28,8 +28,8 @@ class BaseStorage:
 
     def __init__(
         self,
-        serializer: tp.Optional[BaseSerializer] = None,
-        ttl: tp.Optional[tp.Union[int, float]] = None,
+        serializer: Optional[BaseSerializer] = None,
+        ttl: Optional[Union[int, float]] = None,
     ) -> None:
         self._serializer = serializer or JSONSerializer()
 
@@ -43,7 +43,7 @@ class BaseStorage:
     ) -> None:
         raise NotImplementedError()
 
-    async def retrieve(self, key: str) -> tp.Optional[StoredResponse]:
+    async def retrieve(self, key: str) -> Optional[StoredResponse]:
         raise NotImplementedError()
 
     async def remove(self, path: re.Pattern) -> None:
@@ -70,8 +70,8 @@ class InMemoryStorage(BaseStorage):
     def __init__(
         self,
         max_size: int = 1000,
-        serializer: tp.Optional[BaseSerializer] = None,
-        ttl: tp.Optional[tp.Union[int, float]] = None,
+        serializer: Optional[BaseSerializer] = None,
+        ttl: Optional[Union[int, float]] = None,
     ) -> None:
         super().__init__(serializer=serializer, ttl=ttl)
 
@@ -87,7 +87,7 @@ class InMemoryStorage(BaseStorage):
         # OrderedDict for efficient LRU
         self._storage: OrderedDict[str, StoredResponse] = OrderedDict()
         # Separate expiry time storage for fast TTL checking
-        self._expiry_times: tp.Dict[str, float] = {}
+        self._expiry_times: Dict[str, float] = {}
         self._last_expiry_check_time: float = 0
         self._expiry_check_interval: float = 60
 
@@ -126,7 +126,7 @@ class InMemoryStorage(BaseStorage):
 
         self._cleanup_lru_items()
 
-    async def retrieve(self, key: str) -> tp.Optional[StoredResponse]:
+    async def retrieve(self, key: str) -> Optional[StoredResponse]:
         """Gets response from cache with lazy TTL checking.
 
         Element moves to the end to update LRU position.

fast_cache_middleware-0.0.5.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vadim Vakilov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fast_cache_middleware-0.0.5.dist-info/METADATA

@@ -0,0 +1,344 @@
+Metadata-Version: 2.3
+Name: fast-cache-middleware
+Version: 0.0.5
+Summary: An intelligent middleware for caching FastAPI responses
+License: MIT
+Author: www.chud0@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: fastapi (>=0.111.1,<1.0.0)
+Requires-Dist: pydantic (>=1.7.4,!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# FastCacheMiddleware
+
+🚀 **High-performance ASGI middleware for caching with route resolution approach**
+
+## ✨ Key Features
+
+FastCacheMiddleware uses a **route resolution approach** - it analyzes application routes at startup and extracts cache configurations from FastAPI dependencies.
+
+### 🔧 How it works
+
+1. **At application startup:**
+   - Middleware analyzes all routes and their dependencies
+   - Extracts `CacheConfig` and `CacheDropConfig` from dependencies
+   - Creates internal route index with caching configurations
+
+2. **During request processing:**
+   - Checks HTTP method (cache only GET, invalidate for POST/PUT/DELETE)
+   - Finds matching route by path and method
+   - Extracts cache configuration from pre-analyzed dependencies
+   - Performs caching or invalidation according to configuration
+
+### 💡 Benefits
+
+- **⚡ High performance** - pre-route analysis
+- **🎯 Easy integration** - standard FastAPI dependencies
+- **🔧 Flexible configuration** - custom key functions, route-level TTL
+- **🛡️ Automatic invalidation** - cache invalidation for modifying requests
+- **📊 Minimal overhead** - efficient handling of large numbers of routes
+
+## 📦 Installation
+
+```bash
+pip install fast-cache-middleware
+```
+
+## 🎯 Quick Start
+
+```python
+import uvicorn
+from fastapi import FastAPI
+
+from fast_cache_middleware import CacheConfig, CacheDropConfig, FastCacheMiddleware
+
+app = FastAPI()
+
+# Add middleware - it will automatically analyze routes
+app.add_middleware(FastCacheMiddleware)
+
+
+# Routes with caching
+@app.get("/users/{user_id}", dependencies=[CacheConfig(max_age=300)])
+async def get_user(user_id: int) -> dict[str, int | str]:
+    """This endpoint is cached for 5 minutes."""
+    # Simulate database load
+    return {"user_id": user_id, "name": f"User {user_id}"}
+
+
+# Routes with cache invalidation
+@app.post(
+    "/users/{user_id}",
+    dependencies=[CacheDropConfig(paths=["/users/*", "/api/users/*"])],
+)
+async def update_user(user_id: int) -> dict[str, int | str]:
+    """It will invalidate cache for all /users/* paths."""
+    return {"user_id": user_id, "status": "updated"}
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="127.0.0.1", port=8000)
+```
+
+## 🔧 Configuration
+
+### CacheConfig
+
+Configure caching for GET requests:
+
+```python
+from fast_cache_middleware import CacheConfig
+
+# Simple caching
+CacheConfig(max_age=300)  # 5 minutes
+
+# With custom key function, for personalized cache
+def key_func(request: Request):
+    user_id = request.headers.get("Authorization", "anonymous")
+    path = request.url.path
+    query = str(request.query_params)
+    return f"{path}:{user_id}:{query}"
+
+CacheConfig(max_age=600, key_func=key_func)  # 10 minutes
+```
+
+### CacheDropConfig
+
+Configure cache invalidation for modifying requests:
+
+```python
+# Paths can be matched by startswith
+CacheDropConfig(
+    paths=[
+        "/users/",  # Will match /users/123, /users/profile, etc.
+        "/api/",    # Will match all API paths
+    ]
+)
+
+# Paths can be matched by regexp
+CacheDropConfig(
+    paths=[
+        r"^/users/\d+$",  # Will match /users/123, /users/456, etc.
+        r"^/api/.*",      # Will match all API paths
+    ]
+)
+
+# You can mix regexp and simple string matching - use what's more convenient
+CacheDropConfig(
+    paths=[
+        "/users/",        # Simple prefix match
+        r"^/api/\w+/\d+$" # Regexp for specific API endpoints
+    ]
+)
+```
+
+## 🏗️ Architecture
+
+### System Components
+
+```
+FastCacheMiddleware
+├── RouteInfo           # Route information with cache configuration
+├── Controller          # Caching logic and validation
+├── Storage             # Storages (InMemory, Redis, etc.)
+├── Serializers         # Cached data serialization
+└── Dependencies        # FastAPI dependencies for configuration
+```
+
+### Request Processing Flow
+
+```mermaid
+graph TD
+    A[HTTP Request] --> B{Route analysis done?}
+    B -->|No| C[Analyze application routes]
+    C --> D[Save route configurations]
+    B -->|Yes| E{Method supports caching?}
+    D --> E
+    E -->|No| F[Pass to application]
+    E -->|Yes| G[Find matching route]
+    G --> H{Route found?}
+    H -->|No| F
+    H -->|Yes| I{GET request + CacheConfig?}
+    I -->|Yes| J[Check cache]
+    J --> K{Cache found?}
+    K -->|Yes| L[Return from cache]
+    K -->|No| M[Execute request + save to cache]
+    I -->|No| N{POST/PUT/DELETE + CacheDropConfig?}
+    N -->|Yes| O[Invalidate cache]
+    N -->|No| F
+    O --> F
+    M --> P[Return response]
+```
+
+## 🎛️ Storages
+
+### InMemoryStorage (default)
+
+```python
+from fast_cache_middleware import FastCacheMiddleware, InMemoryStorage
+
+storage = InMemoryStorage(max_size=1000)
+app.add_middleware(FastCacheMiddleware, storage=storage)
+```
+
+InMemoryStorage uses batch cleanup for better performance
+
+### Custom Storage
+
+```python
+from fast_cache_middleware import BaseStorage
+
+class RedisStorage(BaseStorage):
+    def __init__(self, redis_url: str):
+        import redis
+        self.redis = redis.from_url(redis_url)
+    
+    async def store(self, key: str, response, request, metadata):
+        # Implementation for saving to Redis
+        pass
+    
+    async def retrieve(self, key: str):
+        # Implementation for retrieving from Redis
+        pass
+
+app.add_middleware(FastCacheMiddleware, storage=RedisStorage("redis://localhost"))
+```
+
+## 🧪 Testing
+
+```python
+import pytest
+from httpx import AsyncClient
+from examples.basic import app
+
+@pytest.mark.asyncio
+async def test_caching():
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        # First request - cache miss
+        response1 = await client.get("/users/1")
+        assert response1.status_code == 200
+        
+        # Second request - cache hit (should be faster)
+        response2 = await client.get("/users/1")
+        assert response2.status_code == 200
+        assert response1.json() == response2.json()
+
+@pytest.mark.asyncio  
+async def test_cache_invalidation():
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        # Cache data
+        await client.get("/users/1")
+        
+        # Invalidate cache
+        await client.post("/users/1", json={})
+        
+        # Next GET should execute new request
+        response = await client.get("/users/1")
+        assert response.status_code == 200
+```
+
+## 📊 Performance
+
+### Benchmarks
+
+- **Route analysis**: ~5ms for 100 routes at startup
+- **Route lookup**: ~0.1ms per request (O(n) by number of cached routes)
+- **Cache hit**: ~1ms per request
+- **Cache miss**: original request time + ~2ms for saving
+
+### Optimization
+
+```python
+# For applications with many routes
+app.add_middleware(
+    FastCacheMiddleware,
+    storage=InMemoryStorage(max_size=10000),  # Increase cache size
+    controller=Controller(default_ttl=3600)   # Increase default TTL
+)
+```
+
+## 🔒 Security
+
+### Cache Isolation
+
+```python
+def user_specific_cache() -> CacheConfig:
+    def secure_key_func(request):
+        # Include user token in key
+        token = request.headers.get("authorization", "").split(" ")[-1]
+        return f"{request.url.path}:token:{token}"
+    
+    return CacheConfig(max_age=300, key_func=secure_key_func)
+
+@app.get("/private/data", dependencies=[Depends(user_specific_cache)])
+async def get_private_data():
+    return {"sensitive": "data"}
+```
+
+### Header Validation
+
+Middleware automatically respects standard HTTP caching headers:
+
+- `Cache-Control: no-cache` - skip cache
+- `Cache-Control: no-store` - forbid caching
+- `Cache-Control: private`  - don't cache private responses
+
+
+## 🛠️ Advanced Usage
+
+### Custom Controller
+
+```python
+from fast_cache_middleware import Controller
+
+class CustomController(Controller):
+    async def is_cachable_request(self, request):
+        # Custom logic - don't cache admin requests
+        if request.headers.get("x-admin-request"):
+            return False
+        return await super().should_cache_request(request)
+    
+    async def generate_cache_key(self, request):
+        # Add API version to key
+        version = request.headers.get("api-version", "v1")
+        base_key = await super().generate_cache_key(request)
+        return f"{version}:{base_key}"
+
+app.add_middleware(
+    FastCacheMiddleware,
+    controller=CustomController()
+)
+```
+
+## 📝 Examples
+
+More examples in the `examples/` folder:
+
+- **quick_start.py** - minimal example showing basic caching and invalidation
+- **basic.py** - basic usage with FastAPI
+
+## 🤝 Contributing
+
+```bash
+git clone https://github.com/chud0/FastCacheMiddleware
+cd FastCacheMiddleware
+poetry install --with dev
+./scripts/test.sh
+```
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE)
+
+---
+
+⭐ **Like the project? Give it a star!**
+
+🐛 **Found a bug?** [Create an issue](https://github.com/chud0/FastCacheMiddleware/issues)
+
+💡 **Have an idea?** [Suggest a feature](https://github.com/chud0/FastCacheMiddleware/discussions/categories/ideas)

fast_cache_middleware-0.0.5.dist-info/RECORD

@@ -0,0 +1,13 @@
+fast_cache_middleware/__init__.py,sha256=0wuBPKrzjyBA2K9Fnm-xzC1mYSXCMuYr1uPutNXCI5Y,983
+fast_cache_middleware/_helpers.py,sha256=0VbqByNP5AL7mEJpdZLYwef2YhgZsGJOf1tJBshuIZI,904
+fast_cache_middleware/controller.py,sha256=gWGS6r6mWiCOS-cxuzniukzunKowyrnkvl1psamYJHg,7216
+fast_cache_middleware/depends.py,sha256=oHahWfC4PN-rGXbUbmK8TWVlztGO5eswZzaIZdEcfs4,1431
+fast_cache_middleware/exceptions.py,sha256=lv3p2-wAj6UZI7czVSy91eZtuXItr1hZHW2LDz8fI9s,109
+fast_cache_middleware/middleware.py,sha256=ptUwKIe-dpd8kdA9DZDSE98luGtom2BTDvNzlUF9qlM,11940
+fast_cache_middleware/schemas.py,sha256=h7Gq4Pdc1DVkHFGUWUZnI063DXcX-n66Uky9z88cOl8,2331
+fast_cache_middleware/serializers.py,sha256=_aBMbqVWVNYo77xhc7qKuVHg3opIfh8Wa0bYO2j6xn4,2342
+fast_cache_middleware/storages.py,sha256=lErquGfVMDXFZayFDuHm3MKq6Z-0D9-Iru7I1U7b5kE,7614
+fast_cache_middleware-0.0.5.dist-info/LICENSE,sha256=8YvnSj0hf8-FrLOBF2gLYdVKdJsvS83pgYwGZ0EN-Xk,1069
+fast_cache_middleware-0.0.5.dist-info/METADATA,sha256=MYnxUUzrwifLSUrtk_pRHgXtKnk3RFpeGOUtNE2Md4Q,9547
+fast_cache_middleware-0.0.5.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+fast_cache_middleware-0.0.5.dist-info/RECORD,,