rate-limiter

Coroutine-native rate limiting with token bucket, sliding window, and fixed window algorithms.

Installation

Gradle (Kotlin DSL)

implementation("com.philiprehberger:rate-limiter:0.1.6")

Maven

<dependency>
    <groupId>com.philiprehberger</groupId>
    <artifactId>rate-limiter</artifactId>
    <version>0.1.6</version>
</dependency>

Usage

Token Bucket

import com.philiprehberger.ratelimiter.*
import kotlin.time.Duration.Companion.seconds

val limiter = TokenBucket(rate = 10, interval = 1.seconds, burst = 20)

if (limiter.tryAcquire()) {
    processRequest()
}

// Or suspend until a permit is available
limiter.acquire()
processRequest()

Sliding Window

val limiter = SlidingWindow(limit = 100, window = 60.seconds)

if (limiter.tryAcquire()) {
    handleRequest()
}

Fixed Window

val limiter = FixedWindow(limit = 1000, window = 60.seconds)

if (limiter.tryAcquire()) {
    handleRequest()
}

Per-Key Rate Limiting

val perUser = KeyedRateLimiter<String> {
    TokenBucket(rate = 10, interval = 1.seconds, burst = 20)
}

if (perUser.tryAcquire(userId)) {
    handleRequest(userId)
}

Rate Limit Info

val info = limiter.info()
println("Remaining: ${info.remaining}/${info.limit}")
println("Resets at: ${info.resetsAt}")

API

Class / Function	Description
RateLimiter	Interface with tryAcquire(), acquire(), and info()
TokenBucket	Token bucket algorithm with configurable rate, interval, and burst
SlidingWindow	Sliding window counter using timestamp deque
FixedWindow	Fixed window counter that resets at boundaries
KeyedRateLimiter<K>	Per-key rate limiting with independent limiter instances
RateLimitInfo	Data class with remaining permits, limit, and reset time

Development

./gradlew test       # Run tests
./gradlew check      # Run all checks
./gradlew build      # Build JAR

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT