Configuration

Configuration

BucketGuard uses immutable specification objects to define behavior. This design ensures that rate limiters are safe to share and difficult to misuse.

TokenBucketSpec

TokenBucketSpec defines the rules for token generation and consumption.

TokenBucketSpec spec = TokenBucketSpec.builder()
    .capacity(50)
    .refillTokens(10)
    .refillPeriod(Duration.ofSeconds(1))
    .allowBurst(true)
    .strictMath(true)
    .build();

Field	Description	Default
capacity	Maximum (full) capacity of the bucket. A bucket can never hold more tokens than this.	Required
refillTokens	Number of tokens added to the bucket every period.	Required
refillPeriod	The frequency at which tokens are added.	Required
allowBurst	If true, the bucket can accumulate tokens up to capacity during idle time. If false, the bucket throttles strictly to the refill rate (tokens exceeding 1 are unavailable).	true
strictMath	If true, enables Math.*Exact checking to throw ArithmeticException on overflow. Recommended for critical financial or security applications.	false
contentionStrategy	Defines how the bucket handles concurrent access.	ATOMIC

Contention Strategies

• ATOMIC: Uses a single CAS-based bucket. Best for most use cases.
• STRIPED: Partitions the capacity across multiple buckets. Use this for extremely high-concurrency environments where CAS failures become a bottleneck.

KeyedStoreSpec

KeyedStoreSpec defines how a KeyedRateLimiter manages its internal map of buckets.

KeyedStoreSpec<String> storeSpec = KeyedStoreSpec.<String>builder()
    .maxKeys(10000)
    .evictionPolicy(EvictionPolicy.EXPIRE_AFTER_ACCESS)
    .expireAfterAccess(Duration.ofMinutes(15))
    .build();

Field	Description	Default
maxKeys	The maximum number of keys (buckets) to store. Required for LRU policy.	-1 (Unbounded)
evictionPolicy	Strategy for removing keys.	NONE
expireAfterAccess	Duration after which an idle key becomes eligible for eviction.	null
removalListener	Callback invoked when a key is evicted.	null
maintenanceEnabled	If true, enables integration with startMaintenance().	false

Eviction Policies

• NONE: Keeps all keys forever. Fastest, but risky for unbounded key sets (e.g., user IDs).
• LRU: Keeps the most recently used keys, up to maxKeys.
• EXPIRE_AFTER_ACCESS: Removes keys that haven't been accessed for the specified duration.