Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTRIBUTING.md
• fastlimit/algorithms/sliding_window.py
• fastlimit/decorators.py
• examples/fastapi_app.py
• tests/test_utils.py
• tests/test_security.py

FastLimit is a high-performance, Redis-backed rate limiting library designed for modern Python applications, particularly those built with FastAPI. It employs an async-first design to ensure low-latency enforcement of rate limits across distributed environments. The architecture relies on atomic operations via Redis Lua scripts to eliminate race conditions, ensuring that rate limit counters remain accurate even under high concurrency.

The system is structured into three primary layers: the Application Interface (decorators and middleware), the Core Limiter Logic (orchestration and algorithm selection), and the Storage Backend (Redis with Lua-based atomic execution).

Sources: README.md:14-25, CONTRIBUTING.md:111-137

System Component Hierarchy

The project is organized into several distinct modules that handle specific responsibilities, from high-level web framework integration to low-level cryptographic hashing of keys.

Component	Description	Key Files
Public API	Main RateLimiter class and decorator interface.	fastlimit/limiter.py, fastlimit/decorators.py
Algorithms	Logic for Fixed Window, Token Bucket, and Sliding Window.	fastlimit/algorithms/
Backends	Redis integration and Lua script management.	fastlimit/backends/redis.py
Middleware	Starlette/FastAPI compatible middleware for headers.	fastlimit/middleware.py
Utilities	Key generation, URL encoding, and rate parsing.	fastlimit/utils.py

Sources: CONTRIBUTING.md:111-137

Core Request Flow

When an incoming request hits a decorated endpoint, the library follows a specific sequence of operations to determine if the request should be allowed or throttled.

The diagram above illustrates the typical lifecycle of a rate-limited request from extraction to response generation.
Sources: fastlimit/decorators.py:164-211, README.md:300-310

Data Flow and Logic

Key Generation and Security

FastLimit uses a sophisticated key generation strategy to prevent collisions and ensure security. Keys are generated by combining a prefix, a unique identifier (like an IP or User ID), a tenant type, and a time-window identifier. To prevent key injection and delimiter collisions, the library applies URL encoding to individual components before joining them with colons.

• Collision Prevention: Components like user:123 and user_123 are encoded differently to ensure they map to unique Redis keys.
• Hashing: For extremely long identifiers, the library hashes the key to maintain a manageable length within Redis (typically under 200-300 characters).
• Redaction: Redis connection URLs containing passwords are automatically redacted in logs to prevent credential leakage.

Sources: tests/test_utils.py:101-140, tests/test_security.py:20-60, tests/test_security.py:100-115

Rate Limit Algorithms

The architecture supports multiple algorithms that can be selected per-endpoint:

1. Fixed Window: Divides time into discrete blocks. It is memory-efficient but susceptible to boundary bursts.
2. Token Bucket: Uses a virtual bucket of tokens that refills at a steady rate. This is ideal for smoothing bursty traffic.
3. Sliding Window: Calculates a weighted average of the current and previous windows. This provides the highest accuracy by preventing gaming of window boundaries.

The Sliding Window algorithm combines counts from the current and previous periods to provide a smoother transition than Fixed Window.
Sources: fastlimit/algorithms/sliding_window.py:19-50, README.md:85-135

Integration and Web Layer

Decorator API

The limiter.limit() decorator is the primary interface for developers. It handles the extraction of the Request object from function arguments and orchestrates the rate check.

async def _check_rate_limit(
    limiter: Any,
    request: Any,
    rate: str,
    key_func: Optional[KeyFunc],
    tenant_func: Optional[TenantFunc],
    algorithm: Optional[str],
    cost_func: Optional[CostFunc],
    trust_proxy_headers: bool = False,
) -> None:
    # Logic to extract key, tenant, and cost from request
    # Performs check_with_info to minimize Redis round trips

Sources: fastlimit/decorators.py:164-188

Multi-Tenant Architecture

FastLimit provides native support for multi-tenant applications. By utilizing tenant_type and custom key_func parameters, developers can isolate limits based on API keys, organization IDs, or user tiers.

• Tiered Limits: Different rates can be applied based on the tenant's subscription level (e.g., Free vs. Premium).
• Isolation: Each tenant+tier combination results in a unique key in Redis, ensuring one tenant's usage does not impact another.

Sources: examples/multi_tenant.py:44-55, tests/test_multi_tenant.py:18-40

Monitoring and Observability

The architecture includes an optional metrics layer using Prometheus. When enabled, it tracks the following metrics:

• fastlimit_checks_total: Total number of rate limit checks performed.
• fastlimit_check_duration_seconds: Latency histogram for Redis operations.
• fastlimit_limit_exceeded_total: Count of requests that were throttled.
• fastlimit_backend_operations_total: Total number of Redis commands executed.

Sources: README.md:214-230, CONTRIBUTING.md:120

Conclusion

The FastLimit architecture is centered on high-performance and distributed reliability. By offloading the state management and atomic logic to Redis Lua scripts, it provides a thread-safe and process-safe solution for async Python applications. Its modular design allows for flexible algorithm selection and deep integration into web frameworks via decorators and middleware while maintaining strict security through component-level encoding and identifier hashing.

Sources: README.md:295-310, fastlimit/algorithms/sliding_window.py:10-15