RateLimitStorage class abstract interface

The RateLimitStorage interface defines the abstraction for JetLeaf’s rate-limiting persistence and quota tracking mechanism.

Implementations are responsible for managing request counts, evaluating quota conditions, and tracking reset windows across potentially distributed systems. A RateLimitStorage can be in-memory, cache-backed, or fully distributed depending on the system configuration.

Purpose

The rate-limit storage forms the foundation of JetLeaf’s traffic-control subsystem. It is queried by RateLimiter and orchestrated by RateLimitManager to ensure consistent and predictable throttling behavior across pods, environments, and profiles.

Responsibilities

  • Persist request counters within defined time windows
  • Enforce rate limits for unique requesters (e.g., users, clients, IPs)
  • Report usage metrics, remaining quota, and reset times
  • Support safe concurrent updates in multi-threaded or multi-instance systems

Typical Implementations

Implementation Description Use Case
InMemoryRateLimitStorage Uses in-memory maps Local testing, lightweight pods
RedisRateLimitStorage Uses Redis INCR/EXPIRE Distributed deployments
DatabaseRateLimitStorage Uses SQL counters Persistent tracking or audits
  • RateLimiter: Consumes this interface to decide if a request is allowed.
  • RateLimitManager: Manages multiple storages with ordered precedence.
  • CacheStorage: Can serve as the base persistence layer.
Implementers

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

clear() → FutureOr<void>
Clears all rate-limit tracking data across all identifiers.
equalizedProperties() → List<Object?>
Mixin-style contract for value-based equality, hashCode, and toString.
inherited
getMetrics() → RateLimitMetrics
Returns the metrics associated with this rate limit storage.
getName() → String
Returns the canonical name of this RateLimitStorage instance.
getRemainingRequests(Object identifier, int limit, Duration window) → FutureOr<int>
Calculates how many requests remain before the rate limit is reached.
getRequestCount(Object identifier, Duration window) → FutureOr<int>
Retrieves the current number of requests recorded for the given identifier.
getResetTime(Object identifier, Duration window) → FutureOr<DateTime?>
Returns the timestamp when the rate-limit window will reset for a given identifier.
getResource() → Resource<Object, RateLimitEntry>
Returns the underlying native rate-limit provider object.
getRetryAfter(Object identifier, Duration window) → FutureOr<ZonedDateTime?>
Calculates and returns the remaining duration before the current rate limit window resets for the given identifier.
invalidate() → FutureOr<void>
Invalidates the current rate-limit storage and cleans up its resources.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
recordRequest(Object identifier, Duration window) → FutureOr<void>
Records a successful request for the given identifier.
reset(Object identifier) → FutureOr<void>
Resets the rate-limit state for a specific identifier.
toString() → String
A string representation of this object.
inherited
tryConsume(Object identifier, int limit, Duration window) → FutureOr<RateLimitResult>
Determines whether a request is permitted under the defined rate limit.

Operators

operator ==(Object other) → bool
The equality operator.
inherited