Getting Started and Installation
Relevant source files
The following files were used as context for generating this wiki page:
FastLimit is a production-ready, high-performance rate limiting library for Python applications, specifically optimized for asynchronous frameworks like FastAPI. It utilizes a Redis backend to ensure atomic operations and consistency across distributed systems, supporting multiple algorithms such as Fixed Window, Token Bucket, and Sliding Window.
The library is designed to be "async-first," providing a declarative decorator-based API, automatic header injection, and comprehensive observability through Prometheus metrics. It serves use cases ranging from simple IP-based throttling to complex multi-tenant SaaS platforms with tier-based limits.
Sources: README.md:1-20, pyproject.toml:1-15
Installation and Prerequisites
FastLimit requires Python 3.9 or higher and a Redis server (version 7.0+). It can be installed via standard Python package managers.
Standard Installation
Users can install the core library or include optional dependencies for production monitoring.
# Core installation
pip install fastlimit
# With Prometheus metrics support
pip install 'fastlimit[metrics]'
Sources: README.md:43-50, CONTRIBUTING.md:41-50
Dependency Overview
The project manages dependencies via Poetry, categorizing them into core, development, and example groups.
| Group | Key Dependencies | Purpose |
|---|---|---|
| Main | python ^3.9, redis ^5.0.0, pydantic ^2.0 | Core library functionality and data validation |
| Dev/Test | pytest, black, ruff, mypy | Linting, formatting, and unit testing |
| Metrics | prometheus-client | Observability and performance tracking |
| Examples | fastapi, uvicorn, httpx | Demonstration of framework integration |
Sources: pyproject.toml:26-55
Development Environment Setup
For contributors looking to build upon or test the library, the following workflow is established for setting up a local environment.
Setup Steps
- Repository Initialization: Fork and clone the repository, then set up a virtual environment.
- Dependency Installation: Install development tools using the editable mode.
pip install -e ".[dev,test,metrics]" - Redis Backend: A local Redis server or a Docker container is required for testing.
docker run -d -p 6379:6379 redis:7-alpine - Verification: Execute the test suite to ensure the environment is correctly configured.
pytest
Sources: CONTRIBUTING.md:75-120
Core Component Architecture
FastLimit operates by intercepting requests through decorators or middleware, consulting the Redis backend via Lua scripts, and returning a rate limit decision.
The diagram shows the request flow from the application through the RateLimiter core to the atomic Lua operations in Redis.
Sources: README.md:275-290, fastlimit/decorators.py:170-210
Basic Integration
Integrating FastLimit involves initializing the RateLimiter, connecting to Redis, and applying the @limiter.limit decorator to endpoints.
Quick Start Example
from fastapi import FastAPI, Request
from fastlimit import RateLimiter, RateLimitHeadersMiddleware
app = FastAPI()
limiter = RateLimiter(redis_url="redis://localhost:6379")
# Recommended for standard headers
app.add_middleware(RateLimitHeadersMiddleware)
@app.on_event("startup")
async def startup():
await limiter.connect()
@app.get("/api/data")
@limiter.limit("100/minute")
async def get_data(request: Request):
return {"data": "success"}
Sources: README.md:52-70, examples/fastapi_app.py:35-80
Configuration Options
The RateLimiter constructor accepts several parameters to customize behavior.
| Parameter | Type | Default | Description |
|---|---|---|---|
redis_url | str | "redis://localhost:6379" | Connection string for the Redis instance |
key_prefix | str | "ratelimit" | Namespace prefix for keys stored in Redis |
default_algorithm | str | "fixed_window" | Fallback algorithm (fixed_window, token_bucket, sliding_window) |
enable_metrics | bool | False | Toggles Prometheus metric collection |
Sources: README.md:128-142
Header Management and Middleware
FastLimit provides RateLimitHeadersMiddleware to automatically inject industry-standard headers into HTTP responses. This enhances client-side awareness of remaining quotas.
The sequence diagram illustrates how middleware manages the lifecycle of rate limit headers for both successful and throttled requests.
Sources: fastlimit/middleware.py, fastlimit/decorators.py:195-215, README.md:175-185
Standard Headers Included:
X-RateLimit-Limit: The total allowed requests in the window.X-RateLimit-Remaining: Requests left before being throttled.X-RateLimit-Reset: Unix timestamp of the window reset.Retry-After: (On 429 errors) Seconds until the next allowed request.
Sources: README.md:188-195, examples/fastapi_app.py:55-70
Summary
The installation of FastLimit is a streamlined process requiring a modern Python environment and a Redis instance. By utilizing the provided middleware and decorators, developers can implement robust, distributed rate limiting with minimal boilerplate, benefiting from atomic Lua-based operations and built-in observability features.
Sources: README.md:320-330