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 debug mode.

Custom Components

The annotation can reference custom implementations registered in the Jetleaf PodFactory or dependency context:

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
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