https://github.com/vladimir-bukhtoyarov/bucket4j

Project version overview:

• 0.9.0 - Bucket4j 8.1.0 - Spring Boot 3.0.x

• 0.8.0 - Bucket4j 8.1.0 - Spring Boot 2.7.x

• 0.7.0 - Bucket4j 7.5.0 - Spring Boot 2.7.x

Examples:

• Ehcache

• Hazelcast

• Caffeine

• Webflux (Async)

• Spring Cloud Gateway (Async)

This project is a Spring Boot Starter for Bucket4j. It can be used limit the rate of access to your REST APIs.

• Prevention of DoS Attacks, brute-force logins attempts

• Request throttling for specific regions, unauthenticated users, authenticated users, not paying users.

The benefit of this project is the configuration of Bucket4j via Spring Boots properties or yaml files. You don’t have to write a single line of code.

This section is meant to help you migrate your application to new version of this starter project.

Spring Boot Starter Bucket4j 0.9

Spring Boot Starter Bucket4j 0.8

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

bucket4j.filters[0].rate-limits[0].bandwidths[0].fixed-refill-interval=0
bucket4j.filters[0].rate-limits[0].bandwidths[0].fixed-refill-interval-unit=minutes

bucket4j.filters[0].rate-limits[0].bandwidths[0].refill-speed=interval

To use the rate limit in your project you have to add the Bucket4j Spring Boot Starter dependency in your project. Additionally you have to choose a caching provider [cache_overview].

The next example uses JSR 107 Ehcache which will be auto configured with the Spring Boot Starter Cache.

Don’t forget to enable the caching feature by adding the @EnableCaching annotation to any of the configuration classes.

The configuration can be done in the application.properties / application.yml. The following configuration limits all requests independently from the user. It allows a maximum of 5 requests within 10 seconds independently from the user.

For Ehcache 3 you also need a ehcache.xml which can be placed in the classpath. The configured cache name buckets must be defined in the configuration file.

The following list contains the Caching implementation which will be autoconfigured by this starter.

Instead of determine the Caching Provider by the Bucket4j Spring Boot Starter project you can implement the SynchCacheResolver or the AsynchCacheResolver by yourself.

You can enable the cache auto configuration explicitly by using the cache-to-use property name or setting it to an invalid value to disable all auto configurations.

Filter strategy

bucket4j.filters[0].strategy=first # [first, all]

To differentiate incoming request you can provide an expression which is used as a key resolver for the underlying cache.

The expression uses the Spring Expression Language (SpEL) which provides the most flexible solution to determine the cache key written in one line of code. The expression compiles to a Java class which will be used.

Depending on the filter method [servlet,webflux,gateway] different SpEL root objects object can be used in the expression so that you have a direct access to the method of these request objects:

• servlet: jakarta.servlet.http.HttpServletRequest (e.g. getRemoteAddr() or getRequestURI())

• webflux: org.springframework.http.server.reactive.ServerHttpRequest

• gateway: org.springframework.http.server.reactive.ServerHttpRequest

The configured URL which is used for filtering is added to the cache-key to provide a unique cache-key for multiple URL. You can read more about it here.

Limiting based on IP-Address:

Limiting based on Username - If not logged in use IP-Address:

The refill speed defines the period of the regeneration of consumed tokens. This starter supports two types of token regeneration. The refill speed can be set with the following property:

• greedy: This is the default refill speed and tries to add tokens as soon as possible.

• interval: You can alternatively chose interval for the token regeneration which refills the token in a fixed interval.

You can read more about the refill speed in the official documentation.

Skip and Execution Predicates can be used to conditionally skip or execute the rate limiting. Each predicate has a unique name and a self-contained configuration. The following section describes the build in Execution Predicates and how to use them.

Path Predicates

bucket4j.filters[0].rate-limits[0].skip-predicates[0]=PATH=/hello,/world,/admin
bucket4j.filters[0].rate-limits[0].execute-predicates[0]=PATH=/hello,/world,/admin

Method Predicate

bucket4j.filters[0].rate-limits[0].skip-predicates[0]=METHOD=GET,POST
bucket4j.filters[0].rate-limits[0].execute-predicates[0]=METHOD=GET,POST

Query Predicate

bucket4j.filters[0].rate-limits[0].skip-predicates[0]=QUERY=PARAM_1
bucket4j.filters[0].rate-limits[0].execute-predicates[0]=QUERY=PARAM_1

Header Predicate

bucket4j.filters[0].rate-limits[0].execute-predicates[0]=Content-Type,.*PDF.*

Custom Predicate

@Component
@Slf4j
public class MyQueryExecutePredicate extends ExecutePredicate<HttpServletRequest> {

	private String query;

	public String name() {
		// The name which can be used on the properties
		return "MY_QUERY";
	}

	public boolean test(HttpServletRequest t) {
	    // the logic to implement the predicate
		boolean result = t.getParameterMap().containsKey(query);
		log.debug("my-query-parametetr;value:%s;result:%s".formatted(query, result));
		return result;
	}

	public ExecutePredicate<HttpServletRequest> parseSimpleConfig(String simpleConfig) {
		// the configuration which is configured behind the equal sign
		// MY_QUERY=P_1 -> simpleConfig == "P_1"
		//
		this.query = simpleConfig;
		return this;
	}
}

Spring Boot ships with a great support for collecting metrics. This project automatically provides metric information about the consumed and rejected buckets. You can extend these information with configurable custom tags like the username or the IP-Address which can then be evaluated in a monitoring system like prometheus/grafana.

Simple configuration to allow a maximum of 5 requests within 10 seconds independently from the user.

Conditional filtering depending of anonymous or logged in user. Because the bucket4j.filters[0].strategy is first you havn’t to check in the second rate-limit that the user is logged in. Only the first one is executed.

Configuration of multiple independently filters (servlet|gateway|webflux filters) with specific rate limit configurations.