Java rate limiting library based on token-bucket algorithm.
The Bucket4j is distributed through Maven Central:
<!-- For java 11+ -->
<dependency>
<groupId>com.bucket4j</groupId>
<artifactId>bucket4j-core</artifactId>
<version>8.10.1</version>
</dependency>
<!-- For java 8 -->
<dependency>
<groupId>com.bucket4j</groupId>
<artifactId>bucket4j_jdk8-core</artifactId>
<version>8.10.1</version>
</dependency>
import io.github.bucket4j.Bucket;
...
// bucket with capacity 20 tokens and with refilling speed 1 token per each 6 second
private static Bucket bucket = Bucket.builder()
.addLimit(limit -> limit.capacity(20).refillGreedy(10, Duration.ofMinutes(1)))
.build();
private void doSomethingProtected() {
if (bucket.tryConsume(1)) {
doSomething();
} else {
throw new SomeRateLimitingException();
}
}
More examples can be found there
Bucket4j is not a framework, it is a library, with Bucket4j you need to write a code to achive your goals. For generic use-cases, try to look at powerfull Spring Boot Starter for Bucket4j, that allows you to set access limits on your API effortlessly. Its key advantage lies in the configuration via properties or yaml files, eliminating the need for manual code authoring.
In additional to basic features described above, Bucket4j
provides ability to implement rate-limiting in cluster of JVMs:
In addition to local in-memory buckets, the Bucket4j supports clustered usage scenario on top of following back-ends:
Back-end | Async supported | Optimized serialization | Thin-client support | Documentation link |
---|---|---|---|---|
JCache API (JSR 107) |
No | No | No | bucket4j-jcache |
Hazelcast |
Yes | Yes | No | bucket4j-hazelcast |
Apache Ignite |
Yes | n/a | Yes | bucket4j-ignite |
Inifinispan |
Yes | Yes | No | bucket4j-infinispan |
Oracle Coherence |
Yes | Yes | No | bucket4j-coherence |
Back-end | Async supported | Redis cluster supported | Documentation link |
---|---|---|---|
Redis/Redisson |
Yes | Yes | bucket4j-redis/Redisson |
Redis/Jedis |
No | Yes | bucket4j-redis/Jedis |
Redis/Lettuce |
Yes | Yes | bucket4j-redis/Lettuce |
Back-end | Documentation link |
---|---|
MySQL |
bucket4j-mysql |
PostgreSQL |
bucket4j-postgresql |
Oracle |
bucket4j-oracle |
Microsoft SQL Server |
bucket4j-mssql |
MariaDB |
bucket4j-mariadb |
Sometimes you are having deal with bucket per key scenarios but distributed synchronization is unnecessary, for example where request stickiness is provided by a load balancer, or other use-cases where stickiness can be achieved by the application itself, for example, Kafka consumer. For such scenarios Bucket4j provides support for following list of local caching libraries:
Back-end | Documentation link |
---|---|
Caffeine |
bucket4j-caffeine |
Back-end | Project page |
---|---|
Datomic Database |
clj-bucket4j-datomic |
Feel free to ask via:
Copyright 2015-2021 Vladimir Bukhtoyarov Licensed under the Apache Software License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0.
:heavy_exclamation_mark: Since July 2022(release 8.0.0) it was decided to migrate Bucket4j to Java 11.
:shit: Obviously, it bad news for all who get stuck on Java 8 by different reasons.
:ambulance: Bucket4j maintainers understand your pain and provide special builds with dedicated artifacts for java 8.
:gift: Maven artifacts for Java 8, currently are provided for free.
:heavy_dollar_sign: Keep in mind that access to fresh releases of Bucket4j for Java 8 can be moved to a commercial model at any moment.
:pill: Right Maven artifact name for Java 8 can be found on jdk-matrix-compatibility page.
Following options are available to increase motivation to develop new features: