Spring Rate Throttler is a library designed for rate limiting or throttling incoming HTTP requests in a Spring application using annotations and application properties. Rate limiting is a common technique used to control the flow of incoming requests to prevent overloading of server resources, ensuring that the server can function effectively for all clients.
With Spring Rate Throttler, you can easily define rate limiting policies based on criteria such as throttle key, number of requests per unit of time, or other custom parameters. The library provides a customizable way to define these policies through annotations or application properties, so you can quickly and easily add rate limiting capabilities to your Spring application.
- Easy integration with Spring Boot applications.
- Annotation and application properties based.
- Configurable rate limiting policies based on different criteria (global level, class level and method level configuration).
- Support for customizable rate limiting exception handling.
- In-memory caching using Caffeine for high performance.
- Token bucket algorithm for rate limiting.
Spring Rate Throttler can be easily installed using JitPack, see Gradle and Maven examples below.
Add the following to your build.gradle file:
repositories {
mavenCentral()
maven { url "https://jitpack.io" }
}
dependencies {
implementation 'com.github.thewaterfall:spring-rate-throttler:1.0.1'
}
Add the following to your pom.xml file:
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.thewaterfall</groupId>
<artifactId>spring-rate-throttler</artifactId>
<version>1.0.1</version>
</dependency>
</dependencies>
There are three levels of configuration that can be applied: global, class and method. Lower level overrides higher levels. From the lowest (strongest) to the highest levels (weakest): method level > class level > global level.
Library is based on such terms and properties as:
- Throttle capacity: initial and maximum capacity of requests
- Throttle refill: number of requests that are refilled (usually is equal to capacity)
- Throttle refill period: the period per which a number of requests (see refill property) are refilled
- Throttle refill period unit: the unit of time used for the refill period (in ChronoUnit, e.g. SECONDS, MINUTES, etc.)
- Throttle key: the type of key used to identify the source or user of the request (supported: IP_ADDRESS, HEADER)
- Throttle key source: the source of the key used to retrieve value from (header name, etc.)
Add @EnableThrottler
to enable throttler:
@EnableThrottler
@SpringBootApplication
public class Application {
public static void main(String[] args) {
Application.run(Application.class, args);
}
}
When rate limit is exceeded, a ThrottleException
will be thrown that can be caught and processed, see example
below.
@ControllerAdvice
public class ErrorHandler {
@ExceptionHandler(value = ThrottleException.class)
protected ResponseEntity<Object> handleThrottleException(ThrottleException e,
HttpServletRequest request) {
return new ResponseEntity<>(response, TOO_MANY_REQUESTS);
}
}
Global configuration is applied to all the requests and endpoints. Additionally, cache can be configured.