Main RateLimiter Interface

Relevant source files

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

• fastlimit/limiter.py
• fastlimit/init.py
• fastlimit/algorithms/sliding_window.py
• README.md
• examples/fastapi_app.py
• examples/multi_tenant.py
• benchmarks/performance.py

The RateLimiter class is the primary interface of the FastLimit library. It provides a high-performance, async-first gateway for managing rate limits using a Redis backend. The interface is designed to be versatile, supporting manual checks, decorator-based application for web frameworks like FastAPI, and administrative tasks such as usage monitoring and limit resets.

Sources: fastlimit/limiter.py:20-41, README.md:14-22

Core Initialization and Lifecycle

The RateLimiter is initialized with configuration parameters that define its connection to Redis and its default behavior. It supports asynchronous context management (async with) to ensure connections are established and closed gracefully.

Configuration Parameters

Parameter	Type	Default	Description
redis_url	str	"redis://localhost:6379"	Connection URL for the Redis instance.
key_prefix	str	"ratelimit"	Prefix applied to all keys stored in Redis.
default_algorithm	str	"fixed_window"	Fallback algorithm (fixed_window, token_bucket, or sliding_window).
enable_metrics	bool	False	Toggles Prometheus metrics collection.

Sources: fastlimit/limiter.py:43-69, README.md:141-152

Lifecycle Management

The class utilizes an internal asyncio.Lock to ensure that connection and disconnection operations are thread-safe and idempotent.

The diagram shows the lifecycle of the RateLimiter from initialization through secure connection handling to termination.
Sources: fastlimit/limiter.py:77-109

Rate Limiting Operations

The interface provides two primary ways to check limits: check() for a boolean response and check_with_info() for detailed metadata.

Check Mechanisms

• check(): Returns True if the request is allowed, or raises a RateLimitExceeded exception if the limit is hit.
• check_with_info(): Returns a CheckResult object containing allowed, remaining, retry_after, and window_seconds. This is more efficient as it avoids multiple Redis calls when metadata is needed for headers.

Sources: fastlimit/limiter.py:111-205, CHANGELOG.md:46-47

Supported Algorithms

The interface routes requests to specific backend implementations based on the chosen algorithm:

Algorithm	Logical Implementation	Characteristics
fixed_window	Counter-based windows (e.g., 14:00-14:01)	Simple, low memory, but allows boundary bursts.
token_bucket	Refilling bucket of tokens	Smooth traffic flow, prevents boundary bursts.
sliding_window	Weighted average of current and previous window	Most accurate, prevents gaming of window edges.

Sources: fastlimit/limiter.py:207-254, README.md:92-132, fastlimit/algorithms/sliding_window.py:18-50

Decorator and Integration

The @limiter.limit() decorator is the most common integration pattern, particularly for FastAPI applications. It allows declarative rate limiting on a per-endpoint basis.

Decorator Usage Logic

The decorator can extract keys dynamically from the request object (e.g., IP address, user ID from path params, or API keys from headers).

This sequence illustrates how the decorator intercepts incoming requests to validate them against the configured Redis-backed limits before allowing access to the application logic.
Sources: fastlimit/limiter.py:279-325, examples/fastapi_app.py:102-140

Administrative and Monitoring Tools

The interface exposes methods to inspect and modify rate limit states manually.

Usage and Resets

• get_usage(): Provides a snapshot of the current state for a specific key/rate combination. The returned dictionary includes algorithm-specific fields, such as weight for sliding windows or tokens for token buckets.
• reset(): Manually clears the rate limit for a key. It can target a specific algorithm or use algorithm="all" to wipe all rate-limiting data associated with the identifier.
• health_check(): Validates the connectivity to the Redis backend.

Sources: fastlimit/limiter.py:330-410, fastlimit/limiter.py:440-475, fastlimit/algorithms/sliding_window.py:145-188

Precision and Cost

The interface implements Integer Precision by multiplying values by 1000 before passing them to Redis. This allows the system to handle sub-unit logic (like token refills) using high-speed integer math rather than floating-point arithmetic. Additionally, every check supports a cost parameter, allowing expensive operations to consume more of the quota than standard requests.

Sources: fastlimit/limiter.py:203-204, README.md:28, examples/fastapi_app.py:175-195

Conclusion

The RateLimiter interface serves as the central hub of the FastLimit library, abstracting complex Redis Lua scripts and algorithm logic into a developer-friendly API. Its support for multiple algorithms, dynamic cost calculation, and multi-tenant key extraction makes it suitable for both simple IP-based throttling and complex SaaS tiered limiting.

Sources: fastlimit/limiter.py:20-30, README.md:6-12