Update 0.3.0

Author: SirStig

.github/workflows/publish.yml

@@ -95,7 +95,7 @@ jobs:
 
       - name: Type check
         run: |
-          mypy src --ignore-missing-imports
+          mypy src --ignore-missing-imports --disable-error-code=unused-ignore
 
   build-and-publish:
     name: Build and Publish to PyPI

.github/workflows/test.yml

@@ -47,7 +47,7 @@ jobs:
 
     - name: Type check with mypy
       run: |
-        mypy src --ignore-missing-imports
+        mypy src --ignore-missing-imports --disable-error-code=unused-ignore
 
     - name: Test with pytest
       run: |

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
     rev: v1.10.0
     hooks:
       - id: mypy
-        args: [--ignore-missing-imports, --no-strict-optional]
+        args: [--ignore-missing-imports, --no-strict-optional, --disable-error-code=unused-ignore]
         exclude: ^(scripts/|examples/)
         additional_dependencies:
           - types-PyYAML

=1.15.0

@@ -262,13 +262,13 @@ async def get_user(user_id: int, db=Depends(cached_get_db)):
 
 ```python
 from fastapi import FastAPI
-from yokedcache.middleware import CacheMiddleware
+from yokedcache.middleware import HTTPCacheMiddleware
 
 app = FastAPI()
 
 # Add HTTP caching middleware
 app.add_middleware(
-    CacheMiddleware,
+    HTTPCacheMiddleware,
     cache_ttl=300,
     cache_key_prefix="http",
     include_paths=["/api/*"],
@@ -585,4 +585,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**Made with care by [Project Yoked LLC](https://github.com/sirstig)**
+**Made with care by [SirStig](https://github.com/sirstig)**

=5.0.0

@@ -19,6 +19,8 @@ YokedCache is a powerful, async-first Python caching library that brings enterpr
 - **🛡️ Production-Ready**: Health checks, error handling, and security features
 - **🔐 Resilient**: Circuit breaker, retry logic, and graceful fallbacks *(v0.2.1)*
 - **⚡ Enhanced**: Smart async/sync context handling and performance optimizations *(v0.2.1)*
+- **🌐 Advanced Patterns**: HTTP middleware, single-flight protection, stale-while-revalidate *(v0.3.0)*
+- **🔍 Observability**: OpenTelemetry tracing and per-prefix backend routing *(v0.3.0)*
 
 ## Quick Start - Python FastAPI Redis Caching
 
@@ -65,6 +67,7 @@ Powerful capabilities for complex use cases:
 - **[Backends & Setup](backends.md)** - Memory, Redis, Memcached backends with setup guides
 - **[Vector Search](vector-search.md)** - Semantic similarity search capabilities
 - **[Monitoring & Health](monitoring.md)** - Comprehensive monitoring, health checks, and alerting *(v0.2.1)*
+- **[Advanced Caching Patterns](usage-patterns.md#advanced-caching-patterns-v030)** - HTTP middleware, SWR, single-flight protection *(v0.3.0)*
 
 ### 📖 **Reference**
 Detailed technical documentation:
@@ -115,8 +118,20 @@ pip install yokedcache[vector]      # Vector search
 pip install yokedcache[monitoring]  # Prometheus & StatsD
 pip install yokedcache[memcached]   # Memcached backend
 pip install yokedcache[fuzzy]       # Fuzzy search
+pip install yokedcache[disk]        # DiskCache backend (v0.3.0)
+pip install yokedcache[tracing]     # OpenTelemetry tracing (v0.3.0)
 ```
 
+## What's New in 0.3.0
+
+- **🌐 HTTP Response Middleware**: ETag/Cache-Control headers with 304 Not Modified responses
+- **🛡️ Single-Flight Protection**: Prevents cache stampede with automatic deduplication
+- **🔄 Stale-While-Revalidate**: Serve stale data while refreshing in background
+- **💪 Stale-If-Error**: Fallback to cached data during service failures
+- **🔀 Per-Prefix Routing**: Shard cache keys across multiple backends by prefix
+- **📊 OpenTelemetry Integration**: Distributed tracing with spans and metrics
+- **💾 New Backends**: DiskCache and SQLite backends for persistent caching
+
 ## What's New in 0.2.0
 
 - **🆕 Multi-Backend Support**: Memory, Redis, and Memcached backends

README.md

@@ -34,7 +34,7 @@
             "price": "0",
             "priceCurrency": "USD"
         },
-        "softwareVersion": "0.2.1",
+        "softwareVersion": "0.3.0",
         "requirements": "Python 3.9+",
         "featureList": [
             "Redis caching with auto-invalidation",

docs/index.md

@@ -543,6 +543,162 @@ async def get_with_fallback(key):
     )
 ```
 
+## Advanced Caching Patterns *(v0.3.0)*
+
+YokedCache 0.3.0 introduces powerful advanced caching patterns designed for high-performance, production-ready applications.
+
+### HTTP Response Middleware
+
+Add HTTP caching middleware to FastAPI applications for automatic ETag and Cache-Control header management:
+
+```python
+from fastapi import FastAPI
+from yokedcache import YokedCache
+from yokedcache.middleware import HTTPCacheMiddleware
+
+app = FastAPI()
+cache = YokedCache()
+
+# Add HTTP caching middleware
+app.add_middleware(
+    HTTPCacheMiddleware,
+    cache=cache,
+    default_ttl=300,
+    include_query=False,
+    cache_control="public, max-age=300"
+)
+
+@app.get("/api/users/{user_id}")
+async def get_user(user_id: int):
+    # Response automatically cached with ETag headers
+    # Returns 304 Not Modified for unchanged data
+    return {"id": user_id, "name": "John Doe"}
+```
+
+### Single-Flight Protection
+
+Prevent cache stampede by ensuring only one request computes a value while others wait:
+
+```python
+from yokedcache import YokedCache, CacheConfig
+
+config = CacheConfig(
+    redis_url="redis://localhost:6379",
+    enable_single_flight=True
+)
+cache = YokedCache(config)
+
+async def expensive_computation():
+    # This will only run once, even with concurrent requests
+    await asyncio.sleep(5)
+    return compute_expensive_data()
+
+# Multiple concurrent requests - only one computation runs
+results = await asyncio.gather(
+    cache.fetch_or_set("expensive_key", expensive_computation, ttl=300),
+    cache.fetch_or_set("expensive_key", expensive_computation, ttl=300),
+    cache.fetch_or_set("expensive_key", expensive_computation, ttl=300),
+)
+# All results are identical, but computation only ran once
+```
+
+### Stale-While-Revalidate (SWR)
+
+Serve stale cached data immediately while refreshing in the background:
+
+```python
+from yokedcache import YokedCache, CacheConfig
+
+config = CacheConfig(
+    redis_url="redis://localhost:6379",
+    enable_stale_while_revalidate=True
+)
+cache = YokedCache(config)
+
+# Function that returns stale data immediately and refreshes in background
+async def get_user_data(user_id: int):
+    return await cache.fetch_or_set(
+        f"user:{user_id}",
+        lambda: fetch_user_from_db(user_id),
+        ttl=60
+    )
+```
+
+### Stale-If-Error
+
+Fallback to cached data when the primary data source fails:
+
+```python
+from yokedcache import YokedCache, CacheConfig
+
+config = CacheConfig(
+    redis_url="redis://localhost:6379",
+    enable_stale_if_error=True,
+    stale_if_error_ttl=120  # Serve stale for up to 2 minutes after TTL expires
+)
+cache = YokedCache(config)
+
+async def get_data_with_fallback(key: str):
+    try:
+        return await fetch_fresh_data(key)
+    except Exception:
+        # Returns stale cached data if available
+        return await cache.get(key, default=None)
+```
+
+### Per-Prefix Backend Routing
+
+Route different cache keys to different backends based on key prefixes:
+
+```python
+from yokedcache import YokedCache
+from yokedcache.backends import DiskCacheBackend, RedisBackend
+
+cache = YokedCache()
+
+# Setup prefix-based routing
+cache.setup_prefix_routing()
+
+# Route different data types to different backends
+cache.add_backend_route("user:", RedisBackend("redis://localhost:6379/0"))
+cache.add_backend_route("temp:", DiskCacheBackend("/tmp/cache"))
+cache.add_backend_route("session:", RedisBackend("redis://localhost:6379/1"))
+
+# Data automatically routed based on key prefix
+await cache.set("user:123", user_data)      # -> Redis DB 0
+await cache.set("temp:abc", temp_data)      # -> Disk cache
+await cache.set("session:xyz", session)     # -> Redis DB 1
+```
+
+### OpenTelemetry Distributed Tracing
+
+Enable distributed tracing for cache operations:
+
+```python
+from yokedcache import YokedCache, CacheConfig
+from yokedcache.tracing import initialize_tracing
+
+# Initialize global tracing
+initialize_tracing(
+    service_name="my-api",
+    enabled=True,
+    sample_rate=1.0
+)
+
+config = CacheConfig(
+    redis_url="redis://localhost:6379",
+    enable_tracing=True
+)
+cache = YokedCache(config)
+
+# All cache operations automatically traced
+async with cache._tracer.trace_operation("get_user", "user:123"):
+    user = await cache.get("user:123")
+    # Span includes timing, hit/miss, backend info
+```
+
+These advanced patterns enable sophisticated caching strategies for high-performance, production applications.
+
 ## Performance Optimization Patterns
 
 ### Connection Reuse

docs/javascripts/schema.js

@@ -1,7 +1,7 @@
 """
 YokedCache Advanced Features Demo
 
-This example demonstrates the new advanced caching features introduced in v0.2.4:
+This example demonstrates the new advanced caching features introduced in v0.3.0:
 - HTTP Response Middleware
 - Single-Flight Protection
 - Stale-While-Revalidate