Interface RateLimitStore

All Known Implementing Classes:
InMemoryRateLimitStore
@ExperimentalJSentinelApi public interface RateLimitStore
Persistent event store for sliding-window rate-limiting policies (V00.70 Phase 7c).

The store is intentionally event-based rather than a counter + window-start pair: a RateLimitStore records one timestamp per event, and the policy decides how to interpret that stream — a fixed window, a sliding window, a leaky bucket, or a token bucket are all expressible on top of the same primitives.

Lifecycle:

  1. recordEvent(RateLimitKey, Instant) appends one timestamp.
  2. countSince(RateLimitKey, Instant) returns how many events the key holds at or after the cutoff — the policy picks cutoff = now - window.
  3. reset(RateLimitKey) drops everything under a key (typically called on a successful authentication that cancels the throttle).
  4. purgeOlderThan(Instant) is the retention sweep — runs on a schedule, drops events the policy would no longer count anyway.

Implementations must be thread-safe; concurrent recordEvent and countSince happen on every protected endpoint.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    countSince(RateLimitKey key, Instant since)
    Returns the number of events under key whose timestamp is at or after since.
    int
    purgeOlderThan(Instant cutoff)
    Across every key, drops events whose timestamp is strictly before cutoff.
    void
    recordEvent(RateLimitKey key, Instant at)
    Appends one event timestamp under key.
    void
    reset(RateLimitKey key)
    Drops every recorded event under key.

  • Method Details

    • recordEvent

      void recordEvent(RateLimitKey key, Instant at)
      Appends one event timestamp under key.
      Parameters:
      key - key the event belongs to; must not be null
      at - event instant; must not be null

    • countSince

      int countSince(RateLimitKey key, Instant since)
      Returns the number of events under key whose timestamp is at or after since.
      Parameters:
      key - key to query; must not be null
      since - inclusive lower bound; events at exactly this instant count; must not be null
      Returns:
      non-negative event count

    • reset

      void reset(RateLimitKey key)
      Drops every recorded event under key.
      Parameters:
      key - key to clear; must not be null

    • purgeOlderThan

      int purgeOlderThan(Instant cutoff)
      Across every key, drops events whose timestamp is strictly before cutoff. Intended as a retention sweep.
      Parameters:
      cutoff - retention boundary; must not be null
      Returns:
      number of events purged