Package org.apache.juneau.rest.server.guard

Interface RateLimitGuard.Storage

Enclosing class:

RateLimitGuard

public static interface RateLimitGuard.Storage

SPI for storing per-key token-bucket state.

Implementations must be thread-safe. The default inMemory() implementation is suitable for single-pod deployments. Multi-pod deployments that share a single rate envelope should substitute a distributed backend.

Since:

10.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final record	RateLimitGuard.Storage.AcquireResult	Outcome of a tryAcquire attempt.

Method Summary

Modifier and Type	Method	Description
void	evict(Duration ttl)	Evicts buckets idle for longer than the given TTL.
static RateLimitGuard.Storage	inMemory()	Creates a new in-memory storage backend with the default size cap (100 000 keys).
static RateLimitGuard.Storage	inMemory(int maxKeys)	Creates a new in-memory storage backend with a custom size cap.
default Map<String,RateLimitGuard.BucketState>	snapshot()	Returns a point-in-time view of every per-key bucket currently held by this storage backend.
RateLimitGuard.Storage.AcquireResult	tryAcquire(String key, int capacity, double permitsPerSecond)	Attempts to acquire one token from the bucket associated with the given key.

Method Details

tryAcquire

RateLimitGuard.Storage.AcquireResult tryAcquire(String key,
 int capacity,
 double permitsPerSecond)

Attempts to acquire one token from the bucket associated with the given key.

Parameters:

key - The bucket key. Never null.

capacity - The maximum tokens the bucket can hold.

permitsPerSecond - The steady-state refill rate.

Returns:

The outcome of the attempt. Never null.

evict

void evict(Duration ttl)

Evicts buckets idle for longer than the given TTL.

The default inMemory() implementation evicts opportunistically when its size cap is exceeded; call this method to force an eager sweep (typically from a scheduled task).

Parameters:

ttl - The idle threshold. Buckets last touched longer than ttl ago are removed.

snapshot

default Map<String,RateLimitGuard.BucketState> snapshot()

Returns a point-in-time view of every per-key bucket currently held by this storage backend.

Optional operation for operational visibility. The default implementation returns an empty map so that external storage backends (Redis, DynamoDB, etc.) that can't cheaply enumerate every bucket stay backwards-compatible without code changes. In-memory implementations SHOULD override this to expose live bucket state — see the bundled inMemory() implementation, which walks its internal map and returns one RateLimitGuard.BucketState per entry.

The returned map is a snapshot, not a live view — concurrent modifications to the underlying storage after this method returns are not reflected. Per-bucket reads are individually consistent (the in-memory implementation reads each bucket under its own monitor), but the snapshot as a whole is not a global point-in-time consistent view.

Cardinality warning: on storages that hold many buckets (the bundled in-memory storage caps at 100 000 keys by default) the returned map can be large. Operator-facing callers should either filter client-side or use a paginated alternative if one is offered by the backend.

Returns:

A point-in-time map of per-key bucket state, keyed by per-request key. Never null.

Since:

10.0.0

inMemory

static RateLimitGuard.Storage inMemory()

Creates a new in-memory storage backend with the default size cap (100 000 keys).

Returns:

A new in-memory storage backend.

inMemory

static RateLimitGuard.Storage inMemory(int maxKeys)

Creates a new in-memory storage backend with a custom size cap.

Parameters:

maxKeys - The maximum number of keys held before LRU-style eviction kicks in. Must be > 0.

Returns:

A new in-memory storage backend.