bucket4j

Java rate-limiting library based on token-bucket algorithm.

Get dependency

The Bucket4j is distributed through Maven Central:

Java 17 dependency

<dependency>
  <groupId>com.bucket4j</groupId>
  <artifactId>bucket4j_jdk17-core</artifactId>
  <version>8.19.0</version>
</dependency>

Quick start

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

Documentation

• Reference
• Quick start examples
• Third-party articles

Bucket4j basic features

• Absolutely non-compromise precision - Bucket4j does not operate with floats or doubles, all calculation are performed in the integer arithmetic, this feature protects end users from calculation errors involved by rounding.
• Effective implementation in terms of concurrency:
  • Bucket4j is good scalable for multi-threading case it by defaults uses lock-free implementation.
  • In same time, library provides different concurrency strategies that can be chosen when default lock-free strategy is not desired.
• Effective API in terms of garbage collector footprint: Bucket4j API tries to use primitive types as much as it is possible in order to avoid boxing and other types of floating garbage.
• Pluggable listener API that allows to implement monitoring and logging.
• Rich diagnostic API that allows to investigate internal state.
• Rich configuration management - configuration of the bucket can be changed on fly

Bucket4j distributed features

In additional to basic features described above, Bucket4j provides ability to implement rate-limiting in cluster of JVMs:

• Bucket4j out of the box supports any GRID solution which compatible with JCache API (JSR 107) specification.
• Bucket4j provides the framework that allows to quickly build integration with your own persistent technology like RDMS or a key-value storage.
• For clustered usage scenarios Bucket4j supports asynchronous API that extremely matters when going to distribute world, because asynchronous API allows avoiding blocking your application threads each time when you need to execute Network request.

Spring boot starter

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.

Supported JCache compatible(or similar) back-ends

In addition to local in-memory buckets, the Bucket4j supports clustered usage scenario on top of following back-ends:

Back-end	Async supported	Flexible per-entry expiration	Optimized serialization	Thin-client support	Documentation link
JCache API (JSR 107)	No	No	No	No	bucket4j-jcache
Hazelcast	Yes	Yes	Yes	No	bucket4j-hazelcast
Apache Ignite	Yes	No	n/a	Yes	bucket4j-ignite
Inifinispan	Yes	Yes	Yes	No	bucket4j-infinispan
Oracle Coherence	Yes	Yes	Yes	No	bucket4j-coherence
Couchbase	Yes	Yes	Yes	No	bucket4j-couchbase
Apache Geode (GemFire)	No	No	n/a	No	bucket4j-geode

Redis back-ends

Back-end	Async supported	Redis cluster supported	Documentation link
Redis/Vert.x Redis Client	Yes	Yes	bucket4j-redis/Vert.x
Redis/Redisson	Yes	Yes	bucket4j-redis/Redisson
Redis/Jedis	No	Yes	bucket4j-redis/Jedis
Redis/Lettuce	Yes	Yes	bucket4j-redis/Lettuce

Valkey back-ends

Back-end	Async supported	Redis cluster supported	Documentation link
Valkey/Glide	Yes	Yes	bucket4j-valkey/Glide

Mongo back-ends

Back-end	Async supported	Documentation link
Mongodb/mongodb-driver-sync	No	bucket4j-mongodb/sync
Mongodb/mongodb-driver-reactivestreams	Yes	bucket4j-mongodb/async

JDBC back-ends

Back-end	Documentation link
MySQL	bucket4j-mysql
PostgreSQL	bucket4j-postgresql
Oracle	bucket4j-oracle
Microsoft SQL Server	bucket4j-mssql
MariaDB	bucket4j-mariadb
DB2	bucket4j-db2

Local caches support

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

Third-party integrations

Back-end	Project page
Datomic Database	clj-bucket4j-datomic

Bucket4j Backward compatibility policy

Snapshot builds

Every commit/merge to the master branch is automatically built and published as a -SNAPSHOT artifact to GitHub Packages (see .github/workflows/snapshot-release.yml).

To consume a snapshot, add the GitHub Packages repository to your pom.xml:

<repositories>
  <repository>
    <id>github</id>
    <name>Bucket4j GitHub Packages</name>
    <url>https://maven.pkg.github.com/bucket4j/bucket4j</url>
  </repository>
</repositories>

GitHub Packages requires authentication even for reading public packages, so add a server entry with your GitHub username and a personal access token that has the read:packages scope to your ~/.m2/settings.xml:

<servers>
  <server>
    <id>github</id>
    <username>YOUR_GITHUB_USERNAME</username>
    <password>YOUR_GITHUB_TOKEN</password>
  </server>
</servers>

Then reference the snapshot version (current pom.xml version with the -SNAPSHOT suffix), for example:

<dependency>
  <groupId>com.bucket4j</groupId>
  <artifactId>bucket4j_jdk17-core</artifactId>
  <version>8.20.0-SNAPSHOT</version>
</dependency>

Have a question?

Feel free to ask via:

• Bucket4j github issue tracker to report a bug.
• Bucket4j github discussions for questions, feature proposals, sharing of experience.

License

Copyright 2015-2024 Vladimir Bukhtoyarov Licensed under the Apache Software License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0.