|
| 1 | +# FastAPI Cap Quick Start |
| 2 | + |
| 3 | +**FastAPI Cap** is a robust, extensible rate limiting library for FastAPI, powered by Redis. This guide will help you get started quickly with the Fixed Window rate limiting strategy. |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## 1. Installation |
| 8 | + |
| 9 | +Install the package using pip: |
| 10 | + |
| 11 | +```bash |
| 12 | +pip install fastapicap |
| 13 | +``` |
| 14 | + |
| 15 | +**Note**: You also need a running Redis instance. You can run one locally using Docker: |
| 16 | + |
| 17 | + |
| 18 | +--- |
| 19 | + |
| 20 | +## 2. Initialize the App |
| 21 | + |
| 22 | +Before using any limiter, you must initialize the shared Redis connection. |
| 23 | +You can do this in your FastAPI app's lifespan event or directly at startup. |
| 24 | + |
| 25 | +```python |
| 26 | +from fastapi import FastAPI |
| 27 | +from fastapicap import Cap |
| 28 | + |
| 29 | +app = FastAPI() |
| 30 | +Cap.init_app("redis://localhost:6379/0") |
| 31 | + |
| 32 | +``` |
| 33 | + |
| 34 | +--- |
| 35 | + |
| 36 | +## 3. Using the Fixed Window Rate Limiter |
| 37 | + |
| 38 | +Import the `RateLimiter` (Also Known As Fixed Window Rate Limiter) and use it as a dependency on your route: |
| 39 | + |
| 40 | +```python |
| 41 | +from fastapi import Depends |
| 42 | +limiter1 = RateLimiter(limit=5, minutes=1) |
| 43 | + |
| 44 | +@app.get("/limited", dependencies=[Depends(limiter1)]) |
| 45 | +async def limited_endpoint(): |
| 46 | + return {"message": "You are within the rate limit!"} |
| 47 | +``` |
| 48 | + |
| 49 | +If the limit is exceeded, the client receives a `429 Too Many Requests` response with a `Retry-After` header. |
| 50 | + |
| 51 | +--- |
| 52 | + |
| 53 | +## 4. Using Multiple Limiters on a Single Route |
| 54 | + |
| 55 | +You can combine multiple limiters for more granular control. |
| 56 | +For example, to allow **1 request per second** and **30 requests per minute**: |
| 57 | + |
| 58 | +```python |
| 59 | +from fastapi import FastAPI, Depends |
| 60 | +from fastapicap import Cap, RateLimiter |
| 61 | + |
| 62 | +## App Init part |
| 63 | + |
| 64 | +limiter_1s = RateLimiter(limit=1, seconds=1) |
| 65 | +limiter_30m = RateLimiter(limit=30, minutes=1) |
| 66 | + |
| 67 | +@app.get("/strict", dependencies=[Depends(limiter_1s), Depends(limiter_30m)]) |
| 68 | +async def strict_endpoint(): |
| 69 | + return {"message": "You passed both rate limits!"} |
| 70 | +``` |
| 71 | + |
| 72 | +If either limit is exceeded, the request will be blocked. |
| 73 | + |
| 74 | +--- |
| 75 | + |
| 76 | +### **Notes** |
| 77 | + |
| 78 | +- The default key for rate limiting is based on the client IP and request path. |
| 79 | +- All limiters are backed by Redis and require a working Redis connection. |
| 80 | +- Only dependency-based usage is currently supported and tested. |
| 81 | + |
| 82 | +--- |
| 83 | + |
| 84 | +## 5. Customizing `on_limit` and `key_func` in FastAPI Cap |
| 85 | +FastAPI Cap allows you to customize how rate limits are enforced and how unique clients are identified by providing your own `on_limit` and `key_func` functions to any limiter. |
| 86 | +This guide explains how to use and implement custom `on_limit` and `key_func` functions, including the parameters they receive. |
| 87 | + |
| 88 | + |
| 89 | +### Default `key_func` Implementation |
| 90 | + |
| 91 | +By default, FastAPI Cap uses the client IP address and request path to generate a unique key for each client and endpoint. |
| 92 | + |
| 93 | +```python |
| 94 | +@staticmethod |
| 95 | +async def _default_key_func(request: Request) -> str: |
| 96 | + """ |
| 97 | + Default key function: uses client IP and request path. |
| 98 | + """ |
| 99 | + x_forwarded_for = request.headers.get("X-Forwarded-For") |
| 100 | + if x_forwarded_for: |
| 101 | + client_ip = x_forwarded_for.split(",")[0].strip() |
| 102 | + else: |
| 103 | + client_ip = request.client.host if request.client else "unknown" |
| 104 | + return f"{client_ip}:{request.url.path}" |
| 105 | +``` |
| 106 | +- **Parameters:** |
| 107 | + - `request`: The FastAPI `Request` object. |
| 108 | +- **Returns:** |
| 109 | + - A string key in the format `client_ip:/path`. |
| 110 | + |
| 111 | +### Default `on_limit` Implementation |
| 112 | + |
| 113 | +By default, FastAPI Cap raises a `429 Too Many Requests` HTTPException and sets the `Retry-After` header. |
| 114 | + |
| 115 | +```python |
| 116 | +@staticmethod |
| 117 | +async def _default_on_limit(request, response, retry_after: int) -> None: |
| 118 | + """ |
| 119 | + Default handler when the rate limit is exceeded. |
| 120 | + """ |
| 121 | + from fastapi import HTTPException |
| 122 | + |
| 123 | + raise HTTPException( |
| 124 | + status_code=429, |
| 125 | + detail="Rate limit exceeded. Please try again later.", |
| 126 | + headers={"Retry-After": str(retry_after)}, |
| 127 | + ) |
| 128 | +``` |
| 129 | + |
| 130 | +- **Parameters:** |
| 131 | + - `request`: The FastAPI `Request` object. |
| 132 | + - `response`: The FastAPI `Response` object (not used in the default). |
| 133 | + - `retry_after`: An integer indicating how many seconds to wait before retrying. |
| 134 | + |
| 135 | +--- |
| 136 | + |
| 137 | + |
| 138 | +### Custom `key_func` |
| 139 | + |
| 140 | +The `key_func` is responsible for generating a unique key for each client/request. |
| 141 | +You can provide your own logic to rate limit by user ID, API key, or any other identifier. |
| 142 | + |
| 143 | +### **Signature** |
| 144 | + |
| 145 | +```python |
| 146 | +async def key_func(request: Request) -> str: |
| 147 | + ... |
| 148 | +``` |
| 149 | + |
| 150 | +### **Example: Rate Limit by User ID** |
| 151 | + |
| 152 | +```python |
| 153 | +from fastapi import Request |
| 154 | + |
| 155 | +async def user_id_key_func(request: Request) -> str: |
| 156 | + # Assume user ID is stored in request.state.user_id |
| 157 | + user_id = getattr(request.state, "user_id", None) |
| 158 | + if user_id is None: |
| 159 | + # Fallback to IP if user is not authenticated |
| 160 | + client_ip = request.client.host if request.client else "unknown" |
| 161 | + return f"anon:{client_ip}:{request.url.path}" |
| 162 | + return f"user:{user_id}:{request.url.path}" |
| 163 | +``` |
| 164 | + |
| 165 | +**Usage:** |
| 166 | + |
| 167 | +```python |
| 168 | +limiter = RateLimiter(limit=10, minutes=1, key_func=user_id_key_func) |
| 169 | +``` |
| 170 | + |
| 171 | +### **Using Your Custom `on_limit` Handler** |
| 172 | + |
| 173 | +The `on_limit` function is called when a client exceeds the rate limit. |
| 174 | +You can customize this to log, return a custom response, or perform other actions. |
| 175 | + |
| 176 | +### Signature |
| 177 | + |
| 178 | +```python |
| 179 | +async def on_limit(request: Request, response: Response, retry_after: int) -> None: |
| 180 | + ... |
| 181 | +``` |
| 182 | + |
| 183 | +### **Example: Custom JSON Error Response** |
| 184 | + |
| 185 | +```python |
| 186 | +from fastapi import Request, Response |
| 187 | +from fastapi.responses import JSONResponse |
| 188 | + |
| 189 | +async def custom_on_limit(request: Request, response: Response, retry_after: int): |
| 190 | + response = JSONResponse( |
| 191 | + status_code=429, |
| 192 | + content={ |
| 193 | + "error": "Too many requests", |
| 194 | + "retry_after": retry_after, |
| 195 | + "detail": "Please slow down!" |
| 196 | + }, |
| 197 | + headers={"Retry-After": str(retry_after)}, |
| 198 | + ) |
| 199 | + raise response |
| 200 | +``` |
| 201 | + |
| 202 | +**Usage:** |
| 203 | + |
| 204 | +```python |
| 205 | +limiter = RateLimiter(limit=5, minutes=1, on_limit=custom_on_limit) |
| 206 | +``` |
| 207 | + |
| 208 | +--- |
| 209 | + |
| 210 | + |
| 211 | +## Next Steps |
| 212 | + |
| 213 | +- Explore other strategies: Sliding Window, Token Bucket, Leaky Bucket, GCRA, and Sliding Window Log. |
| 214 | + |
| 215 | +--- |
| 216 | + |
| 217 | +**Happy rate limiting!** |
0 commit comments