Introduction
Bucket4j is a Java rate-limiting library based on the token-bucket algorithm. It provides a powerful and flexible way to control the rate of operations in distributed and standalone applications, preventing abuse and ensuring fair resource usage.
Core Concepts
Token Bucket Algorithm
The token bucket algorithm works by:
- Bucket Capacity: Maximum number of tokens the bucket can hold
- Refill Rate: How quickly tokens are replenished
- Tokens: Each operation consumes one or more tokens
- Blocking: Operations wait if insufficient tokens are available
Basic Setup and Dependencies
Maven Dependencies
<dependencies> <!-- Core Bucket4j library --> <dependency> <groupId>com.bucket4j</groupId> <artifactId>bucket4j-core</artifactId> <version>8.10.0</version> </dependency> <!-- For distributed caching --> <dependency> <groupId>com.bucket4j</groupId> <artifactId>bucket4j-jcache</artifactId> <version>8.10.0</version> </dependency> <!-- For Hazelcast backend --> <dependency> <groupId>com.hazelcast</groupId> <artifactId>hazelcast</artifactId> <version>5.3.6</version> </dependency> <!-- For Redis backend --> <dependency> <groupId>io.lettuce</groupId> <artifactId>lettuce-core</artifactId> <version>6.3.1.RELEASE</version> </dependency> </dependencies>
Basic Rate Limiting
Local In-Memory Rate Limiter
public class BasicRateLimiter {
public void demonstrateBasicRateLimiting() {
// Create a bandwidth: 10 tokens, refill 10 tokens every 1 minute
Bandwidth limit = Bandwidth.classic(10, Refill.intervally(10, Duration.ofMinutes(1)));
// Create bucket configuration
BucketConfiguration configuration = BucketConfiguration.builder()
.addLimit(limit)
.build();
// Create bucket
Bucket bucket = Bucket4j.builder()
.addLimit(limit)
.build();
// Usage examples
for (int i = 1; i <= 15; i++) {
if (bucket.tryConsume(1)) {
System.out.println("Request " + i + ": Allowed");
} else {
System.out.println("Request " + i + ": Rate limited");
}
}
}
public void blockingOperations() throws InterruptedException {
Bandwidth limit = Bandwidth.classic(5, Refill.intervally(5, Duration.ofMinutes(1)));
Bucket bucket = Bucket4j.builder().addLimit(limit).build();
// Block until tokens available
CompletableFuture<Boolean> future = bucket.asAsync().tryConsume(1);
boolean consumed = future.get(); // blocks until token available
// Or use blocking API
bucket.asBlocking().consume(1); // blocks until token available
}
}
Advanced Configuration
Multiple Bandwidth Limits
public class AdvancedRateLimiting {
public void multipleBandwidthLimits() {
// Multiple limits: 1000 requests per hour AND 100 requests per minute
Bucket bucket = Bucket4j.builder()
.addLimit(Bandwidth.classic(1000, Refill.intervally(1000, Duration.ofHours(1))))
.addLimit(Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1))))
.build();
// Complex refill strategies
Bandwidth greedyRefill = Bandwidth.classic(10,
Refill.greedy(10, Duration.ofMinutes(1)));
Bandwidth intervallyAligned = Bandwidth.classic(100,
Refill.intervallyAligned(100, Duration.ofHours(1),
Instant.now(), true));
}
public void customBandwidthConfiguration() {
// Bandwidth with custom parameters
Bandwidth limit = Bandwidth.classic(50, Refill.intervally(50, Duration.ofMinutes(1)))
.withInitialTokens(25) // Start with 25 tokens
.withId("api-limit"); // Identifier for the limit
Bucket bucket = Bucket4j.builder()
.addLimit(limit)
.build();
}
}
Spring Boot Integration
Configuration Class
@Configuration
public class RateLimitConfig {
@Bean
public Bucket apiRateLimitBucket() {
Bandwidth limit = Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1)));
return Bucket4j.builder().addLimit(limit).build();
}
@Bean
public Bucket loginRateLimitBucket() {
Bandwidth limit = Bandwidth.classic(5, Refill.intervally(5, Duration.ofMinutes(1)));
return Bucket4j.builder().addLimit(limit).build();
}
@Bean
public Bucket premiumUserBucket() {
Bandwidth premiumLimit = Bandwidth.classic(1000, Refill.intervally(1000, Duration.ofHours(1)));
return Bucket4j.builder().addLimit(premiumLimit).build();
}
}
Rate Limit Service
@Service
public class RateLimitService {
private final Bucket apiRateLimitBucket;
private final Bucket loginRateLimitBucket;
private final Bucket premiumUserBucket;
// Cache for user-specific buckets
private final Cache<String, Bucket> userBuckets = Caffeine.newBuilder()
.expireAfterAccess(Duration.ofHours(1))
.build();
public RateLimitService(Bucket apiRateLimitBucket,
Bucket loginRateLimitBucket,
Bucket premiumUserBucket) {
this.apiRateLimitBucket = apiRateLimitBucket;
this.loginRateLimitBucket = loginRateLimitBucket;
this.premiumUserBucket = premiumUserBucket;
}
public boolean tryApiCall() {
return apiRateLimitBucket.tryConsume(1);
}
public boolean tryLogin(String username) {
return loginRateLimitBucket.tryConsume(1);
}
public boolean tryConsume(String bucketKey, long tokens) {
Bucket bucket = userBuckets.get(bucketKey, this::createUserBucket);
return bucket.tryConsume(tokens);
}
private Bucket createUserBucket(String key) {
Bandwidth limit = Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1)));
return Bucket4j.builder().addLimit(limit).build();
}
public ConsumptionProbe tryConsumeWithDetail(String bucketKey, long tokens) {
Bucket bucket = userBuckets.get(bucketKey, this::createUserBucket);
return bucket.tryConsumeAndReturnRemaining(tokens);
}
public Map<String, Object> getRateLimitInfo(String bucketKey) {
Bucket bucket = userBuckets.getIfPresent(bucketKey);
if (bucket == null) {
return Map.of("available", 0, "waitTime", 0);
}
return Map.of(
"available", bucket.getAvailableTokens(),
"waitTime", bucket.getAvailableTokens() > 0 ? 0 :
bucket.estimateAbilityToConsume(1).getNanosToWait() / 1_000_000_000
);
}
}
Spring Web MVC Integration
Rate Limit Annotation
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RateLimited {
String value() default "global";
long tokens() default 1;
String key() default "";
}
Rate Limit Interceptor
@Component
public class RateLimitInterceptor implements HandlerInterceptor {
private final RateLimitService rateLimitService;
public RateLimitInterceptor(RateLimitService rateLimitService) {
this.rateLimitService = rateLimitService;
}
@Override
public boolean preHandle(HttpServletRequest request,
HttpServletResponse response,
Object handler) throws Exception {
if (handler instanceof HandlerMethod) {
HandlerMethod handlerMethod = (HandlerMethod) handler;
RateLimited rateLimited = handlerMethod.getMethodAnnotation(RateLimited.class);
if (rateLimited != null) {
String bucketKey = resolveBucketKey(request, rateLimited);
long tokens = rateLimited.tokens();
ConsumptionProbe probe = rateLimitService.tryConsumeWithDetail(bucketKey, tokens);
if (!probe.isConsumed()) {
response.setStatus(429); // Too Many Requests
response.setContentType("application/json");
Map<String, Object> error = Map.of(
"error", "Rate limit exceeded",
"message", "Too many requests",
"retryAfter", probe.getNanosToWaitForRefill() / 1_000_000_000,
"availableTokens", probe.getRemainingTokens()
);
response.getWriter().write(new ObjectMapper().writeValueAsString(error));
return false;
}
// Add rate limit headers
addRateLimitHeaders(response, probe);
}
}
return true;
}
private String resolveBucketKey(HttpServletRequest request, RateLimited rateLimited) {
if (!rateLimited.key().isEmpty()) {
return rateLimited.key();
}
// Use IP address as default key
String ipAddress = getClientIpAddress(request);
return rateLimited.value() + ":" + ipAddress;
}
private String getClientIpAddress(HttpServletRequest request) {
String xfHeader = request.getHeader("X-Forwarded-For");
if (xfHeader != null) {
return xfHeader.split(",")[0];
}
return request.getRemoteAddr();
}
private void addRateLimitHeaders(HttpServletResponse response, ConsumptionProbe probe) {
response.setHeader("X-RateLimit-Limit", String.valueOf(probe.getConfiguration().getBandwidths()[0].getCapacity()));
response.setHeader("X-RateLimit-Remaining", String.valueOf(probe.getRemainingTokens()));
response.setHeader("X-RateLimit-Reset", String.valueOf(
System.currentTimeMillis() + probe.getNanosToWaitForRefill() / 1_000_000));
}
}
Controller Usage
@RestController
@RequestMapping("/api")
public class ApiController {
private final RateLimitService rateLimitService;
public ApiController(RateLimitService rateLimitService) {
this.rateLimitService = rateLimitService;
}
@GetMapping("/public/data")
@RateLimited(value = "public-api", tokens = 1)
public ResponseEntity<?> getPublicData() {
return ResponseEntity.ok(Map.of("data", "Public data accessed"));
}
@PostMapping("/auth/login")
@RateLimited(value = "login", tokens = 1)
public ResponseEntity<?> login(@RequestBody LoginRequest request) {
if (rateLimitService.tryLogin(request.getUsername())) {
// Process login
return ResponseEntity.ok(Map.of("status", "Login successful"));
} else {
return ResponseEntity.status(429).body(Map.of("error", "Too many login attempts"));
}
}
@GetMapping("/user/profile")
@RateLimited(value = "user-api", key = "#userId", tokens = 1)
public ResponseEntity<?> getUserProfile(@RequestParam String userId) {
return ResponseEntity.ok(Map.of("profile", "User profile data"));
}
@GetMapping("/premium/data")
@RateLimited(value = "premium-api", tokens = 5)
public ResponseEntity<?> getPremiumData() {
return ResponseEntity.ok(Map.of("data", "Premium data accessed"));
}
}
Distributed Rate Limiting
JCache (JSR-107) Integration
@Configuration
public class DistributedRateLimitConfig {
@Bean
public javax.cache.Cache<String, byte[]> cache() {
CachingProvider cachingProvider = Caching.getCachingProvider();
CacheManager cacheManager = cachingProvider.getCacheManager();
CompleteConfiguration<String, byte[]> config =
new MutableConfiguration<String, byte[]>()
.setTypes(String.class, byte.class);
return cacheManager.createCache("rate-limit-cache", config);
}
@Bean
public ProxyManager<String> proxyManager(javax.cache.Cache<String, byte[]> cache) {
return new JCacheProxyManager<>(cache);
}
@Bean
public Bucket userBucket(ProxyManager<String> proxyManager) {
Bandwidth limit = Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1)));
BucketConfiguration configuration = BucketConfiguration.builder()
.addLimit(limit)
.build();
return proxyManager.builder().build("user-bucket", configuration);
}
}
Hazelcast Backend
@Configuration
public class HazelcastConfig {
@Bean
public HazelcastInstance hazelcastInstance() {
Config config = new Config();
config.setClusterName("rate-limit-cluster");
// Configure map for rate limiting
MapConfig mapConfig = new MapConfig();
mapConfig.setName("rate-limit-buckets");
mapConfig.setTimeToLiveSeconds(3600);
config.addMapConfig(mapConfig);
return Hazelcast.newHazelcastInstance(config);
}
@Bean
public ProxyManager<String> hazelcastProxyManager(HazelcastInstance hazelcastInstance) {
return new HazelcastProxyManager<>(hazelcastInstance);
}
}
Redis Backend
@Configuration
public class RedisRateLimitConfig {
@Bean
public RedisClient redisClient() {
return RedisClient.create("redis://localhost:6379");
}
@Bean
public ProxyManager<String> redisProxyManager(RedisClient redisClient) {
return new RedisProxyManager<>(redisClient);
}
@Bean
public BucketConfiguration globalBucketConfig() {
return BucketConfiguration.builder()
.addLimit(Bandwidth.classic(1000, Refill.intervally(1000, Duration.ofHours(1))))
.addLimit(Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1))))
.build();
}
}
Advanced Use Cases
Tiered Rate Limiting
@Service
public class TieredRateLimitService {
private final Map<String, BucketConfiguration> tierConfigs;
private final ProxyManager<String> proxyManager;
public TieredRateLimitService(ProxyManager<String> proxyManager) {
this.proxyManager = proxyManager;
this.tierConfigs = createTierConfigurations();
}
private Map<String, BucketConfiguration> createTierConfigurations() {
Map<String, BucketConfiguration> configs = new HashMap<>();
// Free tier
configs.put("free", BucketConfiguration.builder()
.addLimit(Bandwidth.classic(100, Refill.intervally(100, Duration.ofHours(1))))
.build());
// Basic tier
configs.put("basic", BucketConfiguration.builder()
.addLimit(Bandwidth.classic(1000, Refill.intervally(1000, Duration.ofHours(1))))
.build());
// Premium tier
configs.put("premium", BucketConfiguration.builder()
.addLimit(Bandwidth.classic(10000, Refill.intervally(10000, Duration.ofHours(1))))
.build());
return configs;
}
public boolean tryConsume(String userId, String tier, long tokens) {
BucketConfiguration config = tierConfigs.getOrDefault(tier, tierConfigs.get("free"));
Bucket bucket = proxyManager.builder().build(userId, config);
return bucket.tryConsume(tokens);
}
public ConsumptionProbe tryConsumeWithDetail(String userId, String tier, long tokens) {
BucketConfiguration config = tierConfigs.getOrDefault(tier, tierConfigs.get("free"));
Bucket bucket = proxyManager.builder().build(userId, config);
return bucket.tryConsumeAndReturnRemaining(tokens);
}
}
Adaptive Rate Limiting
@Service
public class AdaptiveRateLimitService {
private final Map<String, Bucket> dynamicBuckets = new ConcurrentHashMap<>();
private final ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(1);
@PostConstruct
public void init() {
// Clean up expired buckets every hour
scheduler.scheduleAtFixedRate(this::cleanupExpiredBuckets, 1, 1, TimeUnit.HOURS);
}
public boolean tryConsumeAdaptive(String key, long baseRate, double loadFactor) {
Bucket bucket = dynamicBuckets.computeIfAbsent(key, k ->
createAdaptiveBucket(baseRate, loadFactor));
return bucket.tryConsume(1);
}
private Bucket createAdaptiveBucket(long baseRate, double loadFactor) {
// Adjust rate based on system load
long adjustedRate = (long) (baseRate / loadFactor);
adjustedRate = Math.max(adjustedRate, 10); // Minimum rate
Bandwidth limit = Bandwidth.classic(adjustedRate,
Refill.intervally(adjustedRate, Duration.ofMinutes(1)));
return Bucket4j.builder().addLimit(limit).build();
}
public void updateRateLimit(String key, long newRate) {
dynamicBuckets.computeIfPresent(key, (k, bucket) -> {
Bandwidth newLimit = Bandwidth.classic(newRate,
Refill.intervally(newRate, Duration.ofMinutes(1)));
return Bucket4j.builder().addLimit(newLimit).build();
});
}
private void cleanupExpiredBuckets() {
long cutoff = System.currentTimeMillis() - Duration.ofHours(24).toMillis();
// Implement cleanup logic based on last access time
}
@PreDestroy
public void shutdown() {
scheduler.shutdown();
}
}
Monitoring and Metrics
Rate Limit Metrics
@Component
public class RateLimitMetrics {
private final MeterRegistry meterRegistry;
private final Counter allowedRequests;
private final Counter limitedRequests;
private final DistributionSummary waitTimeSummary;
public RateLimitMetrics(MeterRegistry meterRegistry) {
this.meterRegistry = meterRegistry;
this.allowedRequests = Counter.builder("rate_limit.requests")
.tag("status", "allowed")
.register(meterRegistry);
this.limitedRequests = Counter.builder("rate_limit.requests")
.tag("status", "limited")
.register(meterRegistry);
this.waitTimeSummary = DistributionSummary.builder("rate_limit.wait_time")
.register(meterRegistry);
}
public void recordRequest(boolean allowed, long waitTimeNanos) {
if (allowed) {
allowedRequests.increment();
} else {
limitedRequests.increment();
}
if (waitTimeNanos > 0) {
waitTimeSummary.record(waitTimeNanos / 1_000_000.0); // Convert to milliseconds
}
}
public void recordBucketState(String bucketKey, long availableTokens, long capacity) {
Gauge.builder("rate_limit.available_tokens", () -> availableTokens)
.tag("bucket", bucketKey)
.register(meterRegistry);
Gauge.builder("rate_limit.capacity", () -> capacity)
.tag("bucket", bucketKey)
.register(meterRegistry);
}
}
Rate Limit Manager
@Service
public class RateLimitManager {
private final RateLimitMetrics metrics;
private final ProxyManager<String> proxyManager;
private final Map<String, BucketConfiguration> configurations;
public RateLimitManager(RateLimitMetrics metrics, ProxyManager<String> proxyManager) {
this.metrics = metrics;
this.proxyManager = proxyManager;
this.configurations = loadConfigurations();
}
public RateLimitResult tryConsume(String bucketKey, String configName, long tokens) {
BucketConfiguration config = configurations.get(configName);
if (config == null) {
return new RateLimitResult(true, 0, 0, 0);
}
Bucket bucket = proxyManager.builder().build(bucketKey, config);
ConsumptionProbe probe = bucket.tryConsumeAndReturnRemaining(tokens);
// Record metrics
metrics.recordRequest(probe.isConsumed(), probe.getNanosToWaitForRefill());
metrics.recordBucketState(bucketKey, probe.getRemainingTokens(),
config.getBandwidths()[0].getCapacity());
return new RateLimitResult(
probe.isConsumed(),
probe.getRemainingTokens(),
probe.getNanosToWaitForRefill(),
config.getBandwidths()[0].getCapacity()
);
}
public void updateConfiguration(String configName, BucketConfiguration newConfig) {
configurations.put(configName, newConfig);
}
public Map<String, Object> getBucketStats(String bucketKey, String configName) {
BucketConfiguration config = configurations.get(configName);
if (config == null) {
return Map.of();
}
Bucket bucket = proxyManager.builder().build(bucketKey, config);
long availableTokens = bucket.getAvailableTokens();
return Map.of(
"availableTokens", availableTokens,
"capacity", config.getBandwidths()[0].getCapacity(),
"config", configName
);
}
private Map<String, BucketConfiguration> loadConfigurations() {
Map<String, BucketConfiguration> configs = new HashMap<>();
// Load from database or configuration file
configs.put("api-global", BucketConfiguration.builder()
.addLimit(Bandwidth.classic(1000, Refill.intervally(1000, Duration.ofHours(1))))
.build());
configs.put("api-user", BucketConfiguration.builder()
.addLimit(Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1))))
.build());
return configs;
}
public static class RateLimitResult {
private final boolean allowed;
private final long remainingTokens;
private final long waitTimeNanos;
private final long capacity;
public RateLimitResult(boolean allowed, long remainingTokens,
long waitTimeNanos, long capacity) {
this.allowed = allowed;
this.remainingTokens = remainingTokens;
this.waitTimeNanos = waitTimeNanos;
this.capacity = capacity;
}
// Getters
public boolean isAllowed() { return allowed; }
public long getRemainingTokens() { return remainingTokens; }
public long getWaitTimeNanos() { return waitTimeNanos; }
public long getCapacity() { return capacity; }
}
}
Testing Rate Limiting
Unit Tests
@ExtendWith(MockitoExtension.class)
class RateLimitServiceTest {
@InjectMocks
private RateLimitService rateLimitService;
private Bucket bucket;
@BeforeEach
void setUp() {
Bandwidth limit = Bandwidth.classic(5, Refill.intervally(5, Duration.ofMinutes(1)));
bucket = Bucket4j.builder().addLimit(limit).build();
}
@Test
void testRateLimitAllowsWithinLimit() {
for (int i = 0; i < 5; i++) {
assertTrue(bucket.tryConsume(1), "Request " + (i + 1) + " should be allowed");
}
}
@Test
void testRateLimitBlocksBeyondLimit() {
// Consume all tokens
for (int i = 0; i < 5; i++) {
bucket.tryConsume(1);
}
// Next request should be blocked
assertFalse(bucket.tryConsume(1), "Request beyond limit should be blocked");
}
@Test
void testConsumptionProbe() {
ConsumptionProbe probe = bucket.tryConsumeAndReturnRemaining(1);
assertTrue(probe.isConsumed());
assertEquals(4, probe.getRemainingTokens());
}
}
@SpringBootTest
class RateLimitIntegrationTest {
@Autowired
private RateLimitService rateLimitService;
@Test
void testDistributedRateLimiting() {
String user1 = "user1";
String user2 = "user2";
// User1 consumes tokens
for (int i = 0; i < 5; i++) {
assertTrue(rateLimitService.tryConsume(user1, 1));
}
// User1 should be limited
assertFalse(rateLimitService.tryConsume(user1, 1));
// User2 should still have tokens
assertTrue(rateLimitService.tryConsume(user2, 1));
}
}
Best Practices
Production Configuration
@Configuration
public class ProductionRateLimitConfig {
@Bean
@Primary
public ProxyManager<String> proxyManager(RedisClient redisClient) {
return new RedisProxyManager<>(redisClient);
}
@Bean
public BucketConfiguration apiGlobalConfig() {
return BucketConfiguration.builder()
.addLimit(Bandwidth.classic(10000, Refill.intervally(10000, Duration.ofHours(1))))
.addLimit(Bandwidth.classic(1000, Refill.intervally(1000, Duration.ofMinutes(1))))
.build();
}
@Bean
public BucketConfiguration apiUserConfig() {
return BucketConfiguration.builder()
.addLimit(Bandwidth.classic(1000, Refill.intervally(1000, Duration.ofHours(1))))
.addLimit(Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1))))
.build();
}
@Bean
public BucketConfiguration loginConfig() {
return BucketConfiguration.builder()
.addLimit(Bandwidth.classic(5, Refill.intervally(5, Duration.ofMinutes(1))))
.build();
}
}
// Configuration properties
@ConfigurationProperties(prefix = "rate-limiting")
@Data
public class RateLimitProperties {
private Map<String, RateLimitConfig> configurations = new HashMap<>();
@Data
public static class RateLimitConfig {
private long capacity;
private Duration period;
private long initialTokens;
}
}
Conclusion
Bucket4j provides a robust and flexible rate-limiting solution for Java applications. Key benefits include:
- Multiple algorithms: Token bucket, leaky bucket support
- Distributed support: Redis, Hazelcast, JCache backends
- Flexible configuration: Multiple bandwidth limits, custom refill strategies
- Spring integration: Easy integration with Spring Boot applications
- Monitoring: Comprehensive metrics and monitoring support
- Performance: High-performance implementation suitable for production use
By implementing rate limiting with Bucket4j, you can protect your APIs from abuse, ensure fair usage, and maintain system stability under high load conditions.