RateLimitEntry class abstract interface

Represents a single tracked rate limit record within a RateLimitStorage.

A RateLimitEntry encapsulates the state of a rate-limited identifier (such as a user ID, IP address, or client token) within a specific rate limit window. It tracks request counts, timestamps, and window keys used to group and identify rate-limited entities.

Overview

Each RateLimitEntry is uniquely associated with a rate limit “window,” identified by getWindowKey. Within this window, it keeps track of:

  • Request Count – how many requests have been made (getCount)
  • Timestamps – when the entry was created (getTimeStamp)
  • Reset Time – when the window will expire (getResetTime)

Once the reset time is reached or the window is deemed expired (isExpired), the entry can be cleared or reinitialized via reset.

Typical Lifecycle

  1. Creation: The RateLimitStorage creates a new entry for a new identifier (e.g., "user:123") when the first request occurs.
  2. Tracking: Each incoming request increments the internal count.
  3. Expiration Check: The system periodically checks whether the entry has expired using isExpired.
  4. Reset: When expired, the counter resets, timestamps are refreshed, and the new window begins.

Example

final entry = DefaultRateLimitEntry(
  windowKey: 'user:123|60s',
  count: 10,
  timeStamp: ZonedDateTime.now(),
  resetTime: ZonedDateTime.now().plusSeconds(60),
);

if (entry.isExpired()) {
  entry.reset();
} else {
  print('Remaining time: ${entry.getResetTime().difference(ZonedDateTime.now())}');
}

Integration

Thread Safety

Implementations must be concurrency-safe in multi-threaded or asynchronous environments to prevent inconsistent state.

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

decrement() → int
Decrements the current request count by one, if possible, and returns the updated count.
getCount() → int
Returns the current request count within the active rate limit window.
getResetTime() → ZonedDateTime
Returns the exact time when the rate limit window will reset.
getRetryAfter() → ZonedDateTime
Calculates and returns the remaining duration before the current rate limit window resets for the given identifier.
getTimeStamp() → ZonedDateTime
Returns the timestamp when this rate limit entry was created or last updated.
getWindowDuration() → Duration
Returns the configured rate limit window for this storage.
getWindowKey() → String
Returns a unique key representing this rate limit window.
increment() → void
Increments the tracked request count by one.
isExpired() → bool
Determines whether the rate limit entry has expired.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
reset() → void
Resets the rate limit entry to the initial state for a new window.
secondsUntilReset() → int
Returns the remaining number of whole seconds before the current rate limit window resets.
toString() → String
A string representation of this object.
inherited

Operators

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