RateLimit class final
Annotation that marks a method to be subject to rate limiting.
The RateLimit annotation defines declarative, fine-grained rate limiting rules on a specific method. When applied, Jetleaf automatically enforces the defined limit of allowed requests per window duration based on the configured RateLimitStorage and optional conditions.
Core Behavior
- Applies rate limiting per unique request identifier (e.g., user, IP, or key).
- Integrates with RateLimitStorage implementations to persist counters.
- Can be dynamically enabled/disabled via condition and unless clauses.
- Allows runtime customization via custom manager or resolver names.
Example
class UserController {
@RateLimit(
{'userLimitStorage'},
limit: 100,
window: Duration(minutes: 1),
)
Future<Response> getProfile(Request request) async {
// This method can be called 100 times per minute per user.
return Response.ok(await _userService.getProfile(request.userId));
}
}
Conditional Rate Limiting
You can use condition and unless to enable or disable rate limiting dynamically based on runtime context:
@RateLimit(
{'apiStorage'},
limit: 50,
window: Duration(seconds: 30),
condition: WhenEnvironmentPropertyEquals('api.enabled', 'true'),
unless: WhenEnvironmentPropertyEquals('mode', 'debug'),
)
In this example:
- Rate limiting is only active if
api.enabled == 'true'. - It is skipped entirely when running in
debugmode.
Custom Components
The annotation can reference custom implementations registered in
the Jetleaf PodFactory or dependency context:
- keyGenerator: Custom implementation of KeyGenerator.
- rateLimitManager: Custom RateLimitManager controlling storage.
- rateLimitResolver: Custom RateLimitResolver deciding storages.
Example:
@RateLimit(
{'defaultStorage'},
limit: 200,
window: Duration(minutes: 5),
keyGenerator: 'customUserKeyGenerator',
rateLimitManager: 'centralRateManager',
)
Parameters
| Parameter | Description | Default |
|---|---|---|
storageNames |
Names of RateLimitStorages to use. | — |
limit |
Maximum number of allowed requests per window. | — |
window |
The time frame for the rate limit window. | — |
condition |
A ResourceCondition that must match for rate limiting to apply. | WhenAlways |
unless |
A ResourceCondition that disables rate limiting if true. | WhenNever |
keyGenerator |
Optional name of a custom KeyGenerator. | null |
rateLimitManager |
Optional name of a custom RateLimitManager. | null |
rateLimitResolver |
Optional name of a custom RateLimitResolver. | null |
Related Components
- RateLimitManager – Manages all RateLimitStorages and lifecycle.
- RateLimitStorage – Persists request counters and timestamps.
- RateLimitResolver – Determines which storages apply to a given method.
RateLimitErrorHandler– Handles rate limit exceptions or I/O errors.- ResourceCondition – Controls conditional activation of the annotation.
- Annotations
-
- @Target.new({TargetKind.method})
Constructors
-
RateLimit(Set<
String> storageNames, {required int limit, required Duration window, ResourceCondition condition = const WhenAlways(), ResourceCondition unless = const WhenNever(), String? keyGenerator, String? rateLimitManager, String? rateLimitResolver}) -
Creates a new RateLimit annotation defining rate limiting behavior.
const
Properties
- annotationType → Type
-
Returns the annotation _type of this annotation.
no setter
- condition → ResourceCondition
-
The activation condition for the rate limit.
final
- hashCode → int
-
Returns a hash code consistent with equality definition.
no setterinherited
- keyGenerator → String?
-
The optional name of a custom KeyGenerator pod.
final
- limit → int
-
The maximum number of requests allowed within the configured window.
final
- rateLimitManager → String?
-
The optional name of a custom RateLimitManager.
final
- rateLimitResolver → String?
-
The optional name of a custom RateLimitResolver.
final
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
-
storageNames
→ Set<
String> -
The names of the RateLimitStorage instances to use for this operation.
final
- unless → ResourceCondition
-
The disabling condition for the rate limit.
final
- window → Duration
-
The duration representing the rate limit window.
final
Methods
-
equals(
Object other) → bool -
Checks whether the given object is logically equivalent to this annotation.
inherited
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
toString(
) → String -
Returns a string representation of this annotation.
inherited
Operators
-
operator ==(
Object other) → bool -
Checks if this annotation is equal to another object.
inherited